From 837bee3f97ba65794f79b0b2be08b371a713ba88 Mon Sep 17 00:00:00 2001 From: kazuhiko Date: Tue, 21 Nov 2000 09:05:56 +0000 Subject: [PATCH] import xemacs-21.2.37 --- info/internals.info-4 | 4 +- info/internals.info-5 | 4 +- info/internals.info-8 | 6 +- info/lispref.info-10 | 415 ++--- info/lispref.info-11 | 401 ++-- info/lispref.info-12 | 451 +++-- info/lispref.info-13 | 456 ++--- info/lispref.info-14 | 411 +++-- info/lispref.info-15 | 403 ++-- info/lispref.info-16 | 523 ++---- info/lispref.info-17 | 681 ++++--- info/lispref.info-18 | 784 ++++---- info/lispref.info-19 | 941 +++++----- info/lispref.info-20 | 1020 ++++++----- info/lispref.info-21 | 965 +++++----- info/lispref.info-22 | 919 +++++----- info/lispref.info-23 | 1016 +++++------ info/lispref.info-24 | 1095 +++++------ info/lispref.info-25 | 1094 ++++++----- info/lispref.info-26 | 1205 ++++++------ info/lispref.info-27 | 1110 ++++++----- info/lispref.info-28 | 1344 +++++++------- info/lispref.info-29 | 1317 +++++++------- info/lispref.info-30 | 1322 +++++++------- info/lispref.info-31 | 1350 +++++++------- info/lispref.info-32 | 1396 +++++++------- info/lispref.info-33 | 1290 +++++++------ info/lispref.info-34 | 1066 ++++++----- info/lispref.info-35 | 1018 +++++------ info/lispref.info-36 | 831 +++++---- info/lispref.info-37 | 702 ++++--- info/lispref.info-38 | 763 ++++---- info/lispref.info-39 | 904 ++++----- info/lispref.info-40 | 1024 +++++------ info/lispref.info-41 | 1107 ++++++----- info/lispref.info-42 | 1225 ++++++------- info/lispref.info-43 | 1259 +++++++------ info/lispref.info-44 | 1426 ++++++--------- info/lispref.info-45 | 1628 +++++++++-------- info/lispref.info-46 | 1574 ++++++++-------- info/lispref.info-47 | 4253 ++++++++----------------------------------- info/new-users-guide.info-2 | 4 +- info/xemacs-faq.info-3 | 145 +- info/xemacs-faq.info-4 | 148 +- info/xemacs-faq.info-5 | 65 + info/xemacs.info-12 | 7 +- info/xemacs.info-13 | 425 +++-- info/xemacs.info-14 | 323 ++-- info/xemacs.info-15 | 356 ++-- info/xemacs.info-16 | 386 ++-- info/xemacs.info-17 | 446 ++--- info/xemacs.info-18 | 251 +++ info/xemacs.info-7 | 8 +- info/xemacs.info-9 | 4 +- 54 files changed, 20353 insertions(+), 22918 deletions(-) diff --git a/info/internals.info-4 b/info/internals.info-4 index 5535878..13db1b3 100644 --- a/info/internals.info-4 +++ b/info/internals.info-4 @@ -915,8 +915,8 @@ are used that are worth remembering are various elisp commands, as for example `or', `and', `if', `cond', `while', `setq', etc., miscellaneous `gui_item_...' functions, everything related to `eval' (`Feval_buffer', `call0', ...) and inside `Fsignal'. The latter is used to handle -signals, as for example the ones raised by every `QUITE'-macro -triggered after pressing Ctrl-g. +signals, as for example the ones raised by every `QUIT'-macro triggered +after pressing Ctrl-g.  File: internals.info, Node: garbage_collect_1, Next: mark_object, Prev: Invocation, Up: Garbage Collection - Step by Step diff --git a/info/internals.info-5 b/info/internals.info-5 index 56833c5..19f604d 100644 --- a/info/internals.info-5 +++ b/info/internals.info-5 @@ -388,8 +388,8 @@ into the enum's code at compile-time. which is used to mark an object. All Lisp objects that are contained within the object need to be marked by applying this function to them. The mark method should also return a Lisp - object, which should be either nil or an object to mark. (This can - be used in lieu of calling `mark_object()' on the object, to + object, which should be either `nil' or an object to mark. (This + can be used in lieu of calling `mark_object()' on the object, to reduce the recursion depth, and consequently should be the most heavily nested sub-object, such as a long list.) diff --git a/info/internals.info-8 b/info/internals.info-8 index c35a30f..0e44efd 100644 --- a/info/internals.info-8 +++ b/info/internals.info-8 @@ -92,14 +92,14 @@ combination window. "hchild" (a list of horizontally-arrayed children), "vchild" (a list of vertically-arrayed children), and "buffer" (the buffer contained in a leaf window). Exactly one of these will be - non-nil. Remember that "horizontally-arrayed" means + non-`nil'. Remember that "horizontally-arrayed" means "side-by-side" and "vertically-arrayed" means "one above the other". 7. Leaf windows also have markers in their `start' (the first buffer position displayed in the window) and `pointm' (the window's stashed value of `point'--see above) fields, while combination - windows have nil in these fields. + windows have `nil' in these fields. 8. The list of children for a window is threaded through the `next' and `prev' fields of each child window. @@ -516,7 +516,7 @@ Zero-Length Extents Extents can be zero-length, and will end up that way if their endpoints are explicitly set that way or if their detachable property -is nil and all the text in the extent is deleted. (The exception is +is `nil' and all the text in the extent is deleted. (The exception is open-open zero-length extents, which are barred from existing because there is no sensible way to define their properties. Deletion of the text in an open-open extent causes it to be converted into a closed-open diff --git a/info/lispref.info-10 b/info/lispref.info-10 index 43fb10f..536420b 100644 --- a/info/lispref.info-10 +++ b/info/lispref.info-10 @@ -50,6 +50,191 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables + +Introduction to Buffer-Local Variables +-------------------------------------- + + A buffer-local variable has a buffer-local binding associated with a +particular buffer. The binding is in effect when that buffer is +current; otherwise, it is not in effect. If you set the variable while +a buffer-local binding is in effect, the new value goes in that binding, +so the global binding is unchanged; this means that the change is +visible in that buffer alone. + + A variable may have buffer-local bindings in some buffers but not in +others. The global binding is shared by all the buffers that don't have +their own bindings. Thus, if you set the variable in a buffer that does +not have a buffer-local binding for it, the new value is visible in all +buffers except those with buffer-local bindings. (Here we are assuming +that there are no `let'-style local bindings to complicate the issue.) + + The most common use of buffer-local bindings is for major modes to +change variables that control the behavior of commands. For example, C +mode and Lisp mode both set the variable `paragraph-start' to specify +that only blank lines separate paragraphs. They do this by making the +variable buffer-local in the buffer that is being put into C mode or +Lisp mode, and then setting it to the new value for that mode. + + The usual way to make a buffer-local binding is with +`make-local-variable', which is what major mode commands use. This +affects just the current buffer; all other buffers (including those yet +to be created) continue to share the global value. + + A more powerful operation is to mark the variable as "automatically +buffer-local" by calling `make-variable-buffer-local'. You can think +of this as making the variable local in all buffers, even those yet to +be created. More precisely, the effect is that setting the variable +automatically makes the variable local to the current buffer if it is +not already so. All buffers start out by sharing the global value of +the variable as usual, but any `setq' creates a buffer-local binding +for the current buffer. The new value is stored in the buffer-local +binding, leaving the (default) global binding untouched. The global +value can no longer be changed with `setq'; you need to use +`setq-default' to do that. + + Local variables in a file you edit are also represented by +buffer-local bindings for the buffer that holds the file within XEmacs. +*Note Auto Major Mode::. + + +File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables + +Creating and Deleting Buffer-Local Bindings +------------------------------------------- + + - Command: make-local-variable variable + This function creates a buffer-local binding in the current buffer + for VARIABLE (a symbol). Other buffers are not affected. The + value returned is VARIABLE. + + The buffer-local value of VARIABLE starts out as the same value + VARIABLE previously had. If VARIABLE was void, it remains void. + + ;; In buffer `b1': + (setq foo 5) ; Affects all buffers. + => 5 + (make-local-variable 'foo) ; Now it is local in `b1'. + => foo + foo ; That did not change + => 5 ; the value. + (setq foo 6) ; Change the value + => 6 ; in `b1'. + foo + => 6 + + ;; In buffer `b2', the value hasn't changed. + (save-excursion + (set-buffer "b2") + foo) + => 5 + + Making a variable buffer-local within a `let'-binding for that + variable does not work. This is because `let' does not distinguish + between different kinds of bindings; it knows only which variable + the binding was made for. + + *Please note:* do not use `make-local-variable' for a hook + variable. Instead, use `make-local-hook'. *Note Hooks::. + + - Command: make-variable-buffer-local variable + This function marks VARIABLE (a symbol) automatically + buffer-local, so that any subsequent attempt to set it will make it + local to the current buffer at the time. + + The value returned is VARIABLE. + + - Function: local-variable-p variable buffer &optional after-set + This returns `t' if VARIABLE is buffer-local in buffer BUFFER; + else `nil'. + + If optional third arg AFTER-SET is non-`nil', return `t' if SYMBOL + would be buffer-local after it is set, regardless of whether it is + so presently. + + A `nil' value for BUFFER is _not_ the same as `(current-buffer)', + but means "no buffer". Specifically: + + If BUFFER is `nil' and AFTER-SET is `nil', a return value of `t' + indicates that the variable is one of the special built-in + variables that is always buffer-local. (This includes + `buffer-file-name', `buffer-read-only', `buffer-undo-list', and + others.) + + If BUFFER is `nil' and AFTER-SET is `t', a return value of `t' + indicates that the variable has had `make-variable-buffer-local' + applied to it. + + - Function: buffer-local-variables &optional buffer + This function returns a list describing the buffer-local variables + in buffer BUFFER. It returns an association list (*note + Association Lists::) in which each association contains one + buffer-local variable and its value. When a buffer-local variable + is void in BUFFER, then it appears directly in the resulting list. + If BUFFER is omitted, the current buffer is used. + + (make-local-variable 'foobar) + (makunbound 'foobar) + (make-local-variable 'bind-me) + (setq bind-me 69) + (setq lcl (buffer-local-variables)) + ;; First, built-in variables local in all buffers: + => ((mark-active . nil) + (buffer-undo-list nil) + (mode-name . "Fundamental") + ... + ;; Next, non-built-in local variables. + ;; This one is local and void: + foobar + ;; This one is local and nonvoid: + (bind-me . 69)) + + Note that storing new values into the CDRs of cons cells in this + list does _not_ change the local values of the variables. + + - Command: kill-local-variable variable + This function deletes the buffer-local binding (if any) for + VARIABLE (a symbol) in the current buffer. As a result, the + global (default) binding of VARIABLE becomes visible in this + buffer. Usually this results in a change in the value of + VARIABLE, since the global value is usually different from the + buffer-local value just eliminated. + + If you kill the local binding of a variable that automatically + becomes local when set, this makes the global value visible in the + current buffer. However, if you set the variable again, that will + once again create a local binding for it. + + `kill-local-variable' returns VARIABLE. + + This function is a command because it is sometimes useful to kill + one buffer-local variable interactively, just as it is useful to + create buffer-local variables interactively. + + - Function: kill-all-local-variables + This function eliminates all the buffer-local variable bindings of + the current buffer except for variables marked as "permanent". As + a result, the buffer will see the default values of most variables. + + This function also resets certain other information pertaining to + the buffer: it sets the local keymap to `nil', the syntax table to + the value of `standard-syntax-table', and the abbrev table to the + value of `fundamental-mode-abbrev-table'. + + Every major mode command begins by calling this function, which + has the effect of switching to Fundamental mode and erasing most + of the effects of the previous major mode. To ensure that this + does its job, the variables that major modes set should not be + marked permanent. + + `kill-all-local-variables' returns `nil'. + + A local variable is "permanent" if the variable name (a symbol) has a +`permanent-local' property that is non-`nil'. Permanent locals are +appropriate for data pertaining to where the file came from or how to +save it, rather than with how to edit the contents. + + File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables The Default Value of a Buffer-Local Variable @@ -157,12 +342,12 @@ Obsoleteness::). variable, a variable that has a buffer-local value in any buffer, or the symbols `nil' or `t'. - - Function: variable-alias variable + - Function: variable-alias variable &optional follow-past-lisp-magic If VARIABLE is aliased to another variable, this function returns that variable. VARIABLE should be a symbol. If VARIABLE is not aliased, this function returns `nil'. - - Function: indirect-variable object + - Function: indirect-variable object &optional follow-past-lisp-magic This function returns the variable at the end of OBJECT's variable-alias chain. If OBJECT is a symbol, follow all variable aliases and return the final (non-aliased) symbol. If OBJECT is @@ -745,7 +930,7 @@ function: - Function: identity arg This function returns ARG and has no side effects. - - Function: ignore &rest args + - Command: ignore &rest args This function ignores any arguments and returns `nil'.  @@ -949,9 +1134,9 @@ cell contains no object whatsoever. can make it void once more using `fmakunbound'. - Function: fboundp symbol - This function returns `t' if the symbol has an object in its - function cell, `nil' otherwise. It does not check that the object - is a legitimate function. + This function returns `t' if SYMBOL has an object in its function + cell, `nil' otherwise. It does not check that the object is a + legitimate function. - Function: fmakunbound symbol This function makes SYMBOL's function cell void, so that a @@ -979,9 +1164,9 @@ can make it void once more using `fmakunbound'. * Giving a symbol a function definition that is not a list and therefore cannot be made with `defun'. For example, you can - use `fset' to give a symbol `s1' a function definition which - is another symbol `s2'; then `s1' serves as an alias for - whatever definition `s2' presently has. + use `fset' to give a symbol SYMBOL1 a function definition + which is another symbol SYMBOL2; then SYMBOL1 serves as an + alias for whatever definition SYMBOL2 presently has. * In constructs for defining or altering functions. If `defun' were not a primitive, it could be written in Lisp (as a @@ -1031,215 +1216,3 @@ before moving aside the old definition of `foo'. But it is unmodular and unclean, in any case, for a Lisp file to redefine a function defined elsewhere. - -File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions - -Inline Functions -================ - - You can define an "inline function" by using `defsubst' instead of -`defun'. An inline function works just like an ordinary function -except for one thing: when you compile a call to the function, the -function's definition is open-coded into the caller. - - Making a function inline makes explicit calls run faster. But it -also has disadvantages. For one thing, it reduces flexibility; if you -change the definition of the function, calls already inlined still use -the old definition until you recompile them. Since the flexibility of -redefining functions is an important feature of XEmacs, you should not -make a function inline unless its speed is really crucial. - - Another disadvantage is that making a large function inline can -increase the size of compiled code both in files and in memory. Since -the speed advantage of inline functions is greatest for small -functions, you generally should not make large functions inline. - - It's possible to define a macro to expand into the same code that an -inline function would execute. But the macro would have a limitation: -you can use it only explicitly--a macro cannot be called with `apply', -`mapcar' and so on. Also, it takes some work to convert an ordinary -function into a macro. (*Note Macros::.) To convert it into an inline -function is very easy; simply replace `defun' with `defsubst'. Since -each argument of an inline function is evaluated exactly once, you -needn't worry about how many times the body uses the arguments, as you -do for macros. (*Note Argument Evaluation::.) - - Inline functions can be used and open-coded later on in the same -file, following the definition, just like macros. - - -File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions - -Other Topics Related to Functions -================================= - - Here is a table of several functions that do things related to -function calling and function definitions. They are documented -elsewhere, but we provide cross references here. - -`apply' - See *Note Calling Functions::. - -`autoload' - See *Note Autoload::. - -`call-interactively' - See *Note Interactive Call::. - -`commandp' - See *Note Interactive Call::. - -`documentation' - See *Note Accessing Documentation::. - -`eval' - See *Note Eval::. - -`funcall' - See *Note Calling Functions::. - -`ignore' - See *Note Calling Functions::. - -`indirect-function' - See *Note Function Indirection::. - -`interactive' - See *Note Using Interactive::. - -`interactive-p' - See *Note Interactive Call::. - -`mapatoms' - See *Note Creating Symbols::. - -`mapcar' - See *Note Mapping Functions::. - -`mapconcat' - See *Note Mapping Functions::. - -`undefined' - See *Note Key Lookup::. - - -File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top - -Macros -****** - - "Macros" enable you to define new control constructs and other -language features. A macro is defined much like a function, but instead -of telling how to compute a value, it tells how to compute another Lisp -expression which will in turn compute the value. We call this -expression the "expansion" of the macro. - - Macros can do this because they operate on the unevaluated -expressions for the arguments, not on the argument values as functions -do. They can therefore construct an expansion containing these -argument expressions or parts of them. - - If you are using a macro to do something an ordinary function could -do, just for the sake of speed, consider using an inline function -instead. *Note Inline Functions::. - -* Menu: - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. - - -File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros - -A Simple Example of a Macro -=========================== - - Suppose we would like to define a Lisp construct to increment a -variable value, much like the `++' operator in C. We would like to -write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a -macro definition that does the job: - - (defmacro inc (var) - (list 'setq var (list '1+ var))) - - When this is called with `(inc x)', the argument `var' has the value -`x'--_not_ the _value_ of `x'. The body of the macro uses this to -construct the expansion, which is `(setq x (1+ x))'. Once the macro -definition returns this expansion, Lisp proceeds to evaluate it, thus -incrementing `x'. - - -File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros - -Expansion of a Macro Call -========================= - - A macro call looks just like a function call in that it is a list -which starts with the name of the macro. The rest of the elements of -the list are the arguments of the macro. - - Evaluation of the macro call begins like evaluation of a function -call except for one crucial difference: the macro arguments are the -actual expressions appearing in the macro call. They are not evaluated -before they are given to the macro definition. By contrast, the -arguments of a function are results of evaluating the elements of the -function call list. - - Having obtained the arguments, Lisp invokes the macro definition just -as a function is invoked. The argument variables of the macro are bound -to the argument values from the macro call, or to a list of them in the -case of a `&rest' argument. And the macro body executes and returns -its value just as a function body does. - - The second crucial difference between macros and functions is that -the value returned by the macro body is not the value of the macro call. -Instead, it is an alternate expression for computing that value, also -known as the "expansion" of the macro. The Lisp interpreter proceeds -to evaluate the expansion as soon as it comes back from the macro. - - Since the expansion is evaluated in the normal manner, it may contain -calls to other macros. It may even be a call to the same macro, though -this is unusual. - - You can see the expansion of a given macro call by calling -`macroexpand'. - - - Function: macroexpand form &optional environment - This function expands FORM, if it is a macro call. If the result - is another macro call, it is expanded in turn, until something - which is not a macro call results. That is the value returned by - `macroexpand'. If FORM is not a macro call to begin with, it is - returned as given. - - Note that `macroexpand' does not look at the subexpressions of - FORM (although some macro definitions may do so). Even if they - are macro calls themselves, `macroexpand' does not expand them. - - The function `macroexpand' does not expand calls to inline - functions. Normally there is no need for that, since a call to an - inline function is no harder to understand than a call to an - ordinary function. - - If ENVIRONMENT is provided, it specifies an alist of macro - definitions that shadow the currently defined macros. Byte - compilation uses this feature. - - (defmacro inc (var) - (list 'setq var (list '1+ var))) - => inc - - (macroexpand '(inc r)) - => (setq r (1+ r)) - - (defmacro inc2 (var1 var2) - (list 'progn (list 'inc var1) (list 'inc var2))) - => inc2 - - (macroexpand '(inc2 r s)) - => (progn (inc r) (inc s)) ; `inc' not expanded here. - diff --git a/info/lispref.info-11 b/info/lispref.info-11 index 1780b0a..d276a20 100644 --- a/info/lispref.info-11 +++ b/info/lispref.info-11 @@ -50,6 +50,218 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions + +Inline Functions +================ + + You can define an "inline function" by using `defsubst' instead of +`defun'. An inline function works just like an ordinary function +except for one thing: when you compile a call to the function, the +function's definition is open-coded into the caller. + + Making a function inline makes explicit calls run faster. But it +also has disadvantages. For one thing, it reduces flexibility; if you +change the definition of the function, calls already inlined still use +the old definition until you recompile them. Since the flexibility of +redefining functions is an important feature of XEmacs, you should not +make a function inline unless its speed is really crucial. + + Another disadvantage is that making a large function inline can +increase the size of compiled code both in files and in memory. Since +the speed advantage of inline functions is greatest for small +functions, you generally should not make large functions inline. + + It's possible to define a macro to expand into the same code that an +inline function would execute. But the macro would have a limitation: +you can use it only explicitly--a macro cannot be called with `apply', +`mapcar' and so on. Also, it takes some work to convert an ordinary +function into a macro. (*Note Macros::.) To convert it into an inline +function is very easy; simply replace `defun' with `defsubst'. Since +each argument of an inline function is evaluated exactly once, you +needn't worry about how many times the body uses the arguments, as you +do for macros. (*Note Argument Evaluation::.) + + Inline functions can be used and open-coded later on in the same +file, following the definition, just like macros. + + +File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions + +Other Topics Related to Functions +================================= + + Here is a table of several functions that do things related to +function calling and function definitions. They are documented +elsewhere, but we provide cross references here. + +`apply' + See *Note Calling Functions::. + +`autoload' + See *Note Autoload::. + +`call-interactively' + See *Note Interactive Call::. + +`commandp' + See *Note Interactive Call::. + +`documentation' + See *Note Accessing Documentation::. + +`eval' + See *Note Eval::. + +`funcall' + See *Note Calling Functions::. + +`ignore' + See *Note Calling Functions::. + +`indirect-function' + See *Note Function Indirection::. + +`interactive' + See *Note Using Interactive::. + +`interactive-p' + See *Note Interactive Call::. + +`mapatoms' + See *Note Creating Symbols::. + +`mapcar' + See *Note Mapping Functions::. + +`mapconcat' + See *Note Mapping Functions::. + +`undefined' + See *Note Key Lookup::. + + +File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top + +Macros +****** + + "Macros" enable you to define new control constructs and other +language features. A macro is defined much like a function, but instead +of telling how to compute a value, it tells how to compute another Lisp +expression which will in turn compute the value. We call this +expression the "expansion" of the macro. + + Macros can do this because they operate on the unevaluated +expressions for the arguments, not on the argument values as functions +do. They can therefore construct an expansion containing these +argument expressions or parts of them. + + If you are using a macro to do something an ordinary function could +do, just for the sake of speed, consider using an inline function +instead. *Note Inline Functions::. + +* Menu: + +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. + + +File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros + +A Simple Example of a Macro +=========================== + + Suppose we would like to define a Lisp construct to increment a +variable value, much like the `++' operator in C. We would like to +write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a +macro definition that does the job: + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + + When this is called with `(inc x)', the argument `var' has the value +`x'--_not_ the _value_ of `x'. The body of the macro uses this to +construct the expansion, which is `(setq x (1+ x))'. Once the macro +definition returns this expansion, Lisp proceeds to evaluate it, thus +incrementing `x'. + + +File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros + +Expansion of a Macro Call +========================= + + A macro call looks just like a function call in that it is a list +which starts with the name of the macro. The rest of the elements of +the list are the arguments of the macro. + + Evaluation of the macro call begins like evaluation of a function +call except for one crucial difference: the macro arguments are the +actual expressions appearing in the macro call. They are not evaluated +before they are given to the macro definition. By contrast, the +arguments of a function are results of evaluating the elements of the +function call list. + + Having obtained the arguments, Lisp invokes the macro definition just +as a function is invoked. The argument variables of the macro are bound +to the argument values from the macro call, or to a list of them in the +case of a `&rest' argument. And the macro body executes and returns +its value just as a function body does. + + The second crucial difference between macros and functions is that +the value returned by the macro body is not the value of the macro call. +Instead, it is an alternate expression for computing that value, also +known as the "expansion" of the macro. The Lisp interpreter proceeds +to evaluate the expansion as soon as it comes back from the macro. + + Since the expansion is evaluated in the normal manner, it may contain +calls to other macros. It may even be a call to the same macro, though +this is unusual. + + You can see the expansion of a given macro call by calling +`macroexpand'. + + - Function: macroexpand form &optional environment + This function expands FORM, if it is a macro call. If the result + is another macro call, it is expanded in turn, until something + which is not a macro call results. That is the value returned by + `macroexpand'. If FORM is not a macro call to begin with, it is + returned as given. + + Note that `macroexpand' does not look at the subexpressions of + FORM (although some macro definitions may do so). Even if they + are macro calls themselves, `macroexpand' does not expand them. + + The function `macroexpand' does not expand calls to inline + functions. Normally there is no need for that, since a call to an + inline function is no harder to understand than a call to an + ordinary function. + + If ENVIRONMENT is provided, it specifies an alist of macro + definitions that shadow the currently defined macros. Byte + compilation uses this feature. + + (defmacro inc (var) + (list 'setq var (list '1+ var))) + => inc + + (macroexpand '(inc r)) + => (setq r (1+ r)) + + (defmacro inc2 (var1 var2) + (list 'progn (list 'inc var1) (list 'inc var2))) + => inc2 + + (macroexpand '(inc2 r s)) + => (progn (inc r) (inc s)) ; `inc' not expanded here. + + File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros Macros and Byte Compilation @@ -1077,192 +1289,3 @@ the forms are function definitions and variable definitions. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. - -File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading - -How Programs Do Loading -======================= - - XEmacs Lisp has several interfaces for loading. For example, -`autoload' creates a placeholder object for a function in a file; -trying to call the autoloading function loads the file to get the -function's real definition (*note Autoload::). `require' loads a file -if it isn't already loaded (*note Named Features::). Ultimately, all -these facilities call the `load' function to do the work. - - - Function: load filename &optional missing-ok nomessage nosuffix - This function finds and opens a file of Lisp code, evaluates all - the forms in it, and closes the file. - - To find the file, `load' first looks for a file named - `FILENAME.elc', that is, for a file whose name is FILENAME with - `.elc' appended. If such a file exists, it is loaded. If there - is no file by that name, then `load' looks for a file named - `FILENAME.el'. If that file exists, it is loaded. Finally, if - neither of those names is found, `load' looks for a file named - FILENAME with nothing appended, and loads it if it exists. (The - `load' function is not clever about looking at FILENAME. In the - perverse case of a file named `foo.el.el', evaluation of `(load - "foo.el")' will indeed find it.) - - If the optional argument NOSUFFIX is non-`nil', then the suffixes - `.elc' and `.el' are not tried. In this case, you must specify - the precise file name you want. - - If FILENAME is a relative file name, such as `foo' or - `baz/foo.bar', `load' searches for the file using the variable - `load-path'. It appends FILENAME to each of the directories - listed in `load-path', and loads the first file it finds whose name - matches. The current default directory is tried only if it is - specified in `load-path', where `nil' stands for the default - directory. `load' tries all three possible suffixes in the first - directory in `load-path', then all three suffixes in the second - directory, and so on. - - If you get a warning that `foo.elc' is older than `foo.el', it - means you should consider recompiling `foo.el'. *Note Byte - Compilation::. - - Messages like `Loading foo...' and `Loading foo...done' appear in - the echo area during loading unless NOMESSAGE is non-`nil'. - - Any unhandled errors while loading a file terminate loading. If - the load was done for the sake of `autoload', any function - definitions made during the loading are undone. - - If `load' can't find the file to load, then normally it signals the - error `file-error' (with `Cannot open load file FILENAME'). But - if MISSING-OK is non-`nil', then `load' just returns `nil'. - - You can use the variable `load-read-function' to specify a function - for `load' to use instead of `read' for reading expressions. See - below. - - `load' returns `t' if the file loads successfully. - - - User Option: load-path - The value of this variable is a list of directories to search when - loading files with `load'. Each element is a string (which must be - a directory name) or `nil' (which stands for the current working - directory). The value of `load-path' is initialized from the - environment variable `EMACSLOADPATH', if that exists; otherwise its - default value is specified in `emacs/src/paths.h' when XEmacs is - built. - - The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:' - (or `;', according to the operating system) separates directory - names, and `.' is used for the current default directory. Here is - an example of how to set your `EMACSLOADPATH' variable from a - `csh' `.login' file: - - setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp - - Here is how to set it using `sh': - - export EMACSLOADPATH - EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp - - Here is an example of code you can place in a `.emacs' file to add - several directories to the front of your default `load-path': - - (setq load-path - (append (list nil "/user/bil/emacs" - "/usr/local/lisplib" - "~/emacs") - load-path)) - - In this example, the path searches the current working directory - first, followed then by the `/user/bil/emacs' directory, the - `/usr/local/lisplib' directory, and the `~/emacs' directory, which - are then followed by the standard directories for Lisp code. - - The command line options `-l' or `-load' specify a Lisp library to - load as part of Emacs startup. Since this file might be in the - current directory, Emacs 18 temporarily adds the current directory - to the front of `load-path' so the file can be found there. Newer - Emacs versions also find such files in the current directory, but - without altering `load-path'. - - Dumping Emacs uses a special value of `load-path'. If the value of - `load-path' at the end of dumping is unchanged (that is, still the - same special value), the dumped Emacs switches to the ordinary - `load-path' value when it starts up, as described above. But if - `load-path' has any other value at the end of dumping, that value - is used for execution of the dumped Emacs also. - - Therefore, if you want to change `load-path' temporarily for - loading a few libraries in `site-init.el' or `site-load.el', you - should bind `load-path' locally with `let' around the calls to - `load'. - - - Function: locate-file filename path-list &optional suffixes mode - This function searches for a file in the same way that `load' does, - and returns the file found (if any). (In fact, `load' uses this - function to search through `load-path'.) It searches for FILENAME - through PATH-LIST, expanded by one of the optional SUFFIXES - (string of suffixes separated by `:'s), checking for access MODE - (0|1|2|4 = exists|executable|writable|readable), default readable. - - `locate-file' keeps hash tables of the directories it searches - through, in order to speed things up. It tries valiantly to not - get confused in the face of a changing and unpredictable - environment, but can occasionally get tripped up. In this case, - you will have to call `locate-file-clear-hashing' to get it back - on track. See that function for details. - - - Function: locate-file-clear-hashing path - This function clears the hash records for the specified list of - directories. `locate-file' uses a hashing scheme to speed lookup, - and will correctly track the following environmental changes: - - * changes of any sort to the list of directories to be searched. - - * addition and deletion of non-shadowing files (see below) from - the directories in the list. - - * byte-compilation of a .el file into a .elc file. - - `locate-file' will primarily get confused if you add a file that - shadows (i.e. has the same name as) another file further down in - the directory list. In this case, you must call - `locate-file-clear-hashing'. - - - Variable: load-in-progress - This variable is non-`nil' if Emacs is in the process of loading a - file, and it is `nil' otherwise. - - - Variable: load-read-function - This variable specifies an alternate expression-reading function - for `load' and `eval-region' to use instead of `read'. The - function should accept one argument, just as `read' does. - - Normally, the variable's value is `nil', which means those - functions should use `read'. - - - User Option: load-warn-when-source-newer - This variable specifies whether `load' should check whether the - source is newer than the binary. If this variable is true, then - when a `.elc' file is being loaded and the corresponding `.el' is - newer, a warning message will be printed. The default is `nil', - but it is bound to `t' during the initial loadup. - - - User Option: load-warn-when-source-only - This variable specifies whether `load' should warn when loading a - `.el' file instead of an `.elc'. If this variable is true, then - when `load' is called with a filename without an extension, and - the `.elc' version doesn't exist but the `.el' version does, then - a message will be printed. If an explicit extension is passed to - `load', no warning will be printed. The default is `nil', but it - is bound to `t' during the initial loadup. - - - User Option: load-ignore-elc-files - This variable specifies whether `load' should ignore `.elc' files - when a suffix is not given. This is normally used only to - bootstrap the `.elc' files when building XEmacs, when you use the - command `make all-elc'. (This forces the `.el' versions to be - loaded in the process of compiling those same files, so that - existing out-of-date `.elc' files do not make it mess things up.) - - To learn how `load' is used to build XEmacs, see *Note Building -XEmacs::. - diff --git a/info/lispref.info-12 b/info/lispref.info-12 index d4dc774..6fd3e06 100644 --- a/info/lispref.info-12 +++ b/info/lispref.info-12 @@ -50,6 +50,195 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading + +How Programs Do Loading +======================= + + XEmacs Lisp has several interfaces for loading. For example, +`autoload' creates a placeholder object for a function in a file; +trying to call the autoloading function loads the file to get the +function's real definition (*note Autoload::). `require' loads a file +if it isn't already loaded (*note Named Features::). Ultimately, all +these facilities call the `load' function to do the work. + + - Function: load filename &optional missing-ok nomessage nosuffix + This function finds and opens a file of Lisp code, evaluates all + the forms in it, and closes the file. + + To find the file, `load' first looks for a file named + `FILENAME.elc', that is, for a file whose name is FILENAME with + `.elc' appended. If such a file exists, it is loaded. If there + is no file by that name, then `load' looks for a file named + `FILENAME.el'. If that file exists, it is loaded. Finally, if + neither of those names is found, `load' looks for a file named + FILENAME with nothing appended, and loads it if it exists. (The + `load' function is not clever about looking at FILENAME. In the + perverse case of a file named `foo.el.el', evaluation of `(load + "foo.el")' will indeed find it.) + + If the optional argument NOSUFFIX is non-`nil', then the suffixes + `.elc' and `.el' are not tried. In this case, you must specify + the precise file name you want. + + If FILENAME is a relative file name, such as `foo' or + `baz/foo.bar', `load' searches for the file using the variable + `load-path'. It appends FILENAME to each of the directories + listed in `load-path', and loads the first file it finds whose name + matches. The current default directory is tried only if it is + specified in `load-path', where `nil' stands for the default + directory. `load' tries all three possible suffixes in the first + directory in `load-path', then all three suffixes in the second + directory, and so on. + + If you get a warning that `foo.elc' is older than `foo.el', it + means you should consider recompiling `foo.el'. *Note Byte + Compilation::. + + Messages like `Loading foo...' and `Loading foo...done' appear in + the echo area during loading unless NOMESSAGE is non-`nil'. + + Any unhandled errors while loading a file terminate loading. If + the load was done for the sake of `autoload', any function + definitions made during the loading are undone. + + If `load' can't find the file to load, then normally it signals the + error `file-error' (with `Cannot open load file FILENAME'). But + if MISSING-OK is non-`nil', then `load' just returns `nil'. + + You can use the variable `load-read-function' to specify a function + for `load' to use instead of `read' for reading expressions. See + below. + + `load' returns `t' if the file loads successfully. + + - User Option: load-path + The value of this variable is a list of directories to search when + loading files with `load'. Each element is a string (which must be + a directory name) or `nil' (which stands for the current working + directory). The value of `load-path' is initialized from the + environment variable `EMACSLOADPATH', if that exists; otherwise its + default value is specified in `emacs/src/paths.h' when XEmacs is + built. + + The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:' + (or `;', according to the operating system) separates directory + names, and `.' is used for the current default directory. Here is + an example of how to set your `EMACSLOADPATH' variable from a + `csh' `.login' file: + + setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp + + Here is how to set it using `sh': + + export EMACSLOADPATH + EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp + + Here is an example of code you can place in a `.emacs' file to add + several directories to the front of your default `load-path': + + (setq load-path + (append (list nil "/user/bil/emacs" + "/usr/local/lisplib" + "~/emacs") + load-path)) + + In this example, the path searches the current working directory + first, followed then by the `/user/bil/emacs' directory, the + `/usr/local/lisplib' directory, and the `~/emacs' directory, which + are then followed by the standard directories for Lisp code. + + The command line options `-l' or `-load' specify a Lisp library to + load as part of Emacs startup. Since this file might be in the + current directory, Emacs 18 temporarily adds the current directory + to the front of `load-path' so the file can be found there. Newer + Emacs versions also find such files in the current directory, but + without altering `load-path'. + + Dumping Emacs uses a special value of `load-path'. If the value of + `load-path' at the end of dumping is unchanged (that is, still the + same special value), the dumped Emacs switches to the ordinary + `load-path' value when it starts up, as described above. But if + `load-path' has any other value at the end of dumping, that value + is used for execution of the dumped Emacs also. + + Therefore, if you want to change `load-path' temporarily for + loading a few libraries in `site-init.el' or `site-load.el', you + should bind `load-path' locally with `let' around the calls to + `load'. + + - Function: locate-file filename path-list &optional suffixes mode + This function searches for a file in the same way that `load' does, + and returns the file found (if any). (In fact, `load' uses this + function to search through `load-path'.) It searches for FILENAME + through PATH-LIST, expanded by one of the optional SUFFIXES + (string of suffixes separated by `:'s), checking for access MODE + (0|1|2|4 = exists|executable|writable|readable), default readable. + + `locate-file' keeps hash tables of the directories it searches + through, in order to speed things up. It tries valiantly to not + get confused in the face of a changing and unpredictable + environment, but can occasionally get tripped up. In this case, + you will have to call `locate-file-clear-hashing' to get it back + on track. See that function for details. + + - Function: locate-file-clear-hashing path + This function clears the hash records for the specified list of + directories. `locate-file' uses a hashing scheme to speed lookup, + and will correctly track the following environmental changes: + + * changes of any sort to the list of directories to be searched. + + * addition and deletion of non-shadowing files (see below) from + the directories in the list. + + * byte-compilation of a .el file into a .elc file. + + `locate-file' will primarily get confused if you add a file that + shadows (i.e. has the same name as) another file further down in + the directory list. In this case, you must call + `locate-file-clear-hashing'. + + - Variable: load-in-progress + This variable is non-`nil' if Emacs is in the process of loading a + file, and it is `nil' otherwise. + + - Variable: load-read-function + This variable specifies an alternate expression-reading function + for `load' and `eval-region' to use instead of `read'. The + function should accept one argument, just as `read' does. + + Normally, the variable's value is `nil', which means those + functions should use `read'. + + - User Option: load-warn-when-source-newer + This variable specifies whether `load' should check whether the + source is newer than the binary. If this variable is true, then + when a `.elc' file is being loaded and the corresponding `.el' is + newer, a warning message will be printed. The default is `nil', + but it is bound to `t' during the initial loadup. + + - User Option: load-warn-when-source-only + This variable specifies whether `load' should warn when loading a + `.el' file instead of an `.elc'. If this variable is true, then + when `load' is called with a filename without an extension, and + the `.elc' version doesn't exist but the `.el' version does, then + a message will be printed. If an explicit extension is passed to + `load', no warning will be printed. The default is `nil', but it + is bound to `t' during the initial loadup. + + - User Option: load-ignore-elc-files + This variable specifies whether `load' should ignore `.elc' files + when a suffix is not given. This is normally used only to + bootstrap the `.elc' files when building XEmacs, when you use the + command `make all-elc'. (This forces the `.el' versions to be + loaded in the process of compiling those same files, so that + existing out-of-date `.elc' files do not make it mess things up.) + + To learn how `load' is used to build XEmacs, see *Note Building +XEmacs::. + + File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, Up: Loading Autoload @@ -78,11 +267,10 @@ installed along with Emacs. specifies the file to load to get the real definition of FUNCTION. The argument DOCSTRING is the documentation string for the - function. Normally, this is the identical to the documentation - string in the function definition itself. Specifying the - documentation string in the call to `autoload' makes it possible - to look at the documentation without loading the function's real - definition. + function. Normally, this is identical to the documentation string + in the function definition itself. Specifying the documentation + string in the call to `autoload' makes it possible to look at the + documentation without loading the function's real definition. If INTERACTIVE is non-`nil', then the function can be called interactively. This lets completion in `M-x' work without loading @@ -344,7 +532,7 @@ loading. and `t' is returned if it is found, `nil' otherwise. If FEXP is a number, the function returns `t' if this Emacs has an - equal or greater number than `fexp', `nil' otherwise. Note that + equal or greater number than FEXP, `nil' otherwise. Note that minor Emacs version is expected to be 2 decimal places wide, so `(featurep 20.4)' will return `nil' on XEmacs 20.4--you must write `(featurep 20.04)', unless you wish to match for XEmacs 20.40. @@ -641,14 +829,21 @@ around the `require' calls (*note Eval During Compile::). -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc - Command: byte-recompile-directory directory &optional flag + norecursion force This function recompiles every `.el' file in DIRECTORY that needs recompilation. A file needs recompilation if a `.elc' file exists but is older than the `.el' file. + Files in subdirectories of DIRECTORY are also processed unless + optional argument NORECURSION is non-`nil'. + When a `.el' file has no corresponding `.elc' file, then FLAG says what to do. If it is `nil', these files are ignored. If it is non-`nil', the user is asked whether to compile each such file. + If the fourth optional argument FORCE is non-`nil', recompile + every `.el' file that already has a `.elc' file. + The return value of this command is unpredictable. - Function: batch-byte-compile @@ -672,7 +867,7 @@ around the `require' calls (*note Eval During Compile::). normally `nil', but is bound to `t' by `batch-byte-recompile-directory'. - - Function: byte-code instructions constants stack-size + - Function: byte-code instructions constants stack-depth This function actually interprets byte-code. Don't call this function yourself. Only the byte compiler knows how to generate valid calls to this function. @@ -855,7 +1050,7 @@ CONSTANTS The vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names. -STACK-SIZE +STACK-DEPTH The maximum stack size this function needs. DOC-STRING @@ -886,7 +1081,7 @@ representation. It is the definition of the command `backward-sexp'. The primitive way to create a compiled-function object is with `make-byte-code': - - Function: make-byte-code arglist instructions constants stack-size + - Function: make-byte-code arglist instructions constants stack-depth &optional doc-string interactive This function constructs and returns a compiled-function object with the specified attributes. @@ -921,7 +1116,7 @@ a compiled-function object. This function returns the vector of Lisp objects referenced by compiled-function object FUNCTION. - - Function: compiled-function-stack-size function + - Function: compiled-function-stack-depth function This function returns the maximum stack size needed by compiled-function object FUNCTION. @@ -941,239 +1136,3 @@ a compiled-function object. FUNCTION, if any. The result will be a string or `nil'. *Note Domain Specification::. - -File: lispref.info, Node: Disassembly, Prev: Compiled-Function Objects, Up: Byte Compilation - -Disassembled Byte-Code -====================== - - People do not write byte-code; that job is left to the byte compiler. -But we provide a disassembler to satisfy a cat-like curiosity. The -disassembler converts the byte-compiled code into humanly readable form. - - The byte-code interpreter is implemented as a simple stack machine. -It pushes values onto a stack of its own, then pops them off to use them -in calculations whose results are themselves pushed back on the stack. -When a byte-code function returns, it pops a value off the stack and -returns it as the value of the function. - - In addition to the stack, byte-code functions can use, bind, and set -ordinary Lisp variables, by transferring values between variables and -the stack. - - - Command: disassemble object &optional stream - This function prints the disassembled code for OBJECT. If STREAM - is supplied, then output goes there. Otherwise, the disassembled - code is printed to the stream `standard-output'. The argument - OBJECT can be a function name or a lambda expression. - - As a special exception, if this function is used interactively, it - outputs to a buffer named `*Disassemble*'. - - Here are two examples of using the `disassemble' function. We have -added explanatory comments to help you relate the byte-code to the Lisp -source; these do not appear in the output of `disassemble'. - - (defun factorial (integer) - "Compute factorial of an integer." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) - => factorial - - (factorial 4) - => 24 - - (disassemble 'factorial) - -| byte-code for factorial: - doc: Compute factorial of an integer. - args: (integer) - - 0 varref integer ; Get value of `integer' - ; from the environment - ; and push the value - ; onto the stack. - - 1 constant 1 ; Push 1 onto stack. - - 2 eqlsign ; Pop top two values off stack, - ; compare them, - ; and push result onto stack. - - 3 goto-if-nil 1 ; Pop and test top of stack; - ; if `nil', - ; go to label 1 (which is also byte 7), - ; else continue. - - 5 constant 1 ; Push 1 onto top of stack. - - 6 return ; Return the top element - ; of the stack. - - 7:1 varref integer ; Push value of `integer' onto stack. - - 8 constant factorial ; Push `factorial' onto stack. - - 9 varref integer ; Push value of `integer' onto stack. - - 10 sub1 ; Pop `integer', decrement value, - ; push new value onto stack. - - ; Stack now contains: - ; - decremented value of `integer' - ; - `factorial' - ; - value of `integer' - - 15 call 1 ; Call function `factorial' using - ; the first (i.e., the top) element - ; of the stack as the argument; - ; push returned value onto stack. - - ; Stack now contains: - ; - result of recursive - ; call to `factorial' - ; - value of `integer' - - 12 mult ; Pop top two values off the stack, - ; multiply them, - ; pushing the result onto the stack. - - 13 return ; Return the top element - ; of the stack. - => nil - - The `silly-loop' function is somewhat more complex: - - (defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) - => silly-loop - - (disassemble 'silly-loop) - -| byte-code for silly-loop: - doc: Return time before and after N iterations of a loop. - args: (n) - - 0 constant current-time-string ; Push - ; `current-time-string' - ; onto top of stack. - - 1 call 0 ; Call `current-time-string' - ; with no argument, - ; pushing result onto stack. - - 2 varbind t1 ; Pop stack and bind `t1' - ; to popped value. - - 3:1 varref n ; Get value of `n' from - ; the environment and push - ; the value onto the stack. - - 4 sub1 ; Subtract 1 from top of stack. - - 5 dup ; Duplicate the top of the stack; - ; i.e., copy the top of - ; the stack and push the - ; copy onto the stack. - - 6 varset n ; Pop the top of the stack, - ; and set `n' to the value. - - ; In effect, the sequence `dup varset' - ; copies the top of the stack - ; into the value of `n' - ; without popping it. - - 7 constant 0 ; Push 0 onto stack. - - 8 gtr ; Pop top two values off stack, - ; test if N is greater than 0 - ; and push result onto stack. - - 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0 - ; (this exits the while loop). - ; else pop top of stack - ; and continue - - 11 varref t1 ; Push value of `t1' onto stack. - - 12 constant current-time-string ; Push - ; `current-time-string' - ; onto top of stack. - - 13 call 0 ; Call `current-time-string' again. - - 14 unbind 1 ; Unbind `t1' in local environment. - - 15 list2 ; Pop top two elements off stack, - ; create a list of them, - ; and push list onto stack. - - 16 return ; Return the top element of the stack. - - => nil - - -File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top - -Debugging Lisp Programs -*********************** - - There are three ways to investigate a problem in an XEmacs Lisp -program, depending on what you are doing with the program when the -problem appears. - - * If the problem occurs when you run the program, you can use a Lisp - debugger (either the default debugger or Edebug) to investigate - what is happening during execution. - - * If the problem is syntactic, so that Lisp cannot even read the - program, you can use the XEmacs facilities for editing Lisp to - localize it. - - * If the problem occurs when trying to compile the program with the - byte compiler, you need to know how to examine the compiler's - input buffer. - -* Menu: - -* Debugger:: How the XEmacs Lisp debugger is implemented. -* Syntax Errors:: How to find syntax errors. -* Compilation Errors:: How to find errors that show up in byte compilation. -* Edebug:: A source-level XEmacs Lisp debugger. - - Another useful debugging tool is the dribble file. When a dribble -file is open, XEmacs copies all keyboard input characters to that file. -Afterward, you can examine the file to find out what input was used. -*Note Terminal Input::. - - For debugging problems in terminal descriptions, the -`open-termscript' function can be useful. *Note Terminal Output::. - - -File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging - -The Lisp Debugger -================= - - The "Lisp debugger" provides the ability to suspend evaluation of a -form. While evaluation is suspended (a state that is commonly known as -a "break"), you may examine the run time stack, examine the values of -local or global variables, or change those values. Since a break is a -recursive edit, all the usual editing facilities of XEmacs are -available; you can even run programs that will enter the debugger -recursively. *Note Recursive Editing::. - -* Menu: - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function `debug'. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - diff --git a/info/lispref.info-13 b/info/lispref.info-13 index f3f19ee..06f3d06 100644 --- a/info/lispref.info-13 +++ b/info/lispref.info-13 @@ -50,6 +50,242 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Disassembly, Prev: Compiled-Function Objects, Up: Byte Compilation + +Disassembled Byte-Code +====================== + + People do not write byte-code; that job is left to the byte compiler. +But we provide a disassembler to satisfy a cat-like curiosity. The +disassembler converts the byte-compiled code into humanly readable form. + + The byte-code interpreter is implemented as a simple stack machine. +It pushes values onto a stack of its own, then pops them off to use them +in calculations whose results are themselves pushed back on the stack. +When a byte-code function returns, it pops a value off the stack and +returns it as the value of the function. + + In addition to the stack, byte-code functions can use, bind, and set +ordinary Lisp variables, by transferring values between variables and +the stack. + + - Command: disassemble object &optional stream + This function prints the disassembled code for OBJECT. If STREAM + is supplied, then output goes there. Otherwise, the disassembled + code is printed to the stream `standard-output'. The argument + OBJECT can be a function name or a lambda expression. + + As a special exception, if this function is used interactively, it + outputs to a buffer named `*Disassemble*'. + + Here are two examples of using the `disassemble' function. We have +added explanatory comments to help you relate the byte-code to the Lisp +source; these do not appear in the output of `disassemble'. + + (defun factorial (integer) + "Compute factorial of an integer." + (if (= 1 integer) 1 + (* integer (factorial (1- integer))))) + => factorial + + (factorial 4) + => 24 + + (disassemble 'factorial) + -| byte-code for factorial: + doc: Compute factorial of an integer. + args: (integer) + + 0 varref integer ; Get value of `integer' + ; from the environment + ; and push the value + ; onto the stack. + + 1 constant 1 ; Push 1 onto stack. + + 2 eqlsign ; Pop top two values off stack, + ; compare them, + ; and push result onto stack. + + 3 goto-if-nil 1 ; Pop and test top of stack; + ; if `nil', + ; go to label 1 (which is also byte 7), + ; else continue. + + 5 constant 1 ; Push 1 onto top of stack. + + 6 return ; Return the top element + ; of the stack. + + 7:1 varref integer ; Push value of `integer' onto stack. + + 8 constant factorial ; Push `factorial' onto stack. + + 9 varref integer ; Push value of `integer' onto stack. + + 10 sub1 ; Pop `integer', decrement value, + ; push new value onto stack. + + ; Stack now contains: + ; - decremented value of `integer' + ; - `factorial' + ; - value of `integer' + + 15 call 1 ; Call function `factorial' using + ; the first (i.e., the top) element + ; of the stack as the argument; + ; push returned value onto stack. + + ; Stack now contains: + ; - result of recursive + ; call to `factorial' + ; - value of `integer' + + 12 mult ; Pop top two values off the stack, + ; multiply them, + ; pushing the result onto the stack. + + 13 return ; Return the top element + ; of the stack. + => nil + + The `silly-loop' function is somewhat more complex: + + (defun silly-loop (n) + "Return time before and after N iterations of a loop." + (let ((t1 (current-time-string))) + (while (> (setq n (1- n)) + 0)) + (list t1 (current-time-string)))) + => silly-loop + + (disassemble 'silly-loop) + -| byte-code for silly-loop: + doc: Return time before and after N iterations of a loop. + args: (n) + + 0 constant current-time-string ; Push + ; `current-time-string' + ; onto top of stack. + + 1 call 0 ; Call `current-time-string' + ; with no argument, + ; pushing result onto stack. + + 2 varbind t1 ; Pop stack and bind `t1' + ; to popped value. + + 3:1 varref n ; Get value of `n' from + ; the environment and push + ; the value onto the stack. + + 4 sub1 ; Subtract 1 from top of stack. + + 5 dup ; Duplicate the top of the stack; + ; i.e., copy the top of + ; the stack and push the + ; copy onto the stack. + + 6 varset n ; Pop the top of the stack, + ; and set `n' to the value. + + ; In effect, the sequence `dup varset' + ; copies the top of the stack + ; into the value of `n' + ; without popping it. + + 7 constant 0 ; Push 0 onto stack. + + 8 gtr ; Pop top two values off stack, + ; test if N is greater than 0 + ; and push result onto stack. + + 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0 + ; (this exits the while loop). + ; else pop top of stack + ; and continue + + 11 varref t1 ; Push value of `t1' onto stack. + + 12 constant current-time-string ; Push + ; `current-time-string' + ; onto top of stack. + + 13 call 0 ; Call `current-time-string' again. + + 14 unbind 1 ; Unbind `t1' in local environment. + + 15 list2 ; Pop top two elements off stack, + ; create a list of them, + ; and push list onto stack. + + 16 return ; Return the top element of the stack. + + => nil + + +File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top + +Debugging Lisp Programs +*********************** + + There are three ways to investigate a problem in an XEmacs Lisp +program, depending on what you are doing with the program when the +problem appears. + + * If the problem occurs when you run the program, you can use a Lisp + debugger (either the default debugger or Edebug) to investigate + what is happening during execution. + + * If the problem is syntactic, so that Lisp cannot even read the + program, you can use the XEmacs facilities for editing Lisp to + localize it. + + * If the problem occurs when trying to compile the program with the + byte compiler, you need to know how to examine the compiler's + input buffer. + +* Menu: + +* Debugger:: How the XEmacs Lisp debugger is implemented. +* Syntax Errors:: How to find syntax errors. +* Compilation Errors:: How to find errors that show up in byte compilation. +* Edebug:: A source-level XEmacs Lisp debugger. + + Another useful debugging tool is the dribble file. When a dribble +file is open, XEmacs copies all keyboard input characters to that file. +Afterward, you can examine the file to find out what input was used. +*Note Terminal Input::. + + For debugging problems in terminal descriptions, the +`open-termscript' function can be useful. *Note Terminal Output::. + + +File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging + +The Lisp Debugger +================= + + The "Lisp debugger" provides the ability to suspend evaluation of a +form. While evaluation is suspended (a state that is commonly known as +a "break"), you may examine the run time stack, examine the values of +local or global variables, or change those values. Since a break is a +recursive edit, all the usual editing facilities of XEmacs are +available; you can even run programs that will enter the debugger +recursively. *Note Recursive Editing::. + +* Menu: + +* Error Debugging:: Entering the debugger when an error happens. +* Infinite Loops:: Stopping and debugging a program that doesn't exit. +* Function Debugging:: Entering it when a certain function is called. +* Explicit Debug:: Entering it at a certain point in the program. +* Using Debugger:: What the debugger does; what you see while in it. +* Debugger Commands:: Commands used while in the debugger. +* Invoking the Debugger:: How to call the function `debug'. +* Internals of Debugger:: Subroutines of the debugger, and global variables. + + File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger Entering the Debugger on an Error @@ -197,7 +433,7 @@ function, and then step through its caller. (debug (quote debug)) (if (zerop n) 1 (* n (fact (1- n))))) - - Command: cancel-debug-on-entry function-name + - Command: cancel-debug-on-entry &optional function-name This function undoes the effect of `debug-on-entry' on FUNCTION-NAME. When called interactively, it prompts for FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the @@ -962,221 +1198,3 @@ keyboard macro outside of Edebug does not affect the command loop inside Edebug. This is usually an advantage. But see `edebug-continue-kbd-macro'. - -File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug - -Jumping -------- - - Commands described here let you jump to a specified location. All, -except `i', use temporary breakpoints to establish the stop point and -then switch to `go' mode. Any other breakpoint reached before the -intended stop point will also stop execution. See *Note Breakpoints:: -for the details on breakpoints. - -`f' - Run the program forward over one expression - (`edebug-forward-sexp'). More precisely, set a temporary - breakpoint at the position that `C-M-f' would reach, then execute - in `go' mode so that the program will stop at breakpoints. - - With a prefix argument N, the temporary breakpoint is placed N - sexps beyond point. If the containing list ends before N more - elements, then the place to stop is after the containing - expression. - - Be careful that the position `C-M-f' finds is a place that the - program will really get to; this may not be true in a `cond', for - example. - - This command does `forward-sexp' starting at point rather than the - stop point. If you want to execute one expression from the - current stop point, type `w' first, to move point there. - -`o' - Continue "out of" an expression (`edebug-step-out'). It places a - temporary breakpoint at the end of the sexp containing point. - - If the containing sexp is a function definition itself, it - continues until just before the last sexp in the definition. If - that is where you are now, it returns from the function and then - stops. In other words, this command does not exit the currently - executing function unless you are positioned after the last sexp. - -`I' - Step into the function or macro after point after first ensuring - that it is instrumented. It does this by calling - `edebug-on-entry' and then switching to `go' mode. - - Although the automatic instrumentation is convenient, it is not - later automatically uninstrumented. - -`h' - Proceed to the stop point near where point is using a temporary - breakpoint (`edebug-goto-here'). - - All the commands in this section may fail to work as expected in case -of nonlocal exit, because a nonlocal exit can bypass the temporary -breakpoint where you expected the program to stop. - - -File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug - -Miscellaneous -------------- - - Some miscellaneous commands are described here. - -`?' - Display the help message for Edebug (`edebug-help'). - -`C-]' - Abort one level back to the previous command level - (`abort-recursive-edit'). - -`q' - Return to the top level editor command loop (`top-level'). This - exits all recursive editing levels, including all levels of Edebug - activity. However, instrumented code protected with - `unwind-protect' or `condition-case' forms may resume debugging. - -`Q' - Like `q' but don't stop even for protected code - (`top-level-nonstop'). - -`r' - Redisplay the most recently known expression result in the echo - area (`edebug-previous-result'). - -`d' - Display a backtrace, excluding Edebug's own functions for clarity - (`edebug-backtrace'). - - You cannot use debugger commands in the backtrace buffer in Edebug - as you would in the standard debugger. - - The backtrace buffer is killed automatically when you continue - execution. - - From the Edebug recursive edit, you may invoke commands that activate -Edebug again recursively. Any time Edebug is active, you can quit to -the top level with `q' or abort one recursive edit level with `C-]'. -You can display a backtrace of all the pending evaluations with `d'. - - -File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug - -Breakpoints ------------ - - There are three more ways to stop execution once it has started: -breakpoints, the global break condition, and embedded breakpoints. - - While using Edebug, you can specify "breakpoints" in the program you -are testing: points where execution should stop. You can set a -breakpoint at any stop point, as defined in *Note Using Edebug::. For -setting and unsetting breakpoints, the stop point that is affected is -the first one at or after point in the source code buffer. Here are the -Edebug commands for breakpoints: - -`b' - Set a breakpoint at the stop point at or after point - (`edebug-set-breakpoint'). If you use a prefix argument, the - breakpoint is temporary (it turns off the first time it stops the - program). - -`u' - Unset the breakpoint (if any) at the stop point at or after the - current point (`edebug-unset-breakpoint'). - -`x CONDITION ' - Set a conditional breakpoint which stops the program only if - CONDITION evaluates to a non-`nil' value - (`edebug-set-conditional-breakpoint'). If you use a prefix - argument, the breakpoint is temporary (it turns off the first time - it stops the program). - -`B' - Move point to the next breakpoint in the definition - (`edebug-next-breakpoint'). - - While in Edebug, you can set a breakpoint with `b' and unset one -with `u'. First you must move point to a position at or before the -desired Edebug stop point, then hit the key to change the breakpoint. -Unsetting a breakpoint that has not been set does nothing. - - Reevaluating or reinstrumenting a definition clears all its -breakpoints. - - A "conditional breakpoint" tests a condition each time the program -gets there. To set a conditional breakpoint, use `x', and specify the -condition expression in the minibuffer. Setting a conditional -breakpoint at a stop point that already has a conditional breakpoint -puts the current condition expression in the minibuffer so you can edit -it. - - You can make both conditional and unconditional breakpoints -"temporary" by using a prefix arg to the command to set the breakpoint. -After breaking at a temporary breakpoint, it is automatically cleared. - - Edebug always stops or pauses at a breakpoint except when the Edebug -mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely. - - To find out where your breakpoints are, use `B', which moves point -to the next breakpoint in the definition following point, or to the -first breakpoint if there are no following breakpoints. This command -does not continue execution--it just moves point in the buffer. - -* Menu: - -* Global Break Condition:: Breaking on an event. -* Embedded Breakpoints:: Embedding breakpoints in code. - - -File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints - -Global Break Condition -...................... - - In contrast to breaking when execution reaches specified locations, -you can also cause a break when a certain event occurs. The "global -break condition" is a condition that is repeatedly evaluated at every -stop point. If it evaluates to a non-`nil' value, then execution is -stopped or paused depending on the execution mode, just like a -breakpoint. Any errors that might occur as a result of evaluating the -condition are ignored, as if the result were `nil'. - - You can set or edit the condition expression, stored in -`edebug-global-break-condition', using `X' -(`edebug-set-global-break-condition'). - - Using the global break condition is perhaps the fastest way to find -where in your code some event occurs, but since it is rather expensive -you should reset the condition to `nil' when not in use. - - -File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints - -Embedded Breakpoints -.................... - - Since all breakpoints in a definition are cleared each time you -reinstrument it, you might rather create an "embedded breakpoint" which -is simply a call to the function `edebug'. You can, of course, make -such a call conditional. For example, in the `fac' function, insert -the first line as shown below to stop when the argument reaches zero: - - (defun fac (n) - (if (= n 0) (edebug)) - (if (< 0 n) - (* n (fac (1- n))) - 1)) - - When the `fac' definition is instrumented and the function is -called, Edebug will stop before the call to `edebug'. Depending on the -execution mode, Edebug will stop or pause. - - However, if no instrumented code is being executed, calling `edebug' -will instead invoke `debug'. Calling `debug' will always invoke the -standard backtrace debugger. - diff --git a/info/lispref.info-14 b/info/lispref.info-14 index 489d392..bd55715 100644 --- a/info/lispref.info-14 +++ b/info/lispref.info-14 @@ -50,6 +50,224 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug + +Jumping +------- + + Commands described here let you jump to a specified location. All, +except `i', use temporary breakpoints to establish the stop point and +then switch to `go' mode. Any other breakpoint reached before the +intended stop point will also stop execution. See *Note Breakpoints:: +for the details on breakpoints. + +`f' + Run the program forward over one expression + (`edebug-forward-sexp'). More precisely, set a temporary + breakpoint at the position that `C-M-f' would reach, then execute + in `go' mode so that the program will stop at breakpoints. + + With a prefix argument N, the temporary breakpoint is placed N + sexps beyond point. If the containing list ends before N more + elements, then the place to stop is after the containing + expression. + + Be careful that the position `C-M-f' finds is a place that the + program will really get to; this may not be true in a `cond', for + example. + + This command does `forward-sexp' starting at point rather than the + stop point. If you want to execute one expression from the + current stop point, type `w' first, to move point there. + +`o' + Continue "out of" an expression (`edebug-step-out'). It places a + temporary breakpoint at the end of the sexp containing point. + + If the containing sexp is a function definition itself, it + continues until just before the last sexp in the definition. If + that is where you are now, it returns from the function and then + stops. In other words, this command does not exit the currently + executing function unless you are positioned after the last sexp. + +`I' + Step into the function or macro after point after first ensuring + that it is instrumented. It does this by calling + `edebug-on-entry' and then switching to `go' mode. + + Although the automatic instrumentation is convenient, it is not + later automatically uninstrumented. + +`h' + Proceed to the stop point near where point is using a temporary + breakpoint (`edebug-goto-here'). + + All the commands in this section may fail to work as expected in case +of nonlocal exit, because a nonlocal exit can bypass the temporary +breakpoint where you expected the program to stop. + + +File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug + +Miscellaneous +------------- + + Some miscellaneous commands are described here. + +`?' + Display the help message for Edebug (`edebug-help'). + +`C-]' + Abort one level back to the previous command level + (`abort-recursive-edit'). + +`q' + Return to the top level editor command loop (`top-level'). This + exits all recursive editing levels, including all levels of Edebug + activity. However, instrumented code protected with + `unwind-protect' or `condition-case' forms may resume debugging. + +`Q' + Like `q' but don't stop even for protected code + (`top-level-nonstop'). + +`r' + Redisplay the most recently known expression result in the echo + area (`edebug-previous-result'). + +`d' + Display a backtrace, excluding Edebug's own functions for clarity + (`edebug-backtrace'). + + You cannot use debugger commands in the backtrace buffer in Edebug + as you would in the standard debugger. + + The backtrace buffer is killed automatically when you continue + execution. + + From the Edebug recursive edit, you may invoke commands that activate +Edebug again recursively. Any time Edebug is active, you can quit to +the top level with `q' or abort one recursive edit level with `C-]'. +You can display a backtrace of all the pending evaluations with `d'. + + +File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug + +Breakpoints +----------- + + There are three more ways to stop execution once it has started: +breakpoints, the global break condition, and embedded breakpoints. + + While using Edebug, you can specify "breakpoints" in the program you +are testing: points where execution should stop. You can set a +breakpoint at any stop point, as defined in *Note Using Edebug::. For +setting and unsetting breakpoints, the stop point that is affected is +the first one at or after point in the source code buffer. Here are the +Edebug commands for breakpoints: + +`b' + Set a breakpoint at the stop point at or after point + (`edebug-set-breakpoint'). If you use a prefix argument, the + breakpoint is temporary (it turns off the first time it stops the + program). + +`u' + Unset the breakpoint (if any) at the stop point at or after the + current point (`edebug-unset-breakpoint'). + +`x CONDITION ' + Set a conditional breakpoint which stops the program only if + CONDITION evaluates to a non-`nil' value + (`edebug-set-conditional-breakpoint'). If you use a prefix + argument, the breakpoint is temporary (it turns off the first time + it stops the program). + +`B' + Move point to the next breakpoint in the definition + (`edebug-next-breakpoint'). + + While in Edebug, you can set a breakpoint with `b' and unset one +with `u'. First you must move point to a position at or before the +desired Edebug stop point, then hit the key to change the breakpoint. +Unsetting a breakpoint that has not been set does nothing. + + Reevaluating or reinstrumenting a definition clears all its +breakpoints. + + A "conditional breakpoint" tests a condition each time the program +gets there. To set a conditional breakpoint, use `x', and specify the +condition expression in the minibuffer. Setting a conditional +breakpoint at a stop point that already has a conditional breakpoint +puts the current condition expression in the minibuffer so you can edit +it. + + You can make both conditional and unconditional breakpoints +"temporary" by using a prefix arg to the command to set the breakpoint. +After breaking at a temporary breakpoint, it is automatically cleared. + + Edebug always stops or pauses at a breakpoint except when the Edebug +mode is `Go-nonstop'. In that mode, it ignores breakpoints entirely. + + To find out where your breakpoints are, use `B', which moves point +to the next breakpoint in the definition following point, or to the +first breakpoint if there are no following breakpoints. This command +does not continue execution--it just moves point in the buffer. + +* Menu: + +* Global Break Condition:: Breaking on an event. +* Embedded Breakpoints:: Embedding breakpoints in code. + + +File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints + +Global Break Condition +...................... + + In contrast to breaking when execution reaches specified locations, +you can also cause a break when a certain event occurs. The "global +break condition" is a condition that is repeatedly evaluated at every +stop point. If it evaluates to a non-`nil' value, then execution is +stopped or paused depending on the execution mode, just like a +breakpoint. Any errors that might occur as a result of evaluating the +condition are ignored, as if the result were `nil'. + + You can set or edit the condition expression, stored in +`edebug-global-break-condition', using `X' +(`edebug-set-global-break-condition'). + + Using the global break condition is perhaps the fastest way to find +where in your code some event occurs, but since it is rather expensive +you should reset the condition to `nil' when not in use. + + +File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints + +Embedded Breakpoints +.................... + + Since all breakpoints in a definition are cleared each time you +reinstrument it, you might rather create an "embedded breakpoint" which +is simply a call to the function `edebug'. You can, of course, make +such a call conditional. For example, in the `fac' function, insert +the first line as shown below to stop when the argument reaches zero: + + (defun fac (n) + (if (= n 0) (edebug)) + (if (< 0 n) + (* n (fac (1- n))) + 1)) + + When the `fac' definition is instrumented and the function is +called, Edebug will stop before the call to `edebug'. Depending on the +execution mode, Edebug will stop or pause. + + However, if no instrumented code is being executed, calling `edebug' +will instead invoke `debug'. Calling `debug' will always invoke the +standard backtrace debugger. + + File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug Trapping Errors @@ -325,7 +543,7 @@ called _tracing_ (see *Note Edebug Execution Modes::), Edebug can produce a traditional trace listing of execution in a separate buffer, `*edebug-trace*'. - If the variable `edebug-trace' is non-nil, each function entry and + If the variable `edebug-trace' is non-`nil', each function entry and exit adds lines to the trace buffer. On function entry, Edebug prints `::::{' followed by the function name and argument values. On function exit, Edebug prints `::::}' followed by the function name and result of @@ -987,194 +1205,3 @@ causes very deep recursion that could fail.) (vector &rest backquote-form) sexp)) - -File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug - -Edebug Options --------------- - - These options affect the behavior of Edebug: - - - User Option: edebug-setup-hook - Functions to call before Edebug is used. Each time it is set to a - new value, Edebug will call those functions once and then - `edebug-setup-hook' is reset to `nil'. You could use this to load - up Edebug specifications associated with a package you are using - but only when you also use Edebug. See *Note Instrumenting::. - - - User Option: edebug-all-defs - If non-`nil', normal evaluation of any defining forms (e.g. - `defun' and `defmacro') will instrument them for Edebug. This - applies to `eval-defun', `eval-region', and `eval-current-buffer'. - - Use the command `M-x edebug-all-defs' to toggle the value of this - variable. You may want to make this variable local to each buffer - by calling `(make-local-variable 'edebug-all-defs)' in your - `emacs-lisp-mode-hook'. See *Note Instrumenting::. - - - User Option: edebug-all-forms - If non-`nil', normal evaluation of any forms by `eval-defun', - `eval-region', and `eval-current-buffer' will instrument them for - Edebug. - - Use the command `M-x edebug-all-forms' to toggle the value of this - option. See *Note Instrumenting::. - - - User Option: edebug-save-windows - If non-`nil', save and restore window configuration on Edebug - calls. It takes some time to do this, so if your program does not - care what happens to data about windows, you may want to set this - variable to `nil'. - - If the value is a list, only the listed windows are saved and - restored. - - `M-x edebug-toggle-save-windows' may be used to change this - variable. This command is bound to `W' in source code buffers. - See *Note Edebug Display Update::. - - - User Option: edebug-save-displayed-buffer-points - If non-`nil', save and restore point in all displayed buffers. - This is necessary if you are debugging code that changes the point - of a buffer which is displayed in a non-selected window. If - Edebug or the user then selects the window, the buffer's point - will be changed to the window's point. - - This is an expensive operation since it visits each window and - therefore each displayed buffer twice for each Edebug activation, - so it is best to avoid it if you can. See *Note Edebug Display - Update::. - - - User Option: edebug-initial-mode - If this variable is non-`nil', it specifies the initial execution - mode for Edebug when it is first activated. Possible values are - `step', `next', `go', `Go-nonstop', `trace', `Trace-fast', - `continue', and `Continue-fast'. - - The default value is `step'. See *Note Edebug Execution Modes::. - - - User Option: edebug-trace - Non-`nil' means display a trace of function entry and exit. - Tracing output is displayed in a buffer named `*edebug-trace*', one - function entry or exit per line, indented by the recursion level. - - The default value is `nil'. - - Also see `edebug-tracing'. See *Note Tracing::. - - - User Option: edebug-test-coverage - If non-`nil', Edebug tests coverage of all expressions debugged. - This is done by comparing the result of each expression with the - previous result. Coverage is considered OK if two different - results are found. So to sufficiently test the coverage of your - code, try to execute it under conditions that evaluate all - expressions more than once, and produce different results for each - expression. - - Use `M-x edebug-display-freq-count' to display the frequency count - and coverage information for a definition. See *Note Coverage - Testing::. - - - User Option: edebug-continue-kbd-macro - If non-`nil', continue defining or executing any keyboard macro - that is executing outside of Edebug. Use this with caution since - it is not debugged. See *Note Edebug Execution Modes::. - - - User Option: edebug-print-length - If non-`nil', bind `print-length' to this while printing results - in Edebug. The default value is `50'. See *Note Printing in - Edebug::. - - - User Option: edebug-print-level - If non-`nil', bind `print-level' to this while printing results in - Edebug. The default value is `50'. - - - User Option: edebug-print-circle - If non-`nil', bind `print-circle' to this while printing results - in Edebug. The default value is `nil'. - - - User Option: edebug-on-error - `debug-on-error' is bound to this while Edebug is active. See - *Note Trapping Errors::. - - - User Option: edebug-on-quit - `debug-on-quit' is bound to this while Edebug is active. See - *Note Trapping Errors::. - - - User Option: edebug-unwrap-results - Non-`nil' if Edebug should unwrap results of expressions. This is - useful when debugging macros where the results of expressions are - instrumented expressions. But don't do this when results might be - circular or an infinite loop will result. See *Note Debugging - Backquote::. - - - User Option: edebug-global-break-condition - If non-`nil', an expression to test for at every stop point. If - the result is non-nil, then break. Errors are ignored. See *Note - Global Break Condition::. - - -File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top - -Reading and Printing Lisp Objects -********************************* - - "Printing" and "reading" are the operations of converting Lisp -objects to textual form and vice versa. They use the printed -representations and read syntax described in *Note Lisp Data Types::. - - This chapter describes the Lisp functions for reading and printing. -It also describes "streams", which specify where to get the text (if -reading) or where to put it (if printing). - -* Menu: - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing functions do. - - -File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print - -Introduction to Reading and Printing -==================================== - - "Reading" a Lisp object means parsing a Lisp expression in textual -form and producing a corresponding Lisp object. This is how Lisp -programs get into Lisp from files of Lisp code. We call the text the -"read syntax" of the object. For example, the text `(a . 5)' is the -read syntax for a cons cell whose CAR is `a' and whose CDR is the -number 5. - - "Printing" a Lisp object means producing text that represents that -object--converting the object to its printed representation. Printing -the cons cell described above produces the text `(a . 5)'. - - Reading and printing are more or less inverse operations: printing -the object that results from reading a given piece of text often -produces the same text, and reading the text that results from printing -an object usually produces a similar-looking object. For example, -printing the symbol `foo' produces the text `foo', and reading that text -returns the symbol `foo'. Printing a list whose elements are `a' and -`b' produces the text `(a b)', and reading that text produces a list -(but not the same list) with elements `a' and `b'. - - However, these two operations are not precisely inverses. There are -three kinds of exceptions: - - * Printing can produce text that cannot be read. For example, - buffers, windows, frames, subprocesses and markers print into text - that starts with `#'; if you try to read this text, you get an - error. There is no way to read those data types. - - * One object can have multiple textual representations. For example, - `1' and `01' represent the same integer, and `(a b)' and `(a . - (b))' represent the same list. Reading will accept any of the - alternatives, but printing must choose one of them. - - * Comments can appear at certain points in the middle of an object's - read sequence without affecting the result of reading it. - diff --git a/info/lispref.info-15 b/info/lispref.info-15 index 9818e56..8e2a635 100644 --- a/info/lispref.info-15 +++ b/info/lispref.info-15 @@ -50,6 +50,197 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug + +Edebug Options +-------------- + + These options affect the behavior of Edebug: + + - User Option: edebug-setup-hook + Functions to call before Edebug is used. Each time it is set to a + new value, Edebug will call those functions once and then + `edebug-setup-hook' is reset to `nil'. You could use this to load + up Edebug specifications associated with a package you are using + but only when you also use Edebug. See *Note Instrumenting::. + + - User Option: edebug-all-defs + If non-`nil', normal evaluation of any defining forms (e.g. + `defun' and `defmacro') will instrument them for Edebug. This + applies to `eval-defun', `eval-region', and `eval-current-buffer'. + + Use the command `M-x edebug-all-defs' to toggle the value of this + variable. You may want to make this variable local to each buffer + by calling `(make-local-variable 'edebug-all-defs)' in your + `emacs-lisp-mode-hook'. See *Note Instrumenting::. + + - User Option: edebug-all-forms + If non-`nil', normal evaluation of any forms by `eval-defun', + `eval-region', and `eval-current-buffer' will instrument them for + Edebug. + + Use the command `M-x edebug-all-forms' to toggle the value of this + option. See *Note Instrumenting::. + + - User Option: edebug-save-windows + If non-`nil', save and restore window configuration on Edebug + calls. It takes some time to do this, so if your program does not + care what happens to data about windows, you may want to set this + variable to `nil'. + + If the value is a list, only the listed windows are saved and + restored. + + `M-x edebug-toggle-save-windows' may be used to change this + variable. This command is bound to `W' in source code buffers. + See *Note Edebug Display Update::. + + - User Option: edebug-save-displayed-buffer-points + If non-`nil', save and restore point in all displayed buffers. + This is necessary if you are debugging code that changes the point + of a buffer which is displayed in a non-selected window. If + Edebug or the user then selects the window, the buffer's point + will be changed to the window's point. + + This is an expensive operation since it visits each window and + therefore each displayed buffer twice for each Edebug activation, + so it is best to avoid it if you can. See *Note Edebug Display + Update::. + + - User Option: edebug-initial-mode + If this variable is non-`nil', it specifies the initial execution + mode for Edebug when it is first activated. Possible values are + `step', `next', `go', `Go-nonstop', `trace', `Trace-fast', + `continue', and `Continue-fast'. + + The default value is `step'. See *Note Edebug Execution Modes::. + + - User Option: edebug-trace + Non-`nil' means display a trace of function entry and exit. + Tracing output is displayed in a buffer named `*edebug-trace*', one + function entry or exit per line, indented by the recursion level. + + The default value is `nil'. + + Also see `edebug-tracing'. See *Note Tracing::. + + - User Option: edebug-test-coverage + If non-`nil', Edebug tests coverage of all expressions debugged. + This is done by comparing the result of each expression with the + previous result. Coverage is considered OK if two different + results are found. So to sufficiently test the coverage of your + code, try to execute it under conditions that evaluate all + expressions more than once, and produce different results for each + expression. + + Use `M-x edebug-display-freq-count' to display the frequency count + and coverage information for a definition. See *Note Coverage + Testing::. + + - User Option: edebug-continue-kbd-macro + If non-`nil', continue defining or executing any keyboard macro + that is executing outside of Edebug. Use this with caution since + it is not debugged. See *Note Edebug Execution Modes::. + + - User Option: edebug-print-length + If non-`nil', bind `print-length' to this while printing results + in Edebug. The default value is `50'. See *Note Printing in + Edebug::. + + - User Option: edebug-print-level + If non-`nil', bind `print-level' to this while printing results in + Edebug. The default value is `50'. + + - User Option: edebug-print-circle + If non-`nil', bind `print-circle' to this while printing results + in Edebug. The default value is `nil'. + + - User Option: edebug-on-error + `debug-on-error' is bound to this while Edebug is active. See + *Note Trapping Errors::. + + - User Option: edebug-on-quit + `debug-on-quit' is bound to this while Edebug is active. See + *Note Trapping Errors::. + + - User Option: edebug-unwrap-results + Non-`nil' if Edebug should unwrap results of expressions. This is + useful when debugging macros where the results of expressions are + instrumented expressions. But don't do this when results might be + circular or an infinite loop will result. See *Note Debugging + Backquote::. + + - User Option: edebug-global-break-condition + If non-`nil', an expression to test for at every stop point. If + the result is non-`nil', then break. Errors are ignored. See + *Note Global Break Condition::. + + +File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top + +Reading and Printing Lisp Objects +********************************* + + "Printing" and "reading" are the operations of converting Lisp +objects to textual form and vice versa. They use the printed +representations and read syntax described in *Note Lisp Data Types::. + + This chapter describes the Lisp functions for reading and printing. +It also describes "streams", which specify where to get the text (if +reading) or where to put it (if printing). + +* Menu: + +* Streams Intro:: Overview of streams, reading and printing. +* Input Streams:: Various data types that can be used as input streams. +* Input Functions:: Functions to read Lisp objects from text. +* Output Streams:: Various data types that can be used as output streams. +* Output Functions:: Functions to print Lisp objects as text. +* Output Variables:: Variables that control what the printing functions do. + + +File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print + +Introduction to Reading and Printing +==================================== + + "Reading" a Lisp object means parsing a Lisp expression in textual +form and producing a corresponding Lisp object. This is how Lisp +programs get into Lisp from files of Lisp code. We call the text the +"read syntax" of the object. For example, the text `(a . 5)' is the +read syntax for a cons cell whose CAR is `a' and whose CDR is the +number 5. + + "Printing" a Lisp object means producing text that represents that +object--converting the object to its printed representation. Printing +the cons cell described above produces the text `(a . 5)'. + + Reading and printing are more or less inverse operations: printing +the object that results from reading a given piece of text often +produces the same text, and reading the text that results from printing +an object usually produces a similar-looking object. For example, +printing the symbol `foo' produces the text `foo', and reading that text +returns the symbol `foo'. Printing a list whose elements are `a' and +`b' produces the text `(a b)', and reading that text produces a list +(but not the same list) with elements `a' and `b'. + + However, these two operations are not precisely inverses. There are +three kinds of exceptions: + + * Printing can produce text that cannot be read. For example, + buffers, windows, frames, subprocesses and markers print into text + that starts with `#'; if you try to read this text, you get an + error. There is no way to read those data types. + + * One object can have multiple textual representations. For example, + `1' and `01' represent the same integer, and `(a b)' and `(a . + (b))' represent the same list. Reading will accept any of the + alternatives, but printing must choose one of them. + + * Comments can appear at certain points in the middle of an object's + read sequence without affecting the result of reading it. + + File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print Input Streams @@ -581,7 +772,7 @@ Variables Affecting Output following the decimal point. With `f', a precision of 0 means to omit the decimal point. 0 is not allowed with `f' or `g'. - A value of nil means to use `%.16g'. + A value of `nil' means to use `%.16g'. Regardless of the value of `float-output-format', a floating point number will never be printed in such a way that it is ambiguous @@ -740,10 +931,10 @@ Defining Commands::. 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 + The optional argument HISTORY, if non-`nil', specifies a history 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. + argument DEFAULT-VALUE 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: @@ -793,7 +984,7 @@ minibuffer. 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 + 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. @@ -832,7 +1023,7 @@ 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 + 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. @@ -844,10 +1035,10 @@ minibuffer. == (eval (read-expression PROMPT INITIAL)) - - Function: edit-and-eval-command prompt command &optional history + - Function: edit-and-eval-command prompt form &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 COMMAND is not optional + `eval-minibuffer' is that here the initial FORM 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 (`"') @@ -993,199 +1184,3 @@ certain kinds of names with completion. * Reading File Names:: Using completion to read file names. * Programmed Completion:: Finding the completions for a given file name. - -File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion - -Basic Completion Functions --------------------------- - - The two functions `try-completion' and `all-completions' have -nothing in themselves to do with minibuffers. We describe them in this -chapter so as to keep them near the higher-level completion features -that do use the minibuffer. - - - Function: try-completion string collection &optional predicate - This function returns the longest common substring of all possible - completions of STRING in COLLECTION. The value of COLLECTION must - be an alist, an obarray, or a function that implements a virtual - set of strings (see below). - - Completion compares STRING against each of the permissible - completions specified by COLLECTION; if the beginning of the - permissible completion equals STRING, it matches. If no - permissible completions match, `try-completion' returns `nil'. If - only one permissible completion matches, and the match is exact, - then `try-completion' returns `t'. Otherwise, the value is the - longest initial sequence common to all the permissible completions - that match. - - If COLLECTION is an alist (*note Association Lists::), the CARs of - the alist elements form the set of permissible completions. - - If COLLECTION is an obarray (*note Creating Symbols::), the names - of all symbols in the obarray form the set of permissible - completions. The global variable `obarray' holds an obarray - containing the names of all interned Lisp symbols. - - Note that the only valid way to make a new obarray is to create it - empty and then add symbols to it one by one using `intern'. Also, - you cannot intern a given symbol in more than one obarray. - - If the argument PREDICATE is non-`nil', then it must be a function - of one argument. It is used to test each possible match, and the - match is accepted only if PREDICATE returns non-`nil'. The - argument given to PREDICATE is either a cons cell from the alist - (the CAR of which is a string) or else it is a symbol (_not_ a - symbol name) from the obarray. - - You can also use a symbol that is a function as COLLECTION. Then - the function is solely responsible for performing completion; - `try-completion' returns whatever this function returns. The - function is called with three arguments: STRING, PREDICATE and - `nil'. (The reason for the third argument is so that the same - function can be used in `all-completions' and do the appropriate - thing in either case.) *Note Programmed Completion::. - - In the first of the following examples, the string `foo' is - matched by three of the alist CARs. All of the matches begin with - the characters `fooba', so that is the result. In the second - example, there is only one possible match, and it is exact, so the - value is `t'. - - (try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) - => "fooba" - - (try-completion "foo" '(("barfoo" 2) ("foo" 3))) - => t - - In the following example, numerous symbols begin with the - characters `forw', and all of them begin with the word `forward'. - In most of the symbols, this is followed with a `-', but not in - all, so no more than `forward' can be completed. - - (try-completion "forw" obarray) - => "forward" - - Finally, in the following example, only two of the three possible - matches pass the predicate `test' (the string `foobaz' is too - short). Both of those begin with the string `foobar'. - - (defun test (s) - (> (length (car s)) 6)) - => test - (try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - => "foobar" - - - Function: all-completions string collection &optional predicate - nospace - This function returns a list of all possible completions of - STRING. The arguments to this function are the same as those of - `try-completion'. - - If COLLECTION is a function, it is called with three arguments: - STRING, PREDICATE and `t'; then `all-completions' returns whatever - the function returns. *Note Programmed Completion::. - - If NOSPACE is non-`nil', completions that start with a space are - ignored unless STRING also starts with a space. - - Here is an example, using the function `test' shown in the example - for `try-completion': - - (defun test (s) - (> (length (car s)) 6)) - => test - - (all-completions - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - => ("foobar1" "foobar2") - - - Variable: completion-ignore-case - If the value of this variable is non-`nil', XEmacs does not - consider case significant in completion. - - -File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion - -Completion and the Minibuffer ------------------------------ - - This section describes the basic interface for reading from the -minibuffer with completion. - - - Function: completing-read prompt collection &optional predicate - require-match initial hist default - This function reads a string in the minibuffer, assisting the user - by providing completion. It activates the minibuffer with prompt - PROMPT, which must be a string. If INITIAL is non-`nil', - `completing-read' inserts it into the minibuffer as part of the - input. Then it allows the user to edit the input, providing - several commands to attempt completion. - - The actual completion is done by passing COLLECTION and PREDICATE - to the function `try-completion'. This happens in certain - commands bound in the local keymaps used for completion. - - If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't - exit unless the input completes to an element of COLLECTION. If - REQUIRE-MATCH is neither `nil' nor `t', then the exit commands - won't exit unless the input typed is itself an element of - COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work - regardless of the input in the minibuffer. - - However, empty input is always permitted, regardless of the value - of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT. - The value of DEFAULT (if non-`nil') is also available to the user - through the history commands. - - The user can exit with null input by typing with an empty - minibuffer. Then `completing-read' returns `""'. This is how the - user requests whatever default the command uses for the value being - read. The user can return using in this way regardless of - the value of REQUIRE-MATCH, and regardless of whether the empty - string is included in COLLECTION. - - 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::. - - The argument HIST specifies which history list variable to use for - saving the input and for minibuffer history commands. It defaults - to `minibuffer-history'. *Note Minibuffer History::. - - Completion ignores case when comparing the input against the - possible matches, if the built-in variable - `completion-ignore-case' is non-`nil'. *Note Basic Completion::. - - Here's an example of using `completing-read': - - (completing-read - "Complete a foo: " - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - nil t "fo") - - ;; After evaluation of the preceding expression, - ;; the following appears in the minibuffer: - - ---------- Buffer: Minibuffer ---------- - Complete a foo: fo-!- - ---------- Buffer: Minibuffer ---------- - - If the user then types ` b ', `completing-read' - returns `barfoo'. - - The `completing-read' function binds three variables to pass - information to the commands that actually do completion. These - variables are `minibuffer-completion-table', - `minibuffer-completion-predicate' and - `minibuffer-completion-confirm'. For more information about them, - see *Note Completion Commands::. - diff --git a/info/lispref.info-16 b/info/lispref.info-16 index 5e63304..f7987c8 100644 --- a/info/lispref.info-16 +++ b/info/lispref.info-16 @@ -50,6 +50,198 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion + +Basic Completion Functions +-------------------------- + + The two functions `try-completion' and `all-completions' have +nothing in themselves to do with minibuffers. We describe them in this +chapter so as to keep them near the higher-level completion features +that do use the minibuffer. + + - Function: try-completion string collection &optional predicate + This function returns the longest common prefix of all possible + completions of STRING in COLLECTION. The value of COLLECTION must + be an alist, an obarray, or a function that implements a virtual + set of strings (see below). + + Completion compares STRING against each of the permissible + completions specified by COLLECTION; if the beginning of the + permissible completion equals STRING, it matches. If no + permissible completions match, `try-completion' returns `nil'. If + only one permissible completion matches, and the match is exact, + then `try-completion' returns `t'. Otherwise, the value is the + longest initial sequence common to all the permissible completions + that match. + + If COLLECTION is an alist (*note Association Lists::), the CARs of + the alist elements form the set of permissible completions. + + If COLLECTION is an obarray (*note Creating Symbols::), the names + of all symbols in the obarray form the set of permissible + completions. The global variable `obarray' holds an obarray + containing the names of all interned Lisp symbols. + + Note that the only valid way to make a new obarray is to create it + empty and then add symbols to it one by one using `intern'. Also, + you cannot intern a given symbol in more than one obarray. + + If the argument PREDICATE is non-`nil', then it must be a function + of one argument. It is used to test each possible match, and the + match is accepted only if PREDICATE returns non-`nil'. The + argument given to PREDICATE is either a cons cell from the alist + (the CAR of which is a string) or else it is a symbol (_not_ a + symbol name) from the obarray. + + You can also use a symbol that is a function as COLLECTION. Then + the function is solely responsible for performing completion; + `try-completion' returns whatever this function returns. The + function is called with three arguments: STRING, PREDICATE and + `nil'. (The reason for the third argument is so that the same + function can be used in `all-completions' and do the appropriate + thing in either case.) *Note Programmed Completion::. + + In the first of the following examples, the string `foo' is + matched by three of the alist CARs. All of the matches begin with + the characters `fooba', so that is the result. In the second + example, there is only one possible match, and it is exact, so the + value is `t'. + + (try-completion + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) + => "fooba" + + (try-completion "foo" '(("barfoo" 2) ("foo" 3))) + => t + + In the following example, numerous symbols begin with the + characters `forw', and all of them begin with the word `forward'. + In most of the symbols, this is followed with a `-', but not in + all, so no more than `forward' can be completed. + + (try-completion "forw" obarray) + => "forward" + + Finally, in the following example, only two of the three possible + matches pass the predicate `test' (the string `foobaz' is too + short). Both of those begin with the string `foobar'. + + (defun test (s) + (> (length (car s)) 6)) + => test + (try-completion + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + 'test) + => "foobar" + + - Function: all-completions string collection &optional predicate + This function returns a list of all possible completions of STRING. + The arguments to this function are the same as those of + `try-completion'. + + If COLLECTION is a function, it is called with three arguments: + STRING, PREDICATE and `t'; then `all-completions' returns whatever + the function returns. *Note Programmed Completion::. + + Here is an example, using the function `test' shown in the example + for `try-completion': + + (defun test (s) + (> (length (car s)) 6)) + => test + + (all-completions + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + 'test) + => ("foobar1" "foobar2") + + - Variable: completion-ignore-case + If the value of this variable is non-`nil', XEmacs does not + consider case significant in completion. + + +File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion + +Completion and the Minibuffer +----------------------------- + + This section describes the basic interface for reading from the +minibuffer with completion. + + - Function: completing-read prompt collection &optional predicate + require-match initial hist default + This function reads a string in the minibuffer, assisting the user + by providing completion. It activates the minibuffer with prompt + PROMPT, which must be a string. If INITIAL is non-`nil', + `completing-read' inserts it into the minibuffer as part of the + input. Then it allows the user to edit the input, providing + several commands to attempt completion. + + The actual completion is done by passing COLLECTION and PREDICATE + to the function `try-completion'. This happens in certain + commands bound in the local keymaps used for completion. + + If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't + exit unless the input completes to an element of COLLECTION. If + REQUIRE-MATCH is neither `nil' nor `t', then the exit commands + won't exit unless the input typed is itself an element of + COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work + regardless of the input in the minibuffer. + + However, empty input is always permitted, regardless of the value + of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT. + The value of DEFAULT (if non-`nil') is also available to the user + through the history commands. + + The user can exit with null input by typing with an empty + minibuffer. Then `completing-read' returns `""'. This is how the + user requests whatever default the command uses for the value being + read. The user can return using in this way regardless of + the value of REQUIRE-MATCH, and regardless of whether the empty + string is included in COLLECTION. + + 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::. + + The argument HIST specifies which history list variable to use for + saving the input and for minibuffer history commands. It defaults + to `minibuffer-history'. *Note Minibuffer History::. + + Completion ignores case when comparing the input against the + possible matches, if the built-in variable + `completion-ignore-case' is non-`nil'. *Note Basic Completion::. + + Here's an example of using `completing-read': + + (completing-read + "Complete a foo: " + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + nil t "fo") + + ;; After evaluation of the preceding expression, + ;; the following appears in the minibuffer: + + ---------- Buffer: Minibuffer ---------- + Complete a foo: fo-!- + ---------- Buffer: Minibuffer ---------- + + If the user then types ` b ', `completing-read' + returns `barfoo'. + + The `completing-read' function binds three variables to pass + information to the commands that actually do completion. These + variables are `minibuffer-completion-table', + `minibuffer-completion-predicate' and + `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 @@ -253,9 +445,9 @@ Defining Commands::. 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'. + string, `read-variable' interns it before returning it. If + DEFAULT-VALUE 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? ") @@ -664,13 +856,13 @@ function `read-passwd'. `read-passwd' returns the null string in that case. - User Option: passwd-invert-frame-when-keyboard-grabbed - If non-nil swap the foreground and background colors of all faces - while reading a password. Default values is `t' unless feature - `infodock' is provided. + If non-`nil', swap the foreground and background colors of all + faces while reading a password. Default values is `t', unless + feature `infodock' is provided. - User Option: passwd-echo This specifies the character echoed when typing a password. When - nil, nothing is echoed. + `nil', nothing is echoed.  File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers @@ -740,7 +932,7 @@ minibuffers. frame--a frame that has no minibuffer of its own necessarily uses some other frame's minibuffer window. - - Function: window-minibuffer-p window + - Function: window-minibuffer-p &optional window This function returns non-`nil' if WINDOW is a minibuffer window. It is not correct to determine whether a given window is a @@ -899,318 +1091,3 @@ controls the reading of arguments for an interactive call. in various ways. * Interactive Examples:: Examples of how to read interactive arguments. - -File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands - -Using `interactive' -------------------- - - This section describes how to write the `interactive' form that -makes a Lisp function an interactively-callable command. - - - Special Form: interactive arg-descriptor - This special form declares that the function in which it appears - is a command, and that it may therefore be called interactively - (via `M-x' or by entering a key sequence bound to it). The - argument ARG-DESCRIPTOR declares how to compute the arguments to - the command when the command is called interactively. - - A command may be called from Lisp programs like any other - function, but then the caller supplies the arguments and - ARG-DESCRIPTOR has no effect. - - The `interactive' form has its effect because the command loop - (actually, its subroutine `call-interactively') scans through the - function definition looking for it, before calling the function. - Once the function is called, all its body forms including the - `interactive' form are executed, but at this time `interactive' - simply returns `nil' without even evaluating its argument. - - There are three possibilities for the argument ARG-DESCRIPTOR: - - * It may be omitted or `nil'; then the command is called with no - arguments. This leads quickly to an error if the command requires - one or more arguments. - - * It may be a Lisp expression that is not a string; then it should - be a form that is evaluated to get a list of arguments to pass to - the command. - - If this expression reads keyboard input (this includes using the - minibuffer), keep in mind that the integer value of point or the - mark before reading input may be incorrect after reading input. - This is because the current buffer may be receiving subprocess - output; if subprocess output arrives while the command is waiting - for input, it could relocate point and the mark. - - Here's an example of what _not_ to do: - - (interactive - (list (region-beginning) (region-end) - (read-string "Foo: " nil 'my-history))) - - Here's how to avoid the problem, by examining point and the mark - only after reading the keyboard input: - - (interactive - (let ((string (read-string "Foo: " nil 'my-history))) - (list (region-beginning) (region-end) string))) - - * It may be a string; then its contents should consist of a code - character followed by a prompt (which some code characters use and - some ignore). The prompt ends either with the end of the string - or with a newline. Here is a simple example: - - (interactive "bFrobnicate buffer: ") - - The code letter `b' says to read the name of an existing buffer, - with completion. The buffer name is the sole argument passed to - the command. The rest of the string is a prompt. - - If there is a newline character in the string, it terminates the - prompt. If the string does not end there, then the rest of the - string should contain another code character and prompt, - specifying another argument. You can specify any number of - arguments in this way. - - The prompt string can use `%' to include previous argument values - (starting with the first argument) in the prompt. This is done - using `format' (*note Formatting Strings::). For example, here is - how you could read the name of an existing buffer followed by a - new name to give to that buffer: - - (interactive "bBuffer to rename: \nsRename buffer %s to: ") - - If the first character in the string is `*', then an error is - signaled if the buffer is read-only. - - If the first character in the string is `@', and if the key - sequence used to invoke the command includes any mouse events, then - the window associated with the first of those events is selected - before the command is run. - - If the first character in the string is `_', then this command will - not cause the region to be deactivated when it completes; that is, - `zmacs-region-stays' will be set to `t' when the command exits - successfully. - - You can use `*', `@', and `_' together; the order does not matter. - Actual reading of arguments is controlled by the rest of the - prompt string (starting with the first character that is not `*', - `@', or `_'). - - - Function: function-interactive function - This function retrieves the interactive specification of FUNCTION, - which may be any funcallable object. The specification will be - returned as the list of the symbol `interactive' and the specs. If - FUNCTION is not interactive, `nil' will be returned. - - -File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands - -Code Characters for `interactive' ---------------------------------- - - The code character descriptions below contain a number of key words, -defined here as follows: - -Completion - Provide completion. , , and perform name - completion because the argument is read using `completing-read' - (*note Completion::). `?' displays a list of possible completions. - -Existing - Require the name of an existing object. An invalid name is not - accepted; the commands to exit the minibuffer do not exit if the - current input is not valid. - -Default - A default value of some sort is used if the user enters no text in - the minibuffer. The default depends on the code character. - -No I/O - This code letter computes an argument without reading any input. - Therefore, it does not use a prompt string, and any prompt string - you supply is ignored. - - Even though the code letter doesn't use a prompt string, you must - follow it with a newline if it is not the last code character in - the string. - -Prompt - A prompt immediately follows the code character. The prompt ends - either with the end of the string or with a newline. - -Special - This code character is meaningful only at the beginning of the - interactive string, and it does not look for a prompt or a newline. - It is a single, isolated character. - - Here are the code character descriptions for use with `interactive': - -`*' - Signal an error if the current buffer is read-only. Special. - -`@' - Select the window mentioned in the first mouse event in the key - sequence that invoked this command. Special. - -`_' - Do not cause the region to be deactivated when this command - completes. Special. - -`a' - A function name (i.e., a symbol satisfying `fboundp'). Existing, - Completion, Prompt. - -`b' - The name of an existing buffer. By default, uses the name of the - current buffer (*note Buffers::). Existing, Completion, Default, - Prompt. - -`B' - A buffer name. The buffer need not exist. By default, uses the - name of a recently used buffer other than the current buffer. - Completion, Default, Prompt. - -`c' - A character. The cursor does not move into the echo area. Prompt. - -`C' - A command name (i.e., a symbol satisfying `commandp'). Existing, - Completion, Prompt. - -`d' - The position of point, as an integer (*note Point::). No I/O. - -`D' - A directory name. The default is the current default directory of - the current buffer, `default-directory' (*note System - Environment::). Existing, Completion, Default, Prompt. - -`e' - The last mouse-button or misc-user event in the key sequence that - invoked the command. No I/O. - - You can use `e' more than once in a single command's interactive - specification. If the key sequence that invoked the command has N - mouse-button or misc-user events, the Nth `e' provides the Nth - such event. - -`f' - A file name of an existing file (*note File Names::). The default - directory is `default-directory'. Existing, Completion, Default, - Prompt. - -`F' - A file name. The file need not exist. Completion, Default, - Prompt. - -`k' - A key sequence (*note Keymap Terminology::). This keeps reading - events until a command (or undefined command) is found in the - current key maps. The key sequence argument is represented as a - vector of events. The cursor does not move into the echo area. - Prompt. - - This kind of input is used by commands such as `describe-key' and - `global-set-key'. - -`K' - A key sequence, whose definition you intend to change. This works - like `k', except that it suppresses, for the last input event in - the key sequence, the conversions that are normally used (when - necessary) to convert an undefined key into a defined one. - -`m' - The position of the mark, as an integer. No I/O. - -`n' - A number read with the minibuffer. If the input is not a number, - the user is asked to try again. The prefix argument, if any, is - not used. Prompt. - -`N' - The raw prefix argument. If the prefix argument is `nil', then - read a number as with `n'. Requires a number. *Note Prefix - Command Arguments::. Prompt. - -`p' - The numeric prefix argument. (Note that this `p' is lower case.) - No I/O. - -`P' - The raw prefix argument. (Note that this `P' is upper case.) No - I/O. - -`r' - Point and the mark, as two numeric arguments, smallest first. - This is the only code letter that specifies two successive - arguments rather than one. No I/O. - -`s' - Arbitrary text, read in the minibuffer and returned as a string - (*note Text from Minibuffer::). Terminate the input with either - or . (`C-q' may be used to include either of these - characters in the input.) Prompt. - -`S' - An interned symbol whose name is read in the minibuffer. Any - whitespace character terminates the input. (Use `C-q' to include - whitespace in the string.) Other characters that normally - terminate a symbol (e.g., parentheses and brackets) do not do so - here. Prompt. - -`v' - A variable declared to be a user option (i.e., satisfying the - predicate `user-variable-p'). *Note High-Level Completion::. - Existing, Completion, Prompt. - -`x' - A Lisp object, specified with its read syntax, terminated with a - or . The object is not evaluated. *Note Object from - Minibuffer::. Prompt. - -`X' - A Lisp form is read as with `x', but then evaluated so that its - value becomes the argument for the command. Prompt. - - -File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands - -Examples of Using `interactive' -------------------------------- - - Here are some examples of `interactive': - - (defun foo1 () ; `foo1' takes no arguments, - (interactive) ; just moves forward two words. - (forward-word 2)) - => foo1 - - (defun foo2 (n) ; `foo2' takes one argument, - (interactive "p") ; which is the numeric prefix. - (forward-word (* 2 n))) - => foo2 - - (defun foo3 (n) ; `foo3' takes one argument, - (interactive "nCount:") ; which is read with the Minibuffer. - (forward-word (* 2 n))) - => foo3 - - (defun three-b (b1 b2 b3) - "Select three existing buffers. - Put them into three windows, selecting the last one." - (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") - (delete-other-windows) - (split-window (selected-window) 8) - (switch-to-buffer b1) - (other-window 1) - (split-window (selected-window) 8) - (switch-to-buffer b2) - (other-window 1) - (switch-to-buffer b3)) - => three-b - (three-b "*scratch*" "declarations.texi" "*mail*") - => nil - diff --git a/info/lispref.info-17 b/info/lispref.info-17 index f9926db..d3a35b9 100644 --- a/info/lispref.info-17 +++ b/info/lispref.info-17 @@ -50,6 +50,321 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands + +Using `interactive' +------------------- + + This section describes how to write the `interactive' form that +makes a Lisp function an interactively-callable command. + + - Special Form: interactive arg-descriptor + This special form declares that the function in which it appears + is a command, and that it may therefore be called interactively + (via `M-x' or by entering a key sequence bound to it). The + argument ARG-DESCRIPTOR declares how to compute the arguments to + the command when the command is called interactively. + + A command may be called from Lisp programs like any other + function, but then the caller supplies the arguments and + ARG-DESCRIPTOR has no effect. + + The `interactive' form has its effect because the command loop + (actually, its subroutine `call-interactively') scans through the + function definition looking for it, before calling the function. + Once the function is called, all its body forms including the + `interactive' form are executed, but at this time `interactive' + simply returns `nil' without even evaluating its argument. + + There are three possibilities for the argument ARG-DESCRIPTOR: + + * It may be omitted or `nil'; then the command is called with no + arguments. This leads quickly to an error if the command requires + one or more arguments. + + * It may be a Lisp expression that is not a string; then it should + be a form that is evaluated to get a list of arguments to pass to + the command. + + If this expression reads keyboard input (this includes using the + minibuffer), keep in mind that the integer value of point or the + mark before reading input may be incorrect after reading input. + This is because the current buffer may be receiving subprocess + output; if subprocess output arrives while the command is waiting + for input, it could relocate point and the mark. + + Here's an example of what _not_ to do: + + (interactive + (list (region-beginning) (region-end) + (read-string "Foo: " nil 'my-history))) + + Here's how to avoid the problem, by examining point and the mark + only after reading the keyboard input: + + (interactive + (let ((string (read-string "Foo: " nil 'my-history))) + (list (region-beginning) (region-end) string))) + + * It may be a string; then its contents should consist of a code + character followed by a prompt (which some code characters use and + some ignore). The prompt ends either with the end of the string + or with a newline. Here is a simple example: + + (interactive "bFrobnicate buffer: ") + + The code letter `b' says to read the name of an existing buffer, + with completion. The buffer name is the sole argument passed to + the command. The rest of the string is a prompt. + + If there is a newline character in the string, it terminates the + prompt. If the string does not end there, then the rest of the + string should contain another code character and prompt, + specifying another argument. You can specify any number of + arguments in this way. + + The prompt string can use `%' to include previous argument values + (starting with the first argument) in the prompt. This is done + using `format' (*note Formatting Strings::). For example, here is + how you could read the name of an existing buffer followed by a + new name to give to that buffer: + + (interactive "bBuffer to rename: \nsRename buffer %s to: ") + + If the first character in the string is `*', then an error is + signaled if the buffer is read-only. + + If the first character in the string is `@', and if the key + sequence used to invoke the command includes any mouse events, then + the window associated with the first of those events is selected + before the command is run. + + If the first character in the string is `_', then this command will + not cause the region to be deactivated when it completes; that is, + `zmacs-region-stays' will be set to `t' when the command exits + successfully. + + You can use `*', `@', and `_' together; the order does not matter. + Actual reading of arguments is controlled by the rest of the + prompt string (starting with the first character that is not `*', + `@', or `_'). + + - Function: function-interactive function + This function retrieves the interactive specification of FUNCTION, + which may be any funcallable object. The specification will be + returned as the list of the symbol `interactive' and the specs. If + FUNCTION is not interactive, `nil' will be returned. + + +File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands + +Code Characters for `interactive' +--------------------------------- + + The code character descriptions below contain a number of key words, +defined here as follows: + +Completion + Provide completion. , , and perform name + completion because the argument is read using `completing-read' + (*note Completion::). `?' displays a list of possible completions. + +Existing + Require the name of an existing object. An invalid name is not + accepted; the commands to exit the minibuffer do not exit if the + current input is not valid. + +Default + A default value of some sort is used if the user enters no text in + the minibuffer. The default depends on the code character. + +No I/O + This code letter computes an argument without reading any input. + Therefore, it does not use a prompt string, and any prompt string + you supply is ignored. + + Even though the code letter doesn't use a prompt string, you must + follow it with a newline if it is not the last code character in + the string. + +Prompt + A prompt immediately follows the code character. The prompt ends + either with the end of the string or with a newline. + +Special + This code character is meaningful only at the beginning of the + interactive string, and it does not look for a prompt or a newline. + It is a single, isolated character. + + Here are the code character descriptions for use with `interactive': + +`*' + Signal an error if the current buffer is read-only. Special. + +`@' + Select the window mentioned in the first mouse event in the key + sequence that invoked this command. Special. + +`_' + Do not cause the region to be deactivated when this command + completes. Special. + +`a' + A function name (i.e., a symbol satisfying `fboundp'). Existing, + Completion, Prompt. + +`b' + The name of an existing buffer. By default, uses the name of the + current buffer (*note Buffers::). Existing, Completion, Default, + Prompt. + +`B' + A buffer name. The buffer need not exist. By default, uses the + name of a recently used buffer other than the current buffer. + Completion, Default, Prompt. + +`c' + A character. The cursor does not move into the echo area. Prompt. + +`C' + A command name (i.e., a symbol satisfying `commandp'). Existing, + Completion, Prompt. + +`d' + The position of point, as an integer (*note Point::). No I/O. + +`D' + A directory name. The default is the current default directory of + the current buffer, `default-directory' (*note System + Environment::). Existing, Completion, Default, Prompt. + +`e' + The last mouse-button or misc-user event in the key sequence that + invoked the command. No I/O. + + You can use `e' more than once in a single command's interactive + specification. If the key sequence that invoked the command has N + mouse-button or misc-user events, the Nth `e' provides the Nth + such event. + +`f' + A file name of an existing file (*note File Names::). The default + directory is `default-directory'. Existing, Completion, Default, + Prompt. + +`F' + A file name. The file need not exist. Completion, Default, + Prompt. + +`k' + A key sequence (*note Keymap Terminology::). This keeps reading + events until a command (or undefined command) is found in the + current key maps. The key sequence argument is represented as a + vector of events. The cursor does not move into the echo area. + Prompt. + + This kind of input is used by commands such as `describe-key' and + `global-set-key'. + +`K' + A key sequence, whose definition you intend to change. This works + like `k', except that it suppresses, for the last input event in + the key sequence, the conversions that are normally used (when + necessary) to convert an undefined key into a defined one. + +`m' + The position of the mark, as an integer. No I/O. + +`n' + A number read with the minibuffer. If the input is not a number, + the user is asked to try again. The prefix argument, if any, is + not used. Prompt. + +`N' + The raw prefix argument. If the prefix argument is `nil', then + read a number as with `n'. Requires a number. *Note Prefix + Command Arguments::. Prompt. + +`p' + The numeric prefix argument. (Note that this `p' is lower case.) + No I/O. + +`P' + The raw prefix argument. (Note that this `P' is upper case.) No + I/O. + +`r' + Point and the mark, as two numeric arguments, smallest first. + This is the only code letter that specifies two successive + arguments rather than one. No I/O. + +`s' + Arbitrary text, read in the minibuffer and returned as a string + (*note Text from Minibuffer::). Terminate the input with either + or . (`C-q' may be used to include either of these + characters in the input.) Prompt. + +`S' + An interned symbol whose name is read in the minibuffer. Any + whitespace character terminates the input. (Use `C-q' to include + whitespace in the string.) Other characters that normally + terminate a symbol (e.g., parentheses and brackets) do not do so + here. Prompt. + +`v' + A variable declared to be a user option (i.e., satisfying the + predicate `user-variable-p'). *Note High-Level Completion::. + Existing, Completion, Prompt. + +`x' + A Lisp object, specified with its read syntax, terminated with a + or . The object is not evaluated. *Note Object from + Minibuffer::. Prompt. + +`X' + A Lisp form is read as with `x', but then evaluated so that its + value becomes the argument for the command. Prompt. + + +File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands + +Examples of Using `interactive' +------------------------------- + + Here are some examples of `interactive': + + (defun foo1 () ; `foo1' takes no arguments, + (interactive) ; just moves forward two words. + (forward-word 2)) + => foo1 + + (defun foo2 (n) ; `foo2' takes one argument, + (interactive "p") ; which is the numeric prefix. + (forward-word (* 2 n))) + => foo2 + + (defun foo3 (n) ; `foo3' takes one argument, + (interactive "nCount:") ; which is read with the Minibuffer. + (forward-word (* 2 n))) + => foo3 + + (defun three-b (b1 b2 b3) + "Select three existing buffers. + Put them into three windows, selecting the last one." + (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") + (delete-other-windows) + (split-window (selected-window) 8) + (switch-to-buffer b1) + (other-window 1) + (split-window (selected-window) 8) + (switch-to-buffer b2) + (other-window 1) + (switch-to-buffer b3)) + => three-b + (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 @@ -61,9 +376,9 @@ definition, it invokes that definition using the function `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'. + - Function: commandp function + Returns `t' if FUNCTION is suitable for calling interactively; + that is, if FUNCTION is a command. Otherwise, returns `nil'. The interactively callable objects include strings and vectors (treated as keyboard macros), lambda expressions that contain a @@ -80,7 +395,7 @@ and calls the command. You can also call these functions yourself. See `documentation' in *Note Accessing Documentation::, for a realistic example of using `commandp'. - - Function: call-interactively command &optional record-flag + - Function: call-interactively command &optional record-flag keys 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 @@ -90,7 +405,7 @@ and calls the command. You can also call these functions yourself. functions. If RECORD-FLAG is the symbol `lambda', the interactive calling - arguments for `command' are read and returned as a list, but the + 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 @@ -98,7 +413,7 @@ and calls the command. You can also call these functions yourself. the command is added only if it uses the minibuffer to read an argument. *Note Command History::. - - Function: command-execute command &optional record-flag + - Function: command-execute command &optional record-flag keys 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. @@ -310,7 +625,7 @@ command binding of the key sequence. *Note Reading Input::. - Function: eventp object - This function returns non-`nil' if EVENT is an input event. + This function returns non-`nil' if OBJECT is an input event. * Menu: @@ -560,7 +875,7 @@ particular type. - Function: key-press-event-p object This is true if OBJECT is a key-press event. - - Function: button-event-p object object + - Function: button-event-p object This is true if OBJECT is a mouse button-press or button-release event. @@ -957,10 +1272,10 @@ latter case. (event-properties EVENT))) - Function: copy-event event1 &optional event2 - This function makes a copy of the given event object. If a second - argument is given, the first event is copied into the second and - the second is returned. If the second argument is not supplied - (or is `nil') then a new event will be made. + This function makes a copy of the event object EVENT1. If a + second event argument EVENT2 is given, EVENT1 is copied into + EVENT2 and EVENT2 is returned. If EVENT2 is not supplied (or is + `nil') then a new event will be made, as with `make-event'. - Function: deallocate-event event This function allows the given event structure to be reused. You @@ -968,345 +1283,5 @@ latter case. it. You will lose. It is not necessary to call this function, as event objects are garbage-collected like all other objects; however, it may be more efficient to explicitly deallocate events - when you are sure that that is safe. - - -File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events - -Converting Events ------------------ - - XEmacs provides some auxiliary functions for converting between -events and other ways of representing keys. These are useful when -working with ASCII strings and with keymaps. - - - Function: character-to-event ch &optional event device - This function converts a numeric ASCII value to an event structure, - replete with modifier bits. CH is the character to convert, and - EVENT is the event object to fill in. This function contains - knowledge about what the codes "mean"--for example, the number 9 is - converted to the character , not the distinct character - . - - Note that CH does not have to be a numeric value, but can be a - symbol such as `clear' or a list such as `(control backspace)'. - - If `event' is not `nil', it is modified; otherwise, a new event - object is created. In both cases, the event is returned. - - Optional third arg DEVICE is the device to store in the event; - this also affects whether the high bit is interpreted as a meta - key. A value of `nil' means use the selected device but always - treat the high bit as meta. - - Beware that `character-to-event' and `event-to-character' are not - strictly inverse functions, since events contain much more - information than the ASCII character set can encode. - - - Function: event-to-character event &optional allow-extra-modifiers - allow-meta allow-non-ascii - This function returns the closest ASCII approximation to EVENT. - If the event isn't a keypress, this returns `nil'. - - If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its - translation; it will ignore modifier keys other than and - , and will ignore the modifier on those characters - which have no shifted ASCII equivalent ( for - example, will be mapped to the same ASCII code as ). - - If ALLOW-META is non-`nil', then the modifier will be - represented by turning on the high bit of the byte returned; - otherwise, `nil' will be returned for events containing the - modifier. - - If ALLOW-NON-ASCII is non-`nil', then characters which are present - in the prevailing character set (*note variable - `character-set-property': Keymaps.) will be returned as their code - in that character set, instead of the return value being - restricted to ASCII. - - Note that specifying both ALLOW-META and ALLOW-NON-ASCII is - ambiguous, as both use the high bit; and will be - indistinguishable. - - - Function: events-to-keys events &optional no-mice - Given a vector of event objects, this function returns a vector of - key descriptors, or a string (if they all fit in the ASCII range). - Optional arg NO-MICE means that button events are not allowed. - - -File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop - -Reading Input -============= - - The editor command loop reads keyboard input using the function -`next-event' and constructs key sequences out of the events using -`dispatch-event'. Lisp programs can also use the function -`read-key-sequence', which reads input a key sequence at a time. See -also `momentary-string-display' in *Note Temporary Displays::, and -`sit-for' in *Note Waiting::. *Note Terminal Input::, for functions -and variables for controlling terminal input modes and debugging -terminal input. - - For higher-level input facilities, see *Note Minibuffers::. - -* Menu: - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Dispatching an Event:: What to do with an event once it has been read. -* Quoted Character Input:: Asking the user to specify a character. -* Peeking and Discarding:: How to reread or throw away input events. - - -File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input - -Key Sequence Input ------------------- - - Lisp programs can read input a key sequence at a time by calling -`read-key-sequence'; for example, `describe-key' uses it to read the -key to describe. - - - Function: read-key-sequence prompt - This function reads a sequence of keystrokes or mouse clicks and - returns it as a vector of events. It keeps reading events until - it has accumulated a full key sequence; that is, enough to specify - a non-prefix command using the currently active keymaps. - - The vector and the event objects it contains are freshly created, - and will not be side-effected by subsequent calls to this function. - - The function `read-key-sequence' suppresses quitting: `C-g' typed - while reading with this function works like any other character, - and does not set `quit-flag'. *Note Quitting::. - - The argument PROMPT is either a string to be displayed in the echo - area as a prompt, or `nil', meaning not to display a prompt. - - If the user selects a menu item while we are prompting for a key - sequence, the returned value will be a vector of a single - menu-selection event (a misc-user event). An error will be - signalled if you pass this value to `lookup-key' or a related - function. - - In the example below, the prompt `?' is displayed in the echo area, - and the user types `C-x C-f'. - - (read-key-sequence "?") - - ---------- Echo Area ---------- - ?C-x C-f - ---------- Echo Area ---------- - - => [# #] - - If an input character is an upper-case letter and has no key binding, -but its lower-case equivalent has one, then `read-key-sequence' -converts the character to lower case. Note that `lookup-key' does not -perform case conversion in this way. - - -File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input - -Reading One Event ------------------ - - The lowest level functions for command input are those which read a -single event. These functions often make a distinction between -"command events", which are user actions (keystrokes and mouse -actions), and other events, which serve as communication between XEmacs -and the window system. - - - Function: next-event &optional event prompt - This function reads and returns the next available event from the - window system or terminal driver, waiting if necessary until an - event is available. Pass this object to `dispatch-event' to - handle it. If an event object is supplied, it is filled in and - returned; otherwise a new event object will be created. - - Events can come directly from the user, from a keyboard macro, or - from `unread-command-events'. - - In most cases, the function `next-command-event' is more - appropriate. - - - Function: next-command-event &optional event - This function returns the next available "user" event from the - window system or terminal driver. Pass this object to - `dispatch-event' to handle it. If an event object is supplied, it - is filled in and returned, otherwise a new event object will be - created. - - The event returned will be a keyboard, mouse press, or mouse - release event. If there are non-command events available (mouse - motion, sub-process output, etc) then these will be executed (with - `dispatch-event') and discarded. This function is provided as a - convenience; it is equivalent to the Lisp code - - (while (progn - (next-event event) - (not (or (key-press-event-p event) - (button-press-event-p event) - (button-release-event-p event) - (menu-event-p event)))) - (dispatch-event event)) - - Here is what happens if you call `next-command-event' and then - press the right-arrow function key: - - (next-command-event) - => # - - - Function: read-char - This function reads and returns a character of command input. If a - mouse click is detected, an error is signalled. The character - typed is returned as an ASCII value. This function is retained for - compatibility with Emacs 18, and is most likely the wrong thing - for you to be using: consider using `next-command-event' instead. - - - Function: enqueue-eval-event function object - This function adds an eval event to the back of the queue. The - eval event will be the next event read after all pending events. - - -File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input - -Dispatching an Event --------------------- - - - Function: dispatch-event event - Given an event object returned by `next-event', this function - executes it. This is the basic function that makes XEmacs respond - to user input; it also deals with notifications from the window - system (such as Expose events). - - -File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input - -Quoted Character Input ----------------------- - - You can use the function `read-quoted-char' to ask the user to -specify a character, and allow the user to specify a control or meta -character conveniently, either literally or as an octal character code. -The command `quoted-insert' uses this function. - - - Function: read-quoted-char &optional prompt - This function is like `read-char', except that if the first - character read is an octal digit (0-7), it reads up to two more - octal digits (but stopping if a non-octal digit is found) and - returns the character represented by those digits in octal. - - Quitting is suppressed when the first character is read, so that - the user can enter a `C-g'. *Note Quitting::. - - If PROMPT is supplied, it specifies a string for prompting the - user. The prompt string is always displayed in the echo area, - followed by a single `-'. - - In the following example, the user types in the octal number 177 - (which is 127 in decimal). - - (read-quoted-char "What character") - - ---------- Echo Area ---------- - What character-177 - ---------- Echo Area ---------- - - => 127 - - -File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input - -Miscellaneous Event Input Features ----------------------------------- - - This section describes how to "peek ahead" at events without using -them up, how to check for pending input, and how to discard pending -input. - - See also the variables `last-command-event' and `last-command-char' -(*Note Command Loop Info::). - - - Variable: unread-command-events - This variable holds a list of events waiting to be read as command - input. The events are used in the order they appear in the list, - and removed one by one as they are used. - - The variable is needed because in some cases a function reads a - event and then decides not to use it. Storing the event in this - variable causes it to be processed normally, by the command loop - or by the functions to read command input. - - For example, the function that implements numeric prefix arguments - reads any number of digits. When it finds a non-digit event, it - must unread the event so that it can be read normally by the - command loop. Likewise, incremental search uses this feature to - unread events with no special meaning in a search, because these - events should exit the search and then execute normally. - - - - Variable: unread-command-event - This variable holds a single event to be read as command input. - - This variable is mostly obsolete now that you can use - `unread-command-events' instead; it exists only to support programs - written for versions of XEmacs prior to 19.12. - - - Function: input-pending-p - This function determines whether any command input is currently - available to be read. It returns immediately, with value `t' if - there is available input, `nil' otherwise. On rare occasions it - may return `t' when no input is available. - - - Variable: last-input-event - This variable is set to the last keyboard or mouse button event - received. - - This variable is off limits: you may not set its value or modify - the event that is its value, as it is destructively modified by - `read-key-sequence'. If you want to keep a pointer to this value, - you must use `copy-event'. - - Note that this variable is an alias for `last-input-char' in FSF - Emacs. - - In the example below, a character is read (the character `1'). It - becomes the value of `last-input-event', while `C-e' (from the - `C-x C-e' command used to evaluate this expression) remains the - value of `last-command-event'. - - (progn (print (next-command-event)) - (print last-command-event) - last-input-event) - -| # - -| # - => # - - - Variable: last-input-char - If the value of `last-input-event' is a keyboard event, then this - is the nearest ASCII equivalent to it. Remember that there is - _not_ a 1:1 mapping between keyboard events and ASCII characters: - the set of keyboard events is much larger, so writing code that - examines this variable to determine what key has been typed is bad - practice, unless you are certain that it will be one of a small - set of characters. - - This function exists for compatibility with Emacs version 18. - - - Function: discard-input - This function discards the contents of the terminal input buffer - and cancels any keyboard macro that might be in the process of - definition. It returns `nil'. - - In the following example, the user may type a number of characters - right after starting the evaluation of the form. After the - `sleep-for' finishes sleeping, `discard-input' discards any - characters typed during the sleep. - - (progn (sleep-for 2) - (discard-input)) - => nil + when you are sure that it is safe to do so. diff --git a/info/lispref.info-18 b/info/lispref.info-18 index 47f826c..79b603d 100644 --- a/info/lispref.info-18 +++ b/info/lispref.info-18 @@ -50,6 +50,369 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events + +Converting Events +----------------- + + XEmacs provides some auxiliary functions for converting between +events and other ways of representing keys. These are useful when +working with ASCII strings and with keymaps. + + - Function: character-to-event key-description &optional event console + use-console-meta-flag + This function converts a keystroke description to an event + structure. KEY-DESCRIPTION is the specification of a key stroke, + and EVENT is the event object to fill in. This function contains + knowledge about what the codes "mean"--for example, the number 9 is + converted to the character , not the distinct character + . + + Note that KEY-DESCRIPTION can be an integer, a character, a symbol + such as `clear' or a list such as `(control backspace)'. + + If optional arg EVENT is non-`nil', it is modified; otherwise, a + new event object is created. In both cases, the event is returned. + + Optional third arg CONSOLE is the console to store in the event, + and defaults to the selected console. + + If KEY-DESCRIPTION is an integer or character, the high bit may be + interpreted as the meta key. (This is done for backward + compatibility in lots of places.) If USE-CONSOLE-META-FLAG is + `nil', this will always be the case. If USE-CONSOLE-META-FLAG is + non-`nil', the `meta' flag for CONSOLE affects whether the high + bit is interpreted as a meta key. (See `set-input-mode'.) If you + don't want this silly meta interpretation done, you should pass in + a list containing the character. + + Beware that `character-to-event' and `event-to-character' are not + strictly inverse functions, since events contain much more + information than the ASCII character set can encode. + + - Function: event-to-character event &optional allow-extra-modifiers + allow-meta allow-non-ascii + This function returns the closest ASCII approximation to EVENT. + If the event isn't a keypress, this returns `nil'. + + If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its + translation; it will ignore modifier keys other than and + , and will ignore the modifier on those characters + which have no shifted ASCII equivalent ( for + example, will be mapped to the same ASCII code as ). + + If ALLOW-META is non-`nil', then the modifier will be + represented by turning on the high bit of the byte returned; + otherwise, `nil' will be returned for events containing the + modifier. + + If ALLOW-NON-ASCII is non-`nil', then characters which are present + in the prevailing character set (*note variable + `character-set-property': Keymaps.) will be returned as their code + in that character set, instead of the return value being + restricted to ASCII. + + Note that specifying both ALLOW-META and ALLOW-NON-ASCII is + ambiguous, as both use the high bit; and will be + indistinguishable. + + - Function: events-to-keys events &optional no-mice + Given a vector of event objects, this function returns a vector of + key descriptors, or a string (if they all fit in the ASCII range). + Optional arg NO-MICE means that button events are not allowed. + + +File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop + +Reading Input +============= + + The editor command loop reads keyboard input using the function +`next-event' and constructs key sequences out of the events using +`dispatch-event'. Lisp programs can also use the function +`read-key-sequence', which reads input a key sequence at a time. See +also `momentary-string-display' in *Note Temporary Displays::, and +`sit-for' in *Note Waiting::. *Note Terminal Input::, for functions +and variables for controlling terminal input modes and debugging +terminal input. + + For higher-level input facilities, see *Note Minibuffers::. + +* Menu: + +* Key Sequence Input:: How to read one key sequence. +* Reading One Event:: How to read just one event. +* Dispatching an Event:: What to do with an event once it has been read. +* Quoted Character Input:: Asking the user to specify a character. +* Peeking and Discarding:: How to reread or throw away input events. + + +File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input + +Key Sequence Input +------------------ + + Lisp programs can read input a key sequence at a time by calling +`read-key-sequence'; for example, `describe-key' uses it to read the +key to describe. + + - Function: read-key-sequence prompt &optional continue-echo + dont-downcase-last + This function reads a sequence of keystrokes or mouse clicks and + returns it as a vector of event objects read. It keeps reading + events until it has accumulated a full key sequence; that is, + enough to specify a non-prefix command using the currently active + keymaps. + + The vector and the event objects it contains are freshly created + (and so will not be side-effected by subsequent calls to this + function). + + The function `read-key-sequence' suppresses quitting: `C-g' typed + while reading with this function works like any other character, + and does not set `quit-flag'. *Note Quitting::. + + The argument PROMPT is either a string to be displayed in the echo + area as a prompt, or `nil', meaning not to display a prompt. + + Second optional arg CONTINUE-ECHO non-`nil' means this key echoes + as a continuation of the previous key. + + Third optional arg DONT-DOWNCASE-LAST non-`nil' means do not + convert the last event to lower case. (Normally any upper case + event is converted to lower case if the original event is + undefined and the lower case equivalent is defined.) This argument + is provided mostly for FSF compatibility; the equivalent effect + can be achieved more generally by binding + `retry-undefined-key-binding-unshifted' to `nil' around the call + to `read-key-sequence'. + + If the user selects a menu item while we are prompting for a key + sequence, the returned value will be a vector of a single + menu-selection event (a misc-user event). An error will be + signalled if you pass this value to `lookup-key' or a related + function. + + In the example below, the prompt `?' is displayed in the echo area, + and the user types `C-x C-f'. + + (read-key-sequence "?") + + ---------- Echo Area ---------- + ?C-x C-f + ---------- Echo Area ---------- + + => [# #] + + If an input character is an upper-case letter and has no key binding, +but its lower-case equivalent has one, then `read-key-sequence' +converts the character to lower case. Note that `lookup-key' does not +perform case conversion in this way. + + +File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input + +Reading One Event +----------------- + + The lowest level functions for command input are those which read a +single event. These functions often make a distinction between +"command events", which are user actions (keystrokes and mouse +actions), and other events, which serve as communication between XEmacs +and the window system. + + - Function: next-event &optional event prompt + This function reads and returns the next available event from the + window system or terminal driver, waiting if necessary until an + event is available. Pass this object to `dispatch-event' to + handle it. If an event object is supplied, it is filled in and + returned; otherwise a new event object will be created. + + Events can come directly from the user, from a keyboard macro, or + from `unread-command-events'. + + In most cases, the function `next-command-event' is more + appropriate. + + - Function: next-command-event &optional event prompt + This function returns the next available "user" event from the + window system or terminal driver. Pass this object to + `dispatch-event' to handle it. If an event object is supplied, it + is filled in and returned, otherwise a new event object will be + created. + + The event returned will be a keyboard, mouse press, or mouse + release event. If there are non-command events available (mouse + motion, sub-process output, etc) then these will be executed (with + `dispatch-event') and discarded. This function is provided as a + convenience; it is equivalent to the Lisp code + + (while (progn + (next-event event) + (not (or (key-press-event-p event) + (button-press-event-p event) + (button-release-event-p event) + (menu-event-p event)))) + (dispatch-event event)) + + Here is what happens if you call `next-command-event' and then + press the right-arrow function key: + + (next-command-event) + => # + + - Function: read-char + This function reads and returns a character of command input. If a + mouse click is detected, an error is signalled. The character + typed is returned as an ASCII value. This function is retained for + compatibility with Emacs 18, and is most likely the wrong thing + for you to be using: consider using `next-command-event' instead. + + - Function: enqueue-eval-event function object + This function adds an eval event to the back of the queue. The + eval event will be the next event read after all pending events. + + +File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input + +Dispatching an Event +-------------------- + + - Function: dispatch-event event + Given an event object returned by `next-event', this function + executes it. This is the basic function that makes XEmacs respond + to user input; it also deals with notifications from the window + system (such as Expose events). + + +File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input + +Quoted Character Input +---------------------- + + You can use the function `read-quoted-char' to ask the user to +specify a character, and allow the user to specify a control or meta +character conveniently, either literally or as an octal character code. +The command `quoted-insert' uses this function. + + - Function: read-quoted-char &optional prompt + This function is like `read-char', except that if the first + character read is an octal digit (0-7), it reads up to two more + octal digits (but stopping if a non-octal digit is found) and + returns the character represented by those digits in octal. + + Quitting is suppressed when the first character is read, so that + the user can enter a `C-g'. *Note Quitting::. + + If PROMPT is supplied, it specifies a string for prompting the + user. The prompt string is always displayed in the echo area, + followed by a single `-'. + + In the following example, the user types in the octal number 177 + (which is 127 in decimal). + + (read-quoted-char "What character") + + ---------- Echo Area ---------- + What character-177 + ---------- Echo Area ---------- + + => 127 + + +File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input + +Miscellaneous Event Input Features +---------------------------------- + + This section describes how to "peek ahead" at events without using +them up, how to check for pending input, and how to discard pending +input. + + See also the variables `last-command-event' and `last-command-char' +(*Note Command Loop Info::). + + - Variable: unread-command-events + This variable holds a list of events waiting to be read as command + input. The events are used in the order they appear in the list, + and removed one by one as they are used. + + The variable is needed because in some cases a function reads a + event and then decides not to use it. Storing the event in this + variable causes it to be processed normally, by the command loop + or by the functions to read command input. + + For example, the function that implements numeric prefix arguments + reads any number of digits. When it finds a non-digit event, it + must unread the event so that it can be read normally by the + command loop. Likewise, incremental search uses this feature to + unread events with no special meaning in a search, because these + events should exit the search and then execute normally. + + + - Variable: unread-command-event + This variable holds a single event to be read as command input. + + This variable is mostly obsolete now that you can use + `unread-command-events' instead; it exists only to support programs + written for versions of XEmacs prior to 19.12. + + - Function: input-pending-p + This function determines whether any command input is currently + available to be read. It returns immediately, with value `t' if + there is available input, `nil' otherwise. On rare occasions it + may return `t' when no input is available. + + - Variable: last-input-event + This variable is set to the last keyboard or mouse button event + received. + + This variable is off limits: you may not set its value or modify + the event that is its value, as it is destructively modified by + `read-key-sequence'. If you want to keep a pointer to this value, + you must use `copy-event'. + + Note that this variable is an alias for `last-input-char' in FSF + Emacs. + + In the example below, a character is read (the character `1'). It + becomes the value of `last-input-event', while `C-e' (from the + `C-x C-e' command used to evaluate this expression) remains the + value of `last-command-event'. + + (progn (print (next-command-event)) + (print last-command-event) + last-input-event) + -| # + -| # + => # + + - Variable: last-input-char + If the value of `last-input-event' is a keyboard event, then this + is the nearest ASCII equivalent to it. Remember that there is + _not_ a 1:1 mapping between keyboard events and ASCII characters: + the set of keyboard events is much larger, so writing code that + examines this variable to determine what key has been typed is bad + practice, unless you are certain that it will be one of a small + set of characters. + + This function exists for compatibility with Emacs version 18. + + - Function: discard-input + This function discards the contents of the terminal input buffer + and cancels any keyboard macro that might be in the process of + definition. It returns `nil'. + + In the following example, the user may type a number of characters + right after starting the evaluation of the form. After the + `sleep-for' finishes sleeping, `discard-input' discards any + characters typed during the sleep. + + (progn (sleep-for 2) + (discard-input)) + => nil + + File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop Waiting for Elapsed Time or Input @@ -65,7 +428,7 @@ input comes in, while `sleep-for' pauses without updating the screen. 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 + - Function: sit-for seconds &optional nodisplay 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 @@ -81,9 +444,9 @@ instead of a single argument that can be either an integer or a float. *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). + If NODISPLAY 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. @@ -276,9 +639,9 @@ argument, either numeric or raw, in the `interactive' declaration. value of the prefix argument directly in the variable `current-prefix-arg', but this is less clean. - - Function: prefix-numeric-value arg + - Function: prefix-numeric-value raw This function returns the numeric meaning of a valid raw prefix - argument value, ARG. The argument may be a symbol, a number, or a + argument value, RAW. The argument may be a symbol, a number, or a list. If it is `nil', the value 1 is returned; if it is `-', the value -1 is returned; if it is a number, that number is returned; if it is a list, the CAR of that list (which should be a number) is @@ -378,7 +741,7 @@ recursive edit but also provides the other features of the debugger. Recursive editing levels are also used when you type `C-r' in `query-replace' or use `C-x q' (`kbd-macro-query'). - - Function: recursive-edit + - Command: recursive-edit This function invokes the editor command loop. It is called automatically by the initialization of XEmacs, to let the user begin editing. When called from a Lisp program, it enters a @@ -679,7 +1042,7 @@ Creating Keymaps entries in it are `nil', meaning "command undefined". The only difference between this function and `make-keymap' is that this function returns a "smaller" keymap (one that is expected to - contain fewer entries). As keymaps dynamically resize, the + contain fewer entries). As keymaps dynamically resize, this distinction is not great. Optional argument NAME specifies a name to assign to the keymap, @@ -760,408 +1123,3 @@ key bindings. This function returns the default binding of KEYMAP, or `nil' if it has none. - -File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps - -Key Sequences -============= - - Contrary to popular belief, the world is not ASCII. When running -under a window manager, XEmacs can tell the difference between, for -example, the keystrokes `control-h', `control-shift-h', and -`backspace'. You can, in fact, bind different commands to each of -these. - - A "key sequence" is a set of keystrokes. A "keystroke" is a keysym -and some set of modifiers (such as and ). A "keysym" -is what is printed on the keys on your keyboard. - - A keysym may be represented by a symbol, or (if and only if it is -equivalent to an ASCII character in the range 32 - 255) by a character -or its equivalent ASCII code. The `A' key may be represented by the -symbol `A', the character `?A', or by the number 65. The `break' key -may be represented only by the symbol `break'. - - A keystroke may be represented by a list: the last element of the -list is the key (a symbol, character, or number, as above) and the -preceding elements are the symbolic names of modifier keys (, -, , , , and ). Thus, the sequence -`control-b' is represented by the forms `(control b)', `(control ?b)', -and `(control 98)'. A keystroke may also be represented by an event -object, as returned by the `next-command-event' and `read-key-sequence' -functions. - - Note that in this context, the keystroke `control-b' is _not_ -represented by the number 2 (the ASCII code for `^B') or the character -`?\^B'. See below. - - The modifier is somewhat of a special case. You should not -(and cannot) use `(meta shift a)' to mean `(meta A)', since for -characters that have ASCII equivalents, the state of the shift key is -implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)' -to mean `+', as that sort of thing varies from keyboard to keyboard. -The modifier is for use only with characters that do not have a -second keysym on the same key, such as `backspace' and `tab'. - - A key sequence is a vector of keystrokes. As a degenerate case, -elements of this vector may also be keysyms if they have no modifiers. -That is, the `A' keystroke is represented by all of these forms: - - A ?A 65 (A) (?A) (65) - [A] [?A] [65] [(A)] [(?A)] [(65)] - - the `control-a' keystroke is represented by these forms: - - (control A) (control ?A) (control 65) - [(control A)] [(control ?A)] [(control 65)] - - the key sequence `control-c control-a' is represented by these forms: - - [(control c) (control a)] [(control ?c) (control ?a)] - [(control 99) (control 65)] etc. - - Mouse button clicks work just like keypresses: `(control button1)' -means pressing the left mouse button while holding down the control -key. `[(control c) (shift button3)]' means `control-c', hold , -click right. - - Commands may be bound to the mouse-button up-stroke rather than the -down-stroke as well. `button1' means the down-stroke, and `button1up' -means the up-stroke. Different commands may be bound to the up and -down strokes, though that is probably not what you want, so be careful. - - For backward compatibility, a key sequence may also be represented by -a string. In this case, it represents the key sequence(s) that would -produce that sequence of ASCII characters in a purely ASCII world. For -example, a string containing the ASCII backspace character, `"\^H"', -would represent two key sequences: `(control h)' and `backspace'. -Binding a command to this will actually bind both of those key -sequences. Likewise for the following pairs: - - control h backspace - control i tab - control m return - control j linefeed - control [ escape - control @ control space - - 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) - - Of course, all of this applies only when running under a window -system. If you're talking to XEmacs through a TTY connection, you -don't get any of these features. - - - Function: event-matches-key-specifier-p event key-specifier - This function returns non-`nil' if EVENT matches KEY-SPECIFIER, - which can be any valid form representing a key sequence. This can - be useful, e.g., to determine if the user pressed `help-char' or - `quit-char'. - - -File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps - -Prefix Keys -=========== - - A "prefix key" has an associated keymap that defines what to do with -key sequences that start with the prefix key. For example, `C-x' is a -prefix key, and it uses a keymap that is also stored in the variable -`ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and -their keymaps: - - * `help-map' is used for events that follow `C-h'. - - * `mode-specific-map' is for events that follow `C-c'. 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. - - * `ctl-x-map' is the map used for events that follow `C-x'. This - map is also the function definition of `Control-X-prefix'. - - * `ctl-x-4-map' is used for events that follow `C-x 4'. - - * `ctl-x-5-map' is used for events that follow `C-x 5'. - - * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have - no special name. - - * `esc-map' is an evil hack that is present for compatibility - purposes with Emacs 18. Defining a key in `esc-map' is equivalent - to defining the same key in `global-map' but with the - prefix added. You should _not_ use this in your code. (This map is - also the function definition of `ESC-prefix'.) - - The binding of a prefix key is the keymap to use for looking up the -events that follow the prefix key. (It may instead be a symbol whose -function definition is a keymap. The effect is the same, but the symbol -serves as a name for the prefix key.) Thus, the binding of `C-x' is -the symbol `Control-X-prefix', whose function definition is the keymap -for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.) - - Prefix key definitions can appear in any active keymap. 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 and -minor modes can redefine a key as a prefix by putting a prefix key -definition for it in the local map or the minor mode's map. *Note -Active Keymaps::. - - If a key is defined as a prefix in more than one active map, then its -various definitions are in effect merged: the commands defined in the -minor mode keymaps come first, followed by those in the local map's -prefix definition, and then by those from the global map. - - In the following example, we make `C-p' a prefix key in the local -keymap, in such a way that `C-p' is identical to `C-x'. Then the -binding for `C-p C-f' is the function `find-file', just like `C-x C-f'. -The key sequence `C-p 6' is not found in any active keymap. - - (use-local-map (make-sparse-keymap)) - => nil - (local-set-key "\C-p" ctl-x-map) - => nil - (key-binding "\C-p\C-f") - => find-file - - (key-binding "\C-p6") - => nil - - - Function: define-prefix-command symbol &optional mapvar - This function defines SYMBOL as a prefix command: it creates a - keymap and stores it as SYMBOL's function definition. Storing the - symbol as the binding of a key makes the key a prefix key that has - a name. If optional argument MAPVAR is not specified, it also - sets SYMBOL as a variable, to have the keymap as its value. (If - MAPVAR is given and is not `t', its value is stored as the value - of SYMBOL.) The function returns SYMBOL. - - In Emacs version 18, only the function definition of SYMBOL was - set, not the value as a variable. - - -File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps - -Active Keymaps -============== - - XEmacs normally contains many keymaps; at any given time, just a few -of them are "active" in that they participate in the interpretation of -user input. These are the global keymap, the current buffer's local -keymap, and the keymaps of any enabled minor modes. - - The "global keymap" holds the bindings of keys that are defined -regardless of the current buffer, such as `C-f'. The variable -`global-map' holds this keymap, which is always active. - - Each buffer may have another keymap, its "local keymap", which may -contain new or overriding definitions for keys. The current buffer's -local keymap is always active except when `overriding-local-map' or -`overriding-terminal-local-map' overrides it. Extents and text -properties can specify an alternative local map for certain parts of the -buffer; see *Note Extents and Events::. - - Each minor mode may have a keymap; if it does, the keymap is active -when the minor mode is enabled. - - The variable `overriding-local-map' and -`overriding-terminal-local-map', if non-`nil', specify other local -keymaps that override the buffer's local map and all the minor mode -keymaps. - - All the active keymaps are used together to determine what command to -execute when a key is entered. XEmacs searches these maps one by one, -in order of decreasing precedence, until it finds a binding in one of -the maps. - - More specifically: - - For key-presses, the order of keymaps searched is: - - * the `keymap' property of any extent(s) or text properties at point; - - * any applicable minor-mode maps; - - * the current local map of the current buffer; - - * the current global map. - - For mouse-clicks, the order of keymaps searched is: - - * the current local map of the `mouse-grabbed-buffer' if any; - - * the `keymap' property of any extent(s) at the position of the click - (this includes modeline extents); - - * the `modeline-map' of the buffer corresponding to the modeline - under the mouse (if the click happened over a modeline); - - * the value of `toolbar-map' in the current buffer (if the click - happened over a toolbar); - - * the current local map of the buffer under the mouse (does not - apply to toolbar clicks); - - * any applicable minor-mode maps; - - * the current global map. - - Note that if `overriding-local-map' or -`overriding-terminal-local-map' is non-`nil', _only_ those two maps and -the current global map are searched. - - The procedure for searching a single keymap is called "key lookup"; -see *Note Key Lookup::. - - Since every buffer that uses the same major mode normally uses the -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using `local-set-key', for -example) is seen also in the other buffers that share that keymap. - - The local keymaps that are used for Lisp mode, C mode, and several -other major modes exist even if they have not yet been used. These -local maps are the values of the variables `lisp-mode-map', -`c-mode-map', and so on. For most other modes, which are less -frequently used, the local keymap is constructed only when the mode is -used for the first time in a session. - - The minibuffer has local keymaps, too; they contain various -completion and exit commands. *Note Intro to Minibuffers::. - - *Note Standard Keymaps::, for a list of standard keymaps. - - - Function: current-keymaps &optional event-or-keys - This function returns a list of the current keymaps that will be - searched for bindings. This lists keymaps such as the current - local map and the minor-mode maps, but does not list the parents - of those keymaps. EVENT-OR-KEYS controls which keymaps will be - listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last - element is a mouse event), the keymaps for that mouse event will - be listed. Otherwise, the keymaps for key presses will be listed. - - - Variable: global-map - This variable contains the default global keymap that maps XEmacs - keyboard input to commands. The global keymap is normally this - keymap. The default global keymap is a full keymap that binds - `self-insert-command' to all of the printing characters. - - It is normal practice to change the bindings in the global map, - but you should not assign this variable any value other than the - keymap it starts out with. - - - Function: current-global-map - This function returns the current global keymap. This is the same - as the value of `global-map' unless you change one or the other. - - (current-global-map) - => # - - - Function: current-local-map - This function returns the current buffer's local keymap, or `nil' - if it has none. In the following example, the keymap for the - `*scratch*' buffer (using Lisp Interaction mode) has a number of - entries, including one prefix key, `C-x'. - - (current-local-map) - => # - (describe-bindings-internal (current-local-map)) - => ; Inserted into the buffer: - backspace backward-delete-char-untabify - linefeed eval-print-last-sexp - delete delete-char - C-j eval-print-last-sexp - C-x << Prefix Command >> - M-tab lisp-complete-symbol - M-; lisp-indent-for-comment - M-C-i lisp-complete-symbol - M-C-q indent-sexp - M-C-x eval-defun - Alt-backspace backward-kill-sexp - Alt-delete kill-sexp - - C-x x edebug-defun - - - Function: current-minor-mode-maps - This function returns a list of the keymaps of currently enabled - minor modes. - - - Function: use-global-map keymap - This function makes KEYMAP the new current global keymap. It - returns `nil'. - - It is very unusual to change the global keymap. - - - Function: use-local-map keymap &optional buffer - This function makes KEYMAP the new local keymap of BUFFER. BUFFER - defaults to the current buffer. If KEYMAP is `nil', then the - buffer has no local keymap. `use-local-map' returns `nil'. Most - major mode commands use this function. - - - Variable: minor-mode-map-alist - This variable is an alist describing keymaps that may or may not be - active according to the values of certain variables. Its elements - look like this: - - (VARIABLE . KEYMAP) - - The keymap KEYMAP is active whenever VARIABLE has a non-`nil' - value. Typically VARIABLE is the variable that enables or - disables a minor mode. *Note Keymaps and Minor Modes::. - - Note that elements of `minor-mode-map-alist' do not have the same - structure as elements of `minor-mode-alist'. The map must be the - CDR of the element; a list with the map as the second element will - not do. - - What's more, the keymap itself must appear in the CDR. It does not - work to store a variable in the CDR and make the map the value of - that variable. - - When more than one minor mode keymap is active, their order of - priority is the order of `minor-mode-map-alist'. But you should - design minor modes so that they don't interfere with each other. - If you do this properly, the order will not matter. - - See also `minor-mode-key-binding', above. See *Note Keymaps and - Minor Modes::, for more information about minor modes. - - - Variable: modeline-map - This variable holds the keymap consulted for mouse-clicks on the - modeline of a window. This variable may be buffer-local; its - value will be looked up in the buffer of the window whose modeline - was clicked upon. - - - Variable: toolbar-map - This variable holds the keymap consulted for mouse-clicks over a - toolbar. - - - Variable: mouse-grabbed-buffer - If non-`nil', a buffer which should be consulted first for all - mouse activity. When a mouse-click is processed, it will first be - looked up in the local-map of this buffer, and then through the - normal mechanism if there is no binding for that click. This - buffer's value of `mode-motion-hook' will be consulted instead of - the `mode-motion-hook' of the buffer of the window under the mouse. - You should _bind_ this, not set it. - - - Variable: overriding-local-map - If non-`nil', this variable holds a keymap to use instead of the - buffer's local keymap and instead of all the minor mode keymaps. - This keymap, if any, overrides all other maps that would have been - active, except for the current global map. - - - Variable: overriding-terminal-local-map - If non-`nil', this variable holds a keymap to use instead of the - buffer's local keymap and instead of all the minor mode keymaps, - but for the selected console only. (In other words, this variable - is always console-local; putting a keymap here only applies to - keystrokes coming from the selected console. *Note Consoles and - Devices::.) This keymap, if any, overrides all other maps that - would have been active, except for the current global map. - diff --git a/info/lispref.info-19 b/info/lispref.info-19 index d2354ad..39a30bf 100644 --- a/info/lispref.info-19 +++ b/info/lispref.info-19 @@ -50,6 +50,413 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps + +Key Sequences +============= + + Contrary to popular belief, the world is not ASCII. When running +under a window manager, XEmacs can tell the difference between, for +example, the keystrokes `control-h', `control-shift-h', and +`backspace'. You can, in fact, bind different commands to each of +these. + + A "key sequence" is a set of keystrokes. A "keystroke" is a keysym +and some set of modifiers (such as and ). A "keysym" +is what is printed on the keys on your keyboard. + + A keysym may be represented by a symbol, or (if and only if it is +equivalent to an ASCII character in the range 32 - 255) by a character +or its equivalent ASCII code. The `A' key may be represented by the +symbol `A', the character `?A', or by the number 65. The `break' key +may be represented only by the symbol `break'. + + A keystroke may be represented by a list: the last element of the +list is the key (a symbol, character, or number, as above) and the +preceding elements are the symbolic names of modifier keys (, +, , , , and ). Thus, the sequence +`control-b' is represented by the forms `(control b)', `(control ?b)', +and `(control 98)'. A keystroke may also be represented by an event +object, as returned by the `next-command-event' and `read-key-sequence' +functions. + + Note that in this context, the keystroke `control-b' is _not_ +represented by the number 2 (the ASCII code for `^B') or the character +`?\^B'. See below. + + The modifier is somewhat of a special case. You should not +(and cannot) use `(meta shift a)' to mean `(meta A)', since for +characters that have ASCII equivalents, the state of the shift key is +implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)' +to mean `+', as that sort of thing varies from keyboard to keyboard. +The modifier is for use only with characters that do not have a +second keysym on the same key, such as `backspace' and `tab'. + + A key sequence is a vector of keystrokes. As a degenerate case, +elements of this vector may also be keysyms if they have no modifiers. +That is, the `A' keystroke is represented by all of these forms: + + A ?A 65 (A) (?A) (65) + [A] [?A] [65] [(A)] [(?A)] [(65)] + + the `control-a' keystroke is represented by these forms: + + (control A) (control ?A) (control 65) + [(control A)] [(control ?A)] [(control 65)] + + the key sequence `control-c control-a' is represented by these forms: + + [(control c) (control a)] [(control ?c) (control ?a)] + [(control 99) (control 65)] etc. + + Mouse button clicks work just like keypresses: `(control button1)' +means pressing the left mouse button while holding down the control +key. `[(control c) (shift button3)]' means `control-c', hold , +click right. + + Commands may be bound to the mouse-button up-stroke rather than the +down-stroke as well. `button1' means the down-stroke, and `button1up' +means the up-stroke. Different commands may be bound to the up and +down strokes, though that is probably not what you want, so be careful. + + For backward compatibility, a key sequence may also be represented by +a string. In this case, it represents the key sequence(s) that would +produce that sequence of ASCII characters in a purely ASCII world. For +example, a string containing the ASCII backspace character, `"\^H"', +would represent two key sequences: `(control h)' and `backspace'. +Binding a command to this will actually bind both of those key +sequences. Likewise for the following pairs: + + control h backspace + control i tab + control m return + control j linefeed + control [ escape + control @ control space + + 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) + + Of course, all of this applies only when running under a window +system. If you're talking to XEmacs through a TTY connection, you +don't get any of these features. + + - Function: event-matches-key-specifier-p event key-specifier + This function returns non-`nil' if EVENT matches KEY-SPECIFIER, + which can be any valid form representing a key sequence. This can + be useful, e.g., to determine if the user pressed `help-char' or + `quit-char'. + + +File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps + +Prefix Keys +=========== + + A "prefix key" has an associated keymap that defines what to do with +key sequences that start with the prefix key. For example, `C-x' is a +prefix key, and it uses a keymap that is also stored in the variable +`ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and +their keymaps: + + * `help-map' is used for events that follow `C-h'. + + * `mode-specific-map' is for events that follow `C-c'. 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. + + * `ctl-x-map' is the map used for events that follow `C-x'. This + map is also the function definition of `Control-X-prefix'. + + * `ctl-x-4-map' is used for events that follow `C-x 4'. + + * `ctl-x-5-map' is used for events that follow `C-x 5'. + + * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have + no special name. + + * `esc-map' is an evil hack that is present for compatibility + purposes with Emacs 18. Defining a key in `esc-map' is equivalent + to defining the same key in `global-map' but with the + prefix added. You should _not_ use this in your code. (This map is + also the function definition of `ESC-prefix'.) + + The binding of a prefix key is the keymap to use for looking up the +events that follow the prefix key. (It may instead be a symbol whose +function definition is a keymap. The effect is the same, but the symbol +serves as a name for the prefix key.) Thus, the binding of `C-x' is +the symbol `Control-X-prefix', whose function definition is the keymap +for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.) + + Prefix key definitions can appear in any active keymap. 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 and +minor modes can redefine a key as a prefix by putting a prefix key +definition for it in the local map or the minor mode's map. *Note +Active Keymaps::. + + If a key is defined as a prefix in more than one active map, then its +various definitions are in effect merged: the commands defined in the +minor mode keymaps come first, followed by those in the local map's +prefix definition, and then by those from the global map. + + In the following example, we make `C-p' a prefix key in the local +keymap, in such a way that `C-p' is identical to `C-x'. Then the +binding for `C-p C-f' is the function `find-file', just like `C-x C-f'. +The key sequence `C-p 6' is not found in any active keymap. + + (use-local-map (make-sparse-keymap)) + => nil + (local-set-key "\C-p" ctl-x-map) + => nil + (key-binding "\C-p\C-f") + => find-file + + (key-binding "\C-p6") + => nil + + - Function: define-prefix-command symbol &optional mapvar + This function defines SYMBOL as a prefix command: it creates a + keymap and stores it as SYMBOL's function definition. Storing the + symbol as the binding of a key makes the key a prefix key that has + a name. If optional argument MAPVAR is not specified, it also + sets SYMBOL as a variable, to have the keymap as its value. (If + MAPVAR is given and is not `t', its value is stored as the value + of SYMBOL.) The function returns SYMBOL. + + In Emacs version 18, only the function definition of SYMBOL was + set, not the value as a variable. + + +File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps + +Active Keymaps +============== + + XEmacs normally contains many keymaps; at any given time, just a few +of them are "active" in that they participate in the interpretation of +user input. These are the global keymap, the current buffer's local +keymap, and the keymaps of any enabled minor modes. + + The "global keymap" holds the bindings of keys that are defined +regardless of the current buffer, such as `C-f'. The variable +`global-map' holds this keymap, which is always active. + + Each buffer may have another keymap, its "local keymap", which may +contain new or overriding definitions for keys. The current buffer's +local keymap is always active except when `overriding-local-map' or +`overriding-terminal-local-map' overrides it. Extents and text +properties can specify an alternative local map for certain parts of the +buffer; see *Note Extents and Events::. + + Each minor mode may have a keymap; if it does, the keymap is active +when the minor mode is enabled. + + The variable `overriding-local-map' and +`overriding-terminal-local-map', if non-`nil', specify other local +keymaps that override the buffer's local map and all the minor mode +keymaps. + + All the active keymaps are used together to determine what command to +execute when a key is entered. XEmacs searches these maps one by one, +in order of decreasing precedence, until it finds a binding in one of +the maps. + + More specifically: + + For key-presses, the order of keymaps searched is: + + * the `keymap' property of any extent(s) or text properties at point; + + * any applicable minor-mode maps; + + * the current local map of the current buffer; + + * the current global map. + + For mouse-clicks, the order of keymaps searched is: + + * the current local map of the `mouse-grabbed-buffer' if any; + + * the `keymap' property of any extent(s) at the position of the click + (this includes modeline extents); + + * the `modeline-map' of the buffer corresponding to the modeline + under the mouse (if the click happened over a modeline); + + * the value of `toolbar-map' in the current buffer (if the click + happened over a toolbar); + + * the current local map of the buffer under the mouse (does not + apply to toolbar clicks); + + * any applicable minor-mode maps; + + * the current global map. + + Note that if `overriding-local-map' or +`overriding-terminal-local-map' is non-`nil', _only_ those two maps and +the current global map are searched. + + The procedure for searching a single keymap is called "key lookup"; +see *Note Key Lookup::. + + Since every buffer that uses the same major mode normally uses the +same local keymap, you can think of the keymap as local to the mode. A +change to the local keymap of a buffer (using `local-set-key', for +example) is seen also in the other buffers that share that keymap. + + The local keymaps that are used for Lisp mode, C mode, and several +other major modes exist even if they have not yet been used. These +local maps are the values of the variables `lisp-mode-map', +`c-mode-map', and so on. For most other modes, which are less +frequently used, the local keymap is constructed only when the mode is +used for the first time in a session. + + The minibuffer has local keymaps, too; they contain various +completion and exit commands. *Note Intro to Minibuffers::. + + *Note Standard Keymaps::, for a list of standard keymaps. + + - Function: current-keymaps &optional event-or-keys + This function returns a list of the current keymaps that will be + searched for bindings. This lists keymaps such as the current + local map and the minor-mode maps, but does not list the parents + of those keymaps. EVENT-OR-KEYS controls which keymaps will be + listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last + element is a mouse event), the keymaps for that mouse event will + be listed. Otherwise, the keymaps for key presses will be listed. + + - Variable: global-map + This variable contains the default global keymap that maps XEmacs + keyboard input to commands. The global keymap is normally this + keymap. The default global keymap is a full keymap that binds + `self-insert-command' to all of the printing characters. + + It is normal practice to change the bindings in the global map, + but you should not assign this variable any value other than the + keymap it starts out with. + + - Function: current-global-map + This function returns the current global keymap. This is the same + as the value of `global-map' unless you change one or the other. + + (current-global-map) + => # + + - Function: current-local-map &optional buffer + This function returns BUFFER's local keymap, or `nil' if it has + none. BUFFER defaults to the current buffer. + + In the following example, the keymap for the `*scratch*' buffer + (using Lisp Interaction mode) has a number of entries, including + one prefix key, `C-x'. + + (current-local-map) + => # + (describe-bindings-internal (current-local-map)) + => ; Inserted into the buffer: + backspace backward-delete-char-untabify + linefeed eval-print-last-sexp + delete delete-char + C-j eval-print-last-sexp + C-x << Prefix Command >> + M-tab lisp-complete-symbol + M-; lisp-indent-for-comment + M-C-i lisp-complete-symbol + M-C-q indent-sexp + M-C-x eval-defun + Alt-backspace backward-kill-sexp + Alt-delete kill-sexp + + C-x x edebug-defun + + - Function: current-minor-mode-maps + This function returns a list of the keymaps of currently enabled + minor modes. + + - Function: use-global-map keymap + This function makes KEYMAP the new current global keymap. It + returns `nil'. + + It is very unusual to change the global keymap. + + - Function: use-local-map keymap &optional buffer + This function makes KEYMAP the new local keymap of BUFFER. BUFFER + defaults to the current buffer. If KEYMAP is `nil', then the + buffer has no local keymap. `use-local-map' returns `nil'. Most + major mode commands use this function. + + - Variable: minor-mode-map-alist + This variable is an alist describing keymaps that may or may not be + active according to the values of certain variables. Its elements + look like this: + + (VARIABLE . KEYMAP) + + The keymap KEYMAP is active whenever VARIABLE has a non-`nil' + value. Typically VARIABLE is the variable that enables or + disables a minor mode. *Note Keymaps and Minor Modes::. + + Note that elements of `minor-mode-map-alist' do not have the same + structure as elements of `minor-mode-alist'. The map must be the + CDR of the element; a list with the map as the second element will + not do. + + What's more, the keymap itself must appear in the CDR. It does not + work to store a variable in the CDR and make the map the value of + that variable. + + When more than one minor mode keymap is active, their order of + priority is the order of `minor-mode-map-alist'. But you should + design minor modes so that they don't interfere with each other. + If you do this properly, the order will not matter. + + See also `minor-mode-key-binding', above. See *Note Keymaps and + Minor Modes::, for more information about minor modes. + + - Variable: modeline-map + This variable holds the keymap consulted for mouse-clicks on the + modeline of a window. This variable may be buffer-local; its + value will be looked up in the buffer of the window whose modeline + was clicked upon. + + - Variable: toolbar-map + This variable holds the keymap consulted for mouse-clicks over a + toolbar. + + - Variable: mouse-grabbed-buffer + If non-`nil', a buffer which should be consulted first for all + mouse activity. When a mouse-click is processed, it will first be + looked up in the local-map of this buffer, and then through the + normal mechanism if there is no binding for that click. This + buffer's value of `mode-motion-hook' will be consulted instead of + the `mode-motion-hook' of the buffer of the window under the mouse. + You should _bind_ this, not set it. + + - Variable: overriding-local-map + If non-`nil', this variable holds a keymap to use instead of the + buffer's local keymap and instead of all the minor mode keymaps. + This keymap, if any, overrides all other maps that would have been + active, except for the current global map. + + - Variable: overriding-terminal-local-map + If non-`nil', this variable holds a keymap to use instead of the + buffer's local keymap and instead of all the minor mode keymaps, + but for the selected console only. (In other words, this variable + is always console-local; putting a keymap here only applies to + keystrokes coming from the selected console. *Note Consoles and + Devices::.) This keymap, if any, overrides all other maps that + would have been active, except for the current global map. + + File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps Key Lookup @@ -226,15 +633,15 @@ Functions for Key Lookup (key-binding [escape escape escape]) => keyboard-escape-quit - - Function: local-key-binding key &optional accept-defaults - This function returns the binding for KEY in the current local + - Function: local-key-binding keys &optional accept-defaults + This function returns the binding for KEYS in the current local keymap, or `nil' if it is undefined there. The argument ACCEPT-DEFAULTS controls checking for default bindings, as in `lookup-key' (above). - - Function: global-key-binding key &optional accept-defaults - This function returns the binding for command KEY in the current + - Function: global-key-binding keys &optional accept-defaults + This function returns the binding for command KEYS in the current global keymap, or `nil' if it is undefined there. The argument ACCEPT-DEFAULTS controls checking for default @@ -402,10 +809,13 @@ changing an entry in `ctl-x-map', and this has the effect of changing the bindings of both `C-p C-f' and `C-x C-f' in the default global map. - Function: substitute-key-definition olddef newdef keymap &optional - oldmap + oldmap prefix This function replaces OLDDEF with NEWDEF for any keys in KEYMAP that were bound to OLDDEF. In other words, OLDDEF is replaced - with NEWDEF wherever it appears. The function returns `nil'. + with NEWDEF wherever it appears. Prefix keymaps are checked + recursively. + + The function returns `nil'. For example, this redefines `C-x C-f', if you do it in an XEmacs with standard bindings: @@ -414,7 +824,7 @@ the bindings of both `C-p C-f' and `C-x C-f' in the default global map. 'find-file 'find-file-read-only (current-global-map)) If OLDMAP is non-`nil', then its bindings determine which keys to - rebind. The rebindings still happen in NEWMAP, not in OLDMAP. + rebind. The rebindings still happen in KEYMAP, not in OLDMAP. Thus, you can change one map under the control of the bindings in another. For example, @@ -425,6 +835,10 @@ the bindings of both `C-p C-f' and `C-x C-f' in the default global map. puts the special deletion command in `my-map' for whichever keys are globally bound to the standard deletion command. + If argument PREFIX is non-`nil', then only those occurrences of + OLDDEF found in keymaps accessible through the keymap bound to + PREFIX in KEYMAP are redefined. See also `accessible-keymaps'. + - Function: suppress-keymap keymap &optional nodigits This function changes the contents of the full keymap KEYMAP by @@ -614,7 +1028,7 @@ information. 2 entries 0x3f5>)) - Function: map-keymap function keymap &optional sort-first - This function applies FUNCTION to each element of `KEYMAP'. + This function applies FUNCTION to each element of KEYMAP. FUNCTION will be called with two arguments: a key-description list, and the binding. The order in which the elements of the keymap are passed to the function is unspecified. If the function @@ -649,9 +1063,9 @@ information. exactly those keymaps and no others). If KEYMAPS is nil, search in the currently applicable maps for EVENT-OR-KEYS. - If KEYMAP is a keymap, then the maps searched are KEYMAP and the - global keymap. If KEYMAP is a list of keymaps, then the maps - searched are exactly those keymaps, and no others. If KEYMAP is + If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the + global keymap. If KEYMAPS is a list of keymaps, then the maps + searched are exactly those keymaps, and no others. If KEYMAPS is `nil', then the maps used are the current active keymaps for EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps EVENT-OR-KEYS)' as the argument to KEYMAPS). @@ -685,13 +1099,13 @@ information. `describe-bindings-internal' is used to implement the help command `describe-bindings'. - - Command: describe-bindings prefix mouse-only-p + - Command: describe-bindings &optional prefix mouse-only-p This function creates a listing of all defined keys and their definitions. It writes the listing in a buffer named `*Help*' and displays it in a window. - If PREFIX is non-`nil', it should be a prefix key; then the - listing includes only keys that start with PREFIX. + If optional argument PREFIX is non-`nil', it should be a prefix + key; then the listing includes only keys that start with PREFIX. When several characters with consecutive ASCII codes have the same definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In @@ -703,8 +1117,9 @@ information. digits, punctuation, etc.); all these characters are bound to `self-insert-command'. - If the second argument (prefix arg, interactively) is non-`nil' - then only the mouse bindings are displayed. + If the second optional argument MOUSE-ONLY-P (prefix arg, + interactively) is non-`nil' then only the mouse bindings are + displayed.  File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps @@ -740,497 +1155,3 @@ Menus * Menu Accelerators:: Using and controlling menu accelerator keys * Buffers Menu:: The menu that displays the list of buffers. - -File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus - -Format of Menus -=============== - - A menu is described using a "menu description", which is a list of -menu items, keyword-value pairs, strings, and submenus. The menu -description specifies which items are present in the menu, what function -each item invokes, and whether the item is selectable or not. Pop-up -menus are directly described with a menu description, while menubars are -described slightly differently (see below). - - The first element of a menu must be a string, which is the name of -the menu. This is the string that will be displayed in the parent menu -or menubar, if any. This string is not displayed in the menu itself, -except in the case of the top level pop-up menu, where there is no -parent. In this case, the string will be displayed at the top of the -menu if `popup-menu-titles' is non-`nil'. - - Immediately following the first element there may optionally be up -to four keyword-value pairs, as follows: - -`:included FORM' - This can be used to control the visibility of a menu. The form is - evaluated and the menu will be omitted if the result is `nil'. - -`:config SYMBOL' - This is an efficient shorthand for `:included (memq SYMBOL - menubar-configuration)'. See the variable `menubar-configuration'. - -`:filter FUNCTION' - A menu filter is used to sensitize or incrementally create a - submenu only when it is selected by the user and not every time - the menubar is activated. The filter function is passed the list - of menu items in the submenu and must return a list of menu items - to be used for the menu. It is called only when the menu is about - to be displayed, so other menus may already be displayed. Vile - and terrible things will happen if a menu filter function changes - the current buffer, window, or frame. It also should not raise, - lower, or iconify any frames. Basically, the filter function - should have no side-effects. - -`:accelerator KEY' - A menu accelerator is a keystroke which can be pressed while the - menu is visible which will immediately activate the item. KEY - must be a char or the symbol name of a key. *Note Menu - Accelerators::. - - The rest of the menu consists of elements as follows: - - * A "menu item", which is a vector in the following form: - - `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]' - - NAME is a string, the name of the menu item; it is the string to - display on the menu. It is filtered through the resource - database, so it is possible for resources to override what string - is actually displayed. - - CALLBACK is a form that will be invoked when the menu item is - selected. If the callback of a menu item is a symbol, then it - must name a command. It will be invoked with - `call-interactively'. If it is a list, then it is evaluated with - `eval'. - - The valid keywords and their meanings are described below. - - Note that for compatibility purposes, the form - - `[ NAME CALLBACK ACTIVE-P ]' - - is also accepted and is equivalent to - - `[ NAME CALLBACK :active ACTIVE-P ]' - - and the form - - `[ NAME CALLBACK ACTIVE-P SUFFIX]' - - is accepted and is equivalent to - - `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]' - - However, these older forms are deprecated and should generally not - be used. - - * If an element of a menu is a string, then that string will be - presented in the menu as unselectable text. - - * If an element of a menu is a string consisting solely of hyphens, - then that item will be presented as a solid horizontal line. - - * If an element of a menu is a string beginning with `--:', then a - particular sort of horizontal line will be displayed, as follows: - - `"--:singleLine"' - A solid horizontal line. This is equivalent to a string - consisting solely of hyphens. - - `"--:doubleLine"' - A solid double horizontal line. - - `"--:singleDashedLine"' - A dashed horizontal line. - - `"--:doubleDashedLine"' - A dashed double horizontal line. - - `"--:noLine"' - No line (but a small space is left). - - `"--:shadowEtchedIn"' - A solid horizontal line with a 3-d recessed appearance. - - `"--:shadowEtchedOut"' - A solid horizontal line with a 3-d pushed-out appearance. - - `"--:shadowDoubleEtchedIn"' - A solid double horizontal line with a 3-d recessed appearance. - - `"--:shadowDoubleEtchedOut"' - A solid double horizontal line with a 3-d pushed-out - appearance. - - `"--:shadowEtchedInDash"' - A dashed horizontal line with a 3-d recessed appearance. - - `"--:shadowEtchedOutDash"' - A dashed horizontal line with a 3-d pushed-out appearance. - - `"--:shadowDoubleEtchedInDash"' - A dashed double horizontal line with a 3-d recessed - appearance. - - `"--:shadowDoubleEtchedOutDash"' - A dashed double horizontal line with a 3-d pushed-out - appearance. - - * If an element of a menu is a list, it is treated as a submenu. - The name of that submenu (the first element in the list) will be - used as the name of the item representing this menu on the parent. - - The possible keywords are as follows: - -:active FORM - FORM will be evaluated when the menu that this item is a part of - is about to be displayed, and the item will be selectable only if - the result is non-`nil'. If the item is unselectable, it will - usually be displayed grayed-out to indicate this. - -:suffix FORM - FORM will be evaluated when the menu that this item is a part of - is about to be displayed, and the resulting string is appended to - the displayed name. This provides a convenient way of adding the - name of a command's "argument" to the menu, like `Kill Buffer - NAME'. - -:keys STRING - Normally, the keyboard equivalents of commands in menus are - displayed when the "callback" is a symbol. This can be used to - specify keys for more complex menu items. It is passed through - `substitute-command-keys' first. - -:style STYLE - Specifies what kind of object this menu item is. STYLE be one of - the symbols - - `nil' - A normal menu item. - - `toggle' - A toggle button. - - `radio' - A radio button. - - `button' - A menubar button. - - The only difference between toggle and radio buttons is how they - are displayed. But for consistency, a toggle button should be - used when there is one option whose value can be turned on or off, - and radio buttons should be used when there is a set of mutually - exclusive options. When using a group of radio buttons, you - should arrange for no more than one to be marked as selected at a - time. - -:selected FORM - Meaningful only when STYLE is `toggle', `radio' or `button'. This - specifies whether the button will be in the selected or unselected - state. FORM is evaluated, as for `:active'. - -:included FORM - This can be used to control the visibility of a menu item. The - form is evaluated and the menu item is only displayed if the - result is non-`nil'. Note that this is different from `:active': - If `:active' evaluates to `nil', the item will be displayed grayed - out, while if `:included' evaluates to `nil', the item will be - omitted entirely. - -:config SYMBOL - This is an efficient shorthand for `:included (memq SYMBOL - menubar-configuration)'. See the variable `menubar-configuration'. - -:accelerator KEY - A menu accelerator is a keystroke which can be pressed while the - menu is visible which will immediately activate the item. KEY - must be a char or the symbol name of a key. *Note Menu - Accelerators::. - - - Variable: menubar-configuration - This variable holds a list of symbols, against which the value of - the `:config' tag for each menubar item will be compared. If a - menubar item has a `:config' tag, then it is omitted from the - menubar if that tag is not a member of the `menubar-configuration' - list. - - For example: - - ("File" - :filter file-menu-filter ; file-menu-filter is a function that takes - ; one argument (a list of menu items) and - ; returns a list of menu items - [ "Save As..." write-file] - [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ] - [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ] - ) - - -File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus - -Format of the Menubar -===================== - - A menubar is a list of menus, menu items, and strings. The format is -similar to that of a menu, except: - - * The first item need not be a string, and is not treated specially. - - * A string consisting solely of hyphens is not treated specially. - - * If an element of a menubar is `nil', then it is used to represent - the division between the set of menubar items which are flush-left - and those which are flush-right. (Note: this isn't completely - implemented yet.) - - -File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus - -Menubar -======= - - - Variable: current-menubar - This variable holds the description of the current menubar. This - may be buffer-local. When the menubar is changed, the function - `set-menubar-dirty-flag' has to be called in order for the menubar - to be updated on the screen. - - - Constant: default-menubar - This variable holds the menubar description of the menubar that is - visible at startup. This is the value that `current-menubar' has - at startup. - - - Function: set-menubar-dirty-flag - This function tells XEmacs that the menubar widget has to be - updated. Changes to the menubar will generally not be visible - until this function is called. - - The following convenience functions are provided for setting the -menubar. They are equivalent to doing the appropriate action to change -`current-menubar', and then calling `set-menubar-dirty-flag'. Note -that these functions copy their argument using `copy-sequence'. - - - Function: set-menubar menubar - This function sets the default menubar to be MENUBAR (*note Menu - Format::). This is the menubar that will be visible in buffers - that have not defined their own, buffer-local menubar. - - - Function: set-buffer-menubar menubar - This function sets the buffer-local menubar to be MENUBAR. This - does not change the menubar in any buffers other than the current - one. - - Miscellaneous: - - - Variable: menubar-show-keybindings - If true, the menubar will display keyboard equivalents. If false, - only the command names will be displayed. - - - Variable: activate-menubar-hook - Function or functions called before a menubar menu is pulled down. - These functions are called with no arguments, and should - interrogate and modify the value of `current-menubar' as desired. - - The functions on this hook are invoked after the mouse goes down, - but before the menu is mapped, and may be used to activate, - deactivate, add, or delete items from the menus. However, using a - filter (with the `:filter' keyword in a menu description) is - generally a more efficient way of accomplishing the same thing, - because the filter is invoked only when the actual menu goes down. - With a complex menu, there can be a quite noticeable and - sometimes aggravating delay if all menu modification is - implemented using the `activate-menubar-hook'. See above. - - These functions may return the symbol `t' to assert that they have - made no changes to the menubar. If any other value is returned, - the menubar is recomputed. If `t' is returned but the menubar has - been changed, then the changes may not show up right away. - Returning `nil' when the menubar has not changed is not so bad; - more computation will be done, but redisplay of the menubar will - still be performed optimally. - - - Variable: menu-no-selection-hook - Function or functions to call when a menu or dialog box is - dismissed without a selection having been made. - - -File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus - -Modifying Menus -=============== - - The following functions are provided to modify the menubar of one of -its submenus. Note that these functions modify the menu in-place, -rather than copying it and making a new menu. - - Some of these functions take a "menu path", which is a list of -strings identifying the menu to be modified. For example, `("File")' -names the top-level "File" menu. `("File" "Foo")' names a hypothetical -submenu of "File". - - Others take a "menu item path", which is similar to a menu path but -also specifies a particular item to be modified. For example, `("File" -"Save")' means the menu item called "Save" under the top-level "File" -menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under -the "Foo" submenu of "Menu". - - - Function: add-submenu menu-path submenu &optional before - This function adds a menu to the menubar or one of its submenus. - If the named menu exists already, it is changed. - - MENU-PATH identifies the menu under which the new menu should be - inserted. If MENU-PATH is `nil', then the menu will be added to - the menubar itself. - - SUBMENU is the new menu to add (*note Menu Format::). - - BEFORE, if provided, is the name of a menu before which this menu - should be added, if this menu is not on its parent already. If - the menu is already present, it will not be moved. - - - Function: add-menu-button menu-path menu-leaf &optional before - This function adds a menu item to some menu, creating the menu - first if necessary. If the named item exists already, it is - changed. - - MENU-PATH identifies the menu under which the new menu item should - be inserted. - - MENU-LEAF is a menubar leaf node (*note Menu Format::). - - BEFORE, if provided, is the name of a menu before which this item - should be added, if this item is not on the menu already. If the - item is already present, it will not be moved. - - - Function: delete-menu-item menu-item-path - This function removes the menu item specified by MENU-ITEM-PATH - from the menu hierarchy. - - - Function: enable-menu-item menu-item-path - This function makes the menu item specified by MENU-ITEM-PATH be - selectable. - - - Function: disable-menu-item menu-item-path - This function makes the menu item specified by MENU-ITEM-PATH be - unselectable. - - - Function: relabel-menu-item menu-item-path new-name - This function changes the string of the menu item specified by - MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be - printed as from now on. - - The following function can be used to search for a particular item in -a menubar specification, given a path to the item. - - - Function: find-menu-item menubar menu-item-path &optional parent - This function searches MENUBAR for the item given by - MENU-ITEM-PATH starting from PARENT (`nil' means start at the top - of MENUBAR). This function returns `(ITEM . PARENT)', where - PARENT is the immediate parent of the item found (a menu - description), and ITEM is either a vector, list, or string, - depending on the nature of the menu item. - - This function signals an error if the item is not found. - - The following deprecated functions are also documented, so that -existing code can be understood. You should not use these functions in -new code. - - - Function: add-menu menu-path menu-name menu-items &optional before - This function adds a menu to the menubar or one of its submenus. - If the named menu exists already, it is changed. This is - obsolete; use `add-submenu' instead. - - MENU-PATH identifies the menu under which the new menu should be - inserted. If MENU-PATH is `nil', then the menu will be added to - the menubar itself. - - MENU-NAME is the string naming the menu to be added; MENU-ITEMS is - a list of menu items, strings, and submenus. These two arguments - are the same as the first and following elements of a menu - description (*note Menu Format::). - - BEFORE, if provided, is the name of a menu before which this menu - should be added, if this menu is not on its parent already. If the - menu is already present, it will not be moved. - - - Function: add-menu-item menu-path item-name function enabled-p - &optional before - This function adds a menu item to some menu, creating the menu - first if necessary. If the named item exists already, it is - changed. This is obsolete; use `add-menu-button' instead. - - MENU-PATH identifies the menu under which the new menu item should - be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first, - second, and third elements of a menu item vector (*note Menu - Format::). - - BEFORE, if provided, is the name of a menu item before which this - item should be added, if this item is not on the menu already. If - the item is already present, it will not be moved. - - -File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus - -Menu Filters -============ - - The following filter functions are provided for use in -`default-menubar'. You may want to use them in your own menubar -description. - - - Function: file-menu-filter menu-items - This function changes the arguments and sensitivity of these File - menu items: - - `Delete Buffer' - Has the name of the current buffer appended to it. - - `Print Buffer' - Has the name of the current buffer appended to it. - - `Pretty-Print Buffer' - Has the name of the current buffer appended to it. - - `Save Buffer' - Has the name of the current buffer appended to it, and is - sensitive only when the current buffer is modified. - - `Revert Buffer' - Has the name of the current buffer appended to it, and is - sensitive only when the current buffer has a file. - - `Delete Frame' - Sensitive only when there is more than one visible frame. - - - Function: edit-menu-filter menu-items - This function changes the arguments and sensitivity of these Edit - menu items: - - `Cut' - Sensitive only when XEmacs owns the primary X Selection (if - `zmacs-regions' is `t', this is equivalent to saying that - there is a region selected). - - `Copy' - Sensitive only when XEmacs owns the primary X Selection. - - `Clear' - Sensitive only when XEmacs owns the primary X Selection. - - `Paste' - Sensitive only when there is an owner for the X Clipboard - Selection. - - `Undo' - Sensitive only when there is undo information. While in the - midst of an undo, this is changed to `Undo More'. - - - Function: buffers-menu-filter menu-items - This function sets up the Buffers menu. *Note Buffers Menu::, for - more information. - diff --git a/info/lispref.info-20 b/info/lispref.info-20 index 4f618d5..3dbc967 100644 --- a/info/lispref.info-20 +++ b/info/lispref.info-20 @@ -50,15 +50,519 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus + +Format of Menus +=============== + + A menu is described using a "menu description", which is a list of +menu items, keyword-value pairs, strings, and submenus. The menu +description specifies which items are present in the menu, what function +each item invokes, and whether the item is selectable or not. Pop-up +menus are directly described with a menu description, while menubars are +described slightly differently (see below). + + The first element of a menu must be a string, which is the name of +the menu. This is the string that will be displayed in the parent menu +or menubar, if any. This string is not displayed in the menu itself, +except in the case of the top level pop-up menu, where there is no +parent. In this case, the string will be displayed at the top of the +menu if `popup-menu-titles' is non-`nil'. + + Immediately following the first element there may optionally be up +to four keyword-value pairs, as follows: + +`:included FORM' + This can be used to control the visibility of a menu. The form is + evaluated and the menu will be omitted if the result is `nil'. + +`:config SYMBOL' + This is an efficient shorthand for `:included (memq SYMBOL + menubar-configuration)'. See the variable `menubar-configuration'. + +`:filter FUNCTION' + A menu filter is used to sensitize or incrementally create a + submenu only when it is selected by the user and not every time + the menubar is activated. The filter function is passed the list + of menu items in the submenu and must return a list of menu items + to be used for the menu. It is called only when the menu is about + to be displayed, so other menus may already be displayed. Vile + and terrible things will happen if a menu filter function changes + the current buffer, window, or frame. It also should not raise, + lower, or iconify any frames. Basically, the filter function + should have no side-effects. + +`:accelerator KEY' + A menu accelerator is a keystroke which can be pressed while the + menu is visible which will immediately activate the item. KEY + must be a char or the symbol name of a key. *Note Menu + Accelerators::. + + The rest of the menu consists of elements as follows: + + * A "menu item", which is a vector in the following form: + + `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]' + + NAME is a string, the name of the menu item; it is the string to + display on the menu. It is filtered through the resource + database, so it is possible for resources to override what string + is actually displayed. + + CALLBACK is a form that will be invoked when the menu item is + selected. If the callback of a menu item is a symbol, then it + must name a command. It will be invoked with + `call-interactively'. If it is a list, then it is evaluated with + `eval'. + + The valid keywords and their meanings are described below. + + Note that for compatibility purposes, the form + + `[ NAME CALLBACK ACTIVE-P ]' + + is also accepted and is equivalent to + + `[ NAME CALLBACK :active ACTIVE-P ]' + + and the form + + `[ NAME CALLBACK ACTIVE-P SUFFIX]' + + is accepted and is equivalent to + + `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]' + + However, these older forms are deprecated and should generally not + be used. + + * If an element of a menu is a string, then that string will be + presented in the menu as unselectable text. + + * If an element of a menu is a string consisting solely of hyphens, + then that item will be presented as a solid horizontal line. + + * If an element of a menu is a string beginning with `--:', then a + particular sort of horizontal line will be displayed, as follows: + + `"--:singleLine"' + A solid horizontal line. This is equivalent to a string + consisting solely of hyphens. + + `"--:doubleLine"' + A solid double horizontal line. + + `"--:singleDashedLine"' + A dashed horizontal line. + + `"--:doubleDashedLine"' + A dashed double horizontal line. + + `"--:noLine"' + No line (but a small space is left). + + `"--:shadowEtchedIn"' + A solid horizontal line with a 3-d recessed appearance. + + `"--:shadowEtchedOut"' + A solid horizontal line with a 3-d pushed-out appearance. + + `"--:shadowDoubleEtchedIn"' + A solid double horizontal line with a 3-d recessed appearance. + + `"--:shadowDoubleEtchedOut"' + A solid double horizontal line with a 3-d pushed-out + appearance. + + `"--:shadowEtchedInDash"' + A dashed horizontal line with a 3-d recessed appearance. + + `"--:shadowEtchedOutDash"' + A dashed horizontal line with a 3-d pushed-out appearance. + + `"--:shadowDoubleEtchedInDash"' + A dashed double horizontal line with a 3-d recessed + appearance. + + `"--:shadowDoubleEtchedOutDash"' + A dashed double horizontal line with a 3-d pushed-out + appearance. + + * If an element of a menu is a list, it is treated as a submenu. + The name of that submenu (the first element in the list) will be + used as the name of the item representing this menu on the parent. + + The possible keywords are as follows: + +:active FORM + FORM will be evaluated when the menu that this item is a part of + is about to be displayed, and the item will be selectable only if + the result is non-`nil'. If the item is unselectable, it will + usually be displayed grayed-out to indicate this. + +:suffix FORM + FORM will be evaluated when the menu that this item is a part of + is about to be displayed, and the resulting string is appended to + the displayed name. This provides a convenient way of adding the + name of a command's "argument" to the menu, like `Kill Buffer + NAME'. + +:keys STRING + Normally, the keyboard equivalents of commands in menus are + displayed when the "callback" is a symbol. This can be used to + specify keys for more complex menu items. It is passed through + `substitute-command-keys' first. + +:style STYLE + Specifies what kind of object this menu item is. STYLE be one of + the symbols + + `nil' + A normal menu item. + + `toggle' + A toggle button. + + `radio' + A radio button. + + `button' + A menubar button. + + The only difference between toggle and radio buttons is how they + are displayed. But for consistency, a toggle button should be + used when there is one option whose value can be turned on or off, + and radio buttons should be used when there is a set of mutually + exclusive options. When using a group of radio buttons, you + should arrange for no more than one to be marked as selected at a + time. + +:selected FORM + Meaningful only when STYLE is `toggle', `radio' or `button'. This + specifies whether the button will be in the selected or unselected + state. FORM is evaluated, as for `:active'. + +:included FORM + This can be used to control the visibility of a menu item. The + form is evaluated and the menu item is only displayed if the + result is non-`nil'. Note that this is different from `:active': + If `:active' evaluates to `nil', the item will be displayed grayed + out, while if `:included' evaluates to `nil', the item will be + omitted entirely. + +:config SYMBOL + This is an efficient shorthand for `:included (memq SYMBOL + menubar-configuration)'. See the variable `menubar-configuration'. + +:accelerator KEY + A menu accelerator is a keystroke which can be pressed while the + menu is visible which will immediately activate the item. KEY + must be a char or the symbol name of a key. *Note Menu + Accelerators::. + + - Variable: menubar-configuration + This variable holds a list of symbols, against which the value of + the `:config' tag for each menubar item will be compared. If a + menubar item has a `:config' tag, then it is omitted from the + menubar if that tag is not a member of the `menubar-configuration' + list. + + For example: + + ("File" + :filter file-menu-filter ; file-menu-filter is a function that takes + ; one argument (a list of menu items) and + ; returns a list of menu items + [ "Save As..." write-file] + [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ] + [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ] + ) + + +File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus + +Format of the Menubar +===================== + + A menubar is a list of menus, menu items, and strings. The format is +similar to that of a menu, except: + + * The first item need not be a string, and is not treated specially. + + * A string consisting solely of hyphens is not treated specially. + + * If an element of a menubar is `nil', then it is used to represent + the division between the set of menubar items which are flush-left + and those which are flush-right. (Note: this isn't completely + implemented yet.) + + +File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus + +Menubar +======= + + - Variable: current-menubar + This variable holds the description of the current menubar. This + may be buffer-local. When the menubar is changed, the function + `set-menubar-dirty-flag' has to be called in order for the menubar + to be updated on the screen. + + - Constant: default-menubar + This variable holds the menubar description of the menubar that is + visible at startup. This is the value that `current-menubar' has + at startup. + + - Function: set-menubar-dirty-flag + This function tells XEmacs that the menubar widget has to be + updated. Changes to the menubar will generally not be visible + until this function is called. + + The following convenience functions are provided for setting the +menubar. They are equivalent to doing the appropriate action to change +`current-menubar', and then calling `set-menubar-dirty-flag'. Note +that these functions copy their argument using `copy-sequence'. + + - Function: set-menubar menubar + This function sets the default menubar to be MENUBAR (*note Menu + Format::). This is the menubar that will be visible in buffers + that have not defined their own, buffer-local menubar. + + - Function: set-buffer-menubar menubar + This function sets the buffer-local menubar to be MENUBAR. This + does not change the menubar in any buffers other than the current + one. + + Miscellaneous: + + - Variable: menubar-show-keybindings + If true, the menubar will display keyboard equivalents. If false, + only the command names will be displayed. + + - Variable: activate-menubar-hook + Function or functions called before a menubar menu is pulled down. + These functions are called with no arguments, and should + interrogate and modify the value of `current-menubar' as desired. + + The functions on this hook are invoked after the mouse goes down, + but before the menu is mapped, and may be used to activate, + deactivate, add, or delete items from the menus. However, using a + filter (with the `:filter' keyword in a menu description) is + generally a more efficient way of accomplishing the same thing, + because the filter is invoked only when the actual menu goes down. + With a complex menu, there can be a quite noticeable and + sometimes aggravating delay if all menu modification is + implemented using the `activate-menubar-hook'. See above. + + These functions may return the symbol `t' to assert that they have + made no changes to the menubar. If any other value is returned, + the menubar is recomputed. If `t' is returned but the menubar has + been changed, then the changes may not show up right away. + Returning `nil' when the menubar has not changed is not so bad; + more computation will be done, but redisplay of the menubar will + still be performed optimally. + + - Variable: menu-no-selection-hook + Function or functions to call when a menu or dialog box is + dismissed without a selection having been made. + + +File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus + +Modifying Menus +=============== + + The following functions are provided to modify the menubar of one of +its submenus. Note that these functions modify the menu in-place, +rather than copying it and making a new menu. + + Some of these functions take a "menu path", which is a list of +strings identifying the menu to be modified. For example, `("File")' +names the top-level "File" menu. `("File" "Foo")' names a hypothetical +submenu of "File". + + Others take a "menu item path", which is similar to a menu path but +also specifies a particular item to be modified. For example, `("File" +"Save")' means the menu item called "Save" under the top-level "File" +menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under +the "Foo" submenu of "Menu". + + - Function: add-submenu menu-path submenu &optional before in-menu + This function adds a menu to the menubar or one of its submenus. + If the named menu exists already, it is changed. + + MENU-PATH identifies the menu under which the new menu should be + inserted. If MENU-PATH is `nil', then the menu will be added to + the menubar itself. + + SUBMENU is the new menu to add (*note Menu Format::). + + BEFORE, if provided, is the name of a menu before which this menu + should be added, if this menu is not on its parent already. If + the menu is already present, it will not be moved. + + If IN-MENU is present use that instead of `current-menubar' as the + menu to change. + + - Function: add-menu-button menu-path menu-leaf &optional before + in-menu + This function adds a menu item to some menu, creating the menu + first if necessary. If the named item exists already, it is + changed. + + MENU-PATH identifies the menu under which the new menu item should + be inserted. + + MENU-LEAF is a menubar leaf node (*note Menu Format::). + + BEFORE, if provided, is the name of a menu before which this item + should be added, if this item is not on the menu already. If the + item is already present, it will not be moved. + + If IN-MENU is present use that instead of `current-menubar' as the + menu to change. + + - Function: delete-menu-item menu-item-path &optional from-menu + This function removes the menu item specified by MENU-ITEM-PATH + from the menu hierarchy. + + If FROM-MENU is present use that instead of `current-menubar' as + the menu to change. + + - Function: enable-menu-item menu-item-path + This function makes the menu item specified by MENU-ITEM-PATH be + selectable. + + - Function: disable-menu-item menu-item-path + This function makes the menu item specified by MENU-ITEM-PATH be + unselectable. + + - Function: relabel-menu-item menu-item-path new-name + This function changes the string of the menu item specified by + MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be + printed as from now on. + + The following function can be used to search for a particular item in +a menubar specification, given a path to the item. + + - Function: find-menu-item menubar menu-item-path &optional parent + This function searches MENUBAR for the item given by + MENU-ITEM-PATH starting from PARENT (`nil' means start at the top + of MENUBAR). This function returns `(ITEM . PARENT)', where + PARENT is the immediate parent of the item found (a menu + description), and ITEM is either a vector, list, or string, + depending on the nature of the menu item. + + This function signals an error if the item is not found. + + The following deprecated functions are also documented, so that +existing code can be understood. You should not use these functions in +new code. + + - Function: add-menu menu-path menu-name menu-items &optional before + This function adds a menu to the menubar or one of its submenus. + If the named menu exists already, it is changed. This is + obsolete; use `add-submenu' instead. + + MENU-PATH identifies the menu under which the new menu should be + inserted. If MENU-PATH is `nil', then the menu will be added to + the menubar itself. + + MENU-NAME is the string naming the menu to be added; MENU-ITEMS is + a list of menu items, strings, and submenus. These two arguments + are the same as the first and following elements of a menu + description (*note Menu Format::). + + BEFORE, if provided, is the name of a menu before which this menu + should be added, if this menu is not on its parent already. If the + menu is already present, it will not be moved. + + - Function: add-menu-item menu-path item-name function enabled-p + &optional before + This function adds a menu item to some menu, creating the menu + first if necessary. If the named item exists already, it is + changed. This is obsolete; use `add-menu-button' instead. + + MENU-PATH identifies the menu under which the new menu item should + be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first, + second, and third elements of a menu item vector (*note Menu + Format::). + + BEFORE, if provided, is the name of a menu item before which this + item should be added, if this item is not on the menu already. If + the item is already present, it will not be moved. + + +File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus + +Menu Filters +============ + + The following filter functions are provided for use in +`default-menubar'. You may want to use them in your own menubar +description. + + - Function: file-menu-filter menu-items + This function changes the arguments and sensitivity of these File + menu items: + + `Delete Buffer' + Has the name of the current buffer appended to it. + + `Print Buffer' + Has the name of the current buffer appended to it. + + `Pretty-Print Buffer' + Has the name of the current buffer appended to it. + + `Save Buffer' + Has the name of the current buffer appended to it, and is + sensitive only when the current buffer is modified. + + `Revert Buffer' + Has the name of the current buffer appended to it, and is + sensitive only when the current buffer has a file. + + `Delete Frame' + Sensitive only when there is more than one visible frame. + + - Function: edit-menu-filter menu-items + This function changes the arguments and sensitivity of these Edit + menu items: + + `Cut' + Sensitive only when XEmacs owns the primary X Selection (if + `zmacs-regions' is `t', this is equivalent to saying that + there is a region selected). + + `Copy' + Sensitive only when XEmacs owns the primary X Selection. + + `Clear' + Sensitive only when XEmacs owns the primary X Selection. + + `Paste' + Sensitive only when there is an owner for the X Clipboard + Selection. + + `Undo' + Sensitive only when there is undo information. While in the + midst of an undo, this is changed to `Undo More'. + + - Function: buffers-menu-filter menu-items + This function sets up the Buffers menu. *Note Buffers Menu::, for + more information. + + File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus Pop-Up Menus ============ - - Function: popup-menu menu-desc - This function pops up a menu specified by MENU-DESC, which is a - menu description (*note Menu Format::). The menu is displayed at - the current mouse position. + - Function: popup-menu menu-description &optional event + This function pops up a menu specified by MENU-DESCRIPTION, which + is a menu description (*note Menu Format::). The menu is + displayed at the current mouse position. - Function: popup-menu-up-p This function returns `t' if a pop-up menu is up, `nil' otherwise. @@ -100,13 +604,14 @@ the binding for button3. The following convenience functions are provided for displaying pop-up menus. - - Function: popup-buffer-menu event + - Command: popup-buffer-menu event This function pops up a copy of the `Buffers' menu (from the - menubar) where the mouse is clicked. + menubar) where the mouse is clicked. It should be bound to a + mouse button event. - - Function: popup-menubar-menu event + - Command: popup-menubar-menu event This function pops up a copy of menu that also appears in the - menubar. + menubar. It should be bound to a mouse button event.  File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus @@ -180,7 +685,7 @@ File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Trav Menu Accelerator Functions -------------------------- - - Function: accelerate-menu + - Command: accelerate-menu Make the menubar immediately active and place the cursor on the left most entry in the top level menu. Menu items can be selected as usual. @@ -593,7 +1098,7 @@ this position. Specifier for the toolbar at the right edge of the frame. - Function: toolbar-specifier-p object - This function returns non-nil if OBJECT is a toolbar specifier. + This function returns non-`nil' if OBJECT is a toolbar specifier. Toolbar specifiers are the actual objects contained in the toolbar variables described above, and their valid instantiators are toolbar descriptors (*note Toolbar Descriptor Format::). @@ -680,8 +1185,8 @@ thickness or visibility that is used in frame geometry calculations. the left toolbar width for that frame to 68 pixels, then the frame will be sized to fit 80 characters plus a 68-pixel left toolbar. If you then set the left toolbar width to 0 for a particular buffer (or if that -buffer does not specify a left toolbar or has a nil value specified for -`left-toolbar-visible-p'), you will find that, when that buffer is +buffer does not specify a left toolbar or has a `nil' value specified +for `left-toolbar-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 toolbar but the selected window specifies that the left toolbar is not visible, so it is @@ -717,494 +1222,3 @@ contain arbitrary text or graphics. * Other Gutter Variables:: Controlling the size of gutters. * Common Gutter Widgets:: Things to put in gutters. - -File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, 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: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter - -Creating Gutter -=============== - - - Function: make-gutter-specifier spec-list - Return a new `gutter' specifier object with the given specification - list. SPEC-LIST can be a list of specifications (each of which is - a cons of a locale and a list of instantiators), a single - instantiator, or a list of instantiators. *Note Specifiers::, for - more information about specifiers. - - Gutter specifiers are used to specify the format of a gutter. The - values of the variables `default-gutter', `top-gutter', - `left-gutter', `right-gutter', and `bottom-gutter' are always - gutter specifiers. - - Valid gutter instantiators are called "gutter descriptors" and are - either strings or property-lists of strings. See `default-gutter' - for a description of the exact format. - - - Function: make-gutter-size-specifier spec-list - Return a new `gutter-size' specifier object with the given spec - list. SPEC-LIST can be a list of specifications (each of which is - a cons of a locale and a list of instantiators), a single - instantiator, or a list of instantiators. *Note Specifiers::, for - more information about specifiers. - - Gutter-size specifiers are used to specify the size of a gutter. - The values of the variables `default-gutter-size', - `top-gutter-size', `left-gutter-size', `right-gutter-size', and - `bottom-gutter-size' are always gutter-size specifiers. - - Valid gutter-size instantiators are either integers or the special - symbol `autodetect'. If a gutter-size is set to `autodetect' them - the size of the gutter will be adjusted to just accommodate the - gutters contents. `autodetect' only works for top and bottom - gutters. - - - Function: make-gutter-visible-specifier spec-list - Return a new `gutter-visible' specifier object with the given spec - list. SPEC-LIST can be a list of specifications (each of which is - a cons of a locale and a list of instantiators), a single - instantiator, or a list of instantiators. *Note Specifiers::, for - more information about specifiers. - - Gutter-visible specifiers are used to specify the visibility of a - gutter. The values of the variables `default-gutter-visible-p', - `top-gutter-visible-p', `left-gutter-visible-p', - `right-gutter-visible-p', and `bottom-gutter-visible-p' are always - gutter-visible specifiers. - - Valid gutter-visible instantiators are t, nil or a list of - symbols. If a gutter-visible instantiator is set to a list of - symbols, and the corresponding gutter specification is a - property-list strings, then elements of the gutter specification - will only be visible if the corresponding symbol occurs in the - gutter-visible instantiator. - - -File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, 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. - - -File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top - -Drag and Drop -************* - - _WARNING_: the Drag'n'Drop API is still under development and the -interface may change! The current implementation is considered -experimental. - - Drag'n'drop is a way to transfer information between multiple -applications. To do this several GUIs define their own protocols. -Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more. -To catch all these protocols, XEmacs provides a generic API. - - One prime idea behind the API is to use a data interface that is -transparent for all systems. The author thinks that this is best -archived by using URL and MIME data, cause any internet enabled system -must support these for email already. XEmacs also already provides -powerful interfaces to support these types of data (tm and w3). - -* Menu: - -* Supported Protocols:: Which low-level protocols are supported. -* Drop Interface:: How XEmacs handles a drop from another application. -* Drag Interface:: Calls to initiate a drag from XEmacs. - - -File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop - -Supported Protocols -=================== - - The current release of XEmacs only support a small set of Drag'n'drop -protocols. Some of these only support limited options available in the -API. - -* Menu: - -* OffiX DND:: A generic X based protocol. -* CDE dt:: Common Desktop Environment used on suns. -* MSWindows OLE:: Mr. Gates way of live. -* Loose ends:: The other protocols. - - -File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols - -OffiX DND ---------- - - _WARNING_: If you compile in OffiX, you may not be able to use -multiple X displays successfully. If the two servers are from -different vendors, the results may be unpredictable. - - The OffiX Drag'n'Drop protocol is part of a X API/Widget library -created by Cesar Crusius. It is based on X-Atoms and ClientMessage -events, and works with any X platform supporting them. - - OffiX is supported if 'offix is member of the variable -dragdrop-protocols, or the feature 'offix is defined. - - Unfortunately it uses it's own data types. Examples are: File, Files, -Exe, Link, URL, MIME. The API tries to choose the right type for the -data that is dragged from XEmacs (well, not yet...). - - XEmacs supports both MIME and URL drags and drops using this API. No -application interaction is possible while dragging is in progress. - - For information about the OffiX project have a look at -http://leb.net/~offix/ - diff --git a/info/lispref.info-21 b/info/lispref.info-21 index bac2669..cf39e4c 100644 --- a/info/lispref.info-21 +++ b/info/lispref.info-21 @@ -50,6 +50,497 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, 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: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter + +Creating Gutter +=============== + + - Function: make-gutter-specifier spec-list + Return a new `gutter' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter specifiers are used to specify the format of a gutter. The + values of the variables `default-gutter', `top-gutter', + `left-gutter', `right-gutter', and `bottom-gutter' are always + gutter specifiers. + + Valid gutter instantiators are called "gutter descriptors" and are + either strings or property-lists of strings. See `default-gutter' + for a description of the exact format. + + - Function: make-gutter-size-specifier spec-list + Return a new `gutter-size' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter-size specifiers are used to specify the size of a gutter. + The values of the variables `default-gutter-size', + `top-gutter-size', `left-gutter-size', `right-gutter-size', and + `bottom-gutter-size' are always gutter-size specifiers. + + Valid gutter-size instantiators are either integers or the special + symbol `autodetect'. If a gutter-size is set to `autodetect' them + the size of the gutter will be adjusted to just accommodate the + gutters contents. `autodetect' only works for top and bottom + gutters. + + - Function: make-gutter-visible-specifier spec-list + Return a new `gutter-visible' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter-visible specifiers are used to specify the visibility of a + gutter. The values of the variables `default-gutter-visible-p', + `top-gutter-visible-p', `left-gutter-visible-p', + `right-gutter-visible-p', and `bottom-gutter-visible-p' are always + gutter-visible specifiers. + + Valid gutter-visible instantiators are `t', `nil' or a list of + symbols. If a gutter-visible instantiator is set to a list of + symbols, and the corresponding gutter specification is a + property-list strings, then elements of the gutter specification + will only be visible if the corresponding symbol occurs in the + gutter-visible instantiator. + + +File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, 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. + + +File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top + +Drag and Drop +************* + + _WARNING_: the Drag'n'Drop API is still under development and the +interface may change! The current implementation is considered +experimental. + + Drag'n'drop is a way to transfer information between multiple +applications. To do this several GUIs define their own protocols. +Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more. +To catch all these protocols, XEmacs provides a generic API. + + One prime idea behind the API is to use a data interface that is +transparent for all systems. The author thinks that this is best +archived by using URL and MIME data, cause any internet enabled system +must support these for email already. XEmacs also already provides +powerful interfaces to support these types of data (tm and w3). + +* Menu: + +* Supported Protocols:: Which low-level protocols are supported. +* Drop Interface:: How XEmacs handles a drop from another application. +* Drag Interface:: Calls to initiate a drag from XEmacs. + + +File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop + +Supported Protocols +=================== + + The current release of XEmacs only support a small set of Drag'n'drop +protocols. Some of these only support limited options available in the +API. + +* Menu: + +* OffiX DND:: A generic X based protocol. +* CDE dt:: Common Desktop Environment used on suns. +* MSWindows OLE:: Mr. Gates way of live. +* Loose ends:: The other protocols. + + +File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols + +OffiX DND +--------- + + _WARNING_: If you compile in OffiX, you may not be able to use +multiple X displays successfully. If the two servers are from +different vendors, the results may be unpredictable. + + The OffiX Drag'n'Drop protocol is part of a X API/Widget library +created by Cesar Crusius. It is based on X-Atoms and ClientMessage +events, and works with any X platform supporting them. + + OffiX is supported if 'offix is member of the variable +dragdrop-protocols, or the feature 'offix is defined. + + Unfortunately it uses it's own data types. Examples are: File, Files, +Exe, Link, URL, MIME. The API tries to choose the right type for the +data that is dragged from XEmacs (well, not yet...). + + XEmacs supports both MIME and URL drags and drops using this API. No +application interaction is possible while dragging is in progress. + + For information about the OffiX project have a look at +http://leb.net/~offix/ + + File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols CDE dt @@ -660,477 +1151,3 @@ visited. `normal-mode' actually takes place here. The argument FORCE usually comes from the argument FIND-FILE given to `normal-mode'. - -File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes - -Getting Help about a Major Mode -------------------------------- - - The `describe-mode' function is used to provide information about -major modes. It is normally called with `C-h m'. The `describe-mode' -function uses the value of `major-mode', which is why every major mode -function needs to set the `major-mode' variable. - - - Command: describe-mode - This function displays the documentation of the current major mode. - - The `describe-mode' function calls the `documentation' function - using the value of `major-mode' as an argument. Thus, it displays - the documentation string of the major mode function. (*Note - Accessing Documentation::.) - - - Variable: major-mode - This variable holds the symbol for the current buffer's major mode. - This symbol should have a function definition that is the command - to switch to that major mode. The `describe-mode' function uses - the documentation string of the function as the documentation of - the major mode. - - -File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes - -Defining Derived Modes ----------------------- - - It's often useful to define a new major mode in terms of an existing -one. An easy way to do this is to use `define-derived-mode'. - - - Macro: define-derived-mode variant parent name docstring body... - This construct defines VARIANT as a major mode command, using NAME - as the string form of the mode name. - - The new command VARIANT is defined to call the function PARENT, - then override certain aspects of that parent mode: - - * The new mode has its own keymap, named `VARIANT-map'. - `define-derived-mode' initializes this map to inherit from - `PARENT-map', if it is not already set. - - * The new mode has its own syntax table, kept in the variable - `VARIANT-syntax-table'. `define-derived-mode' initializes - this variable by copying `PARENT-syntax-table', if it is not - already set. - - * The new mode has its own abbrev table, kept in the variable - `VARIANT-abbrev-table'. `define-derived-mode' initializes - this variable by copying `PARENT-abbrev-table', if it is not - already set. - - * The new mode has its own mode hook, `VARIANT-hook', which it - runs in standard fashion as the very last thing that it does. - (The new mode also runs the mode hook of PARENT as part of - calling PARENT.) - - In addition, you can specify how to override other aspects of - PARENT with BODY. The command VARIANT evaluates the forms in BODY - after setting up all its usual overrides, just before running - `VARIANT-hook'. - - The argument DOCSTRING specifies the documentation string for the - new mode. If you omit DOCSTRING, `define-derived-mode' generates - a documentation string. - - Here is a hypothetical example: - - (define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. - \\{hypertext-mode-map}" - (setq case-fold-search nil)) - - (define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) - - -File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes - -Minor Modes -=========== - - A "minor mode" provides features that users may enable or disable -independently of the choice of major mode. Minor modes can be enabled -individually or in combination. Minor modes would be better named -"Generally available, optional feature modes" except that such a name is -unwieldy. - - A minor mode is not usually a modification of single major mode. For -example, Auto Fill mode may be used in any major mode that permits text -insertion. To be general, a minor mode must be effectively independent -of the things major modes do. - - A minor mode is often much more difficult to implement than a major -mode. One reason is that you should be able to activate and deactivate -minor modes in any order. A minor mode should be able to have its -desired effect regardless of the major mode and regardless of the other -minor modes in effect. - - Often the biggest problem in implementing a minor mode is finding a -way to insert the necessary hook into the rest of XEmacs. Minor mode -keymaps make this easier than it used to be. - -* Menu: - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. - - -File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes - -Conventions for Writing Minor Modes ------------------------------------ - - There are conventions for writing minor modes just as there are for -major modes. Several of the major mode conventions apply to minor -modes as well: those regarding the name of the mode initialization -function, the names of global symbols, and the use of keymaps and other -tables. - - In addition, there are several conventions that are specific to -minor modes. - - * Make a variable whose name ends in `-mode' to represent the minor - mode. Its value should enable or disable the mode (`nil' to - disable; anything else to enable.) We call this the "mode - variable". - - This variable is used in conjunction with the `minor-mode-alist' to - display the minor mode name in the modeline. It can also enable - or disable a minor mode keymap. Individual commands or hooks can - also check the variable's value. - - If you want the minor mode to be enabled separately in each buffer, - make the variable buffer-local. - - * Define a command whose name is the same as the mode variable. Its - job is to enable and disable the mode by setting the variable. - - The command should accept one optional argument. If the argument - is `nil', it should toggle the mode (turn it on if it is off, and - off if it is on). Otherwise, it should turn the mode on if the - argument is a positive integer, a symbol other than `nil' or `-', - or a list whose CAR is such an integer or symbol; it should turn - the mode off otherwise. - - Here is an example taken from the definition of - `transient-mark-mode'. It shows the use of `transient-mark-mode' - as a variable that enables or disables the mode's behavior, and - also shows the proper way to toggle, enable or disable the minor - mode based on the raw prefix argument value. - - (setq transient-mark-mode - (if (null arg) (not transient-mark-mode) - (> (prefix-numeric-value arg) 0))) - - * Add an element to `minor-mode-alist' for each minor mode (*note - Modeline Variables::). This element should be a list of the - following form: - - (MODE-VARIABLE STRING) - - Here MODE-VARIABLE is the variable that controls enabling of the - minor mode, and STRING is a short string, starting with a space, - to represent the mode in the modeline. These strings must be - short so that there is room for several of them at once. - - When you add an element to `minor-mode-alist', use `assq' to check - for an existing element, to avoid duplication. For example: - - (or (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) - - -File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes - -Keymaps and Minor Modes ------------------------ - - Each minor mode can have its own keymap, which is active when the -mode is enabled. To set up a keymap for a minor mode, add an element -to the alist `minor-mode-map-alist'. *Note Active Keymaps::. - - One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. In general, this is the only way to do that, since the -facilities for customizing `self-insert-command' are limited to special -cases (designed for abbrevs and Auto Fill mode). (Do not try -substituting your own definition of `self-insert-command' for the -standard one. The editor command loop handles this function specially.) - - -File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes - -Modeline Format -=============== - - Each Emacs window (aside from minibuffer windows) includes a -modeline, which displays status information about the buffer displayed -in the window. The modeline contains information about the buffer, -such as its name, associated file, depth of recursive editing, and the -major and minor modes. - - This section describes how the contents of the modeline are -controlled. It is in the chapter on modes because much of the -information displayed in the modeline relates to the enabled major and -minor modes. - - `modeline-format' is a buffer-local variable that holds a template -used to display the modeline of the current buffer. All windows for -the same buffer use the same `modeline-format' and their modelines -appear the same (except for scrolling percentages and line numbers). - - The modeline of a window is normally updated whenever a different -buffer is shown in the window, or when the buffer's modified-status -changes from `nil' to `t' or vice-versa. If you modify any of the -variables referenced by `modeline-format' (*note Modeline Variables::), -you may want to force an update of the modeline so as to display the -new information. - - - Function: redraw-modeline &optional all - Force redisplay of the current buffer's modeline. If ALL is - non-`nil', then force redisplay of all modelines. - - The modeline is usually displayed in inverse video. This is -controlled using the `modeline' face. *Note Faces::. - -* Menu: - -* Modeline Data:: The data structure that controls the modeline. -* Modeline Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a modeline. - - -File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format - -The Data Structure of the Modeline ----------------------------------- - - The modeline contents are controlled by a data structure of lists, -strings, symbols, and numbers kept in the buffer-local variable -`modeline-format'. The data structure is called a "modeline -construct", and it is built in recursive fashion out of simpler modeline -constructs. The same data structure is used for constructing frame -titles (*note Frame Titles::). - - - Variable: modeline-format - The value of this variable is a modeline construct with overall - responsibility for the modeline format. The value of this variable - controls which other variables are used to form the modeline text, - and where they appear. - - A modeline construct may be as simple as a fixed string of text, but -it usually specifies how to use other variables to construct the text. -Many of these variables are themselves defined to have modeline -constructs as their values. - - The default value of `modeline-format' incorporates the values of -variables such as `mode-name' and `minor-mode-alist'. Because of this, -very few modes need to alter `modeline-format'. For most purposes, it -is sufficient to alter the variables referenced by `modeline-format'. - - A modeline construct may be a string, symbol, glyph, generic -specifier, list or cons cell. - -`STRING' - A string as a modeline construct is displayed verbatim in the mode - line except for "`%'-constructs". Decimal digits after the `%' - specify the field width for space filling on the right (i.e., the - data is left justified). *Note %-Constructs::. - -`SYMBOL' - A symbol as a modeline construct stands for its value. The value - of SYMBOL is processed as a modeline construct, in place of - SYMBOL. However, the symbols `t' and `nil' are ignored; so is any - symbol whose value is void. - - There is one exception: if the value of SYMBOL is a string, it is - displayed verbatim: the `%'-constructs are not recognized. - -`GLYPH' - A glyph is displayed as is. - -`GENERIC-SPECIFIER' - A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands - for its instance. The instance of GENERIC-SPECIFIER is computed - in the current window using the equivalent of `specifier-instance' - and the value is processed. - -`(STRING REST...) or (LIST REST...)' - A list whose first element is a string or list means to process - all the elements recursively and concatenate the results. This is - the most common form of mode line construct. - -`(SYMBOL THEN ELSE)' - A list whose first element is a symbol is a conditional. Its - meaning depends on the value of SYMBOL. If the value is non-`nil', - the second element, THEN, is processed recursively as a modeline - element. But if the value of SYMBOL is `nil', the third element, - ELSE, is processed recursively. You may omit ELSE; then the mode - line element displays nothing if the value of SYMBOL is `nil'. - -`(WIDTH REST...)' - A list whose first element is an integer specifies truncation or - padding of the results of REST. The remaining elements REST are - processed recursively as modeline constructs and concatenated - together. Then the result is space filled (if WIDTH is positive) - or truncated (to -WIDTH columns, if WIDTH is negative) on the - right. - - For example, the usual way to show what percentage of a buffer is - above the top of the window is to use a list like this: `(-3 - "%p")'. - -`(EXTENT REST...)' - A list whose car is an extent means the cdr of the list is - processed normally but the results are displayed using the face of - the extent, and mouse clicks over this section are processed using - the keymap of the extent. (In addition, if the extent has a - help-echo property, that string will be echoed when the mouse - moves over this section.) If extents are nested, all keymaps are - properly consulted when processing mouse clicks, but multiple - faces are not correctly merged (only the first face is used), and - lists of faces are not correctly handled. - - If you do alter `modeline-format' itself, the new value should use -the same variables that appear in the default value (*note Modeline -Variables::), rather than duplicating their contents or displaying the -information in another fashion. This way, customizations made by the -user or by Lisp programs (such as `display-time' and major modes) via -changes to those variables remain effective. - - Here is an example of a `modeline-format' that might be useful for -`shell-mode', since it contains the hostname and default directory. - - (setq modeline-format - (list "" - 'modeline-modified - "%b--" - (getenv "HOST") ; One element is not constant. - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - 'mode-name - 'modeline-process - 'minor-mode-alist - "%n" - ")%]----" - '(line-number-mode "L%l--") - '(-3 . "%p") - "-%-")) - - -File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format - -Variables Used in the Modeline ------------------------------- - - This section describes variables incorporated by the standard value -of `modeline-format' into the text of the mode line. There is nothing -inherently special about these variables; any other variables could -have the same effects on the modeline if `modeline-format' were changed -to use them. - - - Variable: modeline-modified - This variable holds the value of the modeline construct that - displays whether the current buffer is modified. - - The default value of `modeline-modified' is `("--%1*%1+-")'. This - means that the modeline displays `--**-' if the buffer is - modified, `-----' if the buffer is not modified, `--%%-' if the - buffer is read only, and `--%*--' if the buffer is read only and - modified. - - Changing this variable does not force an update of the modeline. - - - Variable: modeline-buffer-identification - This variable identifies the buffer being displayed in the window. - Its default value is `("%F: %17b")', which means that it usually - displays `Emacs:' followed by seventeen characters of the buffer - name. (In a terminal frame, it displays the frame name instead of - `Emacs'; this has the effect of showing the frame number.) You may - want to change this in modes such as Rmail that do not behave like - a "normal" XEmacs. - - - Variable: global-mode-string - This variable holds a modeline spec that appears in the mode line - by default, just after the buffer name. The command `display-time' - sets `global-mode-string' to refer to the variable - `display-time-string', which holds a string containing the time and - load information. - - The `%M' construct substitutes the value of `global-mode-string', - but this is obsolete, since the variable is included directly in - the modeline. - - - Variable: mode-name - This buffer-local variable holds the "pretty" name of the current - buffer's major mode. Each major mode should set this variable so - that the mode name will appear in the modeline. - - - Variable: minor-mode-alist - This variable holds an association list whose elements specify how - the modeline should indicate that a minor mode is active. Each - element of the `minor-mode-alist' should be a two-element list: - - (MINOR-MODE-VARIABLE MODELINE-STRING) - - More generally, MODELINE-STRING can be any mode line spec. It - appears in the mode line when the value of MINOR-MODE-VARIABLE is - non-`nil', and not otherwise. These strings should begin with - spaces so that they don't run together. Conventionally, the - MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil' - value when that minor mode is activated. - - The default value of `minor-mode-alist' is: - - minor-mode-alist - => ((vc-mode vc-mode) - (abbrev-mode " Abbrev") - (overwrite-mode overwrite-mode) - (auto-fill-function " Fill") - (defining-kbd-macro " Def") - (isearch-mode isearch-mode)) - - `minor-mode-alist' is not buffer-local. The variables mentioned - in the alist should be buffer-local if the minor mode can be - enabled separately in each buffer. - - - Variable: modeline-process - This buffer-local variable contains the modeline information on - process status in modes used for communicating with subprocesses. - It is displayed immediately following the major mode name, with no - intervening space. For example, its value in the `*shell*' buffer - is `(": %s")', which allows the shell to display its status along - with the major mode as: `(Shell: run)'. Normally this variable is - `nil'. - - - Variable: default-modeline-format - This variable holds the default `modeline-format' for buffers that - do not override it. This is the same as `(default-value - 'modeline-format)'. - - The default value of `default-modeline-format' is: - - ("" - modeline-modified - modeline-buffer-identification - " " - global-mode-string - " %[(" - mode-name - modeline-process - minor-mode-alist - "%n" - ")%]----" - (line-number-mode "L%l--") - (-3 . "%p") - "-%-") - - - Variable: vc-mode - The variable `vc-mode', local in each buffer, records whether the - buffer's visited file is maintained with version control, and, if - so, which kind. Its value is `nil' for no version control, or a - string that appears in the mode line. - diff --git a/info/lispref.info-22 b/info/lispref.info-22 index c9aa60e..fd881c3 100644 --- a/info/lispref.info-22 +++ b/info/lispref.info-22 @@ -50,6 +50,480 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes + +Getting Help about a Major Mode +------------------------------- + + The `describe-mode' function is used to provide information about +major modes. It is normally called with `C-h m'. The `describe-mode' +function uses the value of `major-mode', which is why every major mode +function needs to set the `major-mode' variable. + + - Command: describe-mode + This function displays the documentation of the current major mode. + + The `describe-mode' function calls the `documentation' function + using the value of `major-mode' as an argument. Thus, it displays + the documentation string of the major mode function. (*Note + Accessing Documentation::.) + + - Variable: major-mode + This variable holds the symbol for the current buffer's major mode. + This symbol should have a function definition that is the command + to switch to that major mode. The `describe-mode' function uses + the documentation string of the function as the documentation of + the major mode. + + +File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes + +Defining Derived Modes +---------------------- + + It's often useful to define a new major mode in terms of an existing +one. An easy way to do this is to use `define-derived-mode'. + + - Macro: define-derived-mode variant parent name docstring body... + This construct defines VARIANT as a major mode command, using NAME + as the string form of the mode name. + + The new command VARIANT is defined to call the function PARENT, + then override certain aspects of that parent mode: + + * The new mode has its own keymap, named `VARIANT-map'. + `define-derived-mode' initializes this map to inherit from + `PARENT-map', if it is not already set. + + * The new mode has its own syntax table, kept in the variable + `VARIANT-syntax-table'. `define-derived-mode' initializes + this variable by copying `PARENT-syntax-table', if it is not + already set. + + * The new mode has its own abbrev table, kept in the variable + `VARIANT-abbrev-table'. `define-derived-mode' initializes + this variable by copying `PARENT-abbrev-table', if it is not + already set. + + * The new mode has its own mode hook, `VARIANT-hook', which it + runs in standard fashion as the very last thing that it does. + (The new mode also runs the mode hook of PARENT as part of + calling PARENT.) + + In addition, you can specify how to override other aspects of + PARENT with BODY. The command VARIANT evaluates the forms in BODY + after setting up all its usual overrides, just before running + `VARIANT-hook'. + + The argument DOCSTRING specifies the documentation string for the + new mode. If you omit DOCSTRING, `define-derived-mode' generates + a documentation string. + + Here is a hypothetical example: + + (define-derived-mode hypertext-mode + text-mode "Hypertext" + "Major mode for hypertext. + \\{hypertext-mode-map}" + (setq case-fold-search nil)) + + (define-key hypertext-mode-map + [down-mouse-3] 'do-hyper-link) + + +File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes + +Minor Modes +=========== + + A "minor mode" provides features that users may enable or disable +independently of the choice of major mode. Minor modes can be enabled +individually or in combination. Minor modes would be better named +"Generally available, optional feature modes" except that such a name is +unwieldy. + + A minor mode is not usually a modification of single major mode. For +example, Auto Fill mode may be used in any major mode that permits text +insertion. To be general, a minor mode must be effectively independent +of the things major modes do. + + A minor mode is often much more difficult to implement than a major +mode. One reason is that you should be able to activate and deactivate +minor modes in any order. A minor mode should be able to have its +desired effect regardless of the major mode and regardless of the other +minor modes in effect. + + Often the biggest problem in implementing a minor mode is finding a +way to insert the necessary hook into the rest of XEmacs. Minor mode +keymaps make this easier than it used to be. + +* Menu: + +* Minor Mode Conventions:: Tips for writing a minor mode. +* Keymaps and Minor Modes:: How a minor mode can have its own keymap. + + +File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes + +Conventions for Writing Minor Modes +----------------------------------- + + There are conventions for writing minor modes just as there are for +major modes. Several of the major mode conventions apply to minor +modes as well: those regarding the name of the mode initialization +function, the names of global symbols, and the use of keymaps and other +tables. + + In addition, there are several conventions that are specific to +minor modes. + + * Make a variable whose name ends in `-mode' to represent the minor + mode. Its value should enable or disable the mode (`nil' to + disable; anything else to enable.) We call this the "mode + variable". + + This variable is used in conjunction with the `minor-mode-alist' to + display the minor mode name in the modeline. It can also enable + or disable a minor mode keymap. Individual commands or hooks can + also check the variable's value. + + If you want the minor mode to be enabled separately in each buffer, + make the variable buffer-local. + + * Define a command whose name is the same as the mode variable. Its + job is to enable and disable the mode by setting the variable. + + The command should accept one optional argument. If the argument + is `nil', it should toggle the mode (turn it on if it is off, and + off if it is on). Otherwise, it should turn the mode on if the + argument is a positive integer, a symbol other than `nil' or `-', + or a list whose CAR is such an integer or symbol; it should turn + the mode off otherwise. + + Here is an example taken from the definition of + `transient-mark-mode'. It shows the use of `transient-mark-mode' + as a variable that enables or disables the mode's behavior, and + also shows the proper way to toggle, enable or disable the minor + mode based on the raw prefix argument value. + + (setq transient-mark-mode + (if (null arg) (not transient-mark-mode) + (> (prefix-numeric-value arg) 0))) + + * Add an element to `minor-mode-alist' for each minor mode (*note + Modeline Variables::). This element should be a list of the + following form: + + (MODE-VARIABLE STRING) + + Here MODE-VARIABLE is the variable that controls enabling of the + minor mode, and STRING is a short string, starting with a space, + to represent the mode in the modeline. These strings must be + short so that there is room for several of them at once. + + When you add an element to `minor-mode-alist', use `assq' to check + for an existing element, to avoid duplication. For example: + + (or (assq 'leif-mode minor-mode-alist) + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist))) + + +File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes + +Keymaps and Minor Modes +----------------------- + + Each minor mode can have its own keymap, which is active when the +mode is enabled. To set up a keymap for a minor mode, add an element +to the alist `minor-mode-map-alist'. *Note Active Keymaps::. + + One use of minor mode keymaps is to modify the behavior of certain +self-inserting characters so that they do something else as well as +self-insert. In general, this is the only way to do that, since the +facilities for customizing `self-insert-command' are limited to special +cases (designed for abbrevs and Auto Fill mode). (Do not try +substituting your own definition of `self-insert-command' for the +standard one. The editor command loop handles this function specially.) + + +File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes + +Modeline Format +=============== + + Each Emacs window (aside from minibuffer windows) includes a +modeline, which displays status information about the buffer displayed +in the window. The modeline contains information about the buffer, +such as its name, associated file, depth of recursive editing, and the +major and minor modes. + + This section describes how the contents of the modeline are +controlled. It is in the chapter on modes because much of the +information displayed in the modeline relates to the enabled major and +minor modes. + + `modeline-format' is a buffer-local variable that holds a template +used to display the modeline of the current buffer. All windows for +the same buffer use the same `modeline-format' and their modelines +appear the same (except for scrolling percentages and line numbers). + + The modeline of a window is normally updated whenever a different +buffer is shown in the window, or when the buffer's modified-status +changes from `nil' to `t' or vice-versa. If you modify any of the +variables referenced by `modeline-format' (*note Modeline Variables::), +you may want to force an update of the modeline so as to display the +new information. + + - Function: redraw-modeline &optional all + Force redisplay of the current buffer's modeline. If ALL is + non-`nil', then force redisplay of all modelines. + + The modeline is usually displayed in inverse video. This is +controlled using the `modeline' face. *Note Faces::. + +* Menu: + +* Modeline Data:: The data structure that controls the modeline. +* Modeline Variables:: Variables used in that data structure. +* %-Constructs:: Putting information into a modeline. + + +File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format + +The Data Structure of the Modeline +---------------------------------- + + The modeline contents are controlled by a data structure of lists, +strings, symbols, and numbers kept in the buffer-local variable +`modeline-format'. The data structure is called a "modeline +construct", and it is built in recursive fashion out of simpler modeline +constructs. The same data structure is used for constructing frame +titles (*note Frame Titles::). + + - Variable: modeline-format + The value of this variable is a modeline construct with overall + responsibility for the modeline format. The value of this variable + controls which other variables are used to form the modeline text, + and where they appear. + + A modeline construct may be as simple as a fixed string of text, but +it usually specifies how to use other variables to construct the text. +Many of these variables are themselves defined to have modeline +constructs as their values. + + The default value of `modeline-format' incorporates the values of +variables such as `mode-name' and `minor-mode-alist'. Because of this, +very few modes need to alter `modeline-format'. For most purposes, it +is sufficient to alter the variables referenced by `modeline-format'. + + A modeline construct may be a string, symbol, glyph, generic +specifier, list or cons cell. + +`STRING' + A string as a modeline construct is displayed verbatim in the mode + line except for "`%'-constructs". Decimal digits after the `%' + specify the field width for space filling on the right (i.e., the + data is left justified). *Note %-Constructs::. + +`SYMBOL' + A symbol as a modeline construct stands for its value. The value + of SYMBOL is processed as a modeline construct, in place of + SYMBOL. However, the symbols `t' and `nil' are ignored; so is any + symbol whose value is void. + + There is one exception: if the value of SYMBOL is a string, it is + displayed verbatim: the `%'-constructs are not recognized. + +`GLYPH' + A glyph is displayed as is. + +`GENERIC-SPECIFIER' + A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands + for its instance. The instance of GENERIC-SPECIFIER is computed + in the current window using the equivalent of `specifier-instance' + and the value is processed. + +`(STRING REST...) or (LIST REST...)' + A list whose first element is a string or list means to process + all the elements recursively and concatenate the results. This is + the most common form of mode line construct. + +`(SYMBOL THEN ELSE)' + A list whose first element is a symbol is a conditional. Its + meaning depends on the value of SYMBOL. If the value is non-`nil', + the second element, THEN, is processed recursively as a modeline + element. But if the value of SYMBOL is `nil', the third element, + ELSE, is processed recursively. You may omit ELSE; then the mode + line element displays nothing if the value of SYMBOL is `nil'. + +`(WIDTH REST...)' + A list whose first element is an integer specifies truncation or + padding of the results of REST. The remaining elements REST are + processed recursively as modeline constructs and concatenated + together. Then the result is space filled (if WIDTH is positive) + or truncated (to -WIDTH columns, if WIDTH is negative) on the + right. + + For example, the usual way to show what percentage of a buffer is + above the top of the window is to use a list like this: `(-3 + "%p")'. + +`(EXTENT REST...)' + A list whose car is an extent means the cdr of the list is + processed normally but the results are displayed using the face of + the extent, and mouse clicks over this section are processed using + the keymap of the extent. (In addition, if the extent has a + help-echo property, that string will be echoed when the mouse + moves over this section.) If extents are nested, all keymaps are + properly consulted when processing mouse clicks, but multiple + faces are not correctly merged (only the first face is used), and + lists of faces are not correctly handled. + + If you do alter `modeline-format' itself, the new value should use +the same variables that appear in the default value (*note Modeline +Variables::), rather than duplicating their contents or displaying the +information in another fashion. This way, customizations made by the +user or by Lisp programs (such as `display-time' and major modes) via +changes to those variables remain effective. + + Here is an example of a `modeline-format' that might be useful for +`shell-mode', since it contains the hostname and default directory. + + (setq modeline-format + (list "" + 'modeline-modified + "%b--" + (getenv "HOST") ; One element is not constant. + ":" + 'default-directory + " " + 'global-mode-string + " %[(" + 'mode-name + 'modeline-process + 'minor-mode-alist + "%n" + ")%]----" + '(line-number-mode "L%l--") + '(-3 . "%p") + "-%-")) + + +File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format + +Variables Used in the Modeline +------------------------------ + + This section describes variables incorporated by the standard value +of `modeline-format' into the text of the mode line. There is nothing +inherently special about these variables; any other variables could +have the same effects on the modeline if `modeline-format' were changed +to use them. + + - Variable: modeline-modified + This variable holds the value of the modeline construct that + displays whether the current buffer is modified. + + The default value of `modeline-modified' is `("--%1*%1+-")'. This + means that the modeline displays `--**-' if the buffer is + modified, `-----' if the buffer is not modified, `--%%-' if the + buffer is read only, and `--%*--' if the buffer is read only and + modified. + + Changing this variable does not force an update of the modeline. + + - Variable: modeline-buffer-identification + This variable identifies the buffer being displayed in the window. + Its default value is `("%F: %17b")', which means that it usually + displays `Emacs:' followed by seventeen characters of the buffer + name. (In a terminal frame, it displays the frame name instead of + `Emacs'; this has the effect of showing the frame number.) You may + want to change this in modes such as Rmail that do not behave like + a "normal" XEmacs. + + - Variable: global-mode-string + This variable holds a modeline spec that appears in the mode line + by default, just after the buffer name. The command `display-time' + sets `global-mode-string' to refer to the variable + `display-time-string', which holds a string containing the time and + load information. + + The `%M' construct substitutes the value of `global-mode-string', + but this is obsolete, since the variable is included directly in + the modeline. + + - Variable: mode-name + This buffer-local variable holds the "pretty" name of the current + buffer's major mode. Each major mode should set this variable so + that the mode name will appear in the modeline. + + - Variable: minor-mode-alist + This variable holds an association list whose elements specify how + the modeline should indicate that a minor mode is active. Each + element of the `minor-mode-alist' should be a two-element list: + + (MINOR-MODE-VARIABLE MODELINE-STRING) + + More generally, MODELINE-STRING can be any mode line spec. It + appears in the mode line when the value of MINOR-MODE-VARIABLE is + non-`nil', and not otherwise. These strings should begin with + spaces so that they don't run together. Conventionally, the + MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil' + value when that minor mode is activated. + + The default value of `minor-mode-alist' is: + + minor-mode-alist + => ((vc-mode vc-mode) + (abbrev-mode " Abbrev") + (overwrite-mode overwrite-mode) + (auto-fill-function " Fill") + (defining-kbd-macro " Def") + (isearch-mode isearch-mode)) + + `minor-mode-alist' is not buffer-local. The variables mentioned + in the alist should be buffer-local if the minor mode can be + enabled separately in each buffer. + + - Variable: modeline-process + This buffer-local variable contains the modeline information on + process status in modes used for communicating with subprocesses. + It is displayed immediately following the major mode name, with no + intervening space. For example, its value in the `*shell*' buffer + is `(": %s")', which allows the shell to display its status along + with the major mode as: `(Shell: run)'. Normally this variable is + `nil'. + + - Variable: default-modeline-format + This variable holds the default `modeline-format' for buffers that + do not override it. This is the same as `(default-value + 'modeline-format)'. + + The default value of `default-modeline-format' is: + + ("" + modeline-modified + modeline-buffer-identification + " " + global-mode-string + " %[(" + mode-name + modeline-process + minor-mode-alist + "%n" + ")%]----" + (line-number-mode "L%l--") + (-3 . "%p") + "-%-") + + - Variable: vc-mode + The variable `vc-mode', local in each buffer, records whether the + buffer's visited file is maintained with version control, and, if + so, which kind. Its value is `nil' for no version control, or a + string that appears in the mode line. + + File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format `%'-Constructs in the ModeLine @@ -288,7 +762,7 @@ added with `add-hooks'. difference. - Function: make-local-hook hook - This function makes the hook variable `hook' local to the current + 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. @@ -489,7 +963,7 @@ more information. 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 + 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'. @@ -605,14 +1079,14 @@ XEmacs Lisp. (substitute-command-keys "Substrings of the form \\=\\{MAPVAR} are replaced by summaries - \(made by describe-bindings) of the value of MAPVAR, taken as a keymap. + \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \\=\\ specify to use the value of MAPVAR as the keymap for future \\=\\[COMMAND] substrings. \\=\\= quotes the following character and is discarded; thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.") => "Substrings of the form \{MAPVAR} are replaced by summaries - (made by describe-bindings) of the value of MAPVAR, taken as a keymap. + (made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \ specify to use the value of MAPVAR as the keymap for future \[COMMAND] substrings. \= quotes the following character and is discarded; @@ -671,440 +1145,3 @@ the character itself. (text-char-description ?\C-\M-m) => "M-^M" - -File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation - -Help Functions -============== - - XEmacs provides a variety of on-line help functions, all accessible -to the user as subcommands of the prefix `C-h', or on some keyboards, -`help'. For more information about them, see *Note Help: (emacs)Help. -Here we describe some program-level interfaces to the same information. - - - Command: apropos regexp &optional do-all predicate - This function finds all symbols whose names contain a match for the - regular expression REGEXP, and returns a list of them (*note - Regular Expressions::). It also displays the symbols in a buffer - named `*Help*', each with a one-line description. - - If DO-ALL is non-`nil', then `apropos' also shows key bindings for - the functions that are found. - - If PREDICATE is non-`nil', it should be a function to be called on - each symbol that has matched REGEXP. Only symbols for which - PREDICATE returns a non-`nil' value are listed or displayed. - - In the first of the following examples, `apropos' finds all the - symbols with names containing `exec'. In the second example, it - finds and returns only those symbols that are also commands. (We - don't show the output that results in the `*Help*' buffer.) - - (apropos "exec") - => (Buffer-menu-execute command-execute exec-directory - exec-path execute-extended-command execute-kbd-macro - executing-kbd-macro executing-macro) - - (apropos "exec" nil 'commandp) - => (Buffer-menu-execute execute-extended-command) - - `apropos' is used by various user-level commands, such as `C-h a' - (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A' - (`command-apropos'), which does an apropos over only those - functions which are user commands. `command-apropos' calls - `apropos', specifying a PREDICATE to restrict the output to - symbols that are commands. The call to `apropos' looks like this: - - (apropos string t 'commandp) - - - Variable: help-map - The value of this variable is a local keymap for characters - following the Help key, `C-h'. - - - Prefix Command: help-command - This symbol is not a function; its function definition is actually - the keymap known as `help-map'. It is defined in `help.el' as - follows: - - (define-key global-map "\C-h" 'help-command) - (fset 'help-command help-map) - - - Function: print-help-return-message &optional function - This function builds a string that explains how to restore the - previous state of the windows after a help command. After - building the message, it applies FUNCTION to it if FUNCTION is - non-`nil'. Otherwise it calls `message' to display it in the echo - area. - - This function expects to be called inside a - `with-output-to-temp-buffer' special form, and expects - `standard-output' to have the value bound by that special form. - For an example of its use, see the long example in *Note Accessing - Documentation::. - - - Variable: help-char - The value of this variable is the help character--the character - that XEmacs recognizes as meaning Help. By default, it is the - character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this - character, if `help-form' is non-`nil' Lisp expression, it - evaluates that expression, and displays the result in a window if - it is a string. - - `help-char' can be a character or a key description such as `help' - or `(meta h)'. - - Usually the value of `help-form''s value is `nil'. Then the help - character has no special meaning at the level of command input, and - it becomes part of a key sequence in the normal way. The standard - key binding of `C-h' is a prefix key for several general-purpose - help features. - - The help character is special after prefix keys, too. If it has no - binding as a subcommand of the prefix key, it runs - `describe-prefix-bindings', which displays a list of all the - subcommands of the prefix key. - - - Variable: help-form - If this variable is non-`nil', its value is a form to evaluate - whenever the character `help-char' is read. If evaluating the form - produces a string, that string is displayed. - - A command that calls `next-command-event' or `next-event' probably - should bind `help-form' to a non-`nil' expression while it does - input. (The exception is when `C-h' is meaningful input.) - Evaluating this expression should result in a string that explains - what the input is for and how to enter it properly. - - Entry to the minibuffer binds this variable to the value of - `minibuffer-help-form' (*note Minibuffer Misc::). - - - Variable: prefix-help-command - This variable holds a function to print help for a prefix - character. The function is called when the user types a prefix - key followed by the help character, and the help character has no - binding after that prefix. The variable's default value is - `describe-prefix-bindings'. - - - Function: describe-prefix-bindings - This function calls `describe-bindings' to display a list of all - the subcommands of the prefix key of the most recent key sequence. - The prefix described consists of all but the last event of that - key sequence. (The last event is, presumably, the help character.) - - The following two functions are found in the library `helper'. They -are for modes that want to provide help without relinquishing control, -such as the "electric" modes. You must load that library with -`(require 'helper)' in order to use them. Their names begin with -`Helper' to distinguish them from the ordinary help functions. - - - Command: Helper-describe-bindings - This command pops up a window displaying a help buffer containing a - listing of all of the key bindings from both the local and global - keymaps. It works by calling `describe-bindings'. - - - Command: Helper-help - This command provides help for the current mode. It prompts the - user in the minibuffer with the message `Help (Type ? for further - options)', and then provides assistance in finding out what the key - bindings are, and what the mode is intended for. It returns `nil'. - - This can be customized by changing the map `Helper-help-map'. - - -File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation - -Obsoleteness -============ - - As you add functionality to a package, you may at times want to -replace an older function with a new one. To preserve compatibility -with existing code, the older function needs to still exist; but users -of that function should be told to use the newer one instead. XEmacs -Lisp lets you mark a function or variable as "obsolete", and indicate -what should be used instead. - - - Function: make-obsolete function new - This function indicates that FUNCTION is an obsolete function, and - the function NEW should be used instead. The byte compiler will - issue a warning to this effect when it encounters a usage of the - older function, and the help system will also note this in the - function's documentation. NEW can also be a string (if there is - not a single function with the same functionality any more), and - should be a descriptive statement, such as "use FOO or BAR - instead" or "this function is unnecessary". - - - Function: make-obsolete-variable variable new - This is like `make-obsolete' but is for variables instead of - functions. - - - Function: define-obsolete-function-alias oldfun newfun - This function combines `make-obsolete' and `define-function', - declaring OLDFUN to be an obsolete variant of NEWFUN and defining - OLDFUN as an alias for NEWFUN. - - - Function: define-obsolete-variable-alias oldvar newvar - This is like `define-obsolete-function-alias' but for variables. - - Note that you should not normally put obsoleteness information -explicitly in a function or variable's doc string. The obsoleteness -information that you specify using the above functions will be displayed -whenever the doc string is displayed, and by adding it explicitly the -result is redundancy. - - Also, if an obsolete function is substantially the same as a newer -one but is not actually an alias, you should consider omitting the doc -string entirely (use a null string `""' as the doc string). That way, -the user is told about the obsoleteness and is forced to look at the -documentation of the new function, making it more likely that he will -use the new function. - - - Function: function-obsoleteness-doc function - If FUNCTION is obsolete, this function returns a string describing - this. This is the message that is printed out during byte - compilation or in the function's documentation. If FUNCTION is - not obsolete, `nil' is returned. - - - Function: variable-obsoleteness-doc variable - This is like `function-obsoleteness-doc' but for variables. - - The obsoleteness information is stored internally by putting a -property `byte-obsolete-info' (for functions) or -`byte-obsolete-variable' (for variables) on the symbol that specifies -the obsolete function or variable. For more information, see the -implementation of `make-obsolete' and `make-obsolete-variable' in -`lisp/bytecomp/bytecomp-runtime.el'. - - -File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top - -Files -***** - - In XEmacs, you can find, create, view, save, and otherwise work with -files and file directories. This chapter describes most of the -file-related functions of XEmacs Lisp, but a few others are described in -*Note Buffers::, and those related to backups and auto-saving are -described in *Note Backups and Auto-Saving::. - - Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments using `expand-file-name', so that `~' is -handled correctly, as are relative file names (including `../'). These -functions don't recognize environment variable substitutions such as -`$HOME'. *Note File Name Expansion::. - -* Menu: - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing File Attributes:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Partial Files:: Treating a section of a buffer as a file. -* Format Conversion:: Conversion to and from various file formats. -* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS. - - -File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files - -Visiting Files -============== - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is "visiting" that file, and call the file -"the visited file" of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of XEmacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -"save" the buffer, which means copying the altered buffer contents back -into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -"I am editing a file," rather than, "I am editing a buffer that I will -soon save as a file of the same name." Humans do not usually need to -make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. - -* Menu: - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - - -File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files - -Functions for Visiting Files ----------------------------- - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -`find-' rather than `visit-'. *Note Buffer File Name::, for functions -and variables that access the visited file name of a buffer or that -find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use `insert-file-contents' in a -temporary buffer. Visiting the file is not necessary and takes longer. -*Note Reading from Files::. - - - Command: find-file filename - This command selects a buffer visiting the file FILENAME, using an - existing buffer if there is one, and otherwise creating a new - buffer and reading the file into it. It also returns that buffer. - - The body of the `find-file' function is very simple and looks like - this: - - (switch-to-buffer (find-file-noselect filename)) - - (See `switch-to-buffer' in *Note Displaying Buffers::.) - - When `find-file' is called interactively, it prompts for FILENAME - in the minibuffer. - - - Function: find-file-noselect filename &optional nowarn - This function is the guts of all the file-visiting functions. It - finds or creates a buffer visiting the file FILENAME, and returns - it. It uses an existing buffer if there is one, and otherwise - creates a new buffer and reads the file into it. You may make the - buffer current or display it in a window if you wish, but this - function does not do so. - - When `find-file-noselect' uses an existing buffer, it first - verifies that the file has not changed since it was last visited or - saved in that buffer. If the file has changed, then this function - asks the user whether to reread the changed file. If the user says - `yes', any changes previously made in the buffer are lost. - - If `find-file-noselect' needs to create a buffer, and there is no - file named FILENAME, it displays the message `New file' in the - echo area, and leaves the buffer empty. - - If NO-WARN is non-`nil', various warnings that XEmacs normally - gives (e.g. if another buffer is already visiting FILENAME but - FILENAME has been removed from disk since that buffer was created) - are suppressed. - - The `find-file-noselect' function calls `after-find-file' after - reading the file (*note Subroutines of Visiting::). That function - sets the buffer major mode, parses local variables, warns the user - if there exists an auto-save file more recent than the file just - visited, and finishes by running the functions in - `find-file-hooks'. - - The `find-file-noselect' function returns the buffer that is - visiting the file FILENAME. - - (find-file-noselect "/etc/fstab") - => # - - - Command: find-file-other-window filename - This command selects a buffer visiting the file FILENAME, but does - so in a window other than the selected window. It may use another - existing window or split a window; see *Note Displaying Buffers::. - - When this command is called interactively, it prompts for FILENAME. - - - Command: find-file-read-only filename - This command selects a buffer visiting the file FILENAME, like - `find-file', but it marks the buffer as read-only. *Note Read - Only Buffers::, for related functions and variables. - - When this command is called interactively, it prompts for FILENAME. - - - Command: view-file filename - This command visits FILENAME in View mode, and displays it in a - recursive edit, returning to the previous buffer when done. View - mode is a mode that allows you to skim rapidly through the file - but does not let you modify it. Entering View mode runs the - normal hook `view-mode-hook'. *Note Hooks::. - - When `view-file' is called interactively, it prompts for FILENAME. - - - Variable: find-file-hooks - The value of this variable is a list of functions to be called - after a file is visited. The file's local-variables specification - (if any) will have been processed before the hooks are run. The - buffer visiting the file is current when the hook functions are - run. - - This variable works just like a normal hook, but we think that - renaming it would not be advisable. - - - Variable: find-file-not-found-hooks - The value of this variable is a list of functions to be called when - `find-file' or `find-file-noselect' is passed a nonexistent file - name. `find-file-noselect' calls these functions as soon as it - detects a nonexistent file. It calls them in the order of the - list, until one of them returns non-`nil'. `buffer-file-name' is - already set up. - - This is not a normal hook because the values of the functions are - used and they may not all be called. - - -File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files - -Subroutines of Visiting ------------------------ - - The `find-file-noselect' function uses the `create-file-buffer' and -`after-find-file' functions as subroutines. Sometimes it is useful to -call them directly. - - - Function: create-file-buffer filename - This function creates a suitably named buffer for visiting - FILENAME, and returns it. It uses FILENAME (sans directory) as - the name if that name is free; otherwise, it appends a string such - as `<2>' to get an unused name. See also *Note Creating Buffers::. - - *Please note:* `create-file-buffer' does _not_ associate the new - buffer with a file and does not select the buffer. It also does - not use the default major mode. - - (create-file-buffer "foo") - => # - (create-file-buffer "foo") - => #> - (create-file-buffer "foo") - => #> - - This function is used by `find-file-noselect'. It uses - `generate-new-buffer' (*note Creating Buffers::). - - - Function: after-find-file &optional error warn noauto - This function sets the buffer major mode, and parses local - variables (*note Auto Major Mode::). It is called by - `find-file-noselect' and by the default revert function (*note - Reverting::). - - If reading the file got an error because the file does not exist, - but its directory does exist, the caller should pass a non-`nil' - value for ERROR. In that case, `after-find-file' issues a warning: - `(New File)'. For more serious errors, the caller should usually - not call `after-find-file'. - - If WARN is non-`nil', then this function issues a warning if an - auto-save file exists and is more recent than the visited file. - - If NOAUTO is non-`nil', then this function does not turn on - auto-save mode; otherwise, it does. - - The last thing `after-find-file' does is call all the functions in - `find-file-hooks'. - diff --git a/info/lispref.info-23 b/info/lispref.info-23 index fa1b689..fa5cce6 100644 --- a/info/lispref.info-23 +++ b/info/lispref.info-23 @@ -50,6 +50,446 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation + +Help Functions +============== + + XEmacs provides a variety of on-line help functions, all accessible +to the user as subcommands of the prefix `C-h', or on some keyboards, +`help'. For more information about them, see *Note Help: (emacs)Help. +Here we describe some program-level interfaces to the same information. + + - Command: apropos regexp &optional do-all predicate + This function finds all symbols whose names contain a match for the + regular expression REGEXP, and returns a list of them (*note + Regular Expressions::). It also displays the symbols in a buffer + named `*Help*', each with a one-line description. + + If DO-ALL is non-`nil', then `apropos' also shows key bindings for + the functions that are found. + + If PREDICATE is non-`nil', it should be a function to be called on + each symbol that has matched REGEXP. Only symbols for which + PREDICATE returns a non-`nil' value are listed or displayed. + + In the first of the following examples, `apropos' finds all the + symbols with names containing `exec'. In the second example, it + finds and returns only those symbols that are also commands. (We + don't show the output that results in the `*Help*' buffer.) + + (apropos "exec") + => (Buffer-menu-execute command-execute exec-directory + exec-path execute-extended-command execute-kbd-macro + executing-kbd-macro executing-macro) + + (apropos "exec" nil 'commandp) + => (Buffer-menu-execute execute-extended-command) + + `apropos' is used by various user-level commands, such as `C-h a' + (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A' + (`command-apropos'), which does an apropos over only those + functions which are user commands. `command-apropos' calls + `apropos', specifying a PREDICATE to restrict the output to + symbols that are commands. The call to `apropos' looks like this: + + (apropos string t 'commandp) + + - Variable: help-map + The value of this variable is a local keymap for characters + following the Help key, `C-h'. + + - Prefix Command: help-command + This symbol is not a function; its function definition is actually + the keymap known as `help-map'. It is defined in `help.el' as + follows: + + (define-key global-map "\C-h" 'help-command) + (fset 'help-command help-map) + + - Function: print-help-return-message &optional function + This function builds a string that explains how to restore the + previous state of the windows after a help command. After + building the message, it applies FUNCTION to it if FUNCTION is + non-`nil'. Otherwise it calls `message' to display it in the echo + area. + + This function expects to be called inside a + `with-output-to-temp-buffer' special form, and expects + `standard-output' to have the value bound by that special form. + For an example of its use, see the long example in *Note Accessing + Documentation::. + + - Variable: help-char + The value of this variable is the help character--the character + that XEmacs recognizes as meaning Help. By default, it is the + character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this + character, if `help-form' is non-`nil' Lisp expression, it + evaluates that expression, and displays the result in a window if + it is a string. + + `help-char' can be a character or a key description such as `help' + or `(meta h)'. + + Usually the value of `help-form''s value is `nil'. Then the help + character has no special meaning at the level of command input, and + it becomes part of a key sequence in the normal way. The standard + key binding of `C-h' is a prefix key for several general-purpose + help features. + + The help character is special after prefix keys, too. If it has no + binding as a subcommand of the prefix key, it runs + `describe-prefix-bindings', which displays a list of all the + subcommands of the prefix key. + + - Variable: help-form + If this variable is non-`nil', its value is a form to evaluate + whenever the character `help-char' is read. If evaluating the form + produces a string, that string is displayed. + + A command that calls `next-command-event' or `next-event' probably + should bind `help-form' to a non-`nil' expression while it does + input. (The exception is when `C-h' is meaningful input.) + Evaluating this expression should result in a string that explains + what the input is for and how to enter it properly. + + Entry to the minibuffer binds this variable to the value of + `minibuffer-help-form' (*note Minibuffer Misc::). + + - Variable: prefix-help-command + This variable holds a function to print help for a prefix + character. The function is called when the user types a prefix + key followed by the help character, and the help character has no + binding after that prefix. The variable's default value is + `describe-prefix-bindings'. + + - Command: describe-prefix-bindings + This function calls `describe-bindings' to display a list of all + the subcommands of the prefix key of the most recent key sequence. + The prefix described consists of all but the last event of that + key sequence. (The last event is, presumably, the help character.) + + The following two functions are found in the library `helper'. They +are for modes that want to provide help without relinquishing control, +such as the "electric" modes. You must load that library with +`(require 'helper)' in order to use them. Their names begin with +`Helper' to distinguish them from the ordinary help functions. + + - Command: Helper-describe-bindings + This command pops up a window displaying a help buffer containing a + listing of all of the key bindings from both the local and global + keymaps. It works by calling `describe-bindings'. + + - Command: Helper-help + This command provides help for the current mode. It prompts the + user in the minibuffer with the message `Help (Type ? for further + options)', and then provides assistance in finding out what the key + bindings are, and what the mode is intended for. It returns `nil'. + + This can be customized by changing the map `Helper-help-map'. + + +File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation + +Obsoleteness +============ + + As you add functionality to a package, you may at times want to +replace an older function with a new one. To preserve compatibility +with existing code, the older function needs to still exist; but users +of that function should be told to use the newer one instead. XEmacs +Lisp lets you mark a function or variable as "obsolete", and indicate +what should be used instead. + + - Command: make-obsolete function new + This function indicates that FUNCTION is an obsolete function, and + the function NEW should be used instead. The byte compiler will + issue a warning to this effect when it encounters a usage of the + older function, and the help system will also note this in the + function's documentation. NEW can also be a string (if there is + not a single function with the same functionality any more), and + should be a descriptive statement, such as "use FOO or BAR + instead" or "this function is unnecessary". + + - Command: make-obsolete-variable variable new + This is like `make-obsolete' but is for variables instead of + functions. + + - Function: define-obsolete-function-alias oldfun newfun + This function combines `make-obsolete' and `define-function', + declaring OLDFUN to be an obsolete variant of NEWFUN and defining + OLDFUN as an alias for NEWFUN. + + - Function: define-obsolete-variable-alias oldvar newvar + This is like `define-obsolete-function-alias' but for variables. + + Note that you should not normally put obsoleteness information +explicitly in a function or variable's doc string. The obsoleteness +information that you specify using the above functions will be displayed +whenever the doc string is displayed, and by adding it explicitly the +result is redundancy. + + Also, if an obsolete function is substantially the same as a newer +one but is not actually an alias, you should consider omitting the doc +string entirely (use a null string `""' as the doc string). That way, +the user is told about the obsoleteness and is forced to look at the +documentation of the new function, making it more likely that he will +use the new function. + + - Function: function-obsoleteness-doc function + If FUNCTION is obsolete, this function returns a string describing + this. This is the message that is printed out during byte + compilation or in the function's documentation. If FUNCTION is + not obsolete, `nil' is returned. + + - Function: variable-obsoleteness-doc variable + This is like `function-obsoleteness-doc' but for variables. + + The obsoleteness information is stored internally by putting a +property `byte-obsolete-info' (for functions) or +`byte-obsolete-variable' (for variables) on the symbol that specifies +the obsolete function or variable. For more information, see the +implementation of `make-obsolete' and `make-obsolete-variable' in +`lisp/bytecomp/bytecomp-runtime.el'. + + +File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top + +Files +***** + + In XEmacs, you can find, create, view, save, and otherwise work with +files and file directories. This chapter describes most of the +file-related functions of XEmacs Lisp, but a few others are described in +*Note Buffers::, and those related to backups and auto-saving are +described in *Note Backups and Auto-Saving::. + + Many of the file functions take one or more arguments that are file +names. A file name is actually a string. Most of these functions +expand file name arguments using `expand-file-name', so that `~' is +handled correctly, as are relative file names (including `../'). These +functions don't recognize environment variable substitutions such as +`$HOME'. *Note File Name Expansion::. + +* Menu: + +* Visiting Files:: Reading files into Emacs buffers for editing. +* Saving Buffers:: Writing changed buffers back into files. +* Reading from Files:: Reading files into buffers without visiting. +* Writing to Files:: Writing new files from parts of buffers. +* File Locks:: Locking and unlocking files, to prevent + simultaneous editing by two people. +* Information about Files:: Testing existence, accessibility, size of files. +* Changing File Attributes:: Renaming files, changing protection, etc. +* File Names:: Decomposing and expanding file names. +* Contents of Directories:: Getting a list of the files in a directory. +* Create/Delete Dirs:: Creating and Deleting Directories. +* Magic File Names:: Defining "magic" special handling + for certain file names. +* Partial Files:: Treating a section of a buffer as a file. +* Format Conversion:: Conversion to and from various file formats. +* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS. + + +File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files + +Visiting Files +============== + + Visiting a file means reading a file into a buffer. Once this is +done, we say that the buffer is "visiting" that file, and call the file +"the visited file" of the buffer. + + A file and a buffer are two different things. A file is information +recorded permanently in the computer (unless you delete it). A buffer, +on the other hand, is information inside of XEmacs that will vanish at +the end of the editing session (or when you kill the buffer). Usually, +a buffer contains information that you have copied from a file; then we +say the buffer is visiting that file. The copy in the buffer is what +you modify with editing commands. Such changes to the buffer do not +change the file; therefore, to make the changes permanent, you must +"save" the buffer, which means copying the altered buffer contents back +into the file. + + In spite of the distinction between files and buffers, people often +refer to a file when they mean a buffer and vice-versa. Indeed, we say, +"I am editing a file," rather than, "I am editing a buffer that I will +soon save as a file of the same name." Humans do not usually need to +make the distinction explicit. When dealing with a computer program, +however, it is good to keep the distinction in mind. + +* Menu: + +* Visiting Functions:: The usual interface functions for visiting. +* Subroutines of Visiting:: Lower-level subroutines that they use. + + +File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files + +Functions for Visiting Files +---------------------------- + + This section describes the functions normally used to visit files. +For historical reasons, these functions have names starting with +`find-' rather than `visit-'. *Note Buffer File Name::, for functions +and variables that access the visited file name of a buffer or that +find an existing buffer by its visited file name. + + In a Lisp program, if you want to look at the contents of a file but +not alter it, the fastest way is to use `insert-file-contents' in a +temporary buffer. Visiting the file is not necessary and takes longer. +*Note Reading from Files::. + + - Command: find-file filename + This command selects a buffer visiting the file FILENAME, using an + existing buffer if there is one, and otherwise creating a new + buffer and reading the file into it. It also returns that buffer. + + The body of the `find-file' function is very simple and looks like + this: + + (switch-to-buffer (find-file-noselect filename)) + + (See `switch-to-buffer' in *Note Displaying Buffers::.) + + When `find-file' is called interactively, it prompts for FILENAME + in the minibuffer. + + - Function: find-file-noselect filename &optional nowarn + This function is the guts of all the file-visiting functions. It + finds or creates a buffer visiting the file FILENAME, and returns + it. It uses an existing buffer if there is one, and otherwise + creates a new buffer and reads the file into it. You may make the + buffer current or display it in a window if you wish, but this + function does not do so. + + When `find-file-noselect' uses an existing buffer, it first + verifies that the file has not changed since it was last visited or + saved in that buffer. If the file has changed, then this function + asks the user whether to reread the changed file. If the user says + `yes', any changes previously made in the buffer are lost. + + If `find-file-noselect' needs to create a buffer, and there is no + file named FILENAME, it displays the message `New file' in the + echo area, and leaves the buffer empty. + + If NOWARN is non-`nil', various warnings that XEmacs normally + gives (e.g. if another buffer is already visiting FILENAME but + FILENAME has been removed from disk since that buffer was created) + are suppressed. + + The `find-file-noselect' function calls `after-find-file' after + reading the file (*note Subroutines of Visiting::). That function + sets the buffer major mode, parses local variables, warns the user + if there exists an auto-save file more recent than the file just + visited, and finishes by running the functions in + `find-file-hooks'. + + The `find-file-noselect' function returns the buffer that is + visiting the file FILENAME. + + (find-file-noselect "/etc/fstab") + => # + + - Command: find-file-other-window filename + This command selects a buffer visiting the file FILENAME, but does + so in a window other than the selected window. It may use another + existing window or split a window; see *Note Displaying Buffers::. + + When this command is called interactively, it prompts for FILENAME. + + - Command: find-file-read-only filename + This command selects a buffer visiting the file FILENAME, like + `find-file', but it marks the buffer as read-only. *Note Read + Only Buffers::, for related functions and variables. + + When this command is called interactively, it prompts for FILENAME. + + - Command: view-file filename &optional other-window-p + This command visits FILENAME in View mode, and displays it in a + recursive edit, returning to the previous buffer when done. View + mode is a mode that allows you to skim rapidly through the file + but does not let you modify it. Entering View mode runs the + normal hook `view-mode-hook'. *Note Hooks::. + + When `view-file' is called interactively, it prompts for FILENAME. + + With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in + another window. + + - Variable: find-file-hooks + The value of this variable is a list of functions to be called + after a file is visited. The file's local-variables specification + (if any) will have been processed before the hooks are run. The + buffer visiting the file is current when the hook functions are + run. + + This variable works just like a normal hook, but we think that + renaming it would not be advisable. + + - Variable: find-file-not-found-hooks + The value of this variable is a list of functions to be called when + `find-file' or `find-file-noselect' is passed a nonexistent file + name. `find-file-noselect' calls these functions as soon as it + detects a nonexistent file. It calls them in the order of the + list, until one of them returns non-`nil'. `buffer-file-name' is + already set up. + + This is not a normal hook because the values of the functions are + used and they may not all be called. + + +File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files + +Subroutines of Visiting +----------------------- + + The `find-file-noselect' function uses the `create-file-buffer' and +`after-find-file' functions as subroutines. Sometimes it is useful to +call them directly. + + - Function: create-file-buffer filename + This function creates a suitably named buffer for visiting + FILENAME, and returns it. It uses FILENAME (sans directory) as + the name if that name is free; otherwise, it appends a string such + as `<2>' to get an unused name. See also *Note Creating Buffers::. + + *Please note:* `create-file-buffer' does _not_ associate the new + buffer with a file and does not select the buffer. It also does + not use the default major mode. + + (create-file-buffer "foo") + => # + (create-file-buffer "foo") + => #> + (create-file-buffer "foo") + => #> + + This function is used by `find-file-noselect'. It uses + `generate-new-buffer' (*note Creating Buffers::). + + - Function: after-find-file &optional error warn noauto + This function sets the buffer major mode, and parses local + variables (*note Auto Major Mode::). It is called by + `find-file-noselect' and by the default revert function (*note + Reverting::). + + If reading the file got an error because the file does not exist, + but its directory does exist, the caller should pass a non-`nil' + value for ERROR. In that case, `after-find-file' issues a warning: + `(New File)'. For more serious errors, the caller should usually + not call `after-find-file'. + + If WARN is non-`nil', then this function issues a warning if an + auto-save file exists and is more recent than the visited file. + + If NOAUTO is non-`nil', then this function does not turn on + auto-save mode; otherwise, it does. + + The last thing `after-find-file' does is call all the functions in + `find-file-hooks'. + + File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files Saving Buffers @@ -188,7 +628,7 @@ Reading from Files 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 + - Function: insert-file-contents filename &optional visit start end replace This function inserts the contents of file FILENAME into the current buffer after point. It returns a list of the absolute @@ -207,7 +647,7 @@ the `insert-file-contents' function. Don't use the user-level command 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 + If START 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, @@ -324,10 +764,10 @@ cases of simultaneous editing; see *Note Modification Time::. 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: + - Function: ask-user-about-lock filename other-user + This function is called when the user tries to modify FILENAME, + 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. @@ -341,9 +781,9 @@ cases of simultaneous editing; see *Note Modification Time::. The error message for this error looks like this: - error--> File is locked: FILE OTHER-USER + error--> File is locked: FILENAME OTHER-USER - where `file' is the name of the file and OTHER-USER is the + where FILENAME 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 @@ -696,563 +1136,3 @@ and modification. `-32252' is on file system number -32252. - -File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files - -Changing File Names and Attributes -================================== - - The functions in this section rename, copy, delete, link, and set the -modes of files. - - In the functions that have an argument NEWNAME, if a file by the -name of NEWNAME already exists, the actions taken depend on the value -of the argument OK-IF-ALREADY-EXISTS: - - * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is - `nil'. - - * Request confirmation if OK-IF-ALREADY-EXISTS is a number. - - * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS - is any other value. - - - Command: add-name-to-file oldname newname &optional - ok-if-already-exists - This function gives the file named OLDNAME the additional name - NEWNAME. This means that NEWNAME becomes a new "hard link" to - OLDNAME. - - In the first part of the following example, we list two files, - `foo' and `foo3'. - - % ls -l fo* - -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo - -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 - - Then we evaluate the form `(add-name-to-file "~/lewis/foo" - "~/lewis/foo2")'. Again we list the files. This shows two names, - `foo' and `foo2'. - - (add-name-to-file "~/lewis/foo1" "~/lewis/foo2") - => nil - - % ls -l fo* - -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo - -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 - -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 - - Finally, we evaluate the following: - - (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t) - - and list the files again. Now there are three names for one file: - `foo', `foo2', and `foo3'. The old contents of `foo3' are lost. - - (add-name-to-file "~/lewis/foo1" "~/lewis/foo3") - => nil - - % ls -l fo* - -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo - -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 - -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 - - This function is meaningless on VMS, where multiple names for one - file are not allowed. - - See also `file-nlinks' in *Note File Attributes::. - - - Command: rename-file filename newname &optional ok-if-already-exists - This command renames the file FILENAME as NEWNAME. - - If FILENAME has additional names aside from FILENAME, it continues - to have those names. In fact, adding the name NEWNAME with - `add-name-to-file' and then deleting FILENAME has the same effect - as renaming, aside from momentary intermediate states. - - In an interactive call, this function prompts for FILENAME and - NEWNAME in the minibuffer; also, it requests confirmation if - NEWNAME already exists. - - - Command: copy-file oldname newname &optional ok-if-exists time - This command copies the file OLDNAME to NEWNAME. An error is - signaled if OLDNAME does not exist. - - If TIME is non-`nil', then this functions gives the new file the - same last-modified time that the old one has. (This works on only - some operating systems.) - - In an interactive call, this function prompts for FILENAME and - NEWNAME in the minibuffer; also, it requests confirmation if - NEWNAME already exists. - - - Command: delete-file filename - This command deletes the file FILENAME, like the shell command `rm - FILENAME'. If the file has multiple names, it continues to exist - under the other names. - - A suitable kind of `file-error' error is signaled if the file does - not exist, or is not deletable. (On Unix, a file is deletable if - its directory is writable.) - - See also `delete-directory' in *Note Create/Delete Dirs::. - - - Command: make-symbolic-link filename newname &optional ok-if-exists - This command makes a symbolic link to FILENAME, named NEWNAME. - This is like the shell command `ln -s FILENAME NEWNAME'. - - In an interactive call, this function prompts for FILENAME and - NEWNAME in the minibuffer; also, it requests confirmation if - NEWNAME already exists. - - - Function: define-logical-name varname string - This function defines the logical name NAME to have the value - STRING. It is available only on VMS. - - - Function: set-file-modes filename mode - This function sets mode bits of FILENAME to MODE (which must be an - integer). Only the low 12 bits of MODE are used. - - - Function: set-default-file-modes mode - This function sets the default file protection for new files - created by XEmacs and its subprocesses. Every file created with - XEmacs initially has this protection. On Unix, the default - protection is the bitwise complement of the "umask" value. - - The argument MODE must be an integer. Only the low 9 bits of MODE - are used. - - Saving a modified version of an existing file does not count as - creating the file; it does not change the file's mode, and does - not use the default file protection. - - - Function: default-file-modes - This function returns the current default protection value. - - On MS-DOS, there is no such thing as an "executable" file mode bit. -So Emacs considers a file executable if its name ends in `.com', `.bat' -or `.exe'. This is reflected in the values returned by `file-modes' -and `file-attributes'. - - -File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files - -File Names -========== - - Files are generally referred to by their names, in XEmacs as -elsewhere. File names in XEmacs are represented as strings. The -functions that operate on a file all expect a file name argument. - - In addition to operating on files themselves, XEmacs Lisp programs -often need to operate on the names; i.e., to take them apart and to use -part of a name to construct related file names. This section describes -how to manipulate file names. - - The functions in this section do not actually access files, so they -can operate on file names that do not refer to an existing file or -directory. - - On VMS, all these functions understand both VMS file-name syntax and -Unix syntax. This is so that all the standard Lisp libraries can -specify file names in Unix syntax and work properly on VMS without -change. On MS-DOS, these functions understand MS-DOS file-name syntax -as well as Unix syntax. - -* Menu: - -* File Name Components:: The directory part of a file name, and the rest. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* Relative File Names:: Some file names are relative to a current directory. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* User Name Completion:: Finding the completions for a given user name. - - -File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names - -File Name Components --------------------- - - The operating system groups files into directories. To specify a -file, you must specify the directory and the file's name within that -directory. Therefore, XEmacs considers a file name as having two main -parts: the "directory name" part, and the "nondirectory" part (or "file -name within the directory"). Either part may be empty. Concatenating -these two parts reproduces the original file name. - - On Unix, the directory part is everything up to and including the -last slash; the nondirectory part is the rest. The rules in VMS syntax -are complicated. - - For some purposes, the nondirectory part is further subdivided into -the name proper and the "version number". On Unix, only backup files -have version numbers in their names; on VMS, every file has a version -number, but most of the time the file name actually used in XEmacs -omits the version number. Version numbers are found mostly in -directory lists. - - - Function: file-name-directory filename - This function returns the directory part of FILENAME (or `nil' if - FILENAME does not include a directory part). On Unix, the - function returns a string ending in a slash. On VMS, it returns a - string ending in one of the three characters `:', `]', or `>'. - - (file-name-directory "lewis/foo") ; Unix example - => "lewis/" - (file-name-directory "foo") ; Unix example - => nil - (file-name-directory "[X]FOO.TMP") ; VMS example - => "[X]" - - - Function: file-name-nondirectory filename - This function returns the nondirectory part of FILENAME. - - (file-name-nondirectory "lewis/foo") - => "foo" - (file-name-nondirectory "foo") - => "foo" - ;; The following example is accurate only on VMS. - (file-name-nondirectory "[X]FOO.TMP") - => "FOO.TMP" - - - Function: file-name-sans-versions filename &optional - keep-backup-version - This function returns FILENAME without any file version numbers, - backup version numbers, or trailing tildes. - - If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup - version numbers, only true file version numbers. - - (file-name-sans-versions "~rms/foo.~1~") - => "~rms/foo" - (file-name-sans-versions "~rms/foo~") - => "~rms/foo" - (file-name-sans-versions "~rms/foo") - => "~rms/foo" - ;; The following example applies to VMS only. - (file-name-sans-versions "foo;23") - => "foo" - - - Function: file-name-sans-extension filename - This function returns FILENAME minus its "extension," if any. The - extension, in a file name, is the part that starts with the last - `.' in the last name component. For example, - - (file-name-sans-extension "foo.lose.c") - => "foo.lose" - (file-name-sans-extension "big.hack/foo") - => "big.hack/foo" - - -File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names - -Directory Names ---------------- - - A "directory name" is the name of a directory. A directory is a -kind of file, and it has a file name, which is related to the directory -name but not identical to it. (This is not quite the same as the usual -Unix terminology.) These two different names for the same entity are -related by a syntactic transformation. On Unix, this is simple: a -directory name ends in a slash, whereas the directory's name as a file -lacks that slash. On VMS, the relationship is more complicated. - - The difference between a directory name and its name as a file is -subtle but crucial. When an XEmacs variable or function argument is -described as being a directory name, a file name of a directory is not -acceptable. - - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as `$HOME', and the constructs `~', and `..'. - - - Function: file-name-as-directory filename - This function returns a string representing FILENAME in a form - that the operating system will interpret as the name of a - directory. In Unix, this means appending a slash to the string. - On VMS, the function converts a string of the form `[X]Y.DIR.1' to - the form `[X.Y]'. - - (file-name-as-directory "~rms/lewis") - => "~rms/lewis/" - - - Function: directory-file-name dirname - This function returns a string representing DIRNAME in a form that - the operating system will interpret as the name of a file. On - Unix, this means removing a final slash from the string. On VMS, - the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'. - - (directory-file-name "~lewis/") - => "~lewis" - - Directory name abbreviations are useful for directories that are -normally accessed through symbolic links. Sometimes the users recognize -primarily the link's name as "the name" of the directory, and find it -annoying to see the directory's "real" name. If you define the link -name as an abbreviation for the "real" name, XEmacs shows users the -abbreviation instead. - - If you wish to convert a directory name to its abbreviation, use this -function: - - - Function: abbreviate-file-name dirname &optional hack-homedir - This function applies abbreviations from `directory-abbrev-alist' - to its argument, and substitutes `~' for the user's home directory. - - If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for - the user's home directory. - - - - Variable: directory-abbrev-alist - The variable `directory-abbrev-alist' contains an alist of - abbreviations to use for file directories. Each element has the - form `(FROM . TO)', and says to replace FROM with TO when it - appears in a directory name. The FROM string is actually a - regular expression; it should always start with `^'. The function - `abbreviate-file-name' performs these substitutions. - - You can set this variable in `site-init.el' to describe the - abbreviations appropriate for your site. - - Here's an example, from a system on which file system `/home/fsf' - and so on are normally accessed through symbolic links named `/fsf' - and so on. - - (("^/home/fsf" . "/fsf") - ("^/home/gp" . "/gp") - ("^/home/gd" . "/gd")) - - -File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names - -Absolute and Relative File Names --------------------------------- - - All the directories in the file system form a tree starting at the -root directory. A file name can specify all the directory names -starting from the root of the tree; then it is called an "absolute" -file name. Or it can specify the position of the file in the tree -relative to a default directory; then it is called a "relative" file -name. On Unix, an absolute file name starts with a slash or a tilde -(`~'), and a relative one does not. The rules on VMS are complicated. - - - Function: file-name-absolute-p filename - This function returns `t' if file FILENAME is an absolute file - name, `nil' otherwise. On VMS, this function understands both - Unix syntax and VMS syntax. - - (file-name-absolute-p "~rms/foo") - => t - (file-name-absolute-p "rms/foo") - => nil - (file-name-absolute-p "/user/rms/foo") - => t - - -File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names - -Functions that Expand Filenames -------------------------------- - - "Expansion" of a file name means converting a relative file name to -an absolute one. Since this is done relative to a default directory, -you must specify the default directory name as well as the file name to -be expanded. Expansion also simplifies file names by eliminating -redundancies such as `./' and `NAME/../'. - - - Function: expand-file-name filename &optional directory - This function converts FILENAME to an absolute file name. If - DIRECTORY is supplied, it is the directory to start with if - FILENAME is relative. (The value of DIRECTORY should itself be an - absolute directory name; it may start with `~'.) Otherwise, the - current buffer's value of `default-directory' is used. For - example: - - (expand-file-name "foo") - => "/xcssun/users/rms/lewis/foo" - (expand-file-name "../foo") - => "/xcssun/users/rms/foo" - (expand-file-name "foo" "/usr/spool/") - => "/usr/spool/foo" - (expand-file-name "$HOME/foo") - => "/xcssun/users/rms/lewis/$HOME/foo" - - Filenames containing `.' or `..' are simplified to their canonical - form: - - (expand-file-name "bar/../foo") - => "/xcssun/users/rms/lewis/foo" - - `~/' at the beginning is expanded into the user's home directory. - A `/' or `~' following a `/'. - - Note that `expand-file-name' does _not_ expand environment - variables; only `substitute-in-file-name' does that. - - - Function: file-relative-name filename &optional directory - This function does the inverse of expansion--it tries to return a - relative name that is equivalent to FILENAME when interpreted - relative to DIRECTORY. - - If DIRECTORY is `nil' or omitted, the value of `default-directory' - is used. - - (file-relative-name "/foo/bar" "/foo/") - => "bar") - (file-relative-name "/foo/bar" "/hack/") - => "../foo/bar") - - - Variable: default-directory - The value of this buffer-local variable is the default directory - for the current buffer. It should be an absolute directory name; - it may start with `~'. This variable is local in every buffer. - - `expand-file-name' uses the default directory when its second - argument is `nil'. - - On Unix systems, the value is always a string ending with a slash. - - default-directory - => "/user/lewis/manual/" - - - Function: substitute-in-file-name filename - This function replaces environment variable references in FILENAME - with the environment variable values. Following standard Unix - shell syntax, `$' is the prefix to substitute an environment - variable value. - - The environment variable name is the series of alphanumeric - characters (including underscores) that follow the `$'. If the - character following the `$' is a `{', then the variable name is - everything up to the matching `}'. - - Here we assume that the environment variable `HOME', which holds - the user's home directory name, has value `/xcssun/users/rms'. - - (substitute-in-file-name "$HOME/foo") - => "/xcssun/users/rms/foo" - - After substitution, a `/' or `~' following a `/' is taken to be - the start of an absolute file name that overrides what precedes - it, so everything before that `/' or `~' is deleted. For example: - - (substitute-in-file-name "bar/~/foo") - => "~/foo" - (substitute-in-file-name "/usr/local/$HOME/foo") - => "/xcssun/users/rms/foo" - - On VMS, `$' substitution is not done, so this function does nothing - on VMS except discard superfluous initial components as shown - above. - - -File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names - -Generating Unique File Names ----------------------------- - - Some programs need to write temporary files. Here is the usual way -to construct a name for such a file: - - (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory))) - -Here we use `(temp-directory)' to specify a directory for temporary -files--under Unix, it will normally evaluate to `"/tmp/"'. The job of -`make-temp-name' is to prevent two different users or two different -processes from trying to use the same name. - - - Function: temp-directory - This function returns the name of the directory to use for - temporary files. Under Unix, this will be the value of `TMPDIR', - defaulting to `/tmp'. On Windows, this will be obtained from the - `TEMP' or `TMP' environment variables, defaulting to `/'. - - Note that the `temp-directory' function does not exist under FSF - Emacs. - - - Function: make-temp-name prefix - This function generates a temporary file name starting with - PREFIX. The Emacs process number forms part of the result, so - there is no danger of generating a name being used by another - process. - - (make-temp-name "/tmp/foo") - => "/tmp/fooGaAQjC" - - In addition, this function makes an attempt to choose a name that - does not specify an existing file. To make this work, PREFIX - should be an absolute file name. - - To avoid confusion, each Lisp application should preferably use a - unique PREFIX to `make-temp-name'. - - -File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names - -File Name Completion --------------------- - - This section describes low-level subroutines for completing a file -name. For other completion functions, see *Note Completion::. - - - Function: file-name-all-completions partial-filename directory - This function returns a list of all possible completions for a file - whose name starts with PARTIAL-FILENAME in directory DIRECTORY. - The order of the completions is the order of the files in the - directory, which is unpredictable and conveys no useful - information. - - The argument PARTIAL-FILENAME must be a file name containing no - directory part and no slash. The current buffer's default - directory is prepended to DIRECTORY, if DIRECTORY is not absolute. - - In the following example, suppose that the current default - directory, `~rms/lewis', has five files whose names begin with `f': - `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'. - - (file-name-all-completions "f" "") - => ("foo" "file~" "file.c.~2~" - "file.c.~1~" "file.c") - - (file-name-all-completions "fo" "") - => ("foo") - - - Function: file-name-completion filename directory - This function completes the file name FILENAME in directory - DIRECTORY. It returns the longest prefix common to all file names - in directory DIRECTORY that start with FILENAME. - - If only one match exists and FILENAME matches it exactly, the - function returns `t'. The function returns `nil' if directory - DIRECTORY contains no name starting with FILENAME. - - In the following example, suppose that the current default - directory has five files whose names begin with `f': `foo', - `file~', `file.c', `file.c.~1~', and `file.c.~2~'. - - (file-name-completion "fi" "") - => "file" - - (file-name-completion "file.c.~1" "") - => "file.c.~1~" - - (file-name-completion "file.c.~1~" "") - => t - - (file-name-completion "file.c.~3" "") - => nil - - - User Option: completion-ignored-extensions - `file-name-completion' usually ignores file names that end in any - string in this list. It does not ignore them when all the possible - completions end in one of these suffixes or when a buffer showing - all possible completions is displayed. - - A typical value might look like this: - - completion-ignored-extensions - => (".o" ".elc" "~" ".dvi") - diff --git a/info/lispref.info-24 b/info/lispref.info-24 index f8d1d65..a777571 100644 --- a/info/lispref.info-24 +++ b/info/lispref.info-24 @@ -50,6 +50,555 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files + +Changing File Names and Attributes +================================== + + The functions in this section rename, copy, delete, link, and set the +modes of files. + + In the functions that have arguments NEWNAME and +OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists, +the actions taken depend on the value of OK-IF-ALREADY-EXISTS: + + * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is + `nil'. + + * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is + what happens when the function is invoked interactively. + + * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS + is any other value. + + - Command: add-name-to-file filename newname &optional + ok-if-already-exists + This function gives the file named FILENAME the additional name + NEWNAME. This means that NEWNAME becomes a new "hard link" to + FILENAME. Both these arguments must be strings. + + In the first part of the following example, we list two files, + `foo' and `foo3'. + + % ls -l fo* + -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo + -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 + + Then we evaluate the form `(add-name-to-file "~/lewis/foo" + "~/lewis/foo2")'. Again we list the files. This shows two names, + `foo' and `foo2'. + + (add-name-to-file "~/lewis/foo1" "~/lewis/foo2") + => nil + + % ls -l fo* + -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo + -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 + -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 + + Finally, we evaluate the following: + + (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t) + + and list the files again. Now there are three names for one file: + `foo', `foo2', and `foo3'. The old contents of `foo3' are lost. + + (add-name-to-file "~/lewis/foo1" "~/lewis/foo3") + => nil + + % ls -l fo* + -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo + -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 + -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 + + This function is meaningless on non-Unix systems, where multiple + names for one file are not allowed. + + See also `file-nlinks' in *Note File Attributes::. + + - Command: rename-file filename newname &optional ok-if-already-exists + This command renames the file FILENAME as NEWNAME. + + If FILENAME has additional names aside from FILENAME, it continues + to have those names. In fact, adding the name NEWNAME with + `add-name-to-file' and then deleting FILENAME has the same effect + as renaming, aside from momentary intermediate states. + + In an interactive call, this function prompts for FILENAME and + NEWNAME in the minibuffer; also, it requests confirmation if + NEWNAME already exists. + + - Command: copy-file filename newname &optional ok-if-already-exists + time + This command copies the file FILENAME to NEWNAME. An error is + signaled if FILENAME does not exist. + + If TIME is non-`nil', then this functions gives the new file the + same last-modified time that the old one has. (This works on only + some operating systems.) + + In an interactive call, this function prompts for FILENAME and + NEWNAME in the minibuffer; also, it requests confirmation if + NEWNAME already exists. + + - Command: delete-file filename + This command deletes the file FILENAME, like the shell command `rm + FILENAME'. If the file has multiple names, it continues to exist + under the other names. + + A suitable kind of `file-error' error is signaled if the file does + not exist, or is not deletable. (On Unix, a file is deletable if + its directory is writable.) + + See also `delete-directory' in *Note Create/Delete Dirs::. + + - Command: make-symbolic-link filename newname &optional + ok-if-already-exists + This command makes a symbolic link to FILENAME, named NEWNAME. + This is like the shell command `ln -s FILENAME NEWNAME'. + + In an interactive call, this function prompts for FILENAME and + NEWNAME in the minibuffer; also, it requests confirmation if + NEWNAME already exists. + + - Function: set-file-modes filename mode + This function sets mode bits of FILENAME to MODE (which must be an + integer). Only the low 12 bits of MODE are used. + + - Function: set-default-file-modes mode + This function sets the default file protection for new files + created by XEmacs and its subprocesses. Every file created with + XEmacs initially has this protection. On Unix, the default + protection is the bitwise complement of the "umask" value. + + The argument MODE must be an integer. Only the low 9 bits of MODE + are used. + + Saving a modified version of an existing file does not count as + creating the file; it does not change the file's mode, and does + not use the default file protection. + + - Function: default-file-modes + This function returns the current default protection value. + + On MS-DOS, there is no such thing as an "executable" file mode bit. +So Emacs considers a file executable if its name ends in `.com', `.bat' +or `.exe'. This is reflected in the values returned by `file-modes' +and `file-attributes'. + + +File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files + +File Names +========== + + Files are generally referred to by their names, in XEmacs as +elsewhere. File names in XEmacs are represented as strings. The +functions that operate on a file all expect a file name argument. + + In addition to operating on files themselves, XEmacs Lisp programs +often need to operate on the names; i.e., to take them apart and to use +part of a name to construct related file names. This section describes +how to manipulate file names. + + The functions in this section do not actually access files, so they +can operate on file names that do not refer to an existing file or +directory. + + On MS-DOS, these functions understand MS-DOS file-name syntax as +well as Unix syntax. This is so that all the standard Lisp libraries +can specify file names in Unix syntax and work properly on all systems +without change. Similarly for other operating systems. + +* Menu: + +* File Name Components:: The directory part of a file name, and the rest. +* Directory Names:: A directory's name as a directory + is different from its name as a file. +* Relative File Names:: Some file names are relative to a current directory. +* File Name Expansion:: Converting relative file names to absolute ones. +* Unique File Names:: Generating names for temporary files. +* File Name Completion:: Finding the completions for a given file name. +* User Name Completion:: Finding the completions for a given user name. + + +File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names + +File Name Components +-------------------- + + The operating system groups files into directories. To specify a +file, you must specify the directory and the file's name within that +directory. Therefore, XEmacs considers a file name as having two main +parts: the "directory name" part, and the "nondirectory" part (or "file +name within the directory"). Either part may be empty. Concatenating +these two parts reproduces the original file name. + + On Unix, the directory part is everything up to and including the +last slash; the nondirectory part is the rest. + + For some purposes, the nondirectory part is further subdivided into +the name proper and the "version number". On Unix, only backup files +have version numbers in their names. + + - Function: file-name-directory filename + This function returns the directory part of FILENAME (or `nil' if + FILENAME does not include a directory part). On Unix, the + function returns a string ending in a slash. + + (file-name-directory "lewis/foo") ; Unix example + => "lewis/" + (file-name-directory "foo") ; Unix example + => nil + + - Function: file-name-nondirectory filename + This function returns the nondirectory part of FILENAME. + + (file-name-nondirectory "lewis/foo") + => "foo" + (file-name-nondirectory "foo") + => "foo" + + - Function: file-name-sans-versions filename &optional + keep-backup-version + This function returns FILENAME without any file version numbers, + backup version numbers, or trailing tildes. + + If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup + version numbers, only true file version numbers. + + (file-name-sans-versions "~rms/foo.~1~") + => "~rms/foo" + (file-name-sans-versions "~rms/foo~") + => "~rms/foo" + (file-name-sans-versions "~rms/foo") + => "~rms/foo" + + - Function: file-name-sans-extension filename + This function returns FILENAME minus its "extension," if any. The + extension, in a file name, is the part that starts with the last + `.' in the last name component. For example, + + (file-name-sans-extension "foo.lose.c") + => "foo.lose" + (file-name-sans-extension "big.hack/foo") + => "big.hack/foo" + + +File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names + +Directory Names +--------------- + + A "directory name" is the name of a directory. A directory is a +kind of file, and it has a file name, which is related to the directory +name but not identical to it. (This is not quite the same as the usual +Unix terminology.) These two different names for the same entity are +related by a syntactic transformation. On Unix, this is simple: a +directory name ends in a slash, whereas the directory's name as a file +lacks that slash. + + The difference between a directory name and its name as a file is +subtle but crucial. When an XEmacs variable or function argument is +described as being a directory name, a file name of a directory is not +acceptable. + + The following two functions convert between directory names and file +names. They do nothing special with environment variable substitutions +such as `$HOME', and the constructs `~', and `..'. + + - Function: file-name-as-directory filename + This function returns a string representing FILENAME in a form + that the operating system will interpret as the name of a + directory. In Unix, this means appending a slash to the string. + + (file-name-as-directory "~rms/lewis") + => "~rms/lewis/" + + - Function: directory-file-name dirname + This function returns a string representing DIRNAME in a form that + the operating system will interpret as the name of a file. On + Unix, this means removing a final slash from the string. + + (directory-file-name "~lewis/") + => "~lewis" + + Directory name abbreviations are useful for directories that are +normally accessed through symbolic links. Sometimes the users recognize +primarily the link's name as "the name" of the directory, and find it +annoying to see the directory's "real" name. If you define the link +name as an abbreviation for the "real" name, XEmacs shows users the +abbreviation instead. + + If you wish to convert a directory name to its abbreviation, use this +function: + + - Function: abbreviate-file-name filename &optional hack-homedir + This function applies abbreviations from `directory-abbrev-alist' + to its argument, and substitutes `~' for the user's home directory. + + If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for + the user's home directory. + + + - Variable: directory-abbrev-alist + The variable `directory-abbrev-alist' contains an alist of + abbreviations to use for file directories. Each element has the + form `(FROM . TO)', and says to replace FROM with TO when it + appears in a directory name. The FROM string is actually a + regular expression; it should always start with `^'. The function + `abbreviate-file-name' performs these substitutions. + + You can set this variable in `site-init.el' to describe the + abbreviations appropriate for your site. + + Here's an example, from a system on which file system `/home/fsf' + and so on are normally accessed through symbolic links named `/fsf' + and so on. + + (("^/home/fsf" . "/fsf") + ("^/home/gp" . "/gp") + ("^/home/gd" . "/gd")) + + +File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names + +Absolute and Relative File Names +-------------------------------- + + All the directories in the file system form a tree starting at the +root directory. A file name can specify all the directory names +starting from the root of the tree; then it is called an "absolute" +file name. Or it can specify the position of the file in the tree +relative to a default directory; then it is called a "relative" file +name. On Unix, an absolute file name starts with a slash or a tilde +(`~'), and a relative one does not. + + - Function: file-name-absolute-p filename + This function returns `t' if file FILENAME is an absolute file + name, `nil' otherwise. + + (file-name-absolute-p "~rms/foo") + => t + (file-name-absolute-p "rms/foo") + => nil + (file-name-absolute-p "/user/rms/foo") + => t + + +File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names + +Functions that Expand Filenames +------------------------------- + + "Expansion" of a file name means converting a relative file name to +an absolute one. Since this is done relative to a default directory, +you must specify the default directory name as well as the file name to +be expanded. Expansion also simplifies file names by eliminating +redundancies such as `./' and `NAME/../'. + + - Function: expand-file-name filename &optional directory + This function converts FILENAME to an absolute file name. If + DIRECTORY is supplied, it is the directory to start with if + FILENAME is relative. (The value of DIRECTORY should itself be an + absolute directory name; it may start with `~'.) Otherwise, the + current buffer's value of `default-directory' is used. For + example: + + (expand-file-name "foo") + => "/xcssun/users/rms/lewis/foo" + (expand-file-name "../foo") + => "/xcssun/users/rms/foo" + (expand-file-name "foo" "/usr/spool/") + => "/usr/spool/foo" + (expand-file-name "$HOME/foo") + => "/xcssun/users/rms/lewis/$HOME/foo" + + Filenames containing `.' or `..' are simplified to their canonical + form: + + (expand-file-name "bar/../foo") + => "/xcssun/users/rms/lewis/foo" + + `~/' at the beginning is expanded into the user's home directory. + A `/' or `~' following a `/'. + + Note that `expand-file-name' does _not_ expand environment + variables; only `substitute-in-file-name' does that. + + - Function: file-relative-name filename &optional directory + This function does the inverse of expansion--it tries to return a + relative name that is equivalent to FILENAME when interpreted + relative to DIRECTORY. + + If DIRECTORY is `nil' or omitted, the value of `default-directory' + is used. + + (file-relative-name "/foo/bar" "/foo/") + => "bar") + (file-relative-name "/foo/bar" "/hack/") + => "../foo/bar") + + - Variable: default-directory + The value of this buffer-local variable is the default directory + for the current buffer. It should be an absolute directory name; + it may start with `~'. This variable is local in every buffer. + + `expand-file-name' uses the default directory when its second + argument is `nil'. + + On Unix systems, the value is always a string ending with a slash. + + default-directory + => "/user/lewis/manual/" + + - Function: substitute-in-file-name filename + This function replaces environment variable references in FILENAME + with the environment variable values. Following standard Unix + shell syntax, `$' is the prefix to substitute an environment + variable value. + + The environment variable name is the series of alphanumeric + characters (including underscores) that follow the `$'. If the + character following the `$' is a `{', then the variable name is + everything up to the matching `}'. + + Here we assume that the environment variable `HOME', which holds + the user's home directory name, has value `/xcssun/users/rms'. + + (substitute-in-file-name "$HOME/foo") + => "/xcssun/users/rms/foo" + + After substitution, a `/' or `~' following a `/' is taken to be + the start of an absolute file name that overrides what precedes + it, so everything before that `/' or `~' is deleted. For example: + + (substitute-in-file-name "bar/~/foo") + => "~/foo" + (substitute-in-file-name "/usr/local/$HOME/foo") + => "/xcssun/users/rms/foo" + + +File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names + +Generating Unique File Names +---------------------------- + + Some programs need to write temporary files. Here is the usual way +to construct a name for such a file: + + (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory))) + +Here we use `(temp-directory)' to specify a directory for temporary +files--under Unix, it will normally evaluate to `"/tmp/"'. The job of +`make-temp-name' is to prevent two different users or two different +processes from trying to use the same name. + + - Function: temp-directory + This function returns the name of the directory to use for + temporary files. Under Unix, this will be the value of `TMPDIR', + defaulting to `/tmp'. On Windows, this will be obtained from the + `TEMP' or `TMP' environment variables, defaulting to `/'. + + Note that the `temp-directory' function does not exist under FSF + Emacs. + + - Function: make-temp-name prefix + This function generates a temporary file name starting with + PREFIX. The Emacs process number forms part of the result, so + there is no danger of generating a name being used by another + process. + + (make-temp-name "/tmp/foo") + => "/tmp/fooGaAQjC" + + In addition, this function makes an attempt to choose a name that + does not specify an existing file. To make this work, PREFIX + should be an absolute file name. + + To avoid confusion, each Lisp application should preferably use a + unique PREFIX to `make-temp-name'. + + +File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names + +File Name Completion +-------------------- + + This section describes low-level subroutines for completing a file +name. For other completion functions, see *Note Completion::. + + - Function: file-name-all-completions partial-filename directory + This function returns a list of all possible completions for files + whose name starts with PARTIAL-FILENAME in directory DIRECTORY. + The order of the completions is the order of the files in the + directory, which is unpredictable and conveys no useful + information. + + The argument PARTIAL-FILENAME must be a file name containing no + directory part and no slash. The current buffer's default + directory is prepended to DIRECTORY, if DIRECTORY is not absolute. + + File names which end with any member of + `completion-ignored-extensions' are not considered as possible + completions for PARTIAL-FILENAME unless there is no other possible + completion. `completion-ignored-extensions' is not applied to the + names of directories. + + In the following example, suppose that the current default + directory, `~rms/lewis', has five files whose names begin with `f': + `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'. + + (file-name-all-completions "f" "") + => ("foo" "file~" "file.c.~2~" + "file.c.~1~" "file.c") + + (file-name-all-completions "fo" "") + => ("foo") + + - Function: file-name-completion partial-filename directory + This function completes the file name PARTIAL-FILENAME in directory + DIRECTORY. It returns the longest prefix common to all file names + in directory DIRECTORY that start with PARTIAL-FILENAME. + + If only one match exists and PARTIAL-FILENAME matches it exactly, + the function returns `t'. The function returns `nil' if directory + DIRECTORY contains no name starting with PARTIAL-FILENAME. + + File names which end with any member of + `completion-ignored-extensions' are not considered as possible + completions for PARTIAL-FILENAME unless there is no other possible + completion. `completion-ignored-extensions' is not applied to the + names of directories. + + In the following example, suppose that the current default + directory has five files whose names begin with `f': `foo', + `file~', `file.c', `file.c.~1~', and `file.c.~2~'. + + (file-name-completion "fi" "") + => "file" + + (file-name-completion "file.c.~1" "") + => "file.c.~1~" + + (file-name-completion "file.c.~1~" "") + => t + + (file-name-completion "file.c.~3" "") + => nil + + - User Option: completion-ignored-extensions + `file-name-completion' usually ignores file names that end in any + string in this list. It does not ignore them when all the possible + completions end in one of these suffixes or when a buffer showing + all possible completions is displayed. + + A typical value might look like this: + + completion-ignored-extensions + => (".o" ".elc" "~" ".dvi") + + File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names User Name Completion @@ -59,25 +608,26 @@ User Name Completion name. For other completion functions, see *Note Completion::. - Function: user-name-all-completions partial-username - This function returns a list of all possible completions for a user - whose name starts with PARTIAL-USERNAME. The order of the + This function returns a list of all possible completions for a + user name starting with PARTIAL-USERNAME. The order of the completions is unpredictable and conveys no useful information. The argument PARTIAL-USERNAME must be a partial user name containing no tilde character and no slash. - - Function: user-name-completion username - This function completes the user name USERNAME. It returns the - longest prefix common to all user names that start with USERNAME. + - Function: user-name-completion partial-username + This function completes a user name from PARTIAL-USERNAME. It + returns the longest prefix common to all user names that start with + PARTIAL-USERNAME. - If only one match exists and USERNAME matches it exactly, the - function returns `t'. The function returns `nil' if no user name - starting with USERNAME exists. + If only one match exists and PARTIAL-USERNAME matches it exactly, + the function returns `t'. The function returns `nil' if no user + name starting with PARTIAL-USERNAME exists. - - Function: user-name-completion-1 username - This function completes the user name USERNAME, like - `user-name-completion', differing only in the return value. This - function returns the cons of the completion returned by + - Function: user-name-completion-1 partial-username + This function completes the partial user name PARTIAL-USERNAME, + like `user-name-completion', differing only in the return value. + This function returns the cons of the completion returned by `user-name-completion', and a boolean indicating whether that completion was unique. @@ -274,9 +824,9 @@ that have two file names that may each have handlers. - 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 + - Function: find-file-name-handler filename &optional operation + This function returns the handler function for file name FILENAME, + 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'. @@ -345,7 +895,7 @@ File: lispref.info, Node: Creating a Partial File, Next: Detached Partial File Creating a Partial File ----------------------- - - Function: make-file-part &optional start end name buffer + - Command: 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 @@ -357,7 +907,7 @@ Creating a Partial File 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. + BUFFER's name, and the current buffer, respectively.  File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files @@ -480,36 +1030,13 @@ buffer-local variable `buffer-file-format'. encoding functions for the formats listed in `buffer-file-format', in the order of appearance in the list. - - Function: format-write-file file format + - Command: 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 + - Command: 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. @@ -518,9 +1045,9 @@ the order of appearance in the list. `nil', no conversion takes place. Interactively, typing just for FORMAT specifies `nil'. - - Function: format-insert-file file format &optional beg end + - Command: format-insert-file file format &optional start end This command inserts the contents of file FILE, converting it - according to format FORMAT. If BEG and END are non-`nil', they + according to format FORMAT. If START and END are non-`nil', they specify which part of the file to read, as in `insert-file-contents' (*note Reading from Files::). @@ -699,483 +1226,3 @@ Making Backup Files not lose its value. Major modes should not set this variable--they should set `make-backup-files' instead. - -File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files - -Backup by Renaming or by Copying? ---------------------------------- - - There are two ways that XEmacs can make a backup file: - - * XEmacs can rename the original file so that it becomes a backup - file, and then write the buffer being saved into a new file. - After this procedure, any other names (i.e., hard links) of the - original file now refer to the backup file. The new file is owned - by the user doing the editing, and its group is the default for - new files written by the user in that directory. - - * XEmacs can copy the original file into a backup file, and then - overwrite the original file with new contents. After this - procedure, any other names (i.e., hard links) of the original file - still refer to the current version of the file. The file's owner - and group will be unchanged. - - The first method, renaming, is the default. - - The variable `backup-by-copying', if non-`nil', says to use the -second method, which is to copy the original file and overwrite it with -the new buffer contents. The variable `file-precious-flag', if -non-`nil', also has this effect (as a sideline of its main -significance). *Note Saving Buffers::. - - - Variable: backup-by-copying - If this variable is non-`nil', XEmacs always makes backup files by - copying. - - The following two variables, when non-`nil', cause the second method -to be used in certain special cases. They have no effect on the -treatment of files that don't fall into the special cases. - - - Variable: backup-by-copying-when-linked - If this variable is non-`nil', XEmacs makes backups by copying for - files with multiple names (hard links). - - This variable is significant only if `backup-by-copying' is `nil', - since copying is always used when that variable is non-`nil'. - - - Variable: backup-by-copying-when-mismatch - If this variable is non-`nil', XEmacs makes backups by copying in - cases where renaming would change either the owner or the group of - the file. - - The value has no effect when renaming would not alter the owner or - group of the file; that is, for files which are owned by the user - and whose group matches the default for a new file created there - by the user. - - This variable is significant only if `backup-by-copying' is `nil', - since copying is always used when that variable is non-`nil'. - - -File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files - -Making and Deleting Numbered Backup Files ------------------------------------------ - - If a file's name is `foo', the names of its numbered backup versions -are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~', -`foo.~3~', ..., `foo.~259~', and so on. - - - User Option: version-control - This variable controls whether to make a single non-numbered backup - file or multiple numbered backups. - - `nil' - Make numbered backups if the visited file already has - numbered backups; otherwise, do not. - - `never' - Do not make numbered backups. - - ANYTHING ELSE - Make numbered backups. - - The use of numbered backups ultimately leads to a large number of -backup versions, which must then be deleted. XEmacs can do this -automatically or it can ask the user whether to delete them. - - - User Option: kept-new-versions - The value of this variable is the number of newest versions to keep - when a new numbered backup is made. The newly made backup is - included in the count. The default value is 2. - - - User Option: kept-old-versions - The value of this variable is the number of oldest versions to keep - when a new numbered backup is made. The default value is 2. - - If there are backups numbered 1, 2, 3, 5, and 7, and both of these -variables have the value 2, then the backups numbered 1 and 2 are kept -as old versions and those numbered 5 and 7 are kept as new versions; -backup version 3 is excess. The function `find-backup-file-name' -(*note Backup Names::) is responsible for determining which backup -versions to delete, but does not delete them itself. - - - User Option: delete-old-versions - If this variable is non-`nil', then saving a file deletes excess - backup versions silently. Otherwise, it asks the user whether to - delete them. - - - User Option: dired-kept-versions - This variable specifies how many of the newest backup versions to - keep in the Dired command `.' (`dired-clean-directory'). That's - the same thing `kept-new-versions' specifies when you make a new - backup file. The default value is 2. - - -File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files - -Naming Backup Files -------------------- - - The functions in this section are documented mainly because you can -customize the naming conventions for backup files by redefining them. -If you change one, you probably need to change the rest. - - - Function: backup-file-name-p filename - This function returns a non-`nil' value if FILENAME is a possible - name for a backup file. A file with the name FILENAME need not - exist; the function just checks the name. - - (backup-file-name-p "foo") - => nil - (backup-file-name-p "foo~") - => 3 - - The standard definition of this function is as follows: - - (defun backup-file-name-p (file) - "Return non-nil if FILE is a backup file \ - name (numeric or not)..." - (string-match "~$" file)) - - Thus, the function returns a non-`nil' value if the file name ends - with a `~'. (We use a backslash to split the documentation - string's first line into two lines in the text, but produce just - one line in the string itself.) - - This simple expression is placed in a separate function to make it - easy to redefine for customization. - - - Function: make-backup-file-name filename - This function returns a string that is the name to use for a - non-numbered backup file for file FILENAME. On Unix, this is just - FILENAME with a tilde appended. - - The standard definition of this function is as follows: - - (defun make-backup-file-name (file) - "Create the non-numeric backup file name for FILE. - ..." - (concat file "~")) - - You can change the backup-file naming convention by redefining this - function. The following example redefines `make-backup-file-name' - to prepend a `.' in addition to appending a tilde: - - (defun make-backup-file-name (filename) - (concat "." filename "~")) - - (make-backup-file-name "backups.texi") - => ".backups.texi~" - - - Function: find-backup-file-name filename - This function computes the file name for a new backup file for - FILENAME. It may also propose certain existing backup files for - deletion. `find-backup-file-name' returns a list whose CAR is the - name for the new backup file and whose CDR is a list of backup - files whose deletion is proposed. - - Two variables, `kept-old-versions' and `kept-new-versions', - determine which backup versions should be kept. This function - keeps those versions by excluding them from the CDR of the value. - *Note Numbered Backups::. - - In this example, the value says that `~rms/foo.~5~' is the name to - use for the new backup file, and `~rms/foo.~3~' is an "excess" - version that the caller should consider deleting now. - - (find-backup-file-name "~rms/foo") - => ("~rms/foo.~5~" "~rms/foo.~3~") - - - Function: file-newest-backup filename - This function returns the name of the most recent backup file for - FILENAME, or `nil' if that file has no backup files. - - Some file comparison commands use this function so that they can - automatically compare a file with its most recent backup. - - -File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving - -Auto-Saving -=========== - - XEmacs periodically saves all files that you are visiting; this is -called "auto-saving". Auto-saving prevents you from losing more than a -limited amount of work if the system crashes. By default, auto-saves -happen every 300 keystrokes, or after around 30 seconds of idle time. -*Note Auto-Save: (emacs)Auto-Save, for information on auto-save for -users. Here we describe the functions used to implement auto-saving -and the variables that control them. - - - Variable: buffer-auto-save-file-name - This buffer-local variable is the name of the file used for - auto-saving the current buffer. It is `nil' if the buffer should - not be auto-saved. - - buffer-auto-save-file-name - => "/xcssun/users/rms/lewis/#files.texi#" - - - Command: auto-save-mode arg - When used interactively without an argument, this command is a - toggle switch: it turns on auto-saving of the current buffer if it - is off, and vice-versa. With an argument ARG, the command turns - auto-saving on if the value of ARG is `t', a nonempty list, or a - positive integer. Otherwise, it turns auto-saving off. - - - Function: auto-save-file-name-p filename - This function returns a non-`nil' value if FILENAME is a string - that could be the name of an auto-save file. It works based on - knowledge of the naming convention for auto-save files: a name that - begins and ends with hash marks (`#') is a possible auto-save file - name. The argument FILENAME should not contain a directory part. - - (make-auto-save-file-name) - => "/xcssun/users/rms/lewis/#files.texi#" - (auto-save-file-name-p "#files.texi#") - => 0 - (auto-save-file-name-p "files.texi") - => nil - - The standard definition of this function is as follows: - - (defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) - - This function exists so that you can customize it if you wish to - change the naming convention for auto-save files. If you redefine - it, be sure to redefine the function `make-auto-save-file-name' - correspondingly. - - - Function: make-auto-save-file-name - This function returns the file name to use for auto-saving the - current buffer. This is just the file name with hash marks (`#') - appended and prepended to it. This function does not look at the - variable `auto-save-visited-file-name' (described below); you - should check that before calling this function. - - (make-auto-save-file-name) - => "/xcssun/users/rms/lewis/#backup.texi#" - - The standard definition of this function is as follows: - - (defun make-auto-save-file-name () - "Return file name to use for auto-saves \ - of current buffer. - ..." - (if buffer-file-name - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) - - This exists as a separate function so that you can redefine it to - customize the naming convention for auto-save files. Be sure to - change `auto-save-file-name-p' in a corresponding way. - - - Variable: auto-save-visited-file-name - If this variable is non-`nil', XEmacs auto-saves buffers in the - files they are visiting. That is, the auto-save is done in the - same file that you are editing. Normally, this variable is `nil', - so auto-save files have distinct names that are created by - `make-auto-save-file-name'. - - When you change the value of this variable, the value does not take - effect until the next time auto-save mode is reenabled in any given - buffer. If auto-save mode is already enabled, auto-saves continue - to go in the same file name until `auto-save-mode' is called again. - - - Function: recent-auto-save-p - This function returns `t' if the current buffer has been - auto-saved since the last time it was read in or saved. - - - Function: set-buffer-auto-saved - This function marks the current buffer as auto-saved. The buffer - will not be auto-saved again until the buffer text is changed - again. The function returns `nil'. - - - User Option: auto-save-interval - The value of this variable is the number of characters that XEmacs - reads from the keyboard between auto-saves. Each time this many - more characters are read, auto-saving is done for all buffers in - which it is enabled. - - - User Option: auto-save-timeout - The value of this variable is the number of seconds of idle time - that should cause auto-saving. Each time the user pauses for this - long, XEmacs auto-saves any buffers that need it. (Actually, the - specified timeout is multiplied by a factor depending on the size - of the current buffer.) - - - Variable: auto-save-hook - This normal hook is run whenever an auto-save is about to happen. - - - User Option: auto-save-default - If this variable is non-`nil', buffers that are visiting files - have auto-saving enabled by default. Otherwise, they do not. - - - Command: do-auto-save &optional no-message current-only - This function auto-saves all buffers that need to be auto-saved. - It saves all buffers for which auto-saving is enabled and that - have been changed since the previous auto-save. - - Normally, if any buffers are auto-saved, a message that says - `Auto-saving...' is displayed in the echo area while auto-saving is - going on. However, if NO-MESSAGE is non-`nil', the message is - inhibited. - - If CURRENT-ONLY is non-`nil', only the current buffer is - auto-saved. - - - Function: delete-auto-save-file-if-necessary - This function deletes the current buffer's auto-save file if - `delete-auto-save-files' is non-`nil'. It is called every time a - buffer is saved. - - - Variable: delete-auto-save-files - This variable is used by the function - `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs - deletes auto-save files when a true save is done (in the visited - file). This saves disk space and unclutters your directory. - - - Function: rename-auto-save-file - This function adjusts the current buffer's auto-save file name if - the visited file name has changed. It also renames an existing - auto-save file. If the visited file name has not changed, this - function does nothing. - - - Variable: buffer-saved-size - The value of this buffer-local variable is the length of the - current buffer as of the last time it was read in, saved, or - auto-saved. This is used to detect a substantial decrease in - size, and turn off auto-saving in response. - - If it is -1, that means auto-saving is temporarily shut off in this - buffer due to a substantial deletion. Explicitly saving the buffer - stores a positive value in this variable, thus reenabling - auto-saving. Turning auto-save mode off or on also alters this - variable. - - - Variable: auto-save-list-file-name - This variable (if non-`nil') specifies a file for recording the - names of all the auto-save files. Each time XEmacs does - auto-saving, it writes two lines into this file for each buffer - that has auto-saving enabled. The first line gives the name of - the visited file (it's empty if the buffer has none), and the - second gives the name of the auto-save file. - - If XEmacs exits normally, it deletes this file. If XEmacs - crashes, you can look in the file to find all the auto-save files - that might contain work that was otherwise lost. The - `recover-session' command uses these files. - - The default name for this file is in your home directory and - starts with `.saves-'. It also contains the XEmacs process ID and - the host name. - - -File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving - -Reverting -========= - - If you have made extensive changes to a file and then change your -mind about them, you can get rid of them by reading in the previous -version of the file with the `revert-buffer' command. *Note Reverting -a Buffer: (emacs)Reverting. - - - Command: revert-buffer &optional check-auto-save noconfirm - This command replaces the buffer text with the text of the visited - file on disk. This action undoes all changes since the file was - visited or saved. - - If the argument CHECK-AUTO-SAVE is non-`nil', and the latest - auto-save file is more recent than the visited file, - `revert-buffer' asks the user whether to use that instead. - Otherwise, it always uses the text of the visited file itself. - Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix - argument. - - Normally, `revert-buffer' asks for confirmation before it changes - the buffer; but if the argument NOCONFIRM is non-`nil', - `revert-buffer' does not ask for confirmation. - - Reverting tries to preserve marker positions in the buffer by - using the replacement feature of `insert-file-contents'. If the - buffer contents and the file contents are identical before the - revert operation, reverting preserves all the markers. If they - are not identical, reverting does change the buffer; then it - preserves the markers in the unchanged text (if any) at the - beginning and end of the buffer. Preserving any additional - markers would be problematical. - - You can customize how `revert-buffer' does its work by setting these -variables--typically, as buffer-local variables. - - - Variable: revert-buffer-function - The value of this variable is the function to use to revert this - buffer. If non-`nil', it is called as a function with no - arguments to do the work of reverting. If the value is `nil', - reverting works the usual way. - - Modes such as Dired mode, in which the text being edited does not - consist of a file's contents but can be regenerated in some other - fashion, give this variable a buffer-local value that is a - function to regenerate the contents. - - - Variable: revert-buffer-insert-file-contents-function - The value of this variable, if non-`nil', is the function to use to - insert the updated contents when reverting this buffer. The - function receives two arguments: first the file name to use; - second, `t' if the user has asked to read the auto-save file. - - - Variable: before-revert-hook - This normal hook is run by `revert-buffer' before actually - inserting the modified contents--but only if - `revert-buffer-function' is `nil'. - - Font Lock mode uses this hook to record that the buffer contents - are no longer fontified. - - - Variable: after-revert-hook - This normal hook is run by `revert-buffer' after actually inserting - the modified contents--but only if `revert-buffer-function' is - `nil'. - - Font Lock mode uses this hook to recompute the fonts for the - updated buffer contents. - - -File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top - -Buffers -******* - - A "buffer" is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, exactly one buffer is designated the "current -buffer" at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - -* Menu: - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file is visited. -* Buffer Modification:: A buffer is "modified" if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind XEmacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some other buffer. - diff --git a/info/lispref.info-25 b/info/lispref.info-25 index a34f51c..793aca3 100644 --- a/info/lispref.info-25 +++ b/info/lispref.info-25 @@ -50,6 +50,491 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files + +Backup by Renaming or by Copying? +--------------------------------- + + There are two ways that XEmacs can make a backup file: + + * XEmacs can rename the original file so that it becomes a backup + file, and then write the buffer being saved into a new file. + After this procedure, any other names (i.e., hard links) of the + original file now refer to the backup file. The new file is owned + by the user doing the editing, and its group is the default for + new files written by the user in that directory. + + * XEmacs can copy the original file into a backup file, and then + overwrite the original file with new contents. After this + procedure, any other names (i.e., hard links) of the original file + still refer to the current version of the file. The file's owner + and group will be unchanged. + + The first method, renaming, is the default. + + The variable `backup-by-copying', if non-`nil', says to use the +second method, which is to copy the original file and overwrite it with +the new buffer contents. The variable `file-precious-flag', if +non-`nil', also has this effect (as a sideline of its main +significance). *Note Saving Buffers::. + + - Variable: backup-by-copying + If this variable is non-`nil', XEmacs always makes backup files by + copying. + + The following two variables, when non-`nil', cause the second method +to be used in certain special cases. They have no effect on the +treatment of files that don't fall into the special cases. + + - Variable: backup-by-copying-when-linked + If this variable is non-`nil', XEmacs makes backups by copying for + files with multiple names (hard links). + + This variable is significant only if `backup-by-copying' is `nil', + since copying is always used when that variable is non-`nil'. + + - Variable: backup-by-copying-when-mismatch + If this variable is non-`nil', XEmacs makes backups by copying in + cases where renaming would change either the owner or the group of + the file. + + The value has no effect when renaming would not alter the owner or + group of the file; that is, for files which are owned by the user + and whose group matches the default for a new file created there + by the user. + + This variable is significant only if `backup-by-copying' is `nil', + since copying is always used when that variable is non-`nil'. + + +File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files + +Making and Deleting Numbered Backup Files +----------------------------------------- + + If a file's name is `foo', the names of its numbered backup versions +are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~', +`foo.~3~', ..., `foo.~259~', and so on. + + - User Option: version-control + This variable controls whether to make a single non-numbered backup + file or multiple numbered backups. + + `nil' + Make numbered backups if the visited file already has + numbered backups; otherwise, do not. + + `never' + Do not make numbered backups. + + ANYTHING ELSE + Make numbered backups. + + The use of numbered backups ultimately leads to a large number of +backup versions, which must then be deleted. XEmacs can do this +automatically or it can ask the user whether to delete them. + + - User Option: kept-new-versions + The value of this variable is the number of newest versions to keep + when a new numbered backup is made. The newly made backup is + included in the count. The default value is 2. + + - User Option: kept-old-versions + The value of this variable is the number of oldest versions to keep + when a new numbered backup is made. The default value is 2. + + If there are backups numbered 1, 2, 3, 5, and 7, and both of these +variables have the value 2, then the backups numbered 1 and 2 are kept +as old versions and those numbered 5 and 7 are kept as new versions; +backup version 3 is excess. The function `find-backup-file-name' +(*note Backup Names::) is responsible for determining which backup +versions to delete, but does not delete them itself. + + - User Option: delete-old-versions + If this variable is non-`nil', then saving a file deletes excess + backup versions silently. Otherwise, it asks the user whether to + delete them. + + - User Option: dired-kept-versions + This variable specifies how many of the newest backup versions to + keep in the Dired command `.' (`dired-clean-directory'). That's + the same thing `kept-new-versions' specifies when you make a new + backup file. The default value is 2. + + +File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files + +Naming Backup Files +------------------- + + The functions in this section are documented mainly because you can +customize the naming conventions for backup files by redefining them. +If you change one, you probably need to change the rest. + + - Function: backup-file-name-p filename + This function returns a non-`nil' value if FILENAME is a possible + name for a backup file. A file with the name FILENAME need not + exist; the function just checks the name. + + (backup-file-name-p "foo") + => nil + (backup-file-name-p "foo~") + => 3 + + The standard definition of this function is as follows: + + (defun backup-file-name-p (file) + "Return non-nil if FILE is a backup file \ + name (numeric or not)..." + (string-match "~$" file)) + + Thus, the function returns a non-`nil' value if the file name ends + with a `~'. (We use a backslash to split the documentation + string's first line into two lines in the text, but produce just + one line in the string itself.) + + This simple expression is placed in a separate function to make it + easy to redefine for customization. + + - Function: make-backup-file-name filename + This function returns a string that is the name to use for a + non-numbered backup file for file FILENAME. On Unix, this is just + FILENAME with a tilde appended. + + The standard definition of this function is as follows: + + (defun make-backup-file-name (file) + "Create the non-numeric backup file name for FILE. + ..." + (concat file "~")) + + You can change the backup-file naming convention by redefining this + function. The following example redefines `make-backup-file-name' + to prepend a `.' in addition to appending a tilde: + + (defun make-backup-file-name (filename) + (concat "." filename "~")) + + (make-backup-file-name "backups.texi") + => ".backups.texi~" + + - Function: find-backup-file-name filename + This function computes the file name for a new backup file for + FILENAME. It may also propose certain existing backup files for + deletion. `find-backup-file-name' returns a list whose CAR is the + name for the new backup file and whose CDR is a list of backup + files whose deletion is proposed. + + Two variables, `kept-old-versions' and `kept-new-versions', + determine which backup versions should be kept. This function + keeps those versions by excluding them from the CDR of the value. + *Note Numbered Backups::. + + In this example, the value says that `~rms/foo.~5~' is the name to + use for the new backup file, and `~rms/foo.~3~' is an "excess" + version that the caller should consider deleting now. + + (find-backup-file-name "~rms/foo") + => ("~rms/foo.~5~" "~rms/foo.~3~") + + - Function: file-newest-backup filename + This function returns the name of the most recent backup file for + FILENAME, or `nil' if that file has no backup files. + + Some file comparison commands use this function so that they can + automatically compare a file with its most recent backup. + + +File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving + +Auto-Saving +=========== + + XEmacs periodically saves all files that you are visiting; this is +called "auto-saving". Auto-saving prevents you from losing more than a +limited amount of work if the system crashes. By default, auto-saves +happen every 300 keystrokes, or after around 30 seconds of idle time. +*Note Auto-Save: (emacs)Auto-Save, for information on auto-save for +users. Here we describe the functions used to implement auto-saving +and the variables that control them. + + - Variable: buffer-auto-save-file-name + This buffer-local variable is the name of the file used for + auto-saving the current buffer. It is `nil' if the buffer should + not be auto-saved. + + buffer-auto-save-file-name + => "/xcssun/users/rms/lewis/#files.texi#" + + - Command: auto-save-mode arg + When used interactively without an argument, this command is a + toggle switch: it turns on auto-saving of the current buffer if it + is off, and vice-versa. With an argument ARG, the command turns + auto-saving on if the value of ARG is `t', a nonempty list, or a + positive integer. Otherwise, it turns auto-saving off. + + - Function: auto-save-file-name-p filename + This function returns a non-`nil' value if FILENAME is a string + that could be the name of an auto-save file. It works based on + knowledge of the naming convention for auto-save files: a name that + begins and ends with hash marks (`#') is a possible auto-save file + name. The argument FILENAME should not contain a directory part. + + (make-auto-save-file-name) + => "/xcssun/users/rms/lewis/#files.texi#" + (auto-save-file-name-p "#files.texi#") + => 0 + (auto-save-file-name-p "files.texi") + => nil + + The standard definition of this function is as follows: + + (defun auto-save-file-name-p (filename) + "Return non-nil if FILENAME can be yielded by..." + (string-match "^#.*#$" filename)) + + This function exists so that you can customize it if you wish to + change the naming convention for auto-save files. If you redefine + it, be sure to redefine the function `make-auto-save-file-name' + correspondingly. + + - Function: make-auto-save-file-name &optional filename + This function returns the file name to use for auto-saving the + current buffer. This is just the file name with hash marks (`#') + appended and prepended to it. This function does not look at the + variable `auto-save-visited-file-name' (described below); you + should check that before calling this function. + + (make-auto-save-file-name) + => "/xcssun/users/rms/lewis/#backup.texi#" + + The standard definition of this function is as follows: + + (defun make-auto-save-file-name () + "Return file name to use for auto-saves \ + of current buffer. + ..." + (if buffer-file-name + (concat + (file-name-directory buffer-file-name) + "#" + (file-name-nondirectory buffer-file-name) + "#") + (expand-file-name + (concat "#%" (buffer-name) "#")))) + + This exists as a separate function so that you can redefine it to + customize the naming convention for auto-save files. Be sure to + change `auto-save-file-name-p' in a corresponding way. + + - Variable: auto-save-visited-file-name + If this variable is non-`nil', XEmacs auto-saves buffers in the + files they are visiting. That is, the auto-save is done in the + same file that you are editing. Normally, this variable is `nil', + so auto-save files have distinct names that are created by + `make-auto-save-file-name'. + + When you change the value of this variable, the value does not take + effect until the next time auto-save mode is reenabled in any given + buffer. If auto-save mode is already enabled, auto-saves continue + to go in the same file name until `auto-save-mode' is called again. + + - Function: recent-auto-save-p + This function returns `t' if the current buffer has been + auto-saved since the last time it was read in or saved. + + - Function: set-buffer-auto-saved + This function marks the current buffer as auto-saved. The buffer + will not be auto-saved again until the buffer text is changed + again. The function returns `nil'. + + - User Option: auto-save-interval + The value of this variable is the number of characters that XEmacs + reads from the keyboard between auto-saves. Each time this many + more characters are read, auto-saving is done for all buffers in + which it is enabled. + + - User Option: auto-save-timeout + The value of this variable is the number of seconds of idle time + that should cause auto-saving. Each time the user pauses for this + long, XEmacs auto-saves any buffers that need it. (Actually, the + specified timeout is multiplied by a factor depending on the size + of the current buffer.) + + - Variable: auto-save-hook + This normal hook is run whenever an auto-save is about to happen. + + - User Option: auto-save-default + If this variable is non-`nil', buffers that are visiting files + have auto-saving enabled by default. Otherwise, they do not. + + - Command: do-auto-save &optional no-message current-only + This function auto-saves all buffers that need to be auto-saved. + It saves all buffers for which auto-saving is enabled and that + have been changed since the previous auto-save. + + Normally, if any buffers are auto-saved, a message that says + `Auto-saving...' is displayed in the echo area while auto-saving is + going on. However, if NO-MESSAGE is non-`nil', the message is + inhibited. + + If CURRENT-ONLY is non-`nil', only the current buffer is + auto-saved. + + - Function: delete-auto-save-file-if-necessary + This function deletes the current buffer's auto-save file if + `delete-auto-save-files' is non-`nil'. It is called every time a + buffer is saved. + + - Variable: delete-auto-save-files + This variable is used by the function + `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs + deletes auto-save files when a true save is done (in the visited + file). This saves disk space and unclutters your directory. + + - Function: rename-auto-save-file + This function adjusts the current buffer's auto-save file name if + the visited file name has changed. It also renames an existing + auto-save file. If the visited file name has not changed, this + function does nothing. + + - Variable: buffer-saved-size + The value of this buffer-local variable is the length of the + current buffer as of the last time it was read in, saved, or + auto-saved. This is used to detect a substantial decrease in + size, and turn off auto-saving in response. + + If it is -1, that means auto-saving is temporarily shut off in this + buffer due to a substantial deletion. Explicitly saving the buffer + stores a positive value in this variable, thus reenabling + auto-saving. Turning auto-save mode off or on also alters this + variable. + + - Variable: auto-save-list-file-name + This variable (if non-`nil') specifies a file for recording the + names of all the auto-save files. Each time XEmacs does + auto-saving, it writes two lines into this file for each buffer + that has auto-saving enabled. The first line gives the name of + the visited file (it's empty if the buffer has none), and the + second gives the name of the auto-save file. + + If XEmacs exits normally, it deletes this file. If XEmacs + crashes, you can look in the file to find all the auto-save files + that might contain work that was otherwise lost. The + `recover-session' command uses these files. + + The default name for this file is in your home directory and + starts with `.saves-'. It also contains the XEmacs process ID and + the host name. + + +File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving + +Reverting +========= + + If you have made extensive changes to a file and then change your +mind about them, you can get rid of them by reading in the previous +version of the file with the `revert-buffer' command. *Note Reverting +a Buffer: (emacs)Reverting. + + - Command: revert-buffer &optional check-auto-save noconfirm + preserve-modes + This command replaces the buffer text with the text of the visited + file on disk. This action undoes all changes since the file was + visited or saved. + + If the argument CHECK-AUTO-SAVE is non-`nil', and the latest + auto-save file is more recent than the visited file, + `revert-buffer' asks the user whether to use that instead. + Otherwise, it always uses the text of the visited file itself. + Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix + argument. + + Normally, `revert-buffer' asks for confirmation before it changes + the buffer; but if the argument NOCONFIRM is non-`nil', + `revert-buffer' does not ask for confirmation. + + Optional third argument PRESERVE-MODES non-`nil' means don't alter + the files modes. Normally we reinitialize them using + `normal-mode'. + + Reverting tries to preserve marker positions in the buffer by + using the replacement feature of `insert-file-contents'. If the + buffer contents and the file contents are identical before the + revert operation, reverting preserves all the markers. If they + are not identical, reverting does change the buffer; then it + preserves the markers in the unchanged text (if any) at the + beginning and end of the buffer. Preserving any additional + markers would be problematical. + + You can customize how `revert-buffer' does its work by setting these +variables--typically, as buffer-local variables. + + - Variable: revert-buffer-function + The value of this variable is the function to use to revert this + buffer. If non-`nil', it is called as a function with no + arguments to do the work of reverting. If the value is `nil', + reverting works the usual way. + + Modes such as Dired mode, in which the text being edited does not + consist of a file's contents but can be regenerated in some other + fashion, give this variable a buffer-local value that is a + function to regenerate the contents. + + - Variable: revert-buffer-insert-file-contents-function + The value of this variable, if non-`nil', is the function to use to + insert the updated contents when reverting this buffer. The + function receives two arguments: first the file name to use; + second, `t' if the user has asked to read the auto-save file. + + - Variable: before-revert-hook + This normal hook is run by `revert-buffer' before actually + inserting the modified contents--but only if + `revert-buffer-function' is `nil'. + + Font Lock mode uses this hook to record that the buffer contents + are no longer fontified. + + - Variable: after-revert-hook + This normal hook is run by `revert-buffer' after actually inserting + the modified contents--but only if `revert-buffer-function' is + `nil'. + + Font Lock mode uses this hook to recompute the fonts for the + updated buffer contents. + + +File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top + +Buffers +******* + + A "buffer" is a Lisp object containing text to be edited. Buffers +are used to hold the contents of files that are being visited; there may +also be buffers that are not visiting files. While several buffers may +exist at one time, exactly one buffer is designated the "current +buffer" at any time. Most editing commands act on the contents of the +current buffer. Each buffer, including the current buffer, may or may +not be displayed in any window. + +* Menu: + +* Buffer Basics:: What is a buffer? +* Current Buffer:: Designating a buffer as current + so primitives will access its contents. +* Buffer Names:: Accessing and changing buffer names. +* Buffer File Name:: The buffer file name indicates which file is visited. +* Buffer Modification:: A buffer is "modified" if it needs to be saved. +* Modification Time:: Determining whether the visited file was changed + ``behind XEmacs's back''. +* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. +* The Buffer List:: How to look at all the existing buffers. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Indirect Buffers:: An indirect buffer shares text with some other buffer. + + File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers Buffer Basics @@ -193,9 +678,9 @@ Using `save-excursion', as shown below, handles quitting, errors, and 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. + BUFFER-OR-NAME must be a buffer or the name of an existing + buffer-else an error is signaled. This function returns the buffer + identified by BUFFER-OR-NAME.  File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers @@ -248,11 +733,11 @@ also initially disables recording undo information; see *Note Undo::. shell buffer under the name `*shell*'. - Function: get-buffer buffer-or-name - This function returns the buffer specified by BUFFER-OR-NAME. If + This function returns the buffer named 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: + the value is `nil'. If BUFFER-OR-NAME is actually 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")) => # @@ -396,9 +881,10 @@ file formerly visited. 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'. + - Function: set-buffer-modified-p flag &optional buffer + This function marks BUFFER as modified if FLAG is non-`nil', or as + unmodified if the flag is `nil'. BUFFER defaults to the current + buffer. Another effect of calling this function is to cause unconditional redisplay of the modeline for the current buffer. In fact, the @@ -531,17 +1017,33 @@ narrowing. `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. + - Command: toggle-read-only &optional arg + This command changes whether the current buffer is read-only. + Interactively, if a prefix arg ARG is supplied, set the current + buffer read only if and only if ARG is positive. + + This command is intended for interactive use only; 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 &optional buffer start end + This function signals a `buffer-read-only' error if BUFFER is + read-only. BUFFER defaults to the current buffer. *Note + Interactive Call::, for another way to signal an error if the + current buffer is read-only. + + If optional argument START is non-`nil', all extents in the buffer + which overlap that part of the buffer are checked to ensure none + has a `read-only' property. (Extents that lie completely within the + range, however, are not checked.) END defaults to the value of + START. + + If START and END are equal, the range checked is [START, END] + (i.e. closed on both ends); otherwise, the range checked is + (START, END) \(open on both ends), except that extents that lie + completely within [START, END] are not checked. See + `extent-in-region-p' for a fuller discussion.  File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers @@ -619,8 +1121,7 @@ It is only the order of those elements that is different. (and created, if necessary). Note that in FSF Emacs 19, there is no FRAME argument, and - VISIBLE-OK is the second argument instead of the third. FSF Emacs - 19. + VISIBLE-OK is the second argument instead of the third. - Command: list-buffers &optional files-only This function displays a listing of the names of existing buffers. @@ -629,7 +1130,7 @@ It is only the order of those elements that is different. intended for interactive use, and is described fully in `The XEmacs Reference Manual'. It returns `nil'. - - Command: bury-buffer &optional buffer-or-name + - Command: bury-buffer &optional buffer-or-name before This function puts BUFFER-OR-NAME at the end of the buffer list without changing the order of any of the other buffers on the list. This buffer therefore becomes the least desirable candidate for @@ -644,548 +1145,3 @@ It is only the order of those elements that is different. If you wish to replace a buffer in all the windows that display it, use `replace-buffer-in-windows'. *Note Buffers and Windows::. - -File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers - -Creating Buffers -================ - - This section describes the two primitives for creating buffers. -`get-buffer-create' creates a buffer if it finds no existing buffer -with the specified name; `generate-new-buffer' always creates a new -buffer and gives it a unique name. - - Other functions you can use to create buffers include -`with-output-to-temp-buffer' (*note Temporary Displays::) and -`create-file-buffer' (*note Visiting Files::). Starting a subprocess -can also create a buffer (*note Processes::). - - - Function: get-buffer-create name - This function returns a buffer named NAME. It returns an existing - buffer with that name, if one exists; otherwise, it creates a new - buffer. The buffer does not become the current buffer--this - function does not change which buffer is current. - - An error is signaled if NAME is not a string. - - (get-buffer-create "foo") - => # - - The major mode for the new buffer is set to Fundamental mode. The - variable `default-major-mode' is handled at a higher level. *Note - Auto Major Mode::. - - - Function: generate-new-buffer name - This function returns a newly created, empty buffer, but does not - make it current. If there is no buffer named NAME, then that is - the name of the new buffer. If that name is in use, this function - adds suffixes of the form `' to NAME, where N is an integer. - It tries successive integers starting with 2 until it finds an - available name. - - An error is signaled if NAME is not a string. - - (generate-new-buffer "bar") - => # - (generate-new-buffer "bar") - => #> - (generate-new-buffer "bar") - => #> - - The major mode for the new buffer is set to Fundamental mode. The - variable `default-major-mode' is handled at a higher level. *Note - Auto Major Mode::. - - See the related function `generate-new-buffer-name' in *Note - Buffer Names::. - - -File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers - -Killing Buffers -=============== - - "Killing a buffer" makes its name unknown to XEmacs and makes its -text space available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; two distinct buffers, when killed, remain -distinct according to `eq'. - - If you kill a buffer that is current or displayed in a window, XEmacs -automatically selects or displays some other buffer instead. This means -that killing a buffer can in general change the current buffer. -Therefore, when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). *Note Current Buffer::. - - If you kill a buffer that is the base buffer of one or more indirect -buffers, the indirect buffers are automatically killed as well. - - The `buffer-name' of a killed buffer is `nil'. To test whether a -buffer has been killed, you can either use this feature or the function -`buffer-live-p'. - - - Function: buffer-live-p buffer - This function returns `nil' if BUFFER is deleted, and `t' - otherwise. - - - Command: kill-buffer buffer-or-name - This function kills the buffer BUFFER-OR-NAME, freeing all its - memory for use as space for other buffers. (Emacs version 18 and - older was unable to return the memory to the operating system.) - It returns `nil'. - - Any processes that have this buffer as the `process-buffer' are - sent the `SIGHUP' signal, which normally causes them to terminate. - (The basic meaning of `SIGHUP' is that a dialup line has been - disconnected.) *Note Deleting Processes::. - - If the buffer is visiting a file and contains unsaved changes, - `kill-buffer' asks the user to confirm before the buffer is killed. - It does this even if not called interactively. To prevent the - request for confirmation, clear the modified flag before calling - `kill-buffer'. *Note Buffer Modification::. - - Killing a buffer that is already dead has no effect. - - (kill-buffer "foo.unchanged") - => nil - (kill-buffer "foo.changed") - - ---------- Buffer: Minibuffer ---------- - Buffer foo.changed modified; kill anyway? (yes or no) yes - ---------- Buffer: Minibuffer ---------- - - => nil - - - Variable: kill-buffer-query-functions - After confirming unsaved changes, `kill-buffer' calls the functions - in the list `kill-buffer-query-functions', in order of appearance, - with no arguments. The buffer being killed is the current buffer - when they are called. The idea is that these functions ask for - confirmation from the user for various nonstandard reasons. If - any of them returns `nil', `kill-buffer' spares the buffer's life. - - - Variable: kill-buffer-hook - This is a normal hook run by `kill-buffer' after asking all the - questions it is going to ask, just before actually killing the - buffer. The buffer to be killed is current when the hook - functions run. *Note Hooks::. - - - Variable: buffer-offer-save - This variable, if non-`nil' in a particular buffer, tells - `save-buffers-kill-emacs' and `save-some-buffers' to offer to save - that buffer, just as they offer to save file-visiting buffers. The - variable `buffer-offer-save' automatically becomes buffer-local - when set for any reason. *Note Buffer-Local Variables::. - - -File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers - -Indirect Buffers -================ - - An "indirect buffer" shares the text of some other buffer, which is -called the "base buffer" of the indirect buffer. In some ways it is -the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. One base buffer may have -several "indirect children". - - The text of the indirect buffer is always identical to the text of -its base buffer; changes made by editing either one are visible -immediately in the other. - - But in all other respects, the indirect buffer and its base buffer -are completely separate. They have different names, different values of -point and mark, different narrowing, different markers and extents -(though inserting or deleting text in either buffer relocates the -markers and extents for both), different major modes, and different -local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not -automatically share text properties among themselves and their base -buffer. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer kills all its indirect children. - - - Command: make-indirect-buffer base-buffer name - This creates an indirect buffer named NAME whose base buffer is - BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string. - - If BASE-BUFFER is an indirect buffer, its base buffer is used as - the base for the new buffer. - - (make-indirect-buffer "*scratch*" "indirect") - => # - - - Function: buffer-base-buffer &optional buffer - This function returns the base buffer of BUFFER. If BUFFER is not - indirect, the value is `nil'. Otherwise, the value is another - buffer, which is never an indirect buffer. If BUFFER is not - supplied, it defaults to the current buffer. - - (buffer-base-buffer (get-buffer "indirect")) - => # - - - Function: buffer-indirect-children &optional buffer - This function returns a list of all indirect buffers whose base - buffer is BUFFER. If BUFFER is indirect, the return value will - always be nil; see `make-indirect-buffer'. If BUFFER is not - supplied, it defaults to the current buffer. - - (buffer-indirect-children (get-buffer "*scratch*")) - => (#) - - -File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top - -Windows -******* - - This chapter describes most of the functions and variables related to -Emacs windows. See *Note Display::, for information on how text is -displayed in windows. - -* Menu: - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-lever functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Window Point:: Each window has its own location of point. -* Window Start:: The display-start position controls which text - is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Horizontal Scrolling:: Moving text sideways on the window. -* Size of Window:: Accessing the size of a window. -* Position of Window:: Accessing the position of a window. -* Resizing Windows:: Changing the size of a window. -* Window Configurations:: Saving and restoring the state of the screen. - - -File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows - -Basic Concepts of Emacs Windows -=============================== - - A "window" in XEmacs is the physical area of the screen in which a -buffer is displayed. The term is also used to refer to a Lisp object -that represents that screen area in XEmacs Lisp. It should be clear -from the context which is meant. - - XEmacs groups windows into frames. A frame represents an area of -screen available for XEmacs to use. Each frame always contains at least -one window, but you can subdivide it vertically or horizontally into -multiple nonoverlapping Emacs windows. - - In each frame, at any time, one and only one window is designated as -"selected within the frame". The frame's cursor appears in that -window. At ant time, one frame is the selected frame; and the window -selected within that frame is "the selected window". The selected -window's buffer is usually the current buffer (except when `set-buffer' -has been used). *Note Current Buffer::. - - For practical purposes, a window exists only while it is displayed in -a frame. Once removed from the frame, the window is effectively deleted -and should not be used, _even though there may still be references to -it_ from other Lisp objects. Restoring a saved window configuration is -the only way for a window no longer on the screen to come back to life. -(*Note Deleting Windows::.) - - Each window has the following attributes: - - * containing frame - - * window height - - * window width - - * window edges with respect to the frame or screen - - * the buffer it displays - - * position within the buffer at the upper left of the window - - * amount of horizontal scrolling, in columns - - * point - - * the mark - - * how recently the window was selected - - Users create multiple windows so they can look at several buffers at -once. Lisp libraries use multiple windows for a variety of reasons, but -most often to display related information. In Rmail, for example, you -can move through a summary buffer in one window while the other window -shows messages one at a time as they are reached. - - The meaning of "window" in XEmacs is similar to what it means in the -context of general-purpose window systems such as X, but not identical. -The X Window System places X windows on the screen; XEmacs uses one or -more X windows as frames, and subdivides them into Emacs windows. When -you use XEmacs on a character-only terminal, XEmacs treats the whole -terminal screen as one frame. - - Most window systems support arbitrarily located overlapping windows. -In contrast, Emacs windows are "tiled"; they never overlap, and -together they fill the whole screen or frame. Because of the way in -which XEmacs creates new windows and resizes them, you can't create -every conceivable tiling of windows on an Emacs frame. *Note Splitting -Windows::, and *Note Size of Window::. - - *Note Display::, for information on how the contents of the window's -buffer are displayed in the window. - - - Function: windowp object - This function returns `t' if OBJECT is a window. - - -File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows - -Splitting Windows -================= - - The functions described here are the primitives used to split a -window into two windows. Two higher level functions sometimes split a -window, but not always: `pop-to-buffer' and `display-buffer' (*note -Displaying Buffers::). - - The functions described here do not accept a buffer as an argument. -The two "halves" of the split window initially display the same buffer -previously visible in the window that was split. - - - Function: one-window-p &optional no-mini all-frames - This function returns non-`nil' if there is only one window. The - argument NO-MINI, if non-`nil', means don't count the minibuffer - even if it is active; otherwise, the minibuffer window is - included, if active, in the total number of windows which is - compared against one. - - The argument ALL-FRAME controls which set of windows are counted. - * If it is `nil' or omitted, then count only the selected - frame, plus the minibuffer it uses (which may be on another - frame). - - * If it is `t', then windows on all frames that currently exist - (including invisible and iconified frames) are counted. - - * If it is the symbol `visible', then windows on all visible - frames are counted. - - * If it is the number 0, then windows on all visible and - iconified frames are counted. - - * If it is any other value, then precisely the windows in - WINDOW's frame are counted, excluding the minibuffer in use - if it lies in some other frame. - - - Command: split-window &optional window size horizontal - This function splits WINDOW into two windows. The original window - WINDOW remains the selected window, but occupies only part of its - former screen area. The rest is occupied by a newly created - window which is returned as the value of this function. - - If HORIZONTAL is non-`nil', then WINDOW splits into two side by - side windows. The original window WINDOW keeps the leftmost SIZE - columns, and gives the rest of the columns to the new window. - Otherwise, it splits into windows one above the other, and WINDOW - keeps the upper SIZE lines and gives the rest of the lines to the - new window. The original window is therefore the left-hand or - upper of the two, and the new window is the right-hand or lower. - - If WINDOW is omitted or `nil', then the selected window is split. - If SIZE is omitted or `nil', then WINDOW is divided evenly into - two parts. (If there is an odd line, it is allocated to the new - window.) When `split-window' is called interactively, all its - arguments are `nil'. - - The following example starts with one window on a frame that is 50 - lines high by 80 columns wide; then the window is split. - - (setq w (selected-window)) - => # - (window-edges) ; Edges in order: - => (0 0 80 50) ; left-top-right-bottom - - ;; Returns window created - (setq w2 (split-window w 15)) - => # - (window-edges w2) - => (0 15 80 50) ; Bottom window; - ; top is line 15 - (window-edges w) - => (0 0 80 15) ; Top window - - The frame looks like this: - - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 - - Next, the top window is split horizontally: - - (setq w3 (split-window w 35 t)) - => # - (window-edges w3) - => (35 0 80 15) ; Left edge at column 35 - (window-edges w) - => (0 0 35 15) ; Right edge at column 35 - (window-edges w2) - => (0 15 80 50) ; Bottom window unchanged - - Now, the screen looks like this: - - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 - - Normally, Emacs indicates the border between two side-by-side - windows with a scroll bar (*note Scroll Bars: X Frame Properties.) - or `|' characters. The display table can specify alternative - border characters; see *Note Display Tables::. - - - Command: split-window-vertically &optional size - This function splits the selected window into two windows, one - above the other, leaving the selected window with SIZE lines. - - This function is simply an interface to `split-windows'. Here is - the complete function definition for it: - - (defun split-window-vertically (&optional arg) - "Split current window into two windows, one above the other." - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)))) - - - Command: split-window-horizontally &optional size - This function splits the selected window into two windows - side-by-side, leaving the selected window with SIZE columns. - - This function is simply an interface to `split-windows'. Here is - the complete definition for `split-window-horizontally' (except for - part of the documentation string): - - (defun split-window-horizontally (&optional arg) - "Split selected window into two windows, side by side..." - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)) t)) - - - Function: one-window-p &optional no-mini all-frames - This function returns non-`nil' if there is only one window. The - argument NO-MINI, if non-`nil', means don't count the minibuffer - even if it is active; otherwise, the minibuffer window is - included, if active, in the total number of windows, which is - compared against one. - - The argument ALL-FRAMES specifies which frames to consider. Here - are the possible values and their meanings: - - `nil' - Count the windows in the selected frame, plus the minibuffer - used by that frame even if it lies in some other frame. - - `t' - Count all windows in all existing frames. - - `visible' - Count all windows in all visible frames. - - 0 - Count all windows in all visible or iconified frames. - - anything else - Count precisely the windows in the selected frame, and no - others. - - -File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows - -Deleting Windows -================ - - A window remains visible on its frame unless you "delete" it by -calling certain functions that delete windows. A deleted window cannot -appear on the screen, but continues to exist as a Lisp object until -there are no references to it. There is no way to cancel the deletion -of a window aside from restoring a saved window configuration (*note -Window Configurations::). Restoring a window configuration also -deletes any windows that aren't part of that configuration. - - When you delete a window, the space it took up is given to one -adjacent sibling. (In Emacs version 18, the space was divided evenly -among all the siblings.) - - - Function: window-live-p window - This function returns `nil' if WINDOW is deleted, and `t' - otherwise. - - *Warning:* Erroneous information or fatal errors may result from - using a deleted window as if it were live. - - - Command: delete-window &optional window - This function removes WINDOW from the display. If WINDOW is - omitted, then the selected window is deleted. An error is signaled - if there is only one window when `delete-window' is called. - - This function returns `nil'. - - When `delete-window' is called interactively, WINDOW defaults to - the selected window. - - - Command: delete-other-windows &optional window - This function makes WINDOW the only window on its frame, by - deleting the other windows in that frame. If WINDOW is omitted or - `nil', then the selected window is used by default. - - The result is `nil'. - - - Command: delete-windows-on buffer &optional frame - This function deletes all windows showing BUFFER. If there are no - windows showing BUFFER, it does nothing. - - `delete-windows-on' operates frame by frame. If a frame has - several windows showing different buffers, then those showing - BUFFER are removed, and the others expand to fill the space. If - all windows in some frame are showing BUFFER (including the case - where there is only one window), then the frame reverts to having a - single window showing another buffer chosen with `other-buffer'. - *Note The Buffer List::. - - The argument FRAME controls which frames to operate on: - - * If it is `nil', operate on the selected frame. - - * If it is `t', operate on all frames. - - * If it is `visible', operate on all visible frames. - - * 0 If it is 0, operate on all visible or iconified frames. - - * If it is a frame, operate on that frame. - - This function always returns `nil'. - diff --git a/info/lispref.info-26 b/info/lispref.info-26 index ea018b1..f5f7bde 100644 --- a/info/lispref.info-26 +++ b/info/lispref.info-26 @@ -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: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers + +Creating Buffers +================ + + This section describes the two primitives for creating buffers. +`get-buffer-create' creates a buffer if it finds no existing buffer +with the specified name; `generate-new-buffer' always creates a new +buffer and gives it a unique name. + + Other functions you can use to create buffers include +`with-output-to-temp-buffer' (*note Temporary Displays::) and +`create-file-buffer' (*note Visiting Files::). Starting a subprocess +can also create a buffer (*note Processes::). + + - Function: get-buffer-create name + This function returns a buffer named NAME. It returns an existing + buffer with that name, if one exists; otherwise, it creates a new + buffer. The buffer does not become the current buffer--this + function does not change which buffer is current. + + An error is signaled if NAME is not a string. + + (get-buffer-create "foo") + => # + + The major mode for the new buffer is set to Fundamental mode. The + variable `default-major-mode' is handled at a higher level. *Note + Auto Major Mode::. + + - Function: generate-new-buffer name + This function returns a newly created, empty buffer, but does not + make it current. If there is no buffer named NAME, then that is + the name of the new buffer. If that name is in use, this function + adds suffixes of the form `' to NAME, where N is an integer. + It tries successive integers starting with 2 until it finds an + available name. + + An error is signaled if NAME is not a string. + + (generate-new-buffer "bar") + => # + (generate-new-buffer "bar") + => #> + (generate-new-buffer "bar") + => #> + + The major mode for the new buffer is set to Fundamental mode. The + variable `default-major-mode' is handled at a higher level. *Note + Auto Major Mode::. + + See the related function `generate-new-buffer-name' in *Note + Buffer Names::. + + +File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers + +Killing Buffers +=============== + + "Killing a buffer" makes its name unknown to XEmacs and makes its +text space available for other use. + + The buffer object for the buffer that has been killed remains in +existence as long as anything refers to it, but it is specially marked +so that you cannot make it current or display it. Killed buffers retain +their identity, however; two distinct buffers, when killed, remain +distinct according to `eq'. + + If you kill a buffer that is current or displayed in a window, XEmacs +automatically selects or displays some other buffer instead. This means +that killing a buffer can in general change the current buffer. +Therefore, when you kill a buffer, you should also take the precautions +associated with changing the current buffer (unless you happen to know +that the buffer being killed isn't current). *Note Current Buffer::. + + If you kill a buffer that is the base buffer of one or more indirect +buffers, the indirect buffers are automatically killed as well. + + The `buffer-name' of a killed buffer is `nil'. To test whether a +buffer has been killed, you can either use this feature or the function +`buffer-live-p'. + + - Function: buffer-live-p object + This function returns `t' if OBJECT is an editor buffer that has + not been deleted, `nil' otherwise. + + - Command: kill-buffer buffer-or-name + This function kills the buffer BUFFER-OR-NAME, freeing all its + memory for use as space for other buffers. (Emacs version 18 and + older was unable to return the memory to the operating system.) + It returns `nil'. The argument BUFFER-OR-NAME may be a buffer or + the name of one. + + Any processes that have this buffer as the `process-buffer' are + sent the `SIGHUP' signal, which normally causes them to terminate. + (The basic meaning of `SIGHUP' is that a dialup line has been + disconnected.) *Note Deleting Processes::. + + If the buffer is visiting a file and contains unsaved changes, + `kill-buffer' asks the user to confirm before the buffer is killed. + It does this even if not called interactively. To prevent the + request for confirmation, clear the modified flag before calling + `kill-buffer'. *Note Buffer Modification::. + + Killing a buffer that is already dead has no effect. + + (kill-buffer "foo.unchanged") + => nil + (kill-buffer "foo.changed") + + ---------- Buffer: Minibuffer ---------- + Buffer foo.changed modified; kill anyway? (yes or no) yes + ---------- Buffer: Minibuffer ---------- + + => nil + + - Variable: kill-buffer-query-functions + After confirming unsaved changes, `kill-buffer' calls the functions + in the list `kill-buffer-query-functions', in order of appearance, + with no arguments. The buffer being killed is the current buffer + when they are called. The idea is that these functions ask for + confirmation from the user for various nonstandard reasons. If + any of them returns `nil', `kill-buffer' spares the buffer's life. + + - Variable: kill-buffer-hook + This is a normal hook run by `kill-buffer' after asking all the + questions it is going to ask, just before actually killing the + buffer. The buffer to be killed is current when the hook + functions run. *Note Hooks::. + + - Variable: buffer-offer-save + This variable, if non-`nil' in a particular buffer, tells + `save-buffers-kill-emacs' and `save-some-buffers' to offer to save + that buffer, just as they offer to save file-visiting buffers. The + variable `buffer-offer-save' automatically becomes buffer-local + when set for any reason. *Note Buffer-Local Variables::. + + +File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers + +Indirect Buffers +================ + + An "indirect buffer" shares the text of some other buffer, which is +called the "base buffer" of the indirect buffer. In some ways it is +the analogue, for buffers, of a symbolic link among files. The base +buffer may not itself be an indirect buffer. One base buffer may have +several "indirect children". + + The text of the indirect buffer is always identical to the text of +its base buffer; changes made by editing either one are visible +immediately in the other. + + But in all other respects, the indirect buffer and its base buffer +are completely separate. They have different names, different values of +point and mark, different narrowing, different markers and extents +(though inserting or deleting text in either buffer relocates the +markers and extents for both), different major modes, and different +local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not +automatically share text properties among themselves and their base +buffer. + + An indirect buffer cannot visit a file, but its base buffer can. If +you try to save the indirect buffer, that actually works by saving the +base buffer. + + Killing an indirect buffer has no effect on its base buffer. Killing +the base buffer kills all its indirect children. + + - Command: make-indirect-buffer base-buffer name + This creates an indirect buffer named NAME whose base buffer is + BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string. + + If BASE-BUFFER is an indirect buffer, its base buffer is used as + the base for the new buffer. + + (make-indirect-buffer "*scratch*" "indirect") + => # + + - Function: buffer-base-buffer &optional buffer + This function returns the base buffer of BUFFER. If BUFFER is not + indirect, the value is `nil'. Otherwise, the value is another + buffer, which is never an indirect buffer. If BUFFER is not + supplied, it defaults to the current buffer. + + (buffer-base-buffer (get-buffer "indirect")) + => # + + - Function: buffer-indirect-children &optional buffer + This function returns a list of all indirect buffers whose base + buffer is BUFFER. If BUFFER is indirect, the return value will + always be `nil'; see `make-indirect-buffer'. If BUFFER is not + supplied, it defaults to the current buffer. + + (buffer-indirect-children (get-buffer "*scratch*")) + => (#) + + +File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top + +Windows +******* + + This chapter describes most of the functions and variables related to +Emacs windows. See *Note Display::, for information on how text is +displayed in windows. + +* Menu: + +* Basic Windows:: Basic information on using windows. +* Splitting Windows:: Splitting one window into two windows. +* Deleting Windows:: Deleting a window gives its space to other windows. +* Selecting Windows:: The selected window is the one that you edit in. +* Cyclic Window Ordering:: Moving around the existing windows. +* Buffers and Windows:: Each window displays the contents of a buffer. +* Displaying Buffers:: Higher-lever functions for displaying a buffer + and choosing a window for it. +* Choosing Window:: How to choose a window for displaying a buffer. +* Window Point:: Each window has its own location of point. +* Window Start:: The display-start position controls which text + is on-screen in the window. +* Vertical Scrolling:: Moving text up and down in the window. +* Horizontal Scrolling:: Moving text sideways on the window. +* Size of Window:: Accessing the size of a window. +* Position of Window:: Accessing the position of a window. +* Resizing Windows:: Changing the size of a window. +* Window Configurations:: Saving and restoring the state of the screen. + + +File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows + +Basic Concepts of Emacs Windows +=============================== + + A "window" in XEmacs is the physical area of the screen in which a +buffer is displayed. The term is also used to refer to a Lisp object +that represents that screen area in XEmacs Lisp. It should be clear +from the context which is meant. + + XEmacs groups windows into frames. A frame represents an area of +screen available for XEmacs to use. Each frame always contains at least +one window, but you can subdivide it vertically or horizontally into +multiple nonoverlapping Emacs windows. + + In each frame, at any time, one and only one window is designated as +"selected within the frame". The frame's cursor appears in that +window. At ant time, one frame is the selected frame; and the window +selected within that frame is "the selected window". The selected +window's buffer is usually the current buffer (except when `set-buffer' +has been used). *Note Current Buffer::. + + For practical purposes, a window exists only while it is displayed in +a frame. Once removed from the frame, the window is effectively deleted +and should not be used, _even though there may still be references to +it_ from other Lisp objects. Restoring a saved window configuration is +the only way for a window no longer on the screen to come back to life. +(*Note Deleting Windows::.) + + Each window has the following attributes: + + * containing frame + + * window height + + * window width + + * window edges with respect to the frame or screen + + * the buffer it displays + + * position within the buffer at the upper left of the window + + * amount of horizontal scrolling, in columns + + * point + + * the mark + + * how recently the window was selected + + Users create multiple windows so they can look at several buffers at +once. Lisp libraries use multiple windows for a variety of reasons, but +most often to display related information. In Rmail, for example, you +can move through a summary buffer in one window while the other window +shows messages one at a time as they are reached. + + The meaning of "window" in XEmacs is similar to what it means in the +context of general-purpose window systems such as X, but not identical. +The X Window System places X windows on the screen; XEmacs uses one or +more X windows as frames, and subdivides them into Emacs windows. When +you use XEmacs on a character-only terminal, XEmacs treats the whole +terminal screen as one frame. + + Most window systems support arbitrarily located overlapping windows. +In contrast, Emacs windows are "tiled"; they never overlap, and +together they fill the whole screen or frame. Because of the way in +which XEmacs creates new windows and resizes them, you can't create +every conceivable tiling of windows on an Emacs frame. *Note Splitting +Windows::, and *Note Size of Window::. + + *Note Display::, for information on how the contents of the window's +buffer are displayed in the window. + + - Function: windowp object + This function returns `t' if OBJECT is a window. + + +File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows + +Splitting Windows +================= + + The functions described here are the primitives used to split a +window into two windows. Two higher level functions sometimes split a +window, but not always: `pop-to-buffer' and `display-buffer' (*note +Displaying Buffers::). + + The functions described here do not accept a buffer as an argument. +The two "halves" of the split window initially display the same buffer +previously visible in the window that was split. + + - Function: one-window-p &optional nomini which-frames which-devices + This function returns non-`nil' if there is only one window. The + argument NOMINI, if non-`nil', means don't count the minibuffer + even if it is active; otherwise, the minibuffer window is + included, if active, in the total number of windows which is + compared against one. + + The remaining arguments controls which set of windows are counted, + as with `next-window'. + + - Command: split-window &optional window size horizontal + This function splits WINDOW into two windows. The original window + WINDOW remains the selected window, but occupies only part of its + former screen area. The rest is occupied by a newly created + window which is returned as the value of this function. + + If HORIZONTAL is non-`nil', then WINDOW splits into two side by + side windows. The original window WINDOW keeps the leftmost SIZE + columns, and gives the rest of the columns to the new window. + Otherwise, it splits into windows one above the other, and WINDOW + keeps the upper SIZE lines and gives the rest of the lines to the + new window. The original window is therefore the left-hand or + upper of the two, and the new window is the right-hand or lower. + + If WINDOW is omitted or `nil', then the selected window is split. + If SIZE is omitted or `nil', then WINDOW is divided evenly into + two parts. (If there is an odd line, it is allocated to the new + window.) When `split-window' is called interactively, all its + arguments are `nil'. + + The following example starts with one window on a frame that is 50 + lines high by 80 columns wide; then the window is split. + + (setq w (selected-window)) + => # + (window-edges) ; Edges in order: + => (0 0 80 50) ; left-top-right-bottom + + ;; Returns window created + (setq w2 (split-window w 15)) + => # + (window-edges w2) + => (0 15 80 50) ; Bottom window; + ; top is line 15 + (window-edges w) + => (0 0 80 15) ; Top window + + The frame looks like this: + + __________ + | | line 0 + | w | + |__________| + | | line 15 + | w2 | + |__________| + line 50 + column 0 column 80 + + Next, the top window is split horizontally: + + (setq w3 (split-window w 35 t)) + => # + (window-edges w3) + => (35 0 80 15) ; Left edge at column 35 + (window-edges w) + => (0 0 35 15) ; Right edge at column 35 + (window-edges w2) + => (0 15 80 50) ; Bottom window unchanged + + Now, the screen looks like this: + + column 35 + __________ + | | | line 0 + | w | w3 | + |___|______| + | | line 15 + | w2 | + |__________| + line 50 + column 0 column 80 + + Normally, Emacs indicates the border between two side-by-side + windows with a scroll bar (*note Scroll Bars: X Frame Properties.) + or `|' characters. The display table can specify alternative + border characters; see *Note Display Tables::. + + - Command: split-window-vertically &optional size + This function splits the selected window into two windows, one + above the other, leaving the selected window with SIZE lines. + + This function is simply an interface to `split-window'. Here is + the complete function definition for it: + + (defun split-window-vertically (&optional arg) + "Split current window into two windows, one above the other." + (interactive "P") + (split-window nil (and arg (prefix-numeric-value arg)))) + + - Command: split-window-horizontally &optional size + This function splits the selected window into two windows + side-by-side, leaving the selected window with SIZE columns. + + This function is simply an interface to `split-window'. Here is + the complete definition for `split-window-horizontally' (except for + part of the documentation string): + + (defun split-window-horizontally (&optional arg) + "Split selected window into two windows, side by side..." + (interactive "P") + (split-window nil (and arg (prefix-numeric-value arg)) t)) + + +File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows + +Deleting Windows +================ + + A window remains visible on its frame unless you "delete" it by +calling certain functions that delete windows. A deleted window cannot +appear on the screen, but continues to exist as a Lisp object until +there are no references to it. There is no way to cancel the deletion +of a window aside from restoring a saved window configuration (*note +Window Configurations::). Restoring a window configuration also +deletes any windows that aren't part of that configuration. + + When you delete a window, the space it took up is given to one +adjacent sibling. (In Emacs version 18, the space was divided evenly +among all the siblings.) + + - Function: window-live-p window + This function returns `nil' if WINDOW is deleted, and `t' + otherwise. + + *Warning:* Erroneous information or fatal errors may result from + using a deleted window as if it were live. + + - Command: delete-window &optional window force + This function removes WINDOW from the display. If WINDOW is + omitted, then the selected window is deleted. If window is the + only one on its frame, the frame is deleted as well. + + Normally, you cannot delete the last non-minibuffer-only frame + (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error + is signaled instead. However, if optional second argument FORCE is + non-`nil', you can delete the last frame. (This will automatically + call `save-buffers-kill-emacs'.) + + This function returns `nil'. + + When `delete-window' is called interactively, the selected window + is deleted. + + - Command: delete-other-windows &optional window + This function makes WINDOW the only window on its frame, by + deleting the other windows in that frame. If WINDOW is omitted or + `nil', then the selected window is used by default. + + The result is `nil'. + + - Command: delete-windows-on buffer &optional which-frames + which-devices + This function deletes all windows showing BUFFER. If there are no + windows showing BUFFER, it does nothing. + + `delete-windows-on' operates frame by frame. If a frame has + several windows showing different buffers, then those showing + BUFFER are removed, and the others expand to fill the space. If + all windows in some frame are showing BUFFER (including the case + where there is only one window), then the frame reverts to having a + single window showing another buffer chosen with `other-buffer'. + *Note The Buffer List::. + + The argument WHICH-FRAMES controls which frames to operate on: + + `nil' + Delete all windows showing BUFFER in any frame. + + `t' + Delete only windows showing BUFFER in the selected frame. + + `visible' + Delete all windows showing BUFFER in any visible frame. + + `0' + Delete all windows showing BUFFER in any visible frame. + + FRAME + If it is a frame, delete all windows showing BUFFER in that + frame. + + *Warning:* This is similar to, but not identical to, the meaning + of the WHICH-FRAMES argument to `next-window'; the meanings of + `nil' and `t' are reversed. + + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. This + value is only meaningful if WHICH-FRAMES is not `t'. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + This function always returns `nil'. + + File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows Selecting Windows @@ -81,8 +624,8 @@ current buffer, and the cursor will appear in it. (select-window w) => # - - Macro: save-selected-window forms... - This macro records the selected window, executes FORMS in + - Special Form: save-selected-window forms... + This special form 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 @@ -91,7 +634,7 @@ current buffer, and the cursor will appear in it. The following functions choose one of the windows on the screen, offering various criteria for the choice. - - Function: get-lru-window &optional frame + - Function: get-lru-window &optional which-frames which-devices This function returns the window least recently "used" (that is, selected). The selected window is always the most recently used window. @@ -101,20 +644,56 @@ offering various criteria for the choice. recently used window until it is selected. A minibuffer window is never a candidate. - The argument FRAME controls which windows are considered. + By default, only the windows in the selected frame are considered. + The optional argument WHICH-FRAMES changes this behavior. Here + are the possible values and their meanings: - * If it is `nil', consider windows on the selected frame. + `nil' + Consider all the windows in the selected windows's frame, + plus the minibuffer used by that frame even if it lies in + some other frame. - * If it is `t', consider windows on all frames. + `t' + Consider all windows in all existing frames. - * If it is `visible', consider windows on all visible 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. + + FRAME + Consider all windows on frame FRAME. + + anything else + Consider precisely the windows in the selected window's + frame, and no others. + + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. This + value is only meaningful if WHICH-FRAMES is non-`nil'. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. - * If it is 0, consider windows on all visible or iconified - frames. + CONSOLE + Consider all devices on CONSOLE. - * If it is a frame, consider windows on that frame. + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. - - Function: get-largest-window &optional frame + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + + - Function: get-largest-window &optional which-frames which-devices 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 @@ -124,8 +703,8 @@ offering various criteria for the choice. 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. + The remaining arguments control which set of windows are + considered. See `next-window', above.  File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows @@ -150,7 +729,8 @@ 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 + - Function: next-window &optional window minibuf which-frames + which-devices 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 @@ -169,7 +749,8 @@ the order is left to right, or top to bottom. 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 + By default, only the windows in the selected frame are considered. + The optional argument WHICH-FRAMES changes this behavior. Here are the possible values and their meanings: `nil' @@ -184,13 +765,44 @@ the order is left to right, or top to bottom. Consider all windows in all visible frames. (To get useful results, you must ensure WINDOW is in a visible frame.) - 0 + `0' Consider all windows in all visible or iconified frames. + FRAME + Consider all windows on frame FRAME. + anything else Consider precisely the windows in WINDOW's frame, and no others. + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. This + value is only meaningful if WHICH-FRAMES is non-`nil'. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + If you use consistent values for MINIBUF, WHICH-FRAMES, and + WHICH-DEVICES, you can use `next-window' to iterate through the + entire cycle of acceptable windows, eventually ending up back at + the window you started with. `previous-window' traverses the same + cycle, in the reverse order. + This example assumes there are two windows, both displaying the buffer `windows.texi': @@ -201,42 +813,29 @@ the order is left to right, or top to bottom. (next-window (next-window (selected-window))) => # - - Function: previous-window &optional window minibuf all-frames + - Function: previous-window &optional window minibuf which-frames + which-devices 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 + - Command: other-window count &optional which-frames which-devices This function selects the COUNTth following window in the cyclic - order. If count is negative, then it selects the -COUNTth + 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. + The other arguments specify which windows to include in the cycle, + as in `next-window'. - * If it is `t', then windows on all frames that currently exist - (including invisible and iconified frames) are considered. + - Function: walk-windows function &optional minibuf which-frames + which-devices + This function cycles through all windows, calling `function' once + for each window with the window as its sole argument. - * 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. + The other arguments specify which windows to cycle through, as in + `next-window'.  File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows @@ -251,9 +850,14 @@ 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 + - Function: set-window-buffer window buffer-or-name &optional norecord This function makes WINDOW display BUFFER-OR-NAME as its contents. - It returns `nil'. + BUFFER-OR-NAME can be a buffer or a buffer name. + + With non-`nil' optional argument NORECORD, do not modify the + global or per-frame buffer ordering. + + This function returns `nil'. (set-window-buffer (selected-window) "foo") => nil @@ -266,25 +870,16 @@ window; use these functions when you need complete control. (window-buffer) => # - - Function: get-buffer-window buffer-or-name &optional frame + - Function: get-buffer-window buffer-or-name &optional which-frames + which-devices 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. + The remaining arguments control which windows to consider. They + have the same meaning as for `next-window'.  File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows @@ -383,13 +978,17 @@ without affecting the display of buffers in windows. An example use of this function is found at the end of *Note Filter Functions::. - - Command: replace-buffer-in-windows buffer + - Command: replace-buffer-in-windows buffer &optional which-frames + which-devices 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. + The optional arguments WHICH-FRAMES and WHICH-DEVICES have the + same meaning as with `delete-windows-on'. + This function returns `nil'.  @@ -404,11 +1003,14 @@ 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 + override-frame 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. + BUFFER-OR-NAME can be a buffer or the name of one. + 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 @@ -416,6 +1018,9 @@ and commands use this subroutine. Here we describe how to use BUFFER-OR-NAME is already being displayed in any window, that is good enough, so this function does nothing. + If OVERRIDE-FRAME is non-`nil', display on that frame instead of + the current frame (or the dedicated frame). + `display-buffer' returns the window chosen to display BUFFER-OR-NAME. @@ -597,14 +1202,14 @@ to have multiple windows showing one buffer. when the user switches to another buffer, the cursor jumps to the position of point in that buffer. - - Function: window-point window + - Function: window-point &optional window This function returns the current position of point in WINDOW. For a non-selected window, this is the value point would have (in that window's buffer) if that window were selected. When WINDOW is the selected window and its buffer is also the - current buffer, the value returned is the same as point in that - buffer. + current buffer, the value returned is the same as the value of + point in that buffer. Strictly speaking, it would be more correct to return the "top-level" value of point, outside of any `save-excursion' forms. @@ -614,483 +1219,3 @@ position of point in that buffer. This function positions point in WINDOW at position POSITION in WINDOW's buffer. - -File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows - -The Window Start Position -========================= - - Each window contains a marker used to keep track of a buffer position -that specifies where in the buffer display should start. This position -is called the "display-start" position of the window (or just the -"start"). The character after this position is the one that appears at -the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - - - Function: window-start &optional window - This function returns the display-start position of window WINDOW. - If WINDOW is `nil', the selected window is used. For example, - - (window-start) - => 7058 - - When you create a window, or display a different buffer in it, the - display-start position is set to a display-start position recently - used for the same buffer, or 1 if the buffer doesn't have any. - - For a realistic example, see the description of `count-lines' in - *Note Text Lines::. - - - Function: window-end &optional window - This function returns the position of the end of the display in - window WINDOW. If WINDOW is `nil', the selected window is used. - - Simply changing the buffer text or moving point does not update the - value that `window-end' returns. The value is updated only when - Emacs redisplays and redisplay actually finishes. - - If the last redisplay of WINDOW was preempted, and did not finish, - Emacs does not know the position of the end of display in that - window. In that case, this function returns a value that is not - correct. In a future version, `window-end' will return `nil' in - that case. - - - Function: set-window-start window position &optional noforce - This function sets the display-start position of WINDOW to - POSITION in WINDOW's buffer. It returns POSITION. - - The display routines insist that the position of point be visible - when a buffer is displayed. Normally, they change the - display-start position (that is, scroll the window) whenever - necessary to make point visible. However, if you specify the - start position with this function using `nil' for NOFORCE, it - means you want display to start at POSITION even if that would put - the location of point off the screen. If this does place point - off screen, the display routines move point to the left margin on - the middle line in the window. - - For example, if point is 1 and you set the start of the window - to 2, then point would be "above" the top of the window. The - display routines will automatically move point if it is still 1 - when redisplay occurs. Here is an example: - - ;; Here is what `foo' looks like before executing - ;; the `set-window-start' expression. - - ---------- Buffer: foo ---------- - -!-This is the contents of buffer foo. - 2 - 3 - 4 - 5 - 6 - ---------- Buffer: foo ---------- - - (set-window-start - (selected-window) - (1+ (window-start))) - => 2 - - ;; Here is what `foo' looks like after executing - ;; the `set-window-start' expression. - ---------- Buffer: foo ---------- - his is the contents of buffer foo. - 2 - 3 - -!-4 - 5 - 6 - ---------- Buffer: foo ---------- - - If NOFORCE is non-`nil', and POSITION would place point off screen - at the next redisplay, then redisplay computes a new window-start - position that works well with point, and thus POSITION is not used. - - - Function: pos-visible-in-window-p &optional position window - This function returns `t' if POSITION is within the range of text - currently visible on the screen in WINDOW. It returns `nil' if - POSITION is scrolled vertically out of view. The argument - POSITION defaults to the current position of point; WINDOW, to the - selected window. Here is an example: - - (or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) - - The `pos-visible-in-window-p' function considers only vertical - scrolling. If POSITION is out of view only because WINDOW has - been scrolled horizontally, `pos-visible-in-window-p' returns `t'. - *Note Horizontal Scrolling::. - - -File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows - -Vertical Scrolling -================== - - Vertical scrolling means moving the text up or down in a window. It -works by changing the value of the window's display-start location. It -may also change the value of `window-point' to keep it on the screen. - - In the commands `scroll-up' and `scroll-down', the directions "up" -and "down" refer to the motion of the text in the buffer at which you -are looking through the window. Imagine that the text is written on a -long roll of paper and that the scrolling commands move the paper up -and down. Thus, if you are looking at text in the middle of a buffer -and repeatedly call `scroll-down', you will eventually see the -beginning of the buffer. - - Some people have urged that the opposite convention be used: they -imagine that the window moves over text that remains in place. Then -"down" commands would take you to the end of the buffer. This view is -more consistent with the actual relationship between windows and the -text in the buffer, but it is less like what the user sees. The -position of a window on the terminal does not move, and short scrolling -commands clearly move the text up or down on the screen. We have chosen -names that fit the user's point of view. - - The scrolling functions (aside from `scroll-other-window') have -unpredictable results if the current buffer is different from the buffer -that is displayed in the selected window. *Note Current Buffer::. - - - Command: scroll-up &optional count - This function scrolls the text in the selected window upward COUNT - lines. If COUNT is negative, scrolling is actually downward. - - If COUNT is `nil' (or omitted), then the length of scroll is - `next-screen-context-lines' lines less than the usable height of - the window (not counting its modeline). - - `scroll-up' returns `nil'. - - - Command: scroll-down &optional count - This function scrolls the text in the selected window downward - COUNT lines. If COUNT is negative, scrolling is actually upward. - - If COUNT is omitted or `nil', then the length of the scroll is - `next-screen-context-lines' lines less than the usable height of - the window (not counting its mode line). - - `scroll-down' returns `nil'. - - - Command: scroll-other-window &optional count - This function scrolls the text in another window upward COUNT - lines. Negative values of COUNT, or `nil', are handled as in - `scroll-up'. - - You can specify a buffer to scroll with the variable - `other-window-scroll-buffer'. When the selected window is the - minibuffer, the next window is normally the one at the top left - corner. You can specify a different window to scroll with the - variable `minibuffer-scroll-window'. This variable has no effect - when any other window is selected. *Note Minibuffer Misc::. - - When the minibuffer is active, it is the next window if the - selected window is the one at the bottom right corner. In this - case, `scroll-other-window' attempts to scroll the minibuffer. If - the minibuffer contains just one line, it has nowhere to scroll - to, so the line reappears after the echo area momentarily displays - the message "Beginning of buffer". - - - Variable: other-window-scroll-buffer - If this variable is non-`nil', it tells `scroll-other-window' - which buffer to scroll. - - - User Option: scroll-step - This variable controls how scrolling is done automatically when - point moves off the screen. If the value is zero, then redisplay - scrolls the text to center point vertically in the window. If the - value is a positive integer N, then redisplay brings point back on - screen by scrolling N lines in either direction, if possible; - otherwise, it centers point. The default value is zero. - - - User Option: scroll-conservatively - This variable controls how many lines Emacs tries to scroll before - recentering. If you set it to a small number, then when you move - point a short distance off the screen, XEmacs will scroll the - screen just far enough to bring point back on screen, provided - that does not exceed `scroll-conservatively' lines. This variable - overrides the redisplay preemption. - - - User Option: next-screen-context-lines - The value of this variable is the number of lines of continuity to - retain when scrolling by full screens. For example, `scroll-up' - with an argument of `nil' scrolls so that this many lines at the - bottom of the window appear instead at the top. The default value - is `2'. - - - Command: recenter &optional count - This function scrolls the selected window to put the text where - point is located at a specified vertical position within the - window. - - If COUNT is a nonnegative number, it puts the line containing - point COUNT lines down from the top of the window. If COUNT is a - negative number, then it counts upward from the bottom of the - window, so that -1 stands for the last usable line in the window. - If COUNT is a non-`nil' list, then it stands for the line in the - middle of the window. - - If COUNT is `nil', `recenter' puts the line containing point in - the middle of the window, then clears and redisplays the entire - selected frame. - - When `recenter' is called interactively, COUNT is the raw prefix - argument. Thus, typing `C-u' as the prefix sets the COUNT to a - non-`nil' list, while typing `C-u 4' sets COUNT to 4, which - positions the current line four lines from the top. - - With an argument of zero, `recenter' positions the current line at - the top of the window. This action is so handy that some people - make a separate key binding to do this. For example, - - (defun line-to-top-of-window () - "Scroll current line to top of window. - Replaces three keystroke sequence C-u 0 C-l." - (interactive) - (recenter 0)) - - (global-set-key [kp-multiply] 'line-to-top-of-window) - - -File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows - -Horizontal Scrolling -==================== - - Because we read English first from top to bottom and second from left -to right, horizontal scrolling is not like vertical scrolling. Vertical -scrolling involves selection of a contiguous portion of text to display. -Horizontal scrolling causes part of each line to go off screen. The -amount of horizontal scrolling is therefore specified as a number of -columns rather than as a position in the buffer. It has nothing to do -with the display-start position returned by `window-start'. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the -screen to be revealed by it; so this is not allowed. Scrolling to the -left is allowed; it scrolls the first columns of text off the edge of -the window and can reveal additional columns on the right that were -truncated before. Once a window has a nonzero amount of leftward -horizontal scrolling, you can scroll it back to the right, but only so -far as to reduce the net horizontal scroll to zero. There is no limit -to how far left you can scroll, but eventually all the text will -disappear off the left edge. - - - Command: scroll-left count - This function scrolls the selected window COUNT columns to the - left (or to the right if COUNT is negative). The return value is - the total amount of leftward horizontal scrolling in effect after - the change--just like the value returned by `window-hscroll' - (below). - - - Command: scroll-right count - This function scrolls the selected window COUNT columns to the - right (or to the left if COUNT is negative). The return value is - the total amount of leftward horizontal scrolling in effect after - the change--just like the value returned by `window-hscroll' - (below). - - Once you scroll a window as far right as it can go, back to its - normal position where the total leftward scrolling is zero, - attempts to scroll any farther right have no effect. - - - Function: window-hscroll &optional window - This function returns the total leftward horizontal scrolling of - WINDOW--the number of columns by which the text in WINDOW is - scrolled left past the left margin. - - The value is never negative. It is zero when no horizontal - scrolling has been done in WINDOW (which is usually the case). - - If WINDOW is `nil', the selected window is used. - - (window-hscroll) - => 0 - (scroll-left 5) - => 5 - (window-hscroll) - => 5 - - - Function: set-window-hscroll window columns - This function sets the number of columns from the left margin that - WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS - should be zero or positive; if not, it is taken as zero. - - The value returned is COLUMNS. - - (set-window-hscroll (selected-window) 10) - => 10 - - Here is how you can determine whether a given position POSITION is -off the screen due to horizontal scrolling: - - (defun hscroll-on-screen (window position) - (save-excursion - (goto-char position) - (and - (>= (- (current-column) (window-hscroll window)) 0) - (< (- (current-column) (window-hscroll window)) - (window-width window))))) - - -File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows - -The Size of a Window -==================== - - An Emacs window is rectangular, and its size information consists of -the height (in lines or pixels) and the width (in character positions -or pixels). The modeline is included in the height. The pixel width -and height values include scrollbars and margins, while the -line/character-position values do not. - - Note that the height in lines, and the width in characters, are -determined by dividing the corresponding pixel value by the height or -width of the default font in that window (if this is a variable-width -font, the average width is used). The resulting values may or may not -represent the actual number of lines in the window, or the actual number -of character positions in any particular line, esp. if there are pixmaps -or various different fonts in the window. - - The following functions return size information about a window: - - - Function: window-height &optional window - This function returns the number of lines in WINDOW, including its - modeline but not including the horizontal scrollbar, if any (this - is different from `window-pixel-height'). If WINDOW is `nil', the - function uses the selected window. - - (window-height) - => 40 - (split-window-vertically) - => # - (window-height) - => 20 - - - Function: window-width &optional window - This function returns the number of columns in WINDOW, not - including any left margin, right margin, or vertical scrollbar - (this is different from `window-pixel-width'). If WINDOW is - `nil', the function uses the selected window. - - (window-width) - => 80 - (window-height) - => 40 - (split-window-horizontally) - => # - (window-width) - => 39 - - Note that after splitting the window into two side-by-side windows, -the width of each window is less the half the width of the original -window because a vertical scrollbar appeared between the windows, -occupying two columns worth of space. Also, the height shrunk by one -because horizontal scrollbars appeared that weren't there before. -(Horizontal scrollbars appear only when lines are truncated, not when -they wrap. This is usually the case for horizontally split windows but -not for full-frame windows. You can change this using the variables -`truncate-lines' and `truncate-partial-width-windows'.) - - - Function: window-pixel-height &optional window - This function returns the height of WINDOW in pixels, including - its modeline and horizontal scrollbar, if any. If WINDOW is - `nil', the function uses the selected window. - - (window-pixel-height) - => 600 - (split-window-vertically) - => # - (window-pixel-height) - => 300 - - - Function: window-pixel-width &optional window - This function returns the width of WINDOW in pixels, including any - left margin, right margin, or vertical scrollbar that may be - displayed alongside it. If WINDOW is `nil', the function uses the - selected window. - - (window-pixel-width) - => 735 - (window-pixel-height) - => 600 - (split-window-horizontally) - => # - (window-pixel-width) - => 367 - (window-pixel-height) - => 600 - - - Function: window-text-area-pixel-height &optional window - This function returns the height in pixels of the text displaying - portion of WINDOW, which defaults to the selected window. Unlike - `window-pixel-height', the space occupied by the modeline and - horizontal scrollbar, if any, is not counted. - - - Function: window-text-area-pixel-width &optional window - This function returns the width in pixels of the text displaying - portion of WINDOW, which defaults to the selected window. Unlike - `window-pixel-width', the space occupied by the vertical scrollbar - and divider, if any, is not counted. - - - Function: window-displayed-text-pixel-height &optional window - noclipped - This function returns the height in pixels of the text displayed in - WINDOW, which defaults to the selected window. Unlike - `window-text-area-pixel-height', any blank space below the end of - the buffer is not included. If optional argument NOCLIPPED is - non-`nil', any space occupied by clipped lines will not be - included. - - -File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows - -The Position of a Window -======================== - - XEmacs provides functions to determine the absolute location of -windows within a frame, and the relative location of a window in -comparison to other windows in the same frame. - - - Function: window-pixel-edges &optional window - This function returns a list of the pixel edge coordinates of - WINDOW. If WINDOW is `nil', the selected window is used. - - The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements - relative to 0, 0 at the top left corner of the frame. The element - RIGHT of the value is one more than the rightmost pixel used by - WINDOW (including any left margin, right margin, or vertical - scrollbar displayed alongside it), and BOTTOM is one more than the - bottommost pixel used by WINDOW (including any modeline or - horizontal scrollbar displayed above or below it). The frame area - does not include any frame menubars or toolbars that may be - displayed; thus, for example, if there is only one window on the - frame, the values for LEFT and TOP will always be 0. - - If WINDOW is at the upper left corner of its frame, RIGHT and - BOTTOM are the same as the values returned by - `(window-pixel-width)' and `(window-pixel-height)' respectively, - and TOP and BOTTOM are zero. - - There is no longer a function `window-edges' because it does not -make sense in a world with variable-width and variable-height lines, as -are allowed in XEmacs. - - - Function: window-highest-p window - This function returns non-`nil' if WINDOW is along the top of its - frame. - - - Function: window-lowest-p window - This function returns non-`nil' if WINDOW is along the bottom of - its frame. - - - Function: window-text-area-pixel-edges &optional window - This function allows one to determine the location of the - text-displaying portion of WINDOW, which defaults to the selected - window, with respect to the top left corner of the window. It - returns a list of integer pixel positions `(left top right - bottom)', all relative to `(0,0)' at the top left corner of the - window. - diff --git a/info/lispref.info-27 b/info/lispref.info-27 index c96a385..2c69bce 100644 --- a/info/lispref.info-27 +++ b/info/lispref.info-27 @@ -50,6 +50,493 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows + +The Window Start Position +========================= + + Each window contains a marker used to keep track of a buffer position +that specifies where in the buffer display should start. This position +is called the "display-start" position of the window (or just the +"start"). The character after this position is the one that appears at +the upper left corner of the window. It is usually, but not +inevitably, at the beginning of a text line. + + - Function: window-start &optional window + This function returns the display-start position of window WINDOW. + If WINDOW is `nil', the selected window is used. For example, + + (window-start) + => 7058 + + When you create a window, or display a different buffer in it, the + display-start position is set to a display-start position recently + used for the same buffer, or 1 if the buffer doesn't have any. + + For a realistic example, see the description of `count-lines' in + *Note Text Lines::. + + - Function: window-end &optional window guarantee + This function returns the position of the end of the display in + window WINDOW. If WINDOW is `nil', the selected window is used. + + Simply changing the buffer text or setting `window-start' does not + update the value that `window-end' returns. The value is updated + only when Emacs redisplays and redisplay actually finishes. + + If the last redisplay of WINDOW was preempted, and did not finish, + Emacs does not know the position of the end of display in that + window. In that case, this function returns a value that is not + correct. In a future version, `window-end' will return `nil' in + that case. + + If optional arg GUARANTEE is non-`nil', the return value is + guaranteed to be the same as `window-end' would return at the end + of the next full redisplay assuming nothing else changes in the + meantime. This function is potentially much slower with this flag + set. + + + - Function: set-window-start window position &optional noforce + This function sets the display-start position of WINDOW to + POSITION in WINDOW's buffer. It returns POSITION. + + The display routines insist that the position of point be visible + when a buffer is displayed. Normally, they change the + display-start position (that is, scroll the window) whenever + necessary to make point visible. However, if you specify the + start position with this function using `nil' for NOFORCE, it + means you want display to start at POSITION even if that would put + the location of point off the screen. If this does place point + off screen, the display routines move point to the left margin on + the middle line in the window. + + For example, if point is 1 and you set the start of the window + to 2, then point would be "above" the top of the window. The + display routines will automatically move point if it is still 1 + when redisplay occurs. Here is an example: + + ;; Here is what `foo' looks like before executing + ;; the `set-window-start' expression. + + ---------- Buffer: foo ---------- + -!-This is the contents of buffer foo. + 2 + 3 + 4 + 5 + 6 + ---------- Buffer: foo ---------- + + (set-window-start + (selected-window) + (1+ (window-start))) + => 2 + + ;; Here is what `foo' looks like after executing + ;; the `set-window-start' expression. + ---------- Buffer: foo ---------- + his is the contents of buffer foo. + 2 + 3 + -!-4 + 5 + 6 + ---------- Buffer: foo ---------- + + If NOFORCE is non-`nil', and POSITION would place point off screen + at the next redisplay, then redisplay computes a new window-start + position that works well with point, and thus POSITION is not used. + + - Function: pos-visible-in-window-p &optional position window + This function returns `t' if POSITION is within the range of text + currently visible on the screen in WINDOW. It returns `nil' if + POSITION is scrolled vertically out of view. The argument + POSITION defaults to the current position of point; WINDOW, to the + selected window. Here is an example: + + (or (pos-visible-in-window-p + (point) (selected-window)) + (recenter 0)) + + The `pos-visible-in-window-p' function considers only vertical + scrolling. If POSITION is out of view only because WINDOW has + been scrolled horizontally, `pos-visible-in-window-p' returns `t'. + *Note Horizontal Scrolling::. + + +File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows + +Vertical Scrolling +================== + + Vertical scrolling means moving the text up or down in a window. It +works by changing the value of the window's display-start location. It +may also change the value of `window-point' to keep it on the screen. + + In the commands `scroll-up' and `scroll-down', the directions "up" +and "down" refer to the motion of the text in the buffer at which you +are looking through the window. Imagine that the text is written on a +long roll of paper and that the scrolling commands move the paper up +and down. Thus, if you are looking at text in the middle of a buffer +and repeatedly call `scroll-down', you will eventually see the +beginning of the buffer. + + Some people have urged that the opposite convention be used: they +imagine that the window moves over text that remains in place. Then +"down" commands would take you to the end of the buffer. This view is +more consistent with the actual relationship between windows and the +text in the buffer, but it is less like what the user sees. The +position of a window on the terminal does not move, and short scrolling +commands clearly move the text up or down on the screen. We have chosen +names that fit the user's point of view. + + The scrolling functions (aside from `scroll-other-window') have +unpredictable results if the current buffer is different from the buffer +that is displayed in the selected window. *Note Current Buffer::. + + - Command: scroll-up &optional lines + This function scrolls the text in the selected window upward LINES + lines. If LINES is negative, scrolling is actually downward. + + If LINES is `nil' (or omitted), then the length of scroll is + `next-screen-context-lines' lines less than the usable height of + the window (not counting its modeline). + + `scroll-up' returns `nil'. + + - Command: scroll-down &optional lines + This function scrolls the text in the selected window downward + LINES lines. If LINES is negative, scrolling is actually upward. + + If LINES is omitted or `nil', then the length of the scroll is + `next-screen-context-lines' lines less than the usable height of + the window (not counting its mode line). + + `scroll-down' returns `nil'. + + - Command: scroll-other-window &optional lines + This function scrolls the text in another window upward LINES + lines. Negative values of LINES, or `nil', are handled as in + `scroll-up'. + + You can specify a buffer to scroll with the variable + `other-window-scroll-buffer'. When the selected window is the + minibuffer, the next window is normally the one at the top left + corner. You can specify a different window to scroll with the + variable `minibuffer-scroll-window'. This variable has no effect + when any other window is selected. *Note Minibuffer Misc::. + + When the minibuffer is active, it is the next window if the + selected window is the one at the bottom right corner. In this + case, `scroll-other-window' attempts to scroll the minibuffer. If + the minibuffer contains just one line, it has nowhere to scroll + to, so the line reappears after the echo area momentarily displays + the message "Beginning of buffer". + + - Variable: other-window-scroll-buffer + If this variable is non-`nil', it tells `scroll-other-window' + which buffer to scroll. + + - User Option: scroll-step + This variable controls how scrolling is done automatically when + point moves off the screen. If the value is zero, then redisplay + scrolls the text to center point vertically in the window. If the + value is a positive integer N, then redisplay brings point back on + screen by scrolling N lines in either direction, if possible; + otherwise, it centers point. The default value is zero. + + - User Option: scroll-conservatively + This variable controls how many lines Emacs tries to scroll before + recentering. If you set it to a small number, then when you move + point a short distance off the screen, XEmacs will scroll the + screen just far enough to bring point back on screen, provided + that does not exceed `scroll-conservatively' lines. This variable + overrides the redisplay preemption. + + - User Option: next-screen-context-lines + The value of this variable is the number of lines of continuity to + retain when scrolling by full screens. For example, `scroll-up' + with an argument of `nil' scrolls so that this many lines at the + bottom of the window appear instead at the top. The default value + is `2'. + + - Command: recenter &optional location window + This function scrolls WINDOW (which defaults to the selected + window) to put the text where point is located at a specified + vertical position within the window. + + If LOCATION is a nonnegative number, it puts the line containing + point LOCATION lines down from the top of the window. If LOCATION + is a negative number, then it counts upward from the bottom of the + window, so that -1 stands for the last usable line in the window. + If LOCATION is a non-`nil' list, then it stands for the line in + the middle of the window. + + If LOCATION is `nil', `recenter' puts the line containing point in + the middle of the window, then clears and redisplays the entire + selected frame. + + When `recenter' is called interactively, LOCATION is the raw + prefix argument. Thus, typing `C-u' as the prefix sets the + LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION + to 4, which positions the current line four lines from the top. + + With an argument of zero, `recenter' positions the current line at + the top of the window. This action is so handy that some people + make a separate key binding to do this. For example, + + (defun line-to-top-of-window () + "Scroll current line to top of window. + Replaces three keystroke sequence C-u 0 C-l." + (interactive) + (recenter 0)) + + (global-set-key [kp-multiply] 'line-to-top-of-window) + + +File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows + +Horizontal Scrolling +==================== + + Because we read English first from top to bottom and second from left +to right, horizontal scrolling is not like vertical scrolling. Vertical +scrolling involves selection of a contiguous portion of text to display. +Horizontal scrolling causes part of each line to go off screen. The +amount of horizontal scrolling is therefore specified as a number of +columns rather than as a position in the buffer. It has nothing to do +with the display-start position returned by `window-start'. + + Usually, no horizontal scrolling is in effect; then the leftmost +column is at the left edge of the window. In this state, scrolling to +the right is meaningless, since there is no data to the left of the +screen to be revealed by it; so this is not allowed. Scrolling to the +left is allowed; it scrolls the first columns of text off the edge of +the window and can reveal additional columns on the right that were +truncated before. Once a window has a nonzero amount of leftward +horizontal scrolling, you can scroll it back to the right, but only so +far as to reduce the net horizontal scroll to zero. There is no limit +to how far left you can scroll, but eventually all the text will +disappear off the left edge. + + - Command: scroll-left &optional count + This function scrolls the selected window COUNT columns to the + left (or to the right if COUNT is negative). The return value is + the total amount of leftward horizontal scrolling in effect after + the change--just like the value returned by `window-hscroll' + (below). + + - Command: scroll-right &optional count + This function scrolls the selected window COUNT columns to the + right (or to the left if COUNT is negative). The return value is + the total amount of leftward horizontal scrolling in effect after + the change--just like the value returned by `window-hscroll' + (below). + + Once you scroll a window as far right as it can go, back to its + normal position where the total leftward scrolling is zero, + attempts to scroll any farther right have no effect. + + - Function: window-hscroll &optional window + This function returns the total leftward horizontal scrolling of + WINDOW--the number of columns by which the text in WINDOW is + scrolled left past the left margin. + + The value is never negative. It is zero when no horizontal + scrolling has been done in WINDOW (which is usually the case). + + If WINDOW is `nil', the selected window is used. + + (window-hscroll) + => 0 + (scroll-left 5) + => 5 + (window-hscroll) + => 5 + + - Function: set-window-hscroll window columns + This function sets the number of columns from the left margin that + WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS + should be zero or positive; if not, it is taken as zero. + + The value returned is COLUMNS. + + (set-window-hscroll (selected-window) 10) + => 10 + + Here is how you can determine whether a given position POSITION is +off the screen due to horizontal scrolling: + + (defun hscroll-on-screen (window position) + (save-excursion + (goto-char position) + (and + (>= (- (current-column) (window-hscroll window)) 0) + (< (- (current-column) (window-hscroll window)) + (window-width window))))) + + +File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows + +The Size of a Window +==================== + + An Emacs window is rectangular, and its size information consists of +the height (in lines or pixels) and the width (in character positions +or pixels). The modeline is included in the height. The pixel width +and height values include scrollbars and margins, while the +line/character-position values do not. + + Note that the height in lines, and the width in characters, are +determined by dividing the corresponding pixel value by the height or +width of the default font in that window (if this is a variable-width +font, the average width is used). The resulting values may or may not +represent the actual number of lines in the window, or the actual number +of character positions in any particular line, esp. if there are pixmaps +or various different fonts in the window. + + The following functions return size information about a window: + + - Function: window-height &optional window + This function returns the number of lines in WINDOW, including its + modeline but not including the horizontal scrollbar, if any (this + is different from `window-pixel-height'). If WINDOW is `nil', the + function uses the selected window. + + (window-height) + => 40 + (split-window-vertically) + => # + (window-height) + => 20 + + - Function: window-width &optional window + This function returns the number of columns in WINDOW, not + including any left margin, right margin, or vertical scrollbar + (this is different from `window-pixel-width'). If WINDOW is + `nil', the function uses the selected window. + + (window-width) + => 80 + (window-height) + => 40 + (split-window-horizontally) + => # + (window-width) + => 39 + + Note that after splitting the window into two side-by-side windows, +the width of each window is less the half the width of the original +window because a vertical scrollbar appeared between the windows, +occupying two columns worth of space. Also, the height shrunk by one +because horizontal scrollbars appeared that weren't there before. +(Horizontal scrollbars appear only when lines are truncated, not when +they wrap. This is usually the case for horizontally split windows but +not for full-frame windows. You can change this using the variables +`truncate-lines' and `truncate-partial-width-windows'.) + + - Function: window-pixel-height &optional window + This function returns the height of WINDOW in pixels, including + its modeline and horizontal scrollbar, if any. If WINDOW is + `nil', the function uses the selected window. + + (window-pixel-height) + => 600 + (split-window-vertically) + => # + (window-pixel-height) + => 300 + + - Function: window-pixel-width &optional window + This function returns the width of WINDOW in pixels, including any + left margin, right margin, or vertical scrollbar that may be + displayed alongside it. If WINDOW is `nil', the function uses the + selected window. + + (window-pixel-width) + => 735 + (window-pixel-height) + => 600 + (split-window-horizontally) + => # + (window-pixel-width) + => 367 + (window-pixel-height) + => 600 + + - Function: window-text-area-pixel-height &optional window + This function returns the height in pixels of the text displaying + portion of WINDOW, which defaults to the selected window. Unlike + `window-pixel-height', the space occupied by the modeline and + horizontal scrollbar, if any, is not counted. + + - Function: window-text-area-pixel-width &optional window + This function returns the width in pixels of the text displaying + portion of WINDOW, which defaults to the selected window. Unlike + `window-pixel-width', the space occupied by the vertical scrollbar + and divider, if any, is not counted. + + - Function: window-displayed-text-pixel-height &optional window + noclipped + This function returns the height in pixels of the text displayed in + WINDOW, which defaults to the selected window. Unlike + `window-text-area-pixel-height', any blank space below the end of + the buffer is not included. If optional argument NOCLIPPED is + non-`nil', any space occupied by clipped lines will not be + included. + + +File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows + +The Position of a Window +======================== + + XEmacs provides functions to determine the absolute location of +windows within a frame, and the relative location of a window in +comparison to other windows in the same frame. + + - Function: window-pixel-edges &optional window + This function returns a list of the pixel edge coordinates of + WINDOW. If WINDOW is `nil', the selected window is used. + + The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements + relative to 0, 0 at the top left corner of WINDOW's frame. The + element RIGHT of the value is one more than the rightmost pixel + used by WINDOW (including any left margin, right margin, or + vertical scrollbar displayed alongside it), and BOTTOM is one more + than the bottommost pixel used by WINDOW (including any modeline + or horizontal scrollbar displayed above or below it). The frame + area does not include any frame menubars, toolbars, or gutters + that may be displayed; thus, for example, if there is only one + window on the frame, the values for LEFT and TOP will always be 0. + + If WINDOW is at the upper left corner of its frame, RIGHT and + BOTTOM are the same as the values returned by + `(window-pixel-width)' and `(window-pixel-height)' respectively, + and LEFT and TOP are zero. + + There is no longer a function `window-edges' because it does not +make sense in a world with variable-width and variable-height lines, as +are allowed in XEmacs. + + - Function: window-highest-p window + This function returns non-`nil' if WINDOW is along the top of its + frame. + + - Function: window-lowest-p window + This function returns non-`nil' if WINDOW is along the bottom of + its frame. + + - Function: window-text-area-pixel-edges &optional window + This function allows one to determine the location of the + text-displaying portion of WINDOW, which defaults to the selected + window, with respect to the top left corner of the window. It + returns a list of integer pixel positions `(left top right + 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 @@ -60,23 +547,23 @@ 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, + - Command: enlarge-window count &optional horizontal window + This function makes the selected window COUNT 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. + COUNT 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 + If COUNT is negative, this function shrinks the window by -COUNT 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. @@ -99,13 +586,13 @@ windows, so resizing one window affects other windows. 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 + - Command: shrink-window count &optional horizontal window This function is like `enlarge-window' but negates the argument - SIZE, making the selected window smaller by giving lines (or + COUNT, 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 + If COUNT is negative, the window is enlarged by -COUNT lines or columns. If WINDOW is non-`nil', it specifies a window to change instead of @@ -181,13 +668,15 @@ configuration previously saved. 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: current-window-configuration &optional frame + This function returns a new object representing the current current + window configuration of FRAME, 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. + + FRAME defaults to the selected frame. - Function: set-window-configuration configuration This function restores the configuration of XEmacs's windows and @@ -308,7 +797,7 @@ Creating Frames To create a new frame, call the function `make-frame'. - - Function: make-frame &optional props device + - Command: 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. @@ -365,16 +854,17 @@ Access to Frame Properties and their values. - Function: frame-property frame property &optional default - This function returns FRAME's value for the property PROPERTY. + This function returns FRAME's value for the property PROPERTY, or + DEFAULT if there is no such 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. + - Function: set-frame-property frame property value + This function sets the property PROPERTY of frame FRAME to the + value VALUE.  File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties @@ -585,9 +1075,9 @@ in its usual fashion. - 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.) + 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 @@ -670,574 +1160,18 @@ Deleting Frames 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 + - Command: delete-frame &optional frame force This function deletes the frame FRAME. By default, FRAME is the selected frame. + A frame may not be deleted if its minibuffer is used by other + frames. Normally, you cannot delete the last non-minibuffer-only + frame (you must use `save-buffers-kill-emacs' or `kill-emacs'). + However, if optional second argument FORCE is non-`nil', you can + delete the last frame. (This will automatically call + `save-buffers-kill-emacs'.) + - 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 -================== - - - Function: frame-list - The function `frame-list' returns a list of all the frames that - have not been deleted. It is analogous to `buffer-list' for - buffers. The list that you get is newly created, so modifying the - list doesn't have any effect on the internals of XEmacs. - - - Function: device-frame-list &optional device - This function returns a list of all frames on DEVICE. If DEVICE - is `nil', the selected device will be used. - - - Function: visible-frame-list &optional device - This function returns a list of just the currently visible frames. - If DEVICE is specified only frames on that device will be returned. - *Note Visibility of Frames::. (TTY frames always count as - "visible", even though only the selected one is actually - displayed.) - - - Function: next-frame &optional frame minibuf - The function `next-frame' lets you cycle conveniently through all - the frames from an arbitrary starting point. It returns the "next" - frame after FRAME in the cycle. If FRAME is omitted or `nil', it - defaults to the selected frame. - - The second argument, MINIBUF, says which frames to consider: - - `nil' - Exclude minibuffer-only frames. - - `visible' - Consider all visible frames. - - 0 - Consider all visible or iconified frames. - - a window - Consider only the frames using that particular window as their - minibuffer. - - the symbol `visible' - Include all visible frames. - - `0' - Include all visible and iconified frames. - - anything else - Consider all frames. - - - Function: previous-frame &optional frame minibuf - Like `next-frame', but cycles through all frames in the opposite - direction. - - See also `next-window' and `previous-window', in *Note Cyclic Window -Ordering::. - - -File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames - -Frames and Windows -================== - - Each window is part of one and only one frame; you can get the frame -with `window-frame'. - - - Function: frame-root-window &optional frame - This returns the root window of frame FRAME. FRAME defaults to - the selected frame if not specified. - - - Function: window-frame &optional window - This function returns the frame that WINDOW is on. WINDOW - defaults to the selected window if omitted. - - All the non-minibuffer windows in a frame are arranged in a cyclic -order. The order runs from the frame's top window, which is at the -upper left corner, down and to the right, until it reaches the window at -the lower right corner (always the minibuffer window, if the frame has -one), and then it moves back to the top. - - - Function: frame-top-window frame - This returns the topmost, leftmost window of frame FRAME. - - At any time, exactly one window on any frame is "selected within the -frame". The significance of this designation is that selecting the -frame also selects this window. You can get the frame's current -selected window with `frame-selected-window'. - - - Function: frame-selected-window &optional frame - This function returns the window on FRAME that is selected within - FRAME. FRAME defaults to the selected frame if not specified. - - Conversely, selecting a window for XEmacs with `select-window' also -makes that window selected within its frame. *Note Selecting Windows::. - - Another function that (usually) returns one of the windows in a -frame is `minibuffer-window'. *Note Minibuffer Misc::. - - -File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames - -Minibuffers and Frames -====================== - - Normally, each frame has its own minibuffer window at the bottom, -which is used whenever that frame is selected. If the frame has a -minibuffer, you can get it with `minibuffer-window' (*note Minibuffer -Misc::). - - However, you can also create a frame with no minibuffer. Such a -frame must use the minibuffer window of some other frame. When you -create the frame, you can specify explicitly the minibuffer window to -use (in some other frame). If you don't, then the minibuffer is found -in the frame which is the value of the variable -`default-minibuffer-frame'. Its value should be a frame which does -have a minibuffer. - - - Variable: default-minibuffer-frame - This variable specifies the frame to use for the minibuffer - window, by default. - - -File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames - -Input Focus -=========== - - At any time, one frame in XEmacs is the "selected frame". The -selected window always resides on the selected frame. As the focus -moves from device to device, the selected frame on each device is -remembered and restored when the focus moves back to that device. - - - Function: selected-frame &optional device - This function returns the selected frame on DEVICE. If DEVICE is - not specified, the selected device will be used. If no frames - exist on the device, `nil' is returned. - - The X server normally directs keyboard input to the X window that the -mouse is in. Some window managers use mouse clicks or keyboard events -to "shift the focus" to various X windows, overriding the normal -behavior of the server. - - Lisp programs can switch frames "temporarily" by calling the -function `select-frame'. This does not override the window manager; -rather, it escapes from the window manager's control until that control -is somehow reasserted. - - When using a text-only terminal, there is no window manager; -therefore, `select-frame' is the only way to switch frames, and the -effect lasts until overridden by a subsequent call to `select-frame'. -Only the selected terminal frame is actually displayed on the terminal. -Each terminal screen except for the initial one has a number, and the -number of the selected frame appears in the mode line after the word -`XEmacs' (*note Modeline Variables::). - - - Function: select-frame frame - This function selects frame FRAME, temporarily disregarding the - focus of the X server if any. The selection of FRAME lasts until - the next time the user does something to select a different frame, - or until the next time this function is called. - - Note that `select-frame' does not actually cause the window-system - focus to be set to this frame, or the `select-frame-hook' or - `deselect-frame-hook' to be run, until the next time that XEmacs is - waiting for an event. - - Also note that when the variable `focus-follows-mouse' is - non-`nil', the frame selection is temporary and is reverted when - the current command terminates, much like the buffer selected by - `set-buffer'. In order to effect a permanent focus change use - `focus-frame'. - - - Function: focus-frame frame - This function selects FRAME and gives it the window system focus. - The operation of `focus-frame' is not affected by the value of - `focus-follows-mouse'. - - - Macro: save-selected-frame forms... - This macro records the selected frame, executes FORMS in sequence, - then restores the earlier selected frame. The value returned is - the value of the last form. - - - Macro: with-selected-frame frame forms... - This macro records the selected frame, then selects FRAME and - executes FORMS in sequence. After the last form is finished, the - earlier selected frame is restored. The value returned is the - value of the last form. - - -File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames - -Visibility of Frames -==================== - - An X window frame may be "visible", "invisible", or "iconified". If -it is visible, you can see its contents. If it is iconified, the -frame's contents do not appear on the screen, but an icon does. If the -frame is invisible, it doesn't show on the screen, not even as an icon. - - Visibility is meaningless for TTY frames, since only the selected -one is actually displayed in any case. - - - Command: make-frame-visible &optional frame - This function makes frame FRAME visible. If you omit FRAME, it - makes the selected frame visible. - - - Command: make-frame-invisible &optional frame - This function makes frame FRAME invisible. - - - Command: iconify-frame &optional frame - This function iconifies frame FRAME. - - - Command: deiconify-frame &optional frame - This function de-iconifies frame FRAME. Under X, this is - equivalent to `make-frame-visible'. - - - Function: frame-visible-p frame - This returns whether FRAME is currently "visible" (actually in use - for display). A frame that is not visible is not updated, and, if - it works through a window system, may not show at all. - - - Function: frame-iconified-p frame - This returns whether FRAME is iconified. Not all window managers - use icons; some merely unmap the window, so this function is not - the inverse of `frame-visible-p'. It is possible for a frame to - not be visible and not be iconified either. However, if the frame - is iconified, it will not be visible. (Under FSF Emacs, the - functionality of this function is obtained through - `frame-visible-p'.) - - - Function: frame-totally-visible-p frame - This returns whether FRAME is not obscured by any other X windows. - On TTY frames, this is the same as `frame-visible-p'. - - -File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames - -Raising and Lowering Frames -=========================== - - The X Window System uses a desktop metaphor. Part of this metaphor -is the idea that windows are stacked in a notional third dimension -perpendicular to the screen surface, and thus ordered from "highest" to -"lowest". Where two windows overlap, the one higher up covers the one -underneath. Even a window at the bottom of the stack can be seen if no -other window overlaps it. - - A window's place in this ordering is not fixed; in fact, users tend -to change the order frequently. "Raising" a window means moving it -"up", to the top of the stack. "Lowering" a window means moving it to -the bottom of the stack. This motion is in the notional third -dimension only, and does not change the position of the window on the -screen. - - You can raise and lower XEmacs's X windows with these functions: - - - Command: raise-frame &optional frame - This function raises frame FRAME. - - - Command: lower-frame &optional frame - This function lowers frame FRAME. - - You can also specify auto-raise (raising automatically when a frame -is selected) or auto-lower (lowering automatically when it is -deselected). Under X, most ICCCM-compliant window managers will have -an option to do this for you, but the following variables are provided -in case you're using a broken WM. (Under FSF Emacs, the same -functionality is provided through the `auto-raise' and `auto-lower' -frame properties.) - - - Variable: auto-raise-frame - This variable's value is `t' if frames will be raised to the top - when selected. - - - Variable: auto-lower-frame - This variable's value is `t' if frames will be lowered to the - bottom when no longer selected. - - Auto-raising and auto-lowering is implemented through functions -attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame -Hooks::). Under normal circumstances, you should not call these -functions directly. - - - Function: default-select-frame-hook - This hook function implements the `auto-raise-frame' variable; it - is for use as the value of `select-frame-hook'. - - - Function: default-deselect-frame-hook - This hook function implements the `auto-lower-frame' variable; it - is for use as the value of `deselect-frame-hook'. - - -File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames - -Frame Configurations -==================== - - A "frame configuration" records the current arrangement of frames, -all their properties, and the window configuration of each one. - - - Function: current-frame-configuration - This function returns a frame configuration list that describes - the current arrangement of frames and their contents. - - - Function: set-frame-configuration configuration - This function restores the state of frames described in - CONFIGURATION. - - -File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames - -Hooks for Customizing Frame Behavior -==================================== - - XEmacs provides many hooks that are called at various times during a -frame's lifetime. *Note Hooks::. - - - Variable: create-frame-hook - This hook is called each time a frame is created. The functions - are called with one argument, the newly-created frame. - - - Variable: delete-frame-hook - This hook is called each time a frame is deleted. The functions - are called with one argument, the about-to-be-deleted frame. - - - Variable: select-frame-hook - This is a normal hook that is run just after a frame is selected. - The function `default-select-frame-hook', which implements - auto-raising (*note Raising and Lowering::), is normally attached - to this hook. - - Note that calling `select-frame' does not necessarily set the - focus: The actual window-system focus will not be changed until - the next time that XEmacs is waiting for an event, and even then, - the window manager may refuse the focus-change request. - - - Variable: deselect-frame-hook - This is a normal hook that is run just before a frame is deselected - (and another frame is selected). The function - `default-deselect-frame-hook', which implements auto-lowering - (*note Raising and Lowering::), is normally attached to this hook. - - - Variable: map-frame-hook - This hook is called each time a frame is mapped (i.e. made - visible). The functions are called with one argument, the newly - mapped frame. - - - Variable: unmap-frame-hook - This hook is called each time a frame is unmapped (i.e. made - invisible or iconified). The functions are called with one - argument, the newly unmapped frame. - - -File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top - -Consoles and Devices -******************** - - A "console" is an object representing a single input connection to -XEmacs, such as an X display or a TTY connection. It is possible for -XEmacs to have frames on multiple consoles at once (even on -heterogeneous types--you can simultaneously have a frame on an X -display and a TTY connection). Normally, there is only one console in -existence. - - A "device" is an object representing a single output device, such as -a particular screen on an X display. (Usually there is exactly one -device per X console connection, but there may be more than one if you -have a multi-headed X display. For TTY connections, there is always -exactly one device per console.) - - Each device has one or more "frames" in which text can be displayed. -For X displays and the like, a frame corresponds to the normal -window-system concept of a window. Frames can overlap, be displayed at -various locations within the display, be resized, etc. For TTY, only -one frame can be displayed at a time, and it occupies the entire TTY -display area. - - However, you can still define multiple frames and switch between -them. Their contents are entirely separate from each other. These -sorts of frames resemble the "virtual console" capability provided -under Linux or the multiple screens provided by the multiplexing program -`screen' under Unix. - - When you start up XEmacs, an initial console and device are created -to receive input and display frames on. This will either be an X -display or a TTY connection, depending on what mode you started XEmacs -in (this is determined by the `DISPLAY' environment variable, the -`-nw', `-t' and `-display' command-line options, etc.). - - You can connect to other X displays and TTY connections by creating -new console objects, and to other X screens on an existing display by -creating new device objects, as described below. Many functions (for -example the frame-creation functions) take an optional device argument -specifying which device the function pertains to. If the argument is -omitted, it defaults to the selected device (see below). - - - Function: consolep object - This returns non-`nil' if OBJECT is a console. - - - Function: devicep object - This returns non-`nil' if OBJECT is a device. - -* Menu: - -* Basic Console Functions:: Functions for working with consoles. -* Basic Device Functions:: Functions for working with devices. -* Console Types and Device Classes:: - I/O and color characteristics. -* Connecting to a Console or Device:: -* The Selected Console and Device:: -* Console and Device I/O:: Controlling input and output. - - -File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices - -Basic Console Functions -======================= - - - Function: console-list - This function returns a list of all existing consoles. - - - Function: console-device-list &optional console - This function returns a list of all devices on CONSOLE. If - CONSOLE is `nil', the selected console will be used. - - -File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices - -Basic Device Functions -====================== - - - Function: device-list - This function returns a list of all existing devices. - - - Function: device-or-frame-p object - This function returns non-`nil' if OBJECT is a device or frame. - This function is useful because devices and frames are similar in - many respects and many functions can operate on either one. - - - Function: device-frame-list device - This function returns a list of all frames on DEVICE. - - - Function: frame-device frame - This function returns the device that FRAME is on. - - -File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices - -Console Types and Device Classes -================================ - - Every device is of a particular "type", which describes how the -connection to that device is made and how the device operates, and a -particular "class", which describes other characteristics of the device -(currently, the color capabilities of the device). - - The currently-defined device types are - -`x' - A connection to an X display (such as `willow:0'). - -`tty' - A connection to a tty (such as `/dev/ttyp3'). - -`stream' - A stdio connection. This describes a device for which input and - output is only possible in a stream-like fashion, such as when - XEmacs in running in batch mode. The very first device created by - XEmacs is a terminal device and is used to print out messages of - various sorts (for example, the help message when you use the - `-help' command-line option). - - The currently-defined device classes are -`color' - A color device. - -`grayscale' - A grayscale device (a device that can display multiple shades of - gray, but no color). - -`mono' - A device that can only display two colors (e.g. black and white). - - - Function: device-type device - This function returns the type of DEVICE. This is a symbol whose - name is one of the device types mentioned above. - - - Function: device-or-frame-type device-or-frame - This function returns the type of DEVICE-OR-FRAME. - - - Function: device-class device - This function returns the class (color behavior) of DEVICE. This - is a symbol whose name is one of the device classes mentioned - above. - - - Function: valid-device-type-p device-type - This function returns whether DEVICE-TYPE (which should be a - symbol) specifies a valid device type. - - - Function: valid-device-class-p device-class - This function returns whether DEVICE-CLASS (which should be a - symbol) specifies a valid device class. - - - Variable: terminal-device - This variable holds the initial terminal device object, which - represents XEmacs's stdout. - - -File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices - -Connecting to a Console or Device -================================= - - - Function: make-device &optional type device-data - This function creates a new device. - - The following two functions create devices of specific types and are -written in terms of `make-device'. - - - Function: make-tty-device &optional tty terminal-type - This function creates a new tty device on TTY. This also creates - the tty's first frame. TTY should be a string giving the name of - a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as - returned by the `tty' command issued from the Unix shell. A value - of `nil' means use the stdin and stdout as passed to XEmacs from - the shell. If TERMINAL-TYPE is non-`nil', it should be a string - specifying the type of the terminal attached to the specified tty. - If it is `nil', the terminal type will be inferred from the - `TERM' environment variable. - - - Function: make-x-device &optional display argv-list - This function creates a new device connected to DISPLAY. Optional - argument ARGV-LIST is a list of strings describing command line - options. - - - Function: delete-device device - This function deletes DEVICE, permanently eliminating it from use. - This disconnects XEmacs's connection to the device. - - - Variable: create-device-hook - This variable, if non-`nil', should contain a list of functions, - which are called when a device is created. - - - Variable: delete-device-hook - This variable, if non-`nil', should contain a list of functions, - which are called when a device is deleted. - - - Function: console-live-p object - This function returns non-`nil' if OBJECT is a console that has - not been deleted. - - - Function: device-live-p object - This function returns non-`nil' if OBJECT is a device that has not - been deleted. - - - Function: device-x-display device - This function returns the X display which DEVICE is connected to, - if DEVICE is an X device. - diff --git a/info/lispref.info-28 b/info/lispref.info-28 index 51c114c..02d67fe 100644 --- a/info/lispref.info-28 +++ b/info/lispref.info-28 @@ -50,6 +50,650 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames + +Finding All Frames +================== + + - Function: frame-list + The function `frame-list' returns a list of all the frames that + have not been deleted. It is analogous to `buffer-list' for + buffers. The list that you get is newly created, so modifying the + list doesn't have any effect on the internals of XEmacs. + + - Function: device-frame-list &optional device + This function returns a list of all frames on DEVICE. If DEVICE + is `nil', the selected device will be used. + + - Function: visible-frame-list &optional device + This function returns a list of just the currently visible frames. + If DEVICE is specified only frames on that device will be returned. + *Note Visibility of Frames::. (TTY frames always count as + "visible", even though only the selected one is actually + displayed.) + + - Function: next-frame &optional frame which-frames which-devices + The function `next-frame' lets you cycle conveniently through all + the frames from an arbitrary starting point. It returns the "next" + frame after FRAME in the cycle. If FRAME defaults to the selected + frame. + + The second argument, WHICH-FRAMES, says which frames to consider: + + `visible' + Consider only frames that are visible. + + `iconic' + Consider only frames that are iconic. + + `invisible' + Consider only frames that are invisible (this is different + from iconic). + + `visible-iconic' + Consider frames that are visible or iconic. + + `invisible-iconic' + Consider frames that are invisible or iconic. + + `nomini' + Consider all frames except minibuffer-only ones. + + `visible-nomini' + Like `visible' but omits minibuffer-only frames. + + `iconic-nomini' + Like `iconic' but omits minibuffer-only frames. + + `invisible-nomini' + Like `invisible' but omits minibuffer-only frames. + + `visible-iconic-nomini' + Like `visible-iconic' but omits minibuffer-only frames. + + `invisible-iconic-nomini' + Like `invisible-iconic' but omits minibuffer-only frames. + + `nil' + Identical to `nomini'. + + WINDOW + Consider only the window WINDOW's frame and any frame now + using WINDOW as the minibuffer. + + any other value + Consider all frames. + + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + - Function: previous-frame &optional frame which-frames which-devices + Like `next-frame', but cycles through all frames in the opposite + direction. + + See also `next-window' and `previous-window', in *Note Cyclic Window +Ordering::. + + +File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames + +Frames and Windows +================== + + Each window is part of one and only one frame; you can get the frame +with `window-frame'. + + - Function: frame-root-window &optional frame + This returns the root window of frame FRAME. FRAME defaults to + the selected frame if not specified. + + - Function: window-frame &optional window + This function returns the frame that WINDOW is on. WINDOW + defaults to the selected window if omitted. + + All the non-minibuffer windows in a frame are arranged in a cyclic +order. The order runs from the frame's top window, which is at the +upper left corner, down and to the right, until it reaches the window at +the lower right corner (always the minibuffer window, if the frame has +one), and then it moves back to the top. + + - Function: frame-highest-window &optional frame position + This function returns the topmost, leftmost window of frame FRAME + at position POSITION. + + If omitted, FRAME defaults to the currently selected frame. + + POSITION is used to distinguish between multiple windows that abut + the top of the frame: 0 means the leftmost window abutting the top + of the frame, 1 the next-leftmost, etc. POSITION can also be less + than zero: -1 means the rightmost window abutting the top of the + frame, -2 the next-rightmost, etc. If omitted, POSITION defaults + to 0, i.e. the leftmost highest window. If there is no window at + the given POSITION, `nil' is returned. + + The following three functions work similarly. + + - Function: frame-lowest-window &optional frame position + This function returns the lowest window on FRAME which is at + POSITION. + + - Function: frame-leftmost-window &optional frame position + This function returns the leftmost window on FRAME which is at + POSITION. + + - Function: frame-rightmost-window &optional frame position + This function returns the rightmost window on FRAME which is at + POSITION. + + At any time, exactly one window on any frame is "selected within the +frame". The significance of this designation is that selecting the +frame also selects this window. You can get the frame's current +selected window with `frame-selected-window'. + + - Function: frame-selected-window &optional frame + This function returns the window on FRAME that is selected within + FRAME. FRAME defaults to the selected frame if not specified. + + Conversely, selecting a window for XEmacs with `select-window' also +makes that window selected within its frame. *Note Selecting Windows::. + + Another function that (usually) returns one of the windows in a +frame is `minibuffer-window'. *Note Minibuffer Misc::. + + +File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames + +Minibuffers and Frames +====================== + + Normally, each frame has its own minibuffer window at the bottom, +which is used whenever that frame is selected. If the frame has a +minibuffer, you can get it with `minibuffer-window' (*note Minibuffer +Misc::). + + However, you can also create a frame with no minibuffer. Such a +frame must use the minibuffer window of some other frame. When you +create the frame, you can specify explicitly the minibuffer window to +use (in some other frame). If you don't, then the minibuffer is found +in the frame which is the value of the variable +`default-minibuffer-frame'. Its value should be a frame which does +have a minibuffer. + + - Variable: default-minibuffer-frame + This variable specifies the frame to use for the minibuffer + window, by default. + + +File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames + +Input Focus +=========== + + At any time, one frame in XEmacs is the "selected frame". The +selected window always resides on the selected frame. As the focus +moves from device to device, the selected frame on each device is +remembered and restored when the focus moves back to that device. + + - Function: selected-frame &optional device + This function returns the selected frame on DEVICE. If DEVICE is + not specified, the selected device will be used. If no frames + exist on the device, `nil' is returned. + + The X server normally directs keyboard input to the X window that the +mouse is in. Some window managers use mouse clicks or keyboard events +to "shift the focus" to various X windows, overriding the normal +behavior of the server. + + Lisp programs can switch frames "temporarily" by calling the +function `select-frame'. This does not override the window manager; +rather, it escapes from the window manager's control until that control +is somehow reasserted. + + When using a text-only terminal, there is no window manager; +therefore, `select-frame' is the only way to switch frames, and the +effect lasts until overridden by a subsequent call to `select-frame'. +Only the selected terminal frame is actually displayed on the terminal. +Each terminal screen except for the initial one has a number, and the +number of the selected frame appears in the mode line after the word +`XEmacs' (*note Modeline Variables::). + + - Function: select-frame frame + This function selects frame FRAME, temporarily disregarding the + focus of the X server if any. The selection of FRAME lasts until + the next time the user does something to select a different frame, + or until the next time this function is called. + + Note that `select-frame' does not actually cause the window-system + focus to be set to this frame, or the `select-frame-hook' or + `deselect-frame-hook' to be run, until the next time that XEmacs is + waiting for an event. + + Also note that when the variable `focus-follows-mouse' is + non-`nil', the frame selection is temporary and is reverted when + the current command terminates, much like the buffer selected by + `set-buffer'. In order to effect a permanent focus change use + `focus-frame'. + + - Function: focus-frame frame + This function selects FRAME and gives it the window system focus. + The operation of `focus-frame' is not affected by the value of + `focus-follows-mouse'. + + - Special Form: save-selected-frame forms... + This special form records the selected frame, executes FORMS in + sequence, then restores the earlier selected frame. The value + returned is the value of the last form. + + - Special Form: with-selected-frame frame forms... + This special form records the selected frame, then selects FRAME + and executes FORMS in sequence. After the last form is finished, + the earlier selected frame is restored. The value returned is the + value of the last form. + + +File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames + +Visibility of Frames +==================== + + An frame on a window system may be "visible", "invisible", or +"iconified". If it is visible, you can see its contents. If it is +iconified, the frame's contents do not appear on the screen, but an icon +does. If the frame is invisible, it doesn't show on the screen, not +even as an icon. + + Visibility is meaningless for TTY frames, since only the selected +one is actually displayed in any case. + + - Function: make-frame-visible &optional frame + This function makes frame FRAME visible. If you omit FRAME, it + makes the selected frame visible. + + - Function: make-frame-invisible &optional frame force + This function makes frame FRAME invisible. + + - Command: iconify-frame &optional frame + This function iconifies frame FRAME. + + - Function: Command deiconify-frame &optional frame + This function de-iconifies frame FRAME. Under a window system, + this is equivalent to `make-frame-visible'. + + - Function: frame-visible-p &optional frame + This returns whether FRAME is currently "visible" (actually in use + for display). A frame that is not visible is not updated, and, if + it works through a window system, may not show at all. + + - Function: frame-iconified-p &optional frame + This returns whether FRAME is iconified. Not all window managers + use icons; some merely unmap the window, so this function is not + the inverse of `frame-visible-p'. It is possible for a frame to + not be visible and not be iconified either. However, if the frame + is iconified, it will not be visible. (Under FSF Emacs, the + functionality of this function is obtained through + `frame-visible-p'.) + + - Function: frame-totally-visible-p &optional frame + This returns whether FRAME is not obscured by any other X windows. + On TTY frames, this is the same as `frame-visible-p'. + + +File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames + +Raising and Lowering Frames +=========================== + + The X Window System uses a desktop metaphor. Part of this metaphor +is the idea that windows are stacked in a notional third dimension +perpendicular to the screen surface, and thus ordered from "highest" to +"lowest". Where two windows overlap, the one higher up covers the one +underneath. Even a window at the bottom of the stack can be seen if no +other window overlaps it. + + A window's place in this ordering is not fixed; in fact, users tend +to change the order frequently. "Raising" a window means moving it +"up", to the top of the stack. "Lowering" a window means moving it to +the bottom of the stack. This motion is in the notional third +dimension only, and does not change the position of the window on the +screen. + + You can raise and lower XEmacs's X windows with these functions: + + - Command: raise-frame &optional frame + This function raises frame FRAME. + + - Command: lower-frame &optional frame + This function lowers frame FRAME. + + You can also specify auto-raise (raising automatically when a frame +is selected) or auto-lower (lowering automatically when it is +deselected). Under X, most ICCCM-compliant window managers will have +an option to do this for you, but the following variables are provided +in case you're using a broken WM. (Under FSF Emacs, the same +functionality is provided through the `auto-raise' and `auto-lower' +frame properties.) + + - Variable: auto-raise-frame + This variable's value is `t' if frames will be raised to the top + when selected. + + - Variable: auto-lower-frame + This variable's value is `t' if frames will be lowered to the + bottom when no longer selected. + + Auto-raising and auto-lowering is implemented through functions +attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame +Hooks::). Under normal circumstances, you should not call these +functions directly. + + - Function: default-select-frame-hook + This hook function implements the `auto-raise-frame' variable; it + is for use as the value of `select-frame-hook'. + + - Function: default-deselect-frame-hook + This hook function implements the `auto-lower-frame' variable; it + is for use as the value of `deselect-frame-hook'. + + +File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames + +Frame Configurations +==================== + + A "frame configuration" records the current arrangement of frames, +all their properties, and the window configuration of each one. + + - Function: current-frame-configuration + This function returns a frame configuration list that describes + the current arrangement of frames and their contents. + + - Function: set-frame-configuration configuration &optional nodelete + This function restores the state of frames described by + CONFIGURATION, which should be the return value from a previous + call to `current-frame-configuration'. + + Each frame listed in CONFIGURATION has its position, size, window + configuration, and other properties set as specified in + CONFIGURATION. + + Ordinarily, this function deletes all existing frames not listed in + CONFIGURATION. But if optional second argument NODELETE is + non-`nil', the unwanted frames are iconified instead. + + +File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames + +Hooks for Customizing Frame Behavior +==================================== + + XEmacs provides many hooks that are called at various times during a +frame's lifetime. *Note Hooks::. + + - Variable: create-frame-hook + This hook is called each time a frame is created. The functions + are called with one argument, the newly-created frame. + + - Variable: delete-frame-hook + This hook is called each time a frame is deleted. The functions + are called with one argument, the about-to-be-deleted frame. + + - Variable: select-frame-hook + This is a normal hook that is run just after a frame is selected. + The function `default-select-frame-hook', which implements + auto-raising (*note Raising and Lowering::), is normally attached + to this hook. + + Note that calling `select-frame' does not necessarily set the + focus: The actual window-system focus will not be changed until + the next time that XEmacs is waiting for an event, and even then, + the window manager may refuse the focus-change request. + + - Variable: deselect-frame-hook + This is a normal hook that is run just before a frame is deselected + (and another frame is selected). The function + `default-deselect-frame-hook', which implements auto-lowering + (*note Raising and Lowering::), is normally attached to this hook. + + - Variable: map-frame-hook + This hook is called each time a frame is mapped (i.e. made + visible). The functions are called with one argument, the newly + mapped frame. + + - Variable: unmap-frame-hook + This hook is called each time a frame is unmapped (i.e. made + invisible or iconified). The functions are called with one + argument, the newly unmapped frame. + + +File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top + +Consoles and Devices +******************** + + A "console" is an object representing a single input connection to +XEmacs, such as an X display or a TTY connection. It is possible for +XEmacs to have frames on multiple consoles at once (even on +heterogeneous types--you can simultaneously have a frame on an X +display and a TTY connection). Normally, there is only one console in +existence. + + A "device" is an object representing a single output device, such as +a particular screen on an X display. (Usually there is exactly one +device per X console connection, but there may be more than one if you +have a multi-headed X display. For TTY connections, there is always +exactly one device per console.) + + Each device has one or more "frames" in which text can be displayed. +For X displays and the like, a frame corresponds to the normal +window-system concept of a window. Frames can overlap, be displayed at +various locations within the display, be resized, etc. For TTY, only +one frame can be displayed at a time, and it occupies the entire TTY +display area. + + However, you can still define multiple frames and switch between +them. Their contents are entirely separate from each other. These +sorts of frames resemble the "virtual console" capability provided +under Linux or the multiple screens provided by the multiplexing program +`screen' under Unix. + + When you start up XEmacs, an initial console and device are created +to receive input and display frames on. This will either be an X +display or a TTY connection, depending on what mode you started XEmacs +in (this is determined by the `DISPLAY' environment variable, the +`-nw', `-t' and `-display' command-line options, etc.). + + You can connect to other X displays and TTY connections by creating +new console objects, and to other X screens on an existing display by +creating new device objects, as described below. Many functions (for +example the frame-creation functions) take an optional device argument +specifying which device the function pertains to. If the argument is +omitted, it defaults to the selected device (see below). + + - Function: consolep object + This returns non-`nil' if OBJECT is a console. + + - Function: devicep object + This returns non-`nil' if OBJECT is a device. + +* Menu: + +* Basic Console Functions:: Functions for working with consoles. +* Basic Device Functions:: Functions for working with devices. +* Console Types and Device Classes:: + I/O and color characteristics. +* Connecting to a Console or Device:: +* The Selected Console and Device:: +* Console and Device I/O:: Controlling input and output. + + +File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices + +Basic Console Functions +======================= + + - Function: console-list + This function returns a list of all existing consoles. + + - Function: console-device-list &optional console + This function returns a list of all devices on CONSOLE. If + CONSOLE is `nil', the selected console will be used. + + +File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices + +Basic Device Functions +====================== + + - Function: device-list + This function returns a list of all existing devices. + + - Function: device-or-frame-p object + This function returns non-`nil' if OBJECT is a device or frame. + This function is useful because devices and frames are similar in + many respects and many functions can operate on either one. + + - Function: device-frame-list &optional device + This function returns a list of all frames on DEVICE. DEVICE + defaults to the currently selected device. + + - Function: frame-device &optional frame + This function returns the device that FRAME is on. FRAME defaults + to the currently selected frame. + + +File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices + +Console Types and Device Classes +================================ + + Every device is of a particular "type", which describes how the +connection to that device is made and how the device operates, and a +particular "class", which describes other characteristics of the device +(currently, the color capabilities of the device). + + The currently-defined device types are + +`x' + A connection to an X display (such as `willow:0'). + +`tty' + A connection to a tty (such as `/dev/ttyp3'). + +`stream' + A stdio connection. This describes a device for which input and + output is only possible in a stream-like fashion, such as when + XEmacs in running in batch mode. The very first device created by + XEmacs is a terminal device and is used to print out messages of + various sorts (for example, the help message when you use the + `-help' command-line option). + + The currently-defined device classes are +`color' + A color device. + +`grayscale' + A grayscale device (a device that can display multiple shades of + gray, but no color). + +`mono' + A device that can only display two colors (e.g. black and white). + + - Function: device-type &optional device + This function returns the type of DEVICE. This is a symbol whose + name is one of the device types mentioned above. DEVICE defaults + to the selected device. + + - Function: device-or-frame-type device-or-frame + This function returns the type of DEVICE-OR-FRAME. + + - Function: device-class &optional device + This function returns the class (color behavior) of DEVICE. This + is a symbol whose name is one of the device classes mentioned + above. + + - Function: valid-device-type-p device-type + This function returns whether DEVICE-TYPE (which should be a + symbol) specifies a valid device type. + + - Function: valid-device-class-p device-class + This function returns whether DEVICE-CLASS (which should be a + symbol) specifies a valid device class. + + - Variable: terminal-device + This variable holds the initial terminal device object, which + represents XEmacs's stdout. + + +File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices + +Connecting to a Console or Device +================================= + + - Function: make-device type connection &optional props + This function creates a new device. + + The following two functions create devices of specific types and are +written in terms of `make-device'. + + - Function: make-tty-device &optional tty terminal-type + This function creates a new tty device on TTY. This also creates + the tty's first frame. TTY should be a string giving the name of + a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as + returned by the `tty' command issued from the Unix shell. A value + of `nil' means use the stdin and stdout as passed to XEmacs from + the shell. If TERMINAL-TYPE is non-`nil', it should be a string + specifying the type of the terminal attached to the specified tty. + If it is `nil', the terminal type will be inferred from the + `TERM' environment variable. + + - Function: make-x-device &optional display argv-list + This function creates a new device connected to DISPLAY. Optional + argument ARGV-LIST is a list of strings describing command line + options. + + - Function: delete-device device &optional force + This function deletes DEVICE, permanently eliminating it from use. + This disconnects XEmacs's connection to the device. + + - Variable: create-device-hook + This variable, if non-`nil', should contain a list of functions, + which are called when a device is created. + + - Variable: delete-device-hook + This variable, if non-`nil', should contain a list of functions, + which are called when a device is deleted. + + - Function: console-live-p object + This function returns non-`nil' if OBJECT is a console that has + not been deleted. + + - Function: device-live-p object + This function returns non-`nil' if OBJECT is a device that has not + been deleted. + + - Function: device-x-display 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 @@ -318,26 +962,26 @@ Likewise, to move to the end of the buffer, use: 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 + - Command: beginning-of-buffer &optional count 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. + setting the mark at the previous position. If COUNT is non-`nil', + then it puts point COUNT 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'. + In an interactive call, COUNT is the numeric prefix argument, if + provided; otherwise COUNT defaults to `nil'. Don't use this function in Lisp programs! - - Command: end-of-buffer &optional n + - Command: end-of-buffer &optional count 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. + the mark at the previous position. If COUNT is non-`nil', then it + puts point COUNT 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'. + In an interactive call, COUNT is the numeric prefix argument, if + provided; otherwise COUNT defaults to `nil'. Don't use this function in Lisp programs! @@ -418,7 +1062,7 @@ tabs and control characters are displayed. In an interactive call, COUNT is the numeric prefix argument. - - Function: count-lines start end + - Function: count-lines start end &optional ignore-invisible-lines-flag 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 @@ -426,6 +1070,14 @@ tabs and control characters are displayed. them, considered in isolation, must contain at least one line unless it is empty. + With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines + collapsed with selective-display are excluded from the line count. + + *Note:* The expression to return the current line number is not + obvious: + + (1+ (count-lines 1 (point-at-bol))) + Here is an example of using `count-lines': (defun current-line () @@ -518,671 +1170,3 @@ performance of your code. *Note cache-long-line-scans: Text Lines. 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 -========== - - It is often useful to move point "temporarily" within a localized -portion of the program, or to switch buffers temporarily. This is -called an "excursion", and it is done with the `save-excursion' special -form. This construct saves the current buffer and its values of point -and the mark so they can be restored after the completion of the -excursion. - - The forms for saving and restoring the configuration of windows are -described elsewhere (see *Note Window Configurations:: and *note Frame -Configurations::). - - - Special Form: save-excursion forms... - The `save-excursion' special form saves the identity of the current - buffer and the values of point and the mark in it, evaluates - FORMS, and finally restores the buffer and its saved values of - point and the mark. All three saved values are restored even in - case of an abnormal exit via `throw' or error (*note Nonlocal - Exits::). - - The `save-excursion' special form is the standard way to switch - buffers or move point within one part of a program and avoid - affecting the rest of the program. It is used more than 500 times - in the Lisp sources of XEmacs. - - `save-excursion' does not save the values of point and the mark for - other buffers, so changes in other buffers remain in effect after - `save-excursion' exits. - - Likewise, `save-excursion' does not restore window-buffer - correspondences altered by functions such as `switch-to-buffer'. - One way to restore these correspondences, and the selected window, - is to use `save-window-excursion' inside `save-excursion' (*note - Window Configurations::). - - The value returned by `save-excursion' is the result of the last of - FORMS, or `nil' if no FORMS are given. - - (save-excursion - FORMS) - == - (let ((old-buf (current-buffer)) - (old-pnt (point-marker)) - (old-mark (copy-marker (mark-marker)))) - (unwind-protect - (progn FORMS) - (set-buffer old-buf) - (goto-char old-pnt) - (set-marker (mark-marker) old-mark))) - - - Special Form: save-current-buffer forms... - This special form is similar to `save-excursion' but it only saves - and restores the current buffer. Beginning with XEmacs 20.3, - `save-current-buffer' is a primitive. - - - Special Form: with-current-buffer buffer forms... - This special form evaluates FORMS with BUFFER as the current - buffer. It returns the value of the last form. - - - Special Form: with-temp-file file forms... - This special form creates a new buffer, evaluates FORMS there, and - writes the buffer to FILE. It returns the value of the last form - evaluated. - - - Special Form: save-selected-window forms... - This special form is similar to `save-excursion' but it saves and - restores the selected window and nothing else. - - -File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions - -Narrowing -========= - - "Narrowing" means limiting the text addressable by XEmacs editing -commands to a limited range of characters in a buffer. The text that -remains addressable is called the "accessible portion" of the buffer. - - Narrowing is specified with two buffer positions which become the -beginning and end of the accessible portion. For most editing commands -and most Emacs primitives, these positions replace the values of the -beginning and end of the buffer. While narrowing is in effect, no text -outside the accessible portion is displayed, and point cannot move -outside the accessible portion. - - Values such as positions or line numbers, which usually count from -the beginning of the buffer, do so despite narrowing, but the functions -which use them refuse to operate on text that is inaccessible. - - The commands for saving buffers are unaffected by narrowing; they -save the entire buffer regardless of any narrowing. - - - Command: narrow-to-region start end &optional buffer - This function sets the accessible portion of BUFFER to start at - START and end at END. Both arguments should be character - positions. BUFFER defaults to the current buffer if omitted. - - In an interactive call, START and END are set to the bounds of the - current region (point and the mark, with the smallest first). - - - Command: narrow-to-page &optional move-count - This function sets the accessible portion of the current buffer to - include just the current page. An optional first argument - MOVE-COUNT non-`nil' means to move forward or backward by - MOVE-COUNT pages and then narrow. The variable `page-delimiter' - specifies where pages start and end (*note Standard Regexps::). - - In an interactive call, MOVE-COUNT is set to the numeric prefix - argument. - - - Command: widen &optional buffer - This function cancels any narrowing in BUFFER, so that the entire - contents are accessible. This is called "widening". It is - equivalent to the following expression: - - (narrow-to-region 1 (1+ (buffer-size))) - - BUFFER defaults to the current buffer if omitted. - - - Special Form: save-restriction body... - This special form saves the current bounds of the accessible - portion, evaluates the BODY forms, and finally restores the saved - bounds, thus restoring the same state of narrowing (or absence - thereof) formerly in effect. The state of narrowing is restored - even in the event of an abnormal exit via `throw' or error (*note - Nonlocal Exits::). Therefore, this construct is a clean way to - narrow a buffer temporarily. - - The value returned by `save-restriction' is that returned by the - last form in BODY, or `nil' if no body forms were given. - - *Caution:* it is easy to make a mistake when using the - `save-restriction' construct. Read the entire description here - before you try it. - - If BODY changes the current buffer, `save-restriction' still - restores the restrictions on the original buffer (the buffer whose - restrictions it saved from), but it does not restore the identity - of the current buffer. - - `save-restriction' does _not_ restore point and the mark; use - `save-excursion' for that. If you use both `save-restriction' and - `save-excursion' together, `save-excursion' should come first (on - the outside). Otherwise, the old point value would be restored - with temporary narrowing still in effect. If the old point value - were outside the limits of the temporary narrowing, this would - fail to restore it accurately. - - The `save-restriction' special form records the values of the - beginning and end of the accessible portion as distances from the - beginning and end of the buffer. In other words, it records the - amount of inaccessible text before and after the accessible - portion. - - This method yields correct results if BODY does further narrowing. - However, `save-restriction' can become confused if the body widens - and then make changes outside the range of the saved narrowing. - When this is what you want to do, `save-restriction' is not the - right tool for the job. Here is what you must use instead: - - (let ((beg (point-min-marker)) - (end (point-max-marker))) - (unwind-protect - (progn BODY) - (save-excursion - (set-buffer (marker-buffer beg)) - (narrow-to-region beg end)))) - - Here is a simple example of correct use of `save-restriction': - - ---------- Buffer: foo ---------- - This is the contents of foo - This is the contents of foo - This is the contents of foo-!- - ---------- Buffer: foo ---------- - - (save-excursion - (save-restriction - (goto-char 1) - (forward-line 2) - (narrow-to-region 1 (point)) - (goto-char (point-min)) - (replace-string "foo" "bar"))) - - ---------- Buffer: foo ---------- - This is the contents of bar - This is the contents of bar - This is the contents of foo-!- - ---------- Buffer: foo ---------- - - -File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top - -Markers -******* - - A "marker" is a Lisp object used to specify a position in a buffer -relative to the surrounding text. A marker changes its offset from the -beginning of the buffer automatically whenever text is inserted or -deleted, so that it stays with the two characters on either side of it. - -* Menu: - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character position. -* Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. - - -File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers - -Overview of Markers -=================== - - A marker specifies a buffer and a position in that buffer. The -marker can be used to represent a position in the functions that -require one, just as an integer could be used. *Note Positions::, for -a complete description of positions. - - A marker has two attributes: the marker position, and the marker -buffer. The marker position is an integer that is equivalent (at a -given time) to the marker as a position in that buffer. But the -marker's position value can change often during the life of the marker. -Insertion and deletion of text in the buffer relocate the marker. The -idea is that a marker positioned between two characters remains between -those two characters despite insertion and deletion elsewhere in the -buffer. Relocation changes the integer equivalent of the marker. - - Deleting text around a marker's position leaves the marker between -the characters immediately before and after the deleted text. Inserting -text at the position of a marker normally leaves the marker in front of -the new text--unless it is inserted with `insert-before-markers' (*note -Insertion::). - - Insertion and deletion in a buffer must check all the markers and -relocate them if necessary. This slows processing in a buffer with a -large number of markers. For this reason, it is a good idea to make a -marker point nowhere if you are sure you don't need it any more. -Unreferenced markers are garbage collected eventually, but until then -will continue to use time if they do point somewhere. - - Because it is common to perform arithmetic operations on a marker -position, most of the arithmetic operations (including `+' and `-') -accept markers as arguments. In such cases, the marker stands for its -current position. - - Note that you can use extents to achieve the same functionality, and -more, as markers. (Markers were defined before extents, which is why -they both continue to exist.) A zero-length extent with the -`detachable' property removed is almost identical to a marker. (*Note -Extent Endpoints::, for more information on zero-length extents.) - - In particular: - - * In order to get marker-like behavior in a zero-length extent, the - `detachable' property must be removed (otherwise, the extent will - disappear when text near it is deleted) and exactly one endpoint - must be closed (if both endpoints are closed, the extent will - expand to contain text inserted where it is located). - - * If a zero-length extent has the `end-open' property but not the - `start-open' property (this is the default), text inserted at the - extent's location causes the extent to move forward, just like a - marker. - - * If a zero-length extent has the `start-open' property but not the - `end-open' property, text inserted at the extent's location causes - the extent to remain before the text, like what happens to markers - when `insert-before-markers' is used. - - * Markers end up after or before inserted text depending on whether - `insert' or `insert-before-markers' was called. These functions - do not affect zero-length extents differently; instead, the - presence or absence of the `start-open' and `end-open' extent - properties determines this, as just described. - - * Markers are automatically removed from a buffer when they are no - longer in use. Extents remain around until explicitly removed - from a buffer. - - * Many functions are provided for listing the extents in a buffer or - in a region of a buffer. No such functions exist for markers. - - Here are examples of creating markers, setting markers, and moving -point to markers: - - ;; Make a new marker that initially does not point anywhere: - (setq m1 (make-marker)) - => # - - ;; Set `m1' to point between the 99th and 100th characters - ;; in the current buffer: - (set-marker m1 100) - => # - - ;; Now insert one character at the beginning of the buffer: - (goto-char (point-min)) - => 1 - (insert "Q") - => nil - - ;; `m1' is updated appropriately. - m1 - => # - - ;; Two markers that point to the same position - ;; are not `eq', but they are `equal'. - (setq m2 (copy-marker m1)) - => # - (eq m1 m2) - => nil - (equal m1 m2) - => t - - ;; When you are finished using a marker, make it point nowhere. - (set-marker m1 nil) - => # - - -File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers - -Predicates on Markers -===================== - - You can test an object to see whether it is a marker, or whether it -is either an integer or a marker or either an integer, a character, or a -marker. The latter tests are useful in connection with the arithmetic -functions that work with any of markers, integers, or characters. - - - Function: markerp object - This function returns `t' if OBJECT is a marker, `nil' otherwise. - Note that integers are not markers, even though many functions - will accept either a marker or an integer. - - - Function: integer-or-marker-p object - This function returns `t' if OBJECT is an integer or a marker, - `nil' otherwise. - - - Function: integer-char-or-marker-p object - This function returns `t' if OBJECT is an integer, a character, or - a marker, `nil' otherwise. - - - Function: number-or-marker-p object - This function returns `t' if OBJECT is a number (either kind) or a - marker, `nil' otherwise. - - - Function: number-char-or-marker-p object - This function returns `t' if OBJECT is a number (either kind), a - character, or a marker, `nil' otherwise. - - -File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers - -Functions That Create Markers -============================= - - When you create a new marker, you can make it point nowhere, or point -to the present position of point, or to the beginning or end of the -accessible portion of the buffer, or to the same place as another given -marker. - - - Function: make-marker - This functions returns a newly created marker that does not point - anywhere. - - (make-marker) - => # - - - Function: point-marker &optional dont-copy-p buffer - This function returns a marker that points to the present position - of point in BUFFER, which defaults to the current buffer. *Note - Point::. For an example, see `copy-marker', below. - - Internally, a marker corresponding to point is always maintained. - Normally the marker returned by `point-marker' is a copy; you may - modify it with reckless abandon. However, if optional argument - DONT-COPY-P is non-`nil', then the real point-marker is returned; - modifying the position of this marker will move point. It is - illegal to change the buffer of it, or make it point nowhere. - - - Function: point-min-marker &optional buffer - This function returns a new marker that points to the beginning of - the accessible portion of BUFFER, which defaults to the current - buffer. This will be the beginning of the buffer unless narrowing - is in effect. *Note Narrowing::. - - - Function: point-max-marker &optional buffer - This function returns a new marker that points to the end of the - accessible portion of BUFFER, which defaults to the current - buffer. This will be the end of the buffer unless narrowing is in - effect. *Note Narrowing::. - - Here are examples of this function and `point-min-marker', shown in - a buffer containing a version of the source file for the text of - this chapter. - - (point-min-marker) - => # - (point-max-marker) - => # - - (narrow-to-region 100 200) - => nil - (point-min-marker) - => # - (point-max-marker) - => # - - - Function: copy-marker marker-or-integer - If passed a marker as its argument, `copy-marker' returns a new - marker that points to the same place and the same buffer as does - MARKER-OR-INTEGER. If passed an integer as its argument, - `copy-marker' returns a new marker that points to position - MARKER-OR-INTEGER in the current buffer. - - If passed an integer argument less than 1, `copy-marker' returns a - new marker that points to the beginning of the current buffer. If - passed an integer argument greater than the length of the buffer, - `copy-marker' returns a new marker that points to the end of the - buffer. - - An error is signaled if MARKER is neither a marker nor an integer. - - (setq p (point-marker)) - => # - - (setq q (copy-marker p)) - => # - - (eq p q) - => nil - - (equal p q) - => t - - (point) - => 2139 - - (set-marker p 3000) - => # - - (point) - => 2139 - - (setq p (point-marker t)) - => # - - (set-marker p 3000) - => # - - (point) - => 3000 - - (copy-marker 0) - => # - - (copy-marker 20000) - => # - - -File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers - -Information from Markers -======================== - - This section describes the functions for accessing the components of -a marker object. - - - Function: marker-position marker - This function returns the position that MARKER points to, or `nil' - if it points nowhere. - - - Function: marker-buffer marker - This function returns the buffer that MARKER points into, or `nil' - if it points nowhere. - - (setq m (make-marker)) - => # - (marker-position m) - => nil - (marker-buffer m) - => nil - - (set-marker m 3770 (current-buffer)) - => # - (marker-buffer m) - => # - (marker-position m) - => 3770 - - Two distinct markers are considered `equal' (even though not `eq') -to each other if they have the same position and buffer, or if they -both point nowhere. - - -File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers - -Changing Marker Positions -========================= - - This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it--otherwise, confusing things may happen in other parts of -Emacs. - - - Function: set-marker marker position &optional buffer - This function moves MARKER to POSITION in BUFFER. If BUFFER is - not provided, it defaults to the current buffer. - - If POSITION is less than 1, `set-marker' moves MARKER to the - beginning of the buffer. If POSITION is greater than the size of - the buffer, `set-marker' moves marker to the end of the buffer. - If POSITION is `nil' or a marker that points nowhere, then MARKER - is set to point nowhere. - - The value returned is MARKER. - - (setq m (point-marker)) - => # - (set-marker m 55) - => # - (setq b (get-buffer "foo")) - => # - (set-marker m 0 b) - => # - - - Function: move-marker marker position &optional buffer - This is another name for `set-marker'. - diff --git a/info/lispref.info-29 b/info/lispref.info-29 index 07d9698..d9b7423 100644 --- a/info/lispref.info-29 +++ b/info/lispref.info-29 @@ -50,6 +50,681 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 count + This function moves backward across COUNT balanced groups of + parentheses. (Other syntactic entities such as words or paired + string quotes are ignored.) COUNT defaults to 1 if omitted. If + COUNT is negative, move forward across that many groups of + parentheses. + + - Command: up-list &optional count + This function moves forward out of COUNT levels of parentheses. A + negative argument means move backward but still to a less deep + spot. + + - Command: down-list &optional count + This function moves forward into COUNT levels of parentheses. A + negative argument means move backward but still go deeper in + parentheses (-COUNT levels). + + - Command: forward-sexp &optional count + This function moves forward across COUNT balanced expressions. + Balanced expressions include both those delimited by parentheses + and other kinds, such as words and string constants. COUNT + defaults to 1 if omitted. If COUNT 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 count + This function moves backward across COUNT balanced expressions. + COUNT defaults to 1 if omitted. If COUNT is negative, move + forward across that many balanced expressions. + + - Command: beginning-of-defun &optional count + This function moves back to the COUNTth beginning of a defun. If + COUNT is negative, this actually moves forward, but it still moves + to the beginning of a defun, not to the end of one. COUNT + defaults to 1 if omitted. + + - Command: end-of-defun &optional count + This function moves forward to the COUNTth end of a defun. If + COUNT is negative, this actually moves backward, but it still + moves to the end of a defun, not to the beginning of one. COUNT + 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 +========== + + It is often useful to move point "temporarily" within a localized +portion of the program, or to switch buffers temporarily. This is +called an "excursion", and it is done with the `save-excursion' special +form. This construct saves the current buffer and its values of point +and the mark so they can be restored after the completion of the +excursion. + + The forms for saving and restoring the configuration of windows are +described elsewhere (see *Note Window Configurations:: and *note Frame +Configurations::). + + - Special Form: save-excursion forms... + The `save-excursion' special form saves the identity of the current + buffer and the values of point and the mark in it, evaluates + FORMS, and finally restores the buffer and its saved values of + point and the mark. All three saved values are restored even in + case of an abnormal exit via `throw' or error (*note Nonlocal + Exits::). + + The `save-excursion' special form is the standard way to switch + buffers or move point within one part of a program and avoid + affecting the rest of the program. It is used more than 500 times + in the Lisp sources of XEmacs. + + `save-excursion' does not save the values of point and the mark for + other buffers, so changes in other buffers remain in effect after + `save-excursion' exits. + + Likewise, `save-excursion' does not restore window-buffer + correspondences altered by functions such as `switch-to-buffer'. + One way to restore these correspondences, and the selected window, + is to use `save-window-excursion' inside `save-excursion' (*note + Window Configurations::). + + The value returned by `save-excursion' is the result of the last of + FORMS, or `nil' if no FORMS are given. + + (save-excursion + FORMS) + == + (let ((old-buf (current-buffer)) + (old-pnt (point-marker)) + (old-mark (copy-marker (mark-marker)))) + (unwind-protect + (progn FORMS) + (set-buffer old-buf) + (goto-char old-pnt) + (set-marker (mark-marker) old-mark))) + + - Special Form: save-current-buffer forms... + This special form is similar to `save-excursion' but it only saves + and restores the current buffer. Beginning with XEmacs 20.3, + `save-current-buffer' is a primitive. + + - Special Form: with-current-buffer buffer forms... + This special form evaluates FORMS with BUFFER as the current + buffer. It returns the value of the last form. + + - Special Form: with-temp-file filename forms... + This special form creates a new buffer, evaluates FORMS there, and + writes the buffer to FILENAME. It returns the value of the last + form evaluated. + + - Special Form: save-selected-window forms... + This special form is similar to `save-excursion' but it saves and + restores the selected window and nothing else. + + +File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions + +Narrowing +========= + + "Narrowing" means limiting the text addressable by XEmacs editing +commands to a limited range of characters in a buffer. The text that +remains addressable is called the "accessible portion" of the buffer. + + Narrowing is specified with two buffer positions which become the +beginning and end of the accessible portion. For most editing commands +and most Emacs primitives, these positions replace the values of the +beginning and end of the buffer. While narrowing is in effect, no text +outside the accessible portion is displayed, and point cannot move +outside the accessible portion. + + Values such as positions or line numbers, which usually count from +the beginning of the buffer, do so despite narrowing, but the functions +which use them refuse to operate on text that is inaccessible. + + The commands for saving buffers are unaffected by narrowing; they +save the entire buffer regardless of any narrowing. + + - Command: narrow-to-region start end &optional buffer + This function sets the accessible portion of BUFFER to start at + START and end at END. Both arguments should be character + positions. BUFFER defaults to the current buffer if omitted. + + In an interactive call, START and END are set to the bounds of the + current region (point and the mark, with the smallest first). + + - Command: narrow-to-page &optional move-count + This function sets the accessible portion of the current buffer to + include just the current page. An optional first argument + MOVE-COUNT non-`nil' means to move forward or backward by + MOVE-COUNT pages and then narrow. The variable `page-delimiter' + specifies where pages start and end (*note Standard Regexps::). + + In an interactive call, MOVE-COUNT is set to the numeric prefix + argument. + + - Command: widen &optional buffer + This function cancels any narrowing in BUFFER, so that the entire + contents are accessible. This is called "widening". It is + equivalent to the following expression: + + (narrow-to-region 1 (1+ (buffer-size))) + + BUFFER defaults to the current buffer if omitted. + + - Special Form: save-restriction body... + This special form saves the current bounds of the accessible + portion, evaluates the BODY forms, and finally restores the saved + bounds, thus restoring the same state of narrowing (or absence + thereof) formerly in effect. The state of narrowing is restored + even in the event of an abnormal exit via `throw' or error (*note + Nonlocal Exits::). Therefore, this construct is a clean way to + narrow a buffer temporarily. + + The value returned by `save-restriction' is that returned by the + last form in BODY, or `nil' if no body forms were given. + + *Caution:* it is easy to make a mistake when using the + `save-restriction' construct. Read the entire description here + before you try it. + + If BODY changes the current buffer, `save-restriction' still + restores the restrictions on the original buffer (the buffer whose + restrictions it saved from), but it does not restore the identity + of the current buffer. + + `save-restriction' does _not_ restore point and the mark; use + `save-excursion' for that. If you use both `save-restriction' and + `save-excursion' together, `save-excursion' should come first (on + the outside). Otherwise, the old point value would be restored + with temporary narrowing still in effect. If the old point value + were outside the limits of the temporary narrowing, this would + fail to restore it accurately. + + The `save-restriction' special form records the values of the + beginning and end of the accessible portion as distances from the + beginning and end of the buffer. In other words, it records the + amount of inaccessible text before and after the accessible + portion. + + This method yields correct results if BODY does further narrowing. + However, `save-restriction' can become confused if the body widens + and then make changes outside the range of the saved narrowing. + When this is what you want to do, `save-restriction' is not the + right tool for the job. Here is what you must use instead: + + (let ((start (point-min-marker)) + (end (point-max-marker))) + (unwind-protect + (progn BODY) + (save-excursion + (set-buffer (marker-buffer start)) + (narrow-to-region start end)))) + + Here is a simple example of correct use of `save-restriction': + + ---------- Buffer: foo ---------- + This is the contents of foo + This is the contents of foo + This is the contents of foo-!- + ---------- Buffer: foo ---------- + + (save-excursion + (save-restriction + (goto-char 1) + (forward-line 2) + (narrow-to-region 1 (point)) + (goto-char (point-min)) + (replace-string "foo" "bar"))) + + ---------- Buffer: foo ---------- + This is the contents of bar + This is the contents of bar + This is the contents of foo-!- + ---------- Buffer: foo ---------- + + +File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top + +Markers +******* + + A "marker" is a Lisp object used to specify a position in a buffer +relative to the surrounding text. A marker changes its offset from the +beginning of the buffer automatically whenever text is inserted or +deleted, so that it stays with the two characters on either side of it. + +* Menu: + +* Overview of Markers:: The components of a marker, and how it relocates. +* Predicates on Markers:: Testing whether an object is a marker. +* Creating Markers:: Making empty markers or markers at certain places. +* Information from Markers:: Finding the marker's buffer or character position. +* Changing Markers:: Moving the marker to a new buffer or position. +* The Mark:: How ``the mark'' is implemented with a marker. +* The Region:: How to access ``the region''. + + +File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers + +Overview of Markers +=================== + + A marker specifies a buffer and a position in that buffer. The +marker can be used to represent a position in the functions that +require one, just as an integer could be used. *Note Positions::, for +a complete description of positions. + + A marker has two attributes: the marker position, and the marker +buffer. The marker position is an integer that is equivalent (at a +given time) to the marker as a position in that buffer. But the +marker's position value can change often during the life of the marker. +Insertion and deletion of text in the buffer relocate the marker. The +idea is that a marker positioned between two characters remains between +those two characters despite insertion and deletion elsewhere in the +buffer. Relocation changes the integer equivalent of the marker. + + Deleting text around a marker's position leaves the marker between +the characters immediately before and after the deleted text. Inserting +text at the position of a marker normally leaves the marker in front of +the new text--unless it is inserted with `insert-before-markers' (*note +Insertion::). + + Insertion and deletion in a buffer must check all the markers and +relocate them if necessary. This slows processing in a buffer with a +large number of markers. For this reason, it is a good idea to make a +marker point nowhere if you are sure you don't need it any more. +Unreferenced markers are garbage collected eventually, but until then +will continue to use time if they do point somewhere. + + Because it is common to perform arithmetic operations on a marker +position, most of the arithmetic operations (including `+' and `-') +accept markers as arguments. In such cases, the marker stands for its +current position. + + Note that you can use extents to achieve the same functionality, and +more, as markers. (Markers were defined before extents, which is why +they both continue to exist.) A zero-length extent with the +`detachable' property removed is almost identical to a marker. (*Note +Extent Endpoints::, for more information on zero-length extents.) + + In particular: + + * In order to get marker-like behavior in a zero-length extent, the + `detachable' property must be removed (otherwise, the extent will + disappear when text near it is deleted) and exactly one endpoint + must be closed (if both endpoints are closed, the extent will + expand to contain text inserted where it is located). + + * If a zero-length extent has the `end-open' property but not the + `start-open' property (this is the default), text inserted at the + extent's location causes the extent to move forward, just like a + marker. + + * If a zero-length extent has the `start-open' property but not the + `end-open' property, text inserted at the extent's location causes + the extent to remain before the text, like what happens to markers + when `insert-before-markers' is used. + + * Markers end up after or before inserted text depending on whether + `insert' or `insert-before-markers' was called. These functions + do not affect zero-length extents differently; instead, the + presence or absence of the `start-open' and `end-open' extent + properties determines this, as just described. + + * Markers are automatically removed from a buffer when they are no + longer in use. Extents remain around until explicitly removed + from a buffer. + + * Many functions are provided for listing the extents in a buffer or + in a region of a buffer. No such functions exist for markers. + + Here are examples of creating markers, setting markers, and moving +point to markers: + + ;; Make a new marker that initially does not point anywhere: + (setq m1 (make-marker)) + => # + + ;; Set `m1' to point between the 99th and 100th characters + ;; in the current buffer: + (set-marker m1 100) + => # + + ;; Now insert one character at the beginning of the buffer: + (goto-char (point-min)) + => 1 + (insert "Q") + => nil + + ;; `m1' is updated appropriately. + m1 + => # + + ;; Two markers that point to the same position + ;; are not `eq', but they are `equal'. + (setq m2 (copy-marker m1)) + => # + (eq m1 m2) + => nil + (equal m1 m2) + => t + + ;; When you are finished using a marker, make it point nowhere. + (set-marker m1 nil) + => # + + +File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers + +Predicates on Markers +===================== + + You can test an object to see whether it is a marker, or whether it +is either an integer or a marker or either an integer, a character, or a +marker. The latter tests are useful in connection with the arithmetic +functions that work with any of markers, integers, or characters. + + - Function: markerp object + This function returns `t' if OBJECT is a marker, `nil' otherwise. + Note that integers are not markers, even though many functions + will accept either a marker or an integer. + + - Function: integer-or-marker-p object + This function returns `t' if OBJECT is an integer or a marker, + `nil' otherwise. + + - Function: integer-char-or-marker-p object + This function returns `t' if OBJECT is an integer, a character, or + a marker, `nil' otherwise. + + - Function: number-or-marker-p object + This function returns `t' if OBJECT is a number (either kind) or a + marker, `nil' otherwise. + + - Function: number-char-or-marker-p object + This function returns `t' if OBJECT is a number (either kind), a + character, or a marker, `nil' otherwise. + + +File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers + +Functions That Create Markers +============================= + + When you create a new marker, you can make it point nowhere, or point +to the present position of point, or to the beginning or end of the +accessible portion of the buffer, or to the same place as another given +marker. + + - Function: make-marker + This functions returns a newly created marker that does not point + anywhere. + + (make-marker) + => # + + - Function: point-marker &optional dont-copy-p buffer + This function returns a marker that points to the present position + of point in BUFFER, which defaults to the current buffer. *Note + Point::. For an example, see `copy-marker', below. + + Internally, a marker corresponding to point is always maintained. + Normally the marker returned by `point-marker' is a copy; you may + modify it with reckless abandon. However, if optional argument + DONT-COPY-P is non-`nil', then the real point-marker is returned; + modifying the position of this marker will move point. It is + illegal to change the buffer of it, or make it point nowhere. + + - Function: point-min-marker &optional buffer + This function returns a new marker that points to the beginning of + the accessible portion of BUFFER, which defaults to the current + buffer. This will be the beginning of the buffer unless narrowing + is in effect. *Note Narrowing::. + + - Function: point-max-marker &optional buffer + This function returns a new marker that points to the end of the + accessible portion of BUFFER, which defaults to the current + buffer. This will be the end of the buffer unless narrowing is in + effect. *Note Narrowing::. + + Here are examples of this function and `point-min-marker', shown in + a buffer containing a version of the source file for the text of + this chapter. + + (point-min-marker) + => # + (point-max-marker) + => # + + (narrow-to-region 100 200) + => nil + (point-min-marker) + => # + (point-max-marker) + => # + + - Function: copy-marker marker-or-integer &optional marker-type + If passed a marker as its argument, `copy-marker' returns a new + marker that points to the same place and the same buffer as does + MARKER-OR-INTEGER. If passed an integer as its argument, + `copy-marker' returns a new marker that points to position + MARKER-OR-INTEGER in the current buffer. + + If passed an integer argument less than 1, `copy-marker' returns a + new marker that points to the beginning of the current buffer. If + passed an integer argument greater than the length of the buffer, + `copy-marker' returns a new marker that points to the end of the + buffer. + + An error is signaled if MARKER-OR-INTEGER is neither a marker nor + an integer. + + Optional second argument MARKER-TYPE specifies the insertion type + of the new marker; see `marker-insertion-type'. + + (setq p (point-marker)) + => # + + (setq q (copy-marker p)) + => # + + (eq p q) + => nil + + (equal p q) + => t + + (point) + => 2139 + + (set-marker p 3000) + => # + + (point) + => 2139 + + (setq p (point-marker t)) + => # + + (set-marker p 3000) + => # + + (point) + => 3000 + + (copy-marker 0) + => # + + (copy-marker 20000) + => # + + +File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers + +Information from Markers +======================== + + This section describes the functions for accessing the components of +a marker object. + + - Function: marker-position marker + This function returns the position that MARKER points to, or `nil' + if it points nowhere. + + - Function: marker-buffer marker + This function returns the buffer that MARKER points into, or `nil' + if it points nowhere. + + (setq m (make-marker)) + => # + (marker-position m) + => nil + (marker-buffer m) + => nil + + (set-marker m 3770 (current-buffer)) + => # + (marker-buffer m) + => # + (marker-position m) + => 3770 + + Two distinct markers are considered `equal' (even though not `eq') +to each other if they have the same position and buffer, or if they +both point nowhere. + + +File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers + +Changing Marker Positions +========================= + + This section describes how to change the position of an existing +marker. When you do this, be sure you know whether the marker is used +outside of your program, and, if so, what effects will result from +moving it--otherwise, confusing things may happen in other parts of +Emacs. + + - Function: set-marker marker position &optional buffer + This function moves MARKER to POSITION in BUFFER. If BUFFER is + not provided, it defaults to the current buffer. + + POSITION can be a marker, an integer or `nil'. If POSITION is an + integer, `set-marker' moves MARKER to point before the POSITIONth + character in BUFFER. If POSITION is `nil', MARKER is made to + point nowhere. Then it no longer slows down editing in any + buffer. If POSITION is less than 1, MARKER is moved to the + beginning of BUFFER. If POSITION is greater than the size of + BUFFER, MARKER is moved to the end of BUFFER. + + The value returned is MARKER. + + (setq m (point-marker)) + => # + (set-marker m 55) + => # + (setq b (get-buffer "foo")) + => # + (set-marker m 0 b) + => # + + - 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 @@ -124,7 +799,7 @@ long, adding a new element deletes the last element. 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 + - Function: mark-marker &optional force 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 @@ -165,9 +840,9 @@ long, adding a new element deletes the last element. To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example: - (let ((beg (point))) + (let ((start (point))) (forward-line 1) - (delete-region beg (point))). + (delete-region start (point))). - Command: exchange-point-and-mark &optional dont-activate-region This function exchanges the positions of point and the mark. It @@ -491,639 +1166,3 @@ operated on the current buffer.) 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 -============================= - - This section describes higher-level commands for inserting text, -commands intended primarily for the user but useful also in Lisp -programs. - - - Command: insert-buffer from-buffer-or-name - This command inserts the entire contents of FROM-BUFFER-OR-NAME - (which must exist) into the current buffer after point. It leaves - the mark after the inserted text. The value is `nil'. - - - Command: self-insert-command count - This command inserts the last character typed; it does so COUNT - times, before point, and returns `nil'. Most printing characters - are bound to this command. In routine use, `self-insert-command' - is the most frequently called function in XEmacs, but programs - rarely use it except to install it on a keymap. - - In an interactive call, COUNT is the numeric prefix argument. - - This command calls `auto-fill-function' whenever that is non-`nil' - and the character inserted is a space or a newline (*note Auto - Filling::). - - This command performs abbrev expansion if Abbrev mode is enabled - and the inserted character does not have word-constituent syntax. - (*Note Abbrevs::, and *Note Syntax Class Table::.) - - This is also responsible for calling `blink-paren-function' when - the inserted character has close parenthesis syntax (*note - Blinking::). - - - Command: newline &optional number-of-newlines - This command inserts newlines into the current buffer before point. - If NUMBER-OF-NEWLINES is supplied, that many newline characters - are inserted. - - This function calls `auto-fill-function' if the current column - number is greater than the value of `fill-column' and - NUMBER-OF-NEWLINES is `nil'. Typically what `auto-fill-function' - does is insert a newline; thus, the overall result in this case is - to insert two newlines at different places: one at point, and - another earlier in the line. `newline' does not auto-fill if - NUMBER-OF-NEWLINES is non-`nil'. - - This command indents to the left margin if that is not zero. - *Note Margins::. - - The value returned is `nil'. In an interactive call, COUNT is the - numeric prefix argument. - - - Command: split-line - This command splits the current line, moving the portion of the - line after point down vertically so that it is on the next line - directly below where it was before. Whitespace is inserted as - needed at the beginning of the lower line, using the `indent-to' - function. `split-line' returns the position of point. - - Programs hardly ever use this function. - - - Variable: overwrite-mode - This variable controls whether overwrite mode is in effect: a - non-`nil' value enables the mode. It is automatically made - buffer-local when set in any fashion. - - -File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text - -Deleting Text -============= - - Deletion means removing part of the text in a buffer, without saving -it in the kill ring (*note The Kill Ring::). Deleted text can't be -yanked, but can be reinserted using the undo mechanism (*note Undo::). -Some deletion functions do save text in the kill ring in some special -cases. - - All of the deletion functions operate on the current buffer, and all -return a value of `nil'. - - - Function: erase-buffer &optional buffer - This function deletes the entire text of BUFFER, leaving it empty. - If the buffer is read-only, it signals a `buffer-read-only' - error. Otherwise, it deletes the text without asking for any - confirmation. It returns `nil'. BUFFER defaults to the current - buffer if omitted. - - Normally, deleting a large amount of text from a buffer inhibits - further auto-saving of that buffer "because it has shrunk". - However, `erase-buffer' does not do this, the idea being that the - future text is not really related to the former text, and its size - should not be compared with that of the former text. - - - Command: delete-region start end &optional buffer - This command deletes the text in BUFFER in the region defined by - START and END. The value is `nil'. If optional argument BUFFER - is `nil', the current buffer is assumed. - - - Command: delete-char count &optional killp - This command deletes COUNT characters directly after point, or - before point if COUNT is negative. If KILLP is non-`nil', then it - saves the deleted characters in the kill ring. - - In an interactive call, COUNT is the numeric prefix argument, and - KILLP is the unprocessed prefix argument. Therefore, if a prefix - argument is supplied, the text is saved in the kill ring. If no - prefix argument is supplied, then one character is deleted, but - not saved in the kill ring. - - The value returned is always `nil'. - - - Command: delete-backward-char count &optional killp - This command deletes COUNT characters directly before point, or - after point if COUNT is negative. If KILLP is non-`nil', then it - saves the deleted characters in the kill ring. - - In an interactive call, COUNT is the numeric prefix argument, and - KILLP is the unprocessed prefix argument. Therefore, if a prefix - argument is supplied, the text is saved in the kill ring. If no - prefix argument is supplied, then one character is deleted, but - not saved in the kill ring. - - The value returned is always `nil'. - - - Command: backward-delete-char-untabify count &optional killp - This command deletes COUNT characters backward, changing tabs into - spaces. When the next character to be deleted is a tab, it is - first replaced with the proper number of spaces to preserve - alignment and then one of those spaces is deleted instead of the - tab. If KILLP is non-`nil', then the command saves the deleted - characters in the kill ring. - - Conversion of tabs to spaces happens only if COUNT is positive. - If it is negative, exactly -COUNT characters after point are - deleted. - - In an interactive call, COUNT is the numeric prefix argument, and - KILLP is the unprocessed prefix argument. Therefore, if a prefix - argument is supplied, the text is saved in the kill ring. If no - prefix argument is supplied, then one character is deleted, but - not saved in the kill ring. - - The value returned is always `nil'. - - -File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text - -User-Level Deletion Commands -============================ - - This section describes higher-level commands for deleting text, -commands intended primarily for the user but useful also in Lisp -programs. - - - Command: delete-horizontal-space - This function deletes all spaces and tabs around point. It returns - `nil'. - - In the following examples, we call `delete-horizontal-space' four - times, once on each line, with point between the second and third - characters on the line each time. - - ---------- Buffer: foo ---------- - I -!-thought - I -!- thought - We-!- thought - Yo-!-u thought - ---------- Buffer: foo ---------- - - (delete-horizontal-space) ; Four times. - => nil - - ---------- Buffer: foo ---------- - Ithought - Ithought - Wethought - You thought - ---------- Buffer: foo ---------- - - - Command: delete-indentation &optional join-following-p - This function joins the line point is on to the previous line, - deleting any whitespace at the join and in some cases replacing it - with one space. If JOIN-FOLLOWING-P is non-`nil', - `delete-indentation' joins this line to the following line - instead. The value is `nil'. - - If there is a fill prefix, and the second of the lines being joined - starts with the prefix, then `delete-indentation' deletes the fill - prefix before joining the lines. *Note Margins::. - - In the example below, point is located on the line starting - `events', and it makes no difference if there are trailing spaces - in the preceding line. - - ---------- Buffer: foo ---------- - When in the course of human - -!- events, it becomes necessary - ---------- Buffer: foo ---------- - - (delete-indentation) - => nil - - ---------- Buffer: foo ---------- - When in the course of human-!- events, it becomes necessary - ---------- Buffer: foo ---------- - - After the lines are joined, the function `fixup-whitespace' is - responsible for deciding whether to leave a space at the junction. - - - Function: fixup-whitespace - This function replaces all the white space surrounding point with - either one space or no space, according to the context. It - returns `nil'. - - At the beginning or end of a line, the appropriate amount of space - is none. Before a character with close parenthesis syntax, or - after a character with open parenthesis or expression-prefix - syntax, no space is also appropriate. Otherwise, one space is - appropriate. *Note Syntax Class Table::. - - In the example below, `fixup-whitespace' is called the first time - with point before the word `spaces' in the first line. For the - second invocation, point is directly after the `('. - - ---------- Buffer: foo ---------- - This has too many -!-spaces - This has too many spaces at the start of (-!- this list) - ---------- Buffer: foo ---------- - - (fixup-whitespace) - => nil - (fixup-whitespace) - => nil - - ---------- Buffer: foo ---------- - This has too many spaces - This has too many spaces at the start of (this list) - ---------- Buffer: foo ---------- - - - Command: just-one-space - This command replaces any spaces and tabs around point with a - single space. It returns `nil'. - - - Command: delete-blank-lines - This function deletes blank lines surrounding point. If point is - on a blank line with one or more blank lines before or after it, - then all but one of them are deleted. If point is on an isolated - blank line, then it is deleted. If point is on a nonblank line, - the command deletes all blank lines following it. - - A blank line is defined as a line containing only tabs and spaces. - - `delete-blank-lines' returns `nil'. - - -File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text - -The Kill Ring -============= - - "Kill" functions delete text like the deletion functions, but save -it so that the user can reinsert it by "yanking". Most of these -functions have `kill-' in their name. By contrast, the functions whose -names start with `delete-' normally do not save text for yanking -(though they can still be undone); these are "deletion" functions. - - Most of the kill commands are primarily for interactive use, and are -not described here. What we do describe are the functions provided for -use in writing such commands. You can use these functions to write -commands for killing text. When you need to delete text for internal -purposes within a Lisp function, you should normally use deletion -functions, so as not to disturb the kill ring contents. *Note -Deletion::. - - Killed text is saved for later yanking in the "kill ring". This is -a list that holds a number of recent kills, not just the last text -kill. We call this a "ring" because yanking treats it as having -elements in a cyclic order. The list is kept in the variable -`kill-ring', and can be operated on with the usual functions for lists; -there are also specialized functions, described in this section, that -treat it as a ring. - - Some people think this use of the word "kill" is unfortunate, since -it refers to operations that specifically _do not_ destroy the entities -"killed". This is in sharp contrast to ordinary life, in which death -is permanent and "killed" entities do not come back to life. -Therefore, other metaphors have been proposed. For example, the term -"cut ring" makes sense to people who, in pre-computer days, used -scissors and paste to cut up and rearrange manuscripts. However, it -would be difficult to change the terminology now. - -* Menu: - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill-ring data. - - -File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring - -Kill Ring Concepts ------------------- - - The kill ring records killed text as strings in a list, most recent -first. A short kill ring, for example, might look like this: - - ("some text" "a different piece of text" "even older text") - -When the list reaches `kill-ring-max' entries in length, adding a new -entry automatically deletes the last entry. - - When kill commands are interwoven with other commands, each kill -command makes a new entry in the kill ring. Multiple kill commands in -succession build up a single entry in the kill ring, which would be -yanked as a unit; the second and subsequent consecutive kill commands -add text to the entry made by the first one. - - For yanking, one entry in the kill ring is designated the "front" of -the ring. Some yank commands "rotate" the ring by designating a -different element as the "front." But this virtual rotation doesn't -change the list itself--the most recent entry always comes first in the -list. - - -File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring - -Functions for Killing ---------------------- - - `kill-region' is the usual subroutine for killing text. Any command -that calls this function is a "kill command" (and should probably have -`kill' in its name). `kill-region' puts the newly killed text in a new -element at the beginning of the kill ring or adds it to the most recent -element. It uses the `last-command' variable to determine whether the -previous command was a kill command, and if so appends the killed text -to the most recent entry. - - - Command: kill-region start end - This function kills the text in the region defined by START and - END. The text is deleted but saved in the kill ring, along with - its text properties. The value is always `nil'. - - In an interactive call, START and END are point and the mark. - - If the buffer is read-only, `kill-region' modifies the kill ring - just the same, then signals an error without modifying the buffer. - This is convenient because it lets the user use all the kill - commands to copy text into the kill ring from a read-only buffer. - - - Command: copy-region-as-kill start end - This command saves the region defined by START and END on the kill - ring (including text properties), but does not delete the text - from the buffer. It returns `nil'. It also indicates the extent - of the text copied by moving the cursor momentarily, or by - displaying a message in the echo area. - - The command does not set `this-command' to `kill-region', so a - subsequent kill command does not append to the same kill ring - entry. - - Don't call `copy-region-as-kill' in Lisp programs unless you aim to - support Emacs 18. For Emacs 19, it is better to use `kill-new' or - `kill-append' instead. *Note Low-Level Kill Ring::. - - -File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring - -Functions for Yanking ---------------------- - - "Yanking" means reinserting an entry of previously killed text from -the kill ring. The text properties are copied too. - - - Command: yank &optional arg - This command inserts before point the text in the first entry in - the kill ring. It positions the mark at the beginning of that - text, and point at the end. - - If ARG is a list (which occurs interactively when the user types - `C-u' with no digits), then `yank' inserts the text as described - above, but puts point before the yanked text and puts the mark - after it. - - If ARG is a number, then `yank' inserts the ARGth most recently - killed text--the ARGth element of the kill ring list. - - `yank' does not alter the contents of the kill ring or rotate it. - It returns `nil'. - - - Command: yank-pop arg - This command replaces the just-yanked entry from the kill ring - with a different entry from the kill ring. - - This is allowed only immediately after a `yank' or another - `yank-pop'. At such a time, the region contains text that was just - inserted by yanking. `yank-pop' deletes that text and inserts in - its place a different piece of killed text. It does not add the - deleted text to the kill ring, since it is already in the kill - ring somewhere. - - If ARG is `nil', then the replacement text is the previous element - of the kill ring. If ARG is numeric, the replacement is the ARGth - previous kill. If ARG is negative, a more recent kill is the - replacement. - - The sequence of kills in the kill ring wraps around, so that after - the oldest one comes the newest one, and before the newest one - goes the oldest. - - The value is always `nil'. - - -File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring - -Low-Level Kill Ring -------------------- - - These functions and variables provide access to the kill ring at a -lower level, but still convenient for use in Lisp programs. They take -care of interaction with X Window selections. They do not exist in -Emacs version 18. - - - Function: current-kill n &optional do-not-move - The function `current-kill' rotates the yanking pointer which - designates the "front" of the kill ring by N places (from newer - kills to older ones), and returns the text at that place in the - ring. - - If the optional second argument DO-NOT-MOVE is non-`nil', then - `current-kill' doesn't alter the yanking pointer; it just returns - the Nth kill, counting from the current yanking pointer. - - If N is zero, indicating a request for the latest kill, - `current-kill' calls the value of `interprogram-paste-function' - (documented below) before consulting the kill ring. - - - Function: kill-new string - This function puts the text STRING into the kill ring as a new - entry at the front of the ring. It discards the oldest entry if - appropriate. It also invokes the value of - `interprogram-cut-function' (see below). - - - Function: kill-append string before-p - This function appends the text STRING to the first entry in the - kill ring. Normally STRING goes at the end of the entry, but if - BEFORE-P is non-`nil', it goes at the beginning. This function - also invokes the value of `interprogram-cut-function' (see below). - - - Variable: interprogram-paste-function - This variable provides a way of transferring killed text from other - programs, when you are using a window system. Its value should be - `nil' or a function of no arguments. - - If the value is a function, `current-kill' calls it to get the - "most recent kill". If the function returns a non-`nil' value, - then that value is used as the "most recent kill". If it returns - `nil', then the first element of `kill-ring' is used. - - The normal use of this hook is to get the X server's primary - selection as the most recent kill, even if the selection belongs - to another X client. *Note X Selections::. - - - Variable: interprogram-cut-function - This variable provides a way of communicating killed text to other - programs, when you are using a window system. Its value should be - `nil' or a function of one argument. - - If the value is a function, `kill-new' and `kill-append' call it - with the new first element of the kill ring as an argument. - - The normal use of this hook is to set the X server's primary - selection to the newly killed text. - diff --git a/info/lispref.info-30 b/info/lispref.info-30 index 5ca45e7..982442c 100644 --- a/info/lispref.info-30 +++ b/info/lispref.info-30 @@ -50,6 +50,650 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 &optional count ignored buffer + This function inserts COUNT instances of CHARACTER into BUFFER + before point. COUNT must be a number, and CHARACTER must be a + character. + + 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. In XEmacs, it is always ignored.) + + This function always returns `nil'. + + - 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 +============================= + + This section describes higher-level commands for inserting text, +commands intended primarily for the user but useful also in Lisp +programs. + + - Command: insert-buffer from-buffer-or-name + This command inserts the entire contents of FROM-BUFFER-OR-NAME + (which must exist) into the current buffer after point. It leaves + the mark after the inserted text. The value is `nil'. + + - Command: self-insert-command count + This command inserts the last character typed; it does so COUNT + times, before point, and returns `nil'. Most printing characters + are bound to this command. In routine use, `self-insert-command' + is the most frequently called function in XEmacs, but programs + rarely use it except to install it on a keymap. + + In an interactive call, COUNT is the numeric prefix argument. + + This command calls `auto-fill-function' whenever that is non-`nil' + and the character inserted is a space or a newline (*note Auto + Filling::). + + This command performs abbrev expansion if Abbrev mode is enabled + and the inserted character does not have word-constituent syntax. + (*Note Abbrevs::, and *Note Syntax Class Table::.) + + This is also responsible for calling `blink-paren-function' when + the inserted character has close parenthesis syntax (*note + Blinking::). + + - Command: newline &optional count + This command inserts newlines into the current buffer before point. + If COUNT is supplied, that many newline characters are inserted. + + This function calls `auto-fill-function' if the current column + number is greater than the value of `fill-column' and COUNT is + `nil'. Typically what `auto-fill-function' does is insert a + newline; thus, the overall result in this case is to insert two + newlines at different places: one at point, and another earlier in + the line. `newline' does not auto-fill if COUNT is non-`nil'. + + This command indents to the left margin if that is not zero. + *Note Margins::. + + The value returned is `nil'. In an interactive call, COUNT is the + numeric prefix argument. + + - Command: split-line + This command splits the current line, moving the portion of the + line after point down vertically so that it is on the next line + directly below where it was before. Whitespace is inserted as + needed at the beginning of the lower line, using the `indent-to' + function. `split-line' returns the position of point. + + Programs hardly ever use this function. + + - Variable: overwrite-mode + This variable controls whether overwrite mode is in effect: a + non-`nil' value enables the mode. It is automatically made + buffer-local when set in any fashion. + + +File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text + +Deleting Text +============= + + Deletion means removing part of the text in a buffer, without saving +it in the kill ring (*note The Kill Ring::). Deleted text can't be +yanked, but can be reinserted using the undo mechanism (*note Undo::). +Some deletion functions do save text in the kill ring in some special +cases. + + All of the deletion functions operate on the current buffer, and all +return a value of `nil'. + + - Command: erase-buffer &optional buffer + This function deletes the entire text of BUFFER, leaving it empty. + If the buffer is read-only, it signals a `buffer-read-only' + error. Otherwise, it deletes the text without asking for any + confirmation. It returns `nil'. BUFFER defaults to the current + buffer if omitted. + + Normally, deleting a large amount of text from a buffer inhibits + further auto-saving of that buffer "because it has shrunk". + However, `erase-buffer' does not do this, the idea being that the + future text is not really related to the former text, and its size + should not be compared with that of the former text. + + - Command: delete-region start end &optional buffer + This command deletes the text in BUFFER in the region defined by + START and END. The value is `nil'. If optional argument BUFFER + is `nil', the current buffer is assumed. + + - Command: delete-char count &optional killp + This command deletes COUNT characters directly after point, or + before point if COUNT is negative. If KILLP is non-`nil', then it + saves the deleted characters in the kill ring. + + In an interactive call, COUNT is the numeric prefix argument, and + KILLP is the unprocessed prefix argument. Therefore, if a prefix + argument is supplied, the text is saved in the kill ring. If no + prefix argument is supplied, then one character is deleted, but + not saved in the kill ring. + + The value returned is always `nil'. + + - Command: delete-backward-char count &optional killp + This command deletes COUNT characters directly before point, or + after point if COUNT is negative. If KILLP is non-`nil', then it + saves the deleted characters in the kill ring. + + In an interactive call, COUNT is the numeric prefix argument, and + KILLP is the unprocessed prefix argument. Therefore, if a prefix + argument is supplied, the text is saved in the kill ring. If no + prefix argument is supplied, then one character is deleted, but + not saved in the kill ring. + + The value returned is always `nil'. + + - Command: backward-delete-char-untabify count &optional killp + This command deletes COUNT characters backward, changing tabs into + spaces. When the next character to be deleted is a tab, it is + first replaced with the proper number of spaces to preserve + alignment and then one of those spaces is deleted instead of the + tab. If KILLP is non-`nil', then the command saves the deleted + characters in the kill ring. + + Conversion of tabs to spaces happens only if COUNT is positive. + If it is negative, exactly -COUNT characters after point are + deleted. + + In an interactive call, COUNT is the numeric prefix argument, and + KILLP is the unprocessed prefix argument. Therefore, if a prefix + argument is supplied, the text is saved in the kill ring. If no + prefix argument is supplied, then one character is deleted, but + not saved in the kill ring. + + The value returned is always `nil'. + + +File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text + +User-Level Deletion Commands +============================ + + This section describes higher-level commands for deleting text, +commands intended primarily for the user but useful also in Lisp +programs. + + - Command: delete-horizontal-space + This function deletes all spaces and tabs around point. It returns + `nil'. + + In the following examples, we call `delete-horizontal-space' four + times, once on each line, with point between the second and third + characters on the line each time. + + ---------- Buffer: foo ---------- + I -!-thought + I -!- thought + We-!- thought + Yo-!-u thought + ---------- Buffer: foo ---------- + + (delete-horizontal-space) ; Four times. + => nil + + ---------- Buffer: foo ---------- + Ithought + Ithought + Wethought + You thought + ---------- Buffer: foo ---------- + + - Command: delete-indentation &optional join-following-p + This function joins the line point is on to the previous line, + deleting any whitespace at the join and in some cases replacing it + with one space. If JOIN-FOLLOWING-P is non-`nil', + `delete-indentation' joins this line to the following line + instead. The value is `nil'. + + If there is a fill prefix, and the second of the lines being joined + starts with the prefix, then `delete-indentation' deletes the fill + prefix before joining the lines. *Note Margins::. + + In the example below, point is located on the line starting + `events', and it makes no difference if there are trailing spaces + in the preceding line. + + ---------- Buffer: foo ---------- + When in the course of human + -!- events, it becomes necessary + ---------- Buffer: foo ---------- + + (delete-indentation) + => nil + + ---------- Buffer: foo ---------- + When in the course of human-!- events, it becomes necessary + ---------- Buffer: foo ---------- + + After the lines are joined, the function `fixup-whitespace' is + responsible for deciding whether to leave a space at the junction. + + - Command: fixup-whitespace + This function replaces all the white space surrounding point with + either one space or no space, according to the context. It + returns `nil'. + + At the beginning or end of a line, the appropriate amount of space + is none. Before a character with close parenthesis syntax, or + after a character with open parenthesis or expression-prefix + syntax, no space is also appropriate. Otherwise, one space is + appropriate. *Note Syntax Class Table::. + + In the example below, `fixup-whitespace' is called the first time + with point before the word `spaces' in the first line. For the + second invocation, point is directly after the `('. + + ---------- Buffer: foo ---------- + This has too many -!-spaces + This has too many spaces at the start of (-!- this list) + ---------- Buffer: foo ---------- + + (fixup-whitespace) + => nil + (fixup-whitespace) + => nil + + ---------- Buffer: foo ---------- + This has too many spaces + This has too many spaces at the start of (this list) + ---------- Buffer: foo ---------- + + - Command: just-one-space + This command replaces any spaces and tabs around point with a + single space. It returns `nil'. + + - Command: delete-blank-lines + This function deletes blank lines surrounding point. If point is + on a blank line with one or more blank lines before or after it, + then all but one of them are deleted. If point is on an isolated + blank line, then it is deleted. If point is on a nonblank line, + the command deletes all blank lines following it. + + A blank line is defined as a line containing only tabs and spaces. + + `delete-blank-lines' returns `nil'. + + +File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text + +The Kill Ring +============= + + "Kill" functions delete text like the deletion functions, but save +it so that the user can reinsert it by "yanking". Most of these +functions have `kill-' in their name. By contrast, the functions whose +names start with `delete-' normally do not save text for yanking +(though they can still be undone); these are "deletion" functions. + + Most of the kill commands are primarily for interactive use, and are +not described here. What we do describe are the functions provided for +use in writing such commands. You can use these functions to write +commands for killing text. When you need to delete text for internal +purposes within a Lisp function, you should normally use deletion +functions, so as not to disturb the kill ring contents. *Note +Deletion::. + + Killed text is saved for later yanking in the "kill ring". This is +a list that holds a number of recent kills, not just the last text +kill. We call this a "ring" because yanking treats it as having +elements in a cyclic order. The list is kept in the variable +`kill-ring', and can be operated on with the usual functions for lists; +there are also specialized functions, described in this section, that +treat it as a ring. + + Some people think this use of the word "kill" is unfortunate, since +it refers to operations that specifically _do not_ destroy the entities +"killed". This is in sharp contrast to ordinary life, in which death +is permanent and "killed" entities do not come back to life. +Therefore, other metaphors have been proposed. For example, the term +"cut ring" makes sense to people who, in pre-computer days, used +scissors and paste to cut up and rearrange manuscripts. However, it +would be difficult to change the terminology now. + +* Menu: + +* Kill Ring Concepts:: What text looks like in the kill ring. +* Kill Functions:: Functions that kill text. +* Yank Commands:: Commands that access the kill ring. +* Low-Level Kill Ring:: Functions and variables for kill ring access. +* Internals of Kill Ring:: Variables that hold kill-ring data. + + +File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring + +Kill Ring Concepts +------------------ + + The kill ring records killed text as strings in a list, most recent +first. A short kill ring, for example, might look like this: + + ("some text" "a different piece of text" "even older text") + +When the list reaches `kill-ring-max' entries in length, adding a new +entry automatically deletes the last entry. + + When kill commands are interwoven with other commands, each kill +command makes a new entry in the kill ring. Multiple kill commands in +succession build up a single entry in the kill ring, which would be +yanked as a unit; the second and subsequent consecutive kill commands +add text to the entry made by the first one. + + For yanking, one entry in the kill ring is designated the "front" of +the ring. Some yank commands "rotate" the ring by designating a +different element as the "front." But this virtual rotation doesn't +change the list itself--the most recent entry always comes first in the +list. + + +File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring + +Functions for Killing +--------------------- + + `kill-region' is the usual subroutine for killing text. Any command +that calls this function is a "kill command" (and should probably have +`kill' in its name). `kill-region' puts the newly killed text in a new +element at the beginning of the kill ring or adds it to the most recent +element. It uses the `last-command' variable to determine whether the +previous command was a kill command, and if so appends the killed text +to the most recent entry. + + - Command: kill-region start end &optional verbose + This function kills the text in the region defined by START and + END. The text is deleted but saved in the kill ring, along with + its text properties. The value is always `nil'. + + In an interactive call, START and END are point and the mark. + + If the buffer is read-only, `kill-region' modifies the kill ring + just the same, then signals an error without modifying the buffer. + This is convenient because it lets the user use all the kill + commands to copy text into the kill ring from a read-only buffer. + + - Command: copy-region-as-kill start end + This command saves the region defined by START and END on the kill + ring (including text properties), but does not delete the text + from the buffer. It returns `nil'. It also indicates the extent + of the text copied by moving the cursor momentarily, or by + displaying a message in the echo area. + + The command does not set `this-command' to `kill-region', so a + subsequent kill command does not append to the same kill ring + entry. + + Don't call `copy-region-as-kill' in Lisp programs unless you aim to + support Emacs 18. For Emacs 19, it is better to use `kill-new' or + `kill-append' instead. *Note Low-Level Kill Ring::. + + +File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring + +Functions for Yanking +--------------------- + + "Yanking" means reinserting an entry of previously killed text from +the kill ring. The text properties are copied too. + + - Command: yank &optional arg + This command inserts before point the text in the first entry in + the kill ring. It positions the mark at the beginning of that + text, and point at the end. + + If ARG is a list (which occurs interactively when the user types + `C-u' with no digits), then `yank' inserts the text as described + above, but puts point before the yanked text and puts the mark + after it. + + If ARG is a number, then `yank' inserts the ARGth most recently + killed text--the ARGth element of the kill ring list. + + `yank' does not alter the contents of the kill ring or rotate it. + It returns `nil'. + + - Command: yank-pop arg + This command replaces the just-yanked entry from the kill ring + with a different entry from the kill ring. + + This is allowed only immediately after a `yank' or another + `yank-pop'. At such a time, the region contains text that was just + inserted by yanking. `yank-pop' deletes that text and inserts in + its place a different piece of killed text. It does not add the + deleted text to the kill ring, since it is already in the kill + ring somewhere. + + If ARG is `nil', then the replacement text is the previous element + of the kill ring. If ARG is numeric, the replacement is the ARGth + previous kill. If ARG is negative, a more recent kill is the + replacement. + + The sequence of kills in the kill ring wraps around, so that after + the oldest one comes the newest one, and before the newest one + goes the oldest. + + The value is always `nil'. + + +File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring + +Low-Level Kill Ring +------------------- + + These functions and variables provide access to the kill ring at a +lower level, but still convenient for use in Lisp programs. They take +care of interaction with X Window selections. They do not exist in +Emacs version 18. + + - Function: current-kill count &optional do-not-move + The function `current-kill' rotates the yanking pointer which + designates the "front" of the kill ring by COUNT places (from newer + kills to older ones), and returns the text at that place in the + ring. + + If the optional second argument DO-NOT-MOVE is non-`nil', then + `current-kill' doesn't alter the yanking pointer; it just returns + the COUNTth kill, counting from the current yanking pointer. + + If COUNT is zero, indicating a request for the latest kill, + `current-kill' calls the value of `interprogram-paste-function' + (documented below) before consulting the kill ring. + + - Function: kill-new string &optional replace + This function makes the text STRING the latest entry in the kill + ring, and sets `kill-ring-yank-pointer' to point to it. + + Normally, STRING is added to the front of the kill ring as a new + entry. However, if optional argument REPLACE is non-`nil', the + entry previously at the front of the kill ring is discarded, and + STRING replaces it. + + This function runs the functions on `kill-hooks', and also invokes + the value of `interprogram-cut-function' (see below). + + - Function: kill-append string before-p + This function appends the text STRING to the first entry in the + kill ring. Normally STRING goes at the end of the entry, but if + BEFORE-P is non-`nil', it goes at the beginning. This function + also invokes the value of `interprogram-cut-function' (see below). + + - Variable: interprogram-paste-function + This variable provides a way of transferring killed text from other + programs, when you are using a window system. Its value should be + `nil' or a function of no arguments. + + If the value is a function, `current-kill' calls it to get the + "most recent kill". If the function returns a non-`nil' value, + then that value is used as the "most recent kill". If it returns + `nil', then the first element of `kill-ring' is used. + + The normal use of this hook is to get the X server's primary + selection as the most recent kill, even if the selection belongs + to another X client. *Note X Selections::. + + - Variable: interprogram-cut-function + This variable provides a way of communicating killed text to other + programs, when you are using a window system. Its value should be + `nil' or a function of one argument. + + If the value is a function, `kill-new' and `kill-append' call it + with the new first element of the kill ring as an argument. + + 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 @@ -138,10 +782,10 @@ which is in the variable `buffer-undo-list'. commands use these entries to record where point was before the command. -`(BEG . END)' +`(START . 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. + inserted. Upon insertion, the text occupied the range START-END + in the buffer. `(TEXT . POSITION)' This kind of element indicates how to reinsert text that was @@ -157,11 +801,11 @@ which is in the variable `buffer-undo-list'. once again; it does so only if the file's modification time matches those numbers. -`(nil PROPERTY VALUE BEG . END)' +`(nil PROPERTY VALUE START . 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) + (put-text-property START END PROPERTY VALUE) `POSITION' This element indicates where point was at an earlier time. @@ -237,8 +881,8 @@ disable undo recording with the following two functions, or by setting 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 + - Command: buffer-disable-undo &optional buffer + - Command: 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 @@ -469,12 +1113,15 @@ Margins for Filling 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 + - Function: delete-to-left-margin &optional 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. + The arguments FROM and TO are optional; the default is the whole + buffer. + - 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 @@ -515,662 +1162,3 @@ justification style to refill portions of the text. *Note Margins::. 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 -============ - - The sorting functions described in this section all rearrange text in -a buffer. This is in contrast to the function `sort', which rearranges -the order of the elements of a list (*note Rearrangement::). The -values returned by these functions are not meaningful. - - - Function: sort-subr reverse nextrecfun endrecfun &optional - startkeyfun endkeyfun - This function is the general text-sorting routine that divides a - buffer into records and sorts them. Most of the commands in this - section use this function. - - To understand how `sort-subr' works, consider the whole accessible - portion of the buffer as being divided into disjoint pieces called - "sort records". The records may or may not be contiguous; they may - not overlap. A portion of each sort record (perhaps all of it) is - designated as the sort key. Sorting rearranges the records in - order by their sort keys. - - Usually, the records are rearranged in order of ascending sort key. - If the first argument to the `sort-subr' function, REVERSE, is - non-`nil', the sort records are rearranged in order of descending - sort key. - - The next four arguments to `sort-subr' are functions that are - called to move point across a sort record. They are called many - times from within `sort-subr'. - - 1. NEXTRECFUN is called with point at the end of a record. This - function moves point to the start of the next record. The - first record is assumed to start at the position of point - when `sort-subr' is called. Therefore, you should usually - move point to the beginning of the buffer before calling - `sort-subr'. - - This function can indicate there are no more sort records by - leaving point at the end of the buffer. - - 2. ENDRECFUN is called with point within a record. It moves - point to the end of the record. - - 3. STARTKEYFUN is called to move point from the start of a - record to the start of the sort key. This argument is - optional; if it is omitted, the whole record is the sort key. - If supplied, the function should either return a non-`nil' - value to be used as the sort key, or return `nil' to indicate - that the sort key is in the buffer starting at point. In the - latter case, ENDKEYFUN is called to find the end of the sort - key. - - 4. ENDKEYFUN is called to move point from the start of the sort - key to the end of the sort key. This argument is optional. - If STARTKEYFUN returns `nil' and this argument is omitted (or - `nil'), then the sort key extends to the end of the record. - There is no need for ENDKEYFUN if STARTKEYFUN returns a - non-`nil' value. - - As an example of `sort-subr', here is the complete function - definition for `sort-lines': - - ;; Note that the first two lines of doc string - ;; are effectively one line when viewed by a user. - (defun sort-lines (reverse beg end) - "Sort lines in region alphabetically. - Called from a program, there are three arguments: - REVERSE (non-nil means reverse order), - and BEG and END (the region to sort)." - (interactive "P\nr") - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (sort-subr reverse - 'forward-line - 'end-of-line))) - - Here `forward-line' moves point to the start of the next record, - and `end-of-line' moves point to the end of record. We do not pass - the arguments STARTKEYFUN and ENDKEYFUN, because the entire record - is used as the sort key. - - The `sort-paragraphs' function is very much the same, except that - its `sort-subr' call looks like this: - - (sort-subr reverse - (function - (lambda () - (skip-chars-forward "\n \t\f"))) - 'forward-paragraph) - - - Command: sort-regexp-fields reverse record-regexp key-regexp start - end - This command sorts the region between START and END alphabetically - as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a - negative integer, then sorting is in reverse order. - - Alphabetical sorting means that two sort keys are compared by - comparing the first characters of each, the second characters of - each, and so on. If a mismatch is found, it means that the sort - keys are unequal; the sort key whose character is less at the - point of first mismatch is the lesser sort key. The individual - characters are compared according to their numerical values. - Since Emacs uses the ASCII character set, the ordering in that set - determines alphabetical order. - - The value of the RECORD-REGEXP argument specifies how to divide - the buffer into sort records. At the end of each record, a search - is done for this regular expression, and the text that matches it - is the next record. For example, the regular expression `^.+$', - which matches lines with at least one character besides a newline, - would make each such line into a sort record. *Note Regular - Expressions::, for a description of the syntax and meaning of - regular expressions. - - The value of the KEY-REGEXP argument specifies what part of each - record is the sort key. The KEY-REGEXP could match the whole - record, or only a part. In the latter case, the rest of the - record has no effect on the sorted order of records, but it is - carried along when the record moves to its new position. - - The KEY-REGEXP argument can refer to the text matched by a - subexpression of RECORD-REGEXP, or it can be a regular expression - on its own. - - If KEY-REGEXP is: - - `\DIGIT' - then the text matched by the DIGITth `\(...\)' parenthesis - grouping in RECORD-REGEXP is the sort key. - - `\&' - then the whole record is the sort key. - - a regular expression - then `sort-regexp-fields' searches for a match for the regular - expression within the record. If such a match is found, it - is the sort key. If there is no match for KEY-REGEXP within - a record then that record is ignored, which means its - position in the buffer is not changed. (The other records - may move around it.) - - For example, if you plan to sort all the lines in the region by the - first word on each line starting with the letter `f', you should - set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\'. The - resulting expression looks like this: - - (sort-regexp-fields nil "^.*$" "\\" - (region-beginning) - (region-end)) - - If you call `sort-regexp-fields' interactively, it prompts for - RECORD-REGEXP and KEY-REGEXP in the minibuffer. - - - Command: sort-lines reverse start end - This command alphabetically sorts lines in the region between - START and END. If REVERSE is non-`nil', the sort is in reverse - order. - - - Command: sort-paragraphs reverse start end - This command alphabetically sorts paragraphs in the region between - START and END. If REVERSE is non-`nil', the sort is in reverse - order. - - - Command: sort-pages reverse start end - This command alphabetically sorts pages in the region between - START and END. If REVERSE is non-`nil', the sort is in reverse - order. - - - Command: sort-fields field start end - This command sorts lines in the region between START and END, - comparing them alphabetically by the FIELDth field of each line. - Fields are separated by whitespace and numbered starting from 1. - If FIELD is negative, sorting is by the -FIELDth field from the - end of the line. This command is useful for sorting tables. - - - Command: sort-numeric-fields field start end - This command sorts lines in the region between START and END, - comparing them numerically by the FIELDth field of each line. The - specified field must contain a number in each line of the region. - Fields are separated by whitespace and numbered starting from 1. - If FIELD is negative, sorting is by the -FIELDth field from the - end of the line. This command is useful for sorting tables. - - - Command: sort-columns reverse &optional beg end - This command sorts the lines in the region between BEG and END, - comparing them alphabetically by a certain range of columns. The - column positions of BEG and END bound the range of columns to sort - on. - - If REVERSE is non-`nil', the sort is in reverse order. - - One unusual thing about this command is that the entire line - containing position BEG, and the entire line containing position - END, are included in the region sorted. - - Note that `sort-columns' uses the `sort' utility program, and so - cannot work properly on text containing tab characters. Use `M-x - `untabify'' to convert tabs to spaces before sorting. - - -File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text - -Counting Columns -================ - - The column functions convert between a character position (counting -characters from the beginning of the buffer) and a column position -(counting screen characters from the beginning of a line). - - A character counts according to the number of columns it occupies on -the screen. This means control characters count as occupying 2 or 4 -columns, depending upon the value of `ctl-arrow', and tabs count as -occupying a number of columns that depends on the value of `tab-width' -and on the column where the tab begins. *Note Usual Display::. - - Column number computations ignore the width of the window and the -amount of horizontal scrolling. Consequently, a column value can be -arbitrarily high. The first (or leftmost) column is numbered 0. - - - Function: current-column - This function returns the horizontal position of point, measured in - columns, counting from 0 at the left margin. The column position - is the sum of the widths of all the displayed representations of - the characters between the start of the current line and point. - - For an example of using `current-column', see the description of - `count-lines' in *Note Text Lines::. - - - Function: move-to-column column &optional force - This function moves point to COLUMN in the current line. The - calculation of COLUMN takes into account the widths of the - displayed representations of the characters between the start of - the line and point. - - If column COLUMN is beyond the end of the line, point moves to the - end of the line. If COLUMN is negative, point moves to the - beginning of the line. - - If it is impossible to move to column COLUMN because that is in - the middle of a multicolumn character such as a tab, point moves - to the end of that character. However, if FORCE is non-`nil', and - COLUMN is in the middle of a tab, then `move-to-column' converts - the tab into spaces so that it can move precisely to column - COLUMN. Other multicolumn characters can cause anomalies despite - FORCE, since there is no way to split them. - - The argument FORCE also has an effect if the line isn't long - enough to reach column COLUMN; in that case, it says to add - whitespace at the end of the line to reach that column. - - If COLUMN is not an integer, an error is signaled. - - The return value is the column number actually moved to. - - -File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text - -Indentation -=========== - - The indentation functions are used to examine, move to, and change -whitespace that is at the beginning of a line. Some of the functions -can also change whitespace elsewhere on a line. Columns and indentation -count from zero at the left margin. - -* Menu: - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - - -File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation - -Indentation Primitives ----------------------- - - This section describes the primitive functions used to count and -insert indentation. The functions in the following sections use these -primitives. - - - Function: current-indentation - This function returns the indentation of the current line, which is - the horizontal position of the first nonblank character. If the - contents are entirely blank, then this is the horizontal position - of the end of the line. - - - Command: indent-to column &optional minimum - This function indents from point with tabs and spaces until COLUMN - is reached. If MINIMUM is specified and non-`nil', then at least - that many spaces are inserted even if this requires going beyond - COLUMN. Otherwise the function does nothing if point is already - beyond COLUMN. The value is the column at which the inserted - indentation ends. - - - User Option: indent-tabs-mode - If this variable is non-`nil', indentation functions can insert - tabs as well as spaces. Otherwise, they insert only spaces. - Setting this variable automatically makes it local to the current - buffer. - - -File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation - -Indentation Controlled by Major Mode ------------------------------------- - - An important function of each major mode is to customize the -key to indent properly for the language being edited. This section -describes the mechanism of the key and how to control it. The -functions in this section return unpredictable values. - - - Variable: indent-line-function - This variable's value is the function to be used by (and - various commands) to indent the current line. The command - `indent-according-to-mode' does no more than call this function. - - In Lisp mode, the value is the symbol `lisp-indent-line'; in C - mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In - Fundamental mode, Text mode, and many other modes with no standard - for indentation, the value is `indent-to-left-margin' (which is the - default value). - - - Command: indent-according-to-mode - This command calls the function in `indent-line-function' to - indent the current line in a way appropriate for the current major - mode. - - - Command: indent-for-tab-command - This command calls the function in `indent-line-function' to indent - the current line; except that if that function is - `indent-to-left-margin', it calls `insert-tab' instead. (That is - a trivial command that inserts a tab character.) - - - Command: newline-and-indent - This function inserts a newline, then indents the new line (the one - following the newline just inserted) according to the major mode. - - It does indentation by calling the current `indent-line-function'. - In programming language modes, this is the same thing does, - but in some text modes, where inserts a tab, - `newline-and-indent' indents to the column specified by - `left-margin'. - - - Command: reindent-then-newline-and-indent - This command reindents the current line, inserts a newline at - point, and then reindents the new line (the one following the - newline just inserted). - - This command does indentation on both lines according to the - current major mode, by calling the current value of - `indent-line-function'. In programming language modes, this is - the same thing does, but in some text modes, where - inserts a tab, `reindent-then-newline-and-indent' indents to the - column specified by `left-margin'. - - -File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation - -Indenting an Entire Region --------------------------- - - This section describes commands that indent all the lines in the -region. They return unpredictable values. - - - Command: indent-region start end to-column - This command indents each nonblank line starting between START - (inclusive) and END (exclusive). If TO-COLUMN is `nil', - `indent-region' indents each nonblank line by calling the current - mode's indentation function, the value of `indent-line-function'. - - If TO-COLUMN is non-`nil', it should be an integer specifying the - number of columns of indentation; then this function gives each - line exactly that much indentation, by either adding or deleting - whitespace. - - If there is a fill prefix, `indent-region' indents each line by - making it start with the fill prefix. - - - Variable: indent-region-function - The value of this variable is a function that can be used by - `indent-region' as a short cut. You should design the function so - that it will produce the same results as indenting the lines of the - region one by one, but presumably faster. - - If the value is `nil', there is no short cut, and `indent-region' - actually works line by line. - - A short-cut function is useful in modes such as C mode and Lisp - mode, where the `indent-line-function' must scan from the - beginning of the function definition: applying it to each line - would be quadratic in time. The short cut can update the scan - information as it moves through the lines indenting them; this - takes linear time. In a mode where indenting a line individually - is fast, there is no need for a short cut. - - `indent-region' with a non-`nil' argument TO-COLUMN has a - different meaning and does not use this variable. - - - Command: indent-rigidly start end count - This command indents all lines starting between START (inclusive) - and END (exclusive) sideways by COUNT columns. This "preserves - the shape" of the affected region, moving it as a rigid unit. - Consequently, this command is useful not only for indenting - regions of unindented text, but also for indenting regions of - formatted code. - - For example, if COUNT is 3, this command adds 3 columns of - indentation to each of the lines beginning in the region specified. - - In Mail mode, `C-c C-y' (`mail-yank-original') uses - `indent-rigidly' to indent the text copied from the message being - replied to. - - - Function: indent-code-rigidly start end columns &optional - nochange-regexp - This is like `indent-rigidly', except that it doesn't alter lines - that start within strings or comments. - - In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at - the beginning of the line (if NOCHANGE-REGEXP is non-`nil'). - - -File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation - -Indentation Relative to Previous Lines --------------------------------------- - - This section describes two commands that indent the current line -based on the contents of previous lines. - - - Command: indent-relative &optional unindented-ok - This command inserts whitespace at point, extending to the same - column as the next "indent point" of the previous nonblank line. - An indent point is a non-whitespace character following - whitespace. The next indent point is the first one at a column - greater than the current column of point. For example, if point - is underneath and to the left of the first non-blank character of - a line of text, it moves to that column by inserting whitespace. - - If the previous nonblank line has no next indent point (i.e., none - at a great enough column position), `indent-relative' either does - nothing (if UNINDENTED-OK is non-`nil') or calls - `tab-to-tab-stop'. Thus, if point is underneath and to the right - of the last column of a short line of text, this command ordinarily - moves point to the next tab stop by inserting whitespace. - - The return value of `indent-relative' is unpredictable. - - In the following example, point is at the beginning of the second - line: - - This line is indented twelve spaces. - -!-The quick brown fox jumped. - - Evaluation of the expression `(indent-relative nil)' produces the - following: - - This line is indented twelve spaces. - -!-The quick brown fox jumped. - - In this example, point is between the `m' and `p' of `jumped': - - This line is indented twelve spaces. - The quick brown fox jum-!-ped. - - Evaluation of the expression `(indent-relative nil)' produces the - following: - - This line is indented twelve spaces. - The quick brown fox jum -!-ped. - - - Command: indent-relative-maybe - This command indents the current line like the previous nonblank - line. It calls `indent-relative' with `t' as the UNINDENTED-OK - argument. The return value is unpredictable. - - If the previous nonblank line has no indent points beyond the - current column, this command does nothing. - - -File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation - -Adjustable "Tab Stops" ----------------------- - - This section explains the mechanism for user-specified "tab stops" -and the mechanisms that use and set them. The name "tab stops" is used -because the feature is similar to that of the tab stops on a -typewriter. The feature works by inserting an appropriate number of -spaces and tab characters to reach the next tab stop column; it does not -affect the display of tab characters in the buffer (*note Usual -Display::). Note that the character as input uses this tab stop -feature only in a few major modes, such as Text mode. - - - Command: tab-to-tab-stop - This command inserts spaces or tabs up to the next tab stop column - defined by `tab-stop-list'. It searches the list for an element - greater than the current column number, and uses that element as - the column to indent to. It does nothing if no such element is - found. - - - User Option: tab-stop-list - This variable is the list of tab stop columns used by - `tab-to-tab-stops'. The elements should be integers in increasing - order. The tab stop columns need not be evenly spaced. - - Use `M-x edit-tab-stops' to edit the location of tab stops - interactively. - - -File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation - -Indentation-Based Motion Commands ---------------------------------- - - These commands, primarily for interactive use, act based on the -indentation in the text. - - - Command: back-to-indentation - This command moves point to the first non-whitespace character in - the current line (which is the line in which point is located). - It returns `nil'. - - - Command: backward-to-indentation arg - This command moves point backward ARG lines and then to the first - nonblank character on that line. It returns `nil'. - - - Command: forward-to-indentation arg - This command moves point forward ARG lines and then to the first - nonblank character on that line. It returns `nil'. - - -File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text - -Case Changes -============ - - The case change commands described here work on text in the current -buffer. *Note Character Case::, for case conversion commands that work -on strings and characters. *Note Case Tables::, for how to customize -which characters are upper or lower case and how to convert them. - - - Command: capitalize-region start end - This function capitalizes all words in the region defined by START - and END. To capitalize means to convert each word's first - character to upper case and convert the rest of each word to lower - case. The function returns `nil'. - - If one end of the region is in the middle of a word, the part of - the word within the region is treated as an entire word. - - When `capitalize-region' is called interactively, START and END - are point and the mark, with the smallest first. - - ---------- Buffer: foo ---------- - This is the contents of the 5th foo. - ---------- Buffer: foo ---------- - - (capitalize-region 1 44) - => nil - - ---------- Buffer: foo ---------- - This Is The Contents Of The 5th Foo. - ---------- Buffer: foo ---------- - - - Command: downcase-region start end - This function converts all of the letters in the region defined by - START and END to lower case. The function returns `nil'. - - When `downcase-region' is called interactively, START and END are - point and the mark, with the smallest first. - - - Command: upcase-region start end - This function converts all of the letters in the region defined by - START and END to upper case. The function returns `nil'. - - When `upcase-region' is called interactively, START and END are - point and the mark, with the smallest first. - - - Command: capitalize-word count - This function capitalizes COUNT words after point, moving point - over as it does. To capitalize means to convert each word's first - character to upper case and convert the rest of each word to lower - case. If COUNT is negative, the function capitalizes the -COUNT - previous words but does not move point. The value is `nil'. - - If point is in the middle of a word, the part of the word before - point is ignored when moving forward. The rest is treated as an - entire word. - - When `capitalize-word' is called interactively, COUNT is set to - the numeric prefix argument. - - - Command: downcase-word count - This function converts the COUNT words after point to all lower - case, moving point over as it does. If COUNT is negative, it - converts the -COUNT previous words but does not move point. The - value is `nil'. - - When `downcase-word' is called interactively, COUNT is set to the - numeric prefix argument. - - - Command: upcase-word count - This function converts the COUNT words after point to all upper - case, moving point over as it does. If COUNT is negative, it - converts the -COUNT previous words but does not move point. The - value is `nil'. - - When `upcase-word' is called interactively, COUNT is set to the - numeric prefix argument. - - -File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text - -Text Properties -=============== - - Text properties are an alternative interface to extents (*note -Extents::), and are built on top of them. They are useful when you -want to view textual properties as being attached to the characters -themselves rather than to intervals of characters. The text property -interface is compatible with FSF Emacs. - - Each character position in a buffer or a string can have a "text -property list", much like the property list of a symbol (*note Property -Lists::). The properties belong to a particular character at a -particular place, such as, the letter `T' at the beginning of this -sentence or the first `o' in `foo'--if the same character occurs in two -different places, the two occurrences generally have different -properties. - - Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. The usual way to access the -property list is to specify a name and ask what value corresponds to it. - - Note that FSF Emacs also looks at the `category' property to find -defaults for text properties. We consider this too bogus to implement. - - Copying text between strings and buffers preserves the properties -along with the characters; this includes such diverse functions as -`substring', `insert', and `buffer-substring'. - -* Menu: - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Saving Properties:: Saving text properties in files, and reading - them back. - diff --git a/info/lispref.info-31 b/info/lispref.info-31 index 56e71ee..e1a79f9 100644 --- a/info/lispref.info-31 +++ b/info/lispref.info-31 @@ -50,6 +50,680 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Sorting, Next: Columns, Prev: Auto Filling, Up: Text + +Sorting Text +============ + + The sorting functions described in this section all rearrange text in +a buffer. This is in contrast to the function `sort', which rearranges +the order of the elements of a list (*note Rearrangement::). The +values returned by these functions are not meaningful. + + - Function: sort-subr reverse nextrecfun endrecfun &optional + startkeyfun endkeyfun + This function is the general text-sorting routine that divides a + buffer into records and sorts them. Most of the commands in this + section use this function. + + To understand how `sort-subr' works, consider the whole accessible + portion of the buffer as being divided into disjoint pieces called + "sort records". The records may or may not be contiguous; they may + not overlap. A portion of each sort record (perhaps all of it) is + designated as the sort key. Sorting rearranges the records in + order by their sort keys. + + Usually, the records are rearranged in order of ascending sort key. + If the first argument to the `sort-subr' function, REVERSE, is + non-`nil', the sort records are rearranged in order of descending + sort key. + + The next four arguments to `sort-subr' are functions that are + called to move point across a sort record. They are called many + times from within `sort-subr'. + + 1. NEXTRECFUN is called with point at the end of a record. This + function moves point to the start of the next record. The + first record is assumed to start at the position of point + when `sort-subr' is called. Therefore, you should usually + move point to the beginning of the buffer before calling + `sort-subr'. + + This function can indicate there are no more sort records by + leaving point at the end of the buffer. + + 2. ENDRECFUN is called with point within a record. It moves + point to the end of the record. + + 3. STARTKEYFUN is called to move point from the start of a + record to the start of the sort key. This argument is + optional; if it is omitted, the whole record is the sort key. + If supplied, the function should either return a non-`nil' + value to be used as the sort key, or return `nil' to indicate + that the sort key is in the buffer starting at point. In the + latter case, ENDKEYFUN is called to find the end of the sort + key. + + 4. ENDKEYFUN is called to move point from the start of the sort + key to the end of the sort key. This argument is optional. + If STARTKEYFUN returns `nil' and this argument is omitted (or + `nil'), then the sort key extends to the end of the record. + There is no need for ENDKEYFUN if STARTKEYFUN returns a + non-`nil' value. + + As an example of `sort-subr', here is the complete function + definition for `sort-lines': + + ;; Note that the first two lines of doc string + ;; are effectively one line when viewed by a user. + (defun sort-lines (reverse start end) + "Sort lines in region alphabetically. + Called from a program, there are three arguments: + REVERSE (non-nil means reverse order), + and START and END (the region to sort)." + (interactive "P\nr") + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (sort-subr reverse + 'forward-line + 'end-of-line))) + + Here `forward-line' moves point to the start of the next record, + and `end-of-line' moves point to the end of record. We do not pass + the arguments STARTKEYFUN and ENDKEYFUN, because the entire record + is used as the sort key. + + The `sort-paragraphs' function is very much the same, except that + its `sort-subr' call looks like this: + + (sort-subr reverse + (function + (lambda () + (skip-chars-forward "\n \t\f"))) + 'forward-paragraph) + + - Command: sort-regexp-fields reverse record-regexp key-regexp start + end + This command sorts the region between START and END alphabetically + as specified by RECORD-REGEXP and KEY-REGEXP. If REVERSE is a + negative integer, then sorting is in reverse order. + + Alphabetical sorting means that two sort keys are compared by + comparing the first characters of each, the second characters of + each, and so on. If a mismatch is found, it means that the sort + keys are unequal; the sort key whose character is less at the + point of first mismatch is the lesser sort key. The individual + characters are compared according to their numerical values. + Since Emacs uses the ASCII character set, the ordering in that set + determines alphabetical order. + + The value of the RECORD-REGEXP argument specifies how to divide + the buffer into sort records. At the end of each record, a search + is done for this regular expression, and the text that matches it + is the next record. For example, the regular expression `^.+$', + which matches lines with at least one character besides a newline, + would make each such line into a sort record. *Note Regular + Expressions::, for a description of the syntax and meaning of + regular expressions. + + The value of the KEY-REGEXP argument specifies what part of each + record is the sort key. The KEY-REGEXP could match the whole + record, or only a part. In the latter case, the rest of the + record has no effect on the sorted order of records, but it is + carried along when the record moves to its new position. + + The KEY-REGEXP argument can refer to the text matched by a + subexpression of RECORD-REGEXP, or it can be a regular expression + on its own. + + If KEY-REGEXP is: + + `\DIGIT' + then the text matched by the DIGITth `\(...\)' parenthesis + grouping in RECORD-REGEXP is the sort key. + + `\&' + then the whole record is the sort key. + + a regular expression + then `sort-regexp-fields' searches for a match for the regular + expression within the record. If such a match is found, it + is the sort key. If there is no match for KEY-REGEXP within + a record then that record is ignored, which means its + position in the buffer is not changed. (The other records + may move around it.) + + For example, if you plan to sort all the lines in the region by the + first word on each line starting with the letter `f', you should + set RECORD-REGEXP to `^.*$' and set KEY-REGEXP to `\'. The + resulting expression looks like this: + + (sort-regexp-fields nil "^.*$" "\\" + (region-beginning) + (region-end)) + + If you call `sort-regexp-fields' interactively, it prompts for + RECORD-REGEXP and KEY-REGEXP in the minibuffer. + + - Command: sort-lines reverse start end + This command alphabetically sorts lines in the region between + START and END. If REVERSE is non-`nil', the sort is in reverse + order. + + - Command: sort-paragraphs reverse start end + This command alphabetically sorts paragraphs in the region between + START and END. If REVERSE is non-`nil', the sort is in reverse + order. + + - Command: sort-pages reverse start end + This command alphabetically sorts pages in the region between + START and END. If REVERSE is non-`nil', the sort is in reverse + order. + + - Command: sort-fields field start end + This command sorts lines in the region between START and END, + comparing them alphabetically by the FIELDth field of each line. + Fields are separated by whitespace and numbered starting from 1. + If FIELD is negative, sorting is by the -FIELDth field from the + end of the line. This command is useful for sorting tables. + + - Command: sort-numeric-fields field start end + This command sorts lines in the region between START and END, + comparing them numerically by the FIELDth field of each line. The + specified field must contain a number in each line of the region. + Fields are separated by whitespace and numbered starting from 1. + If FIELD is negative, sorting is by the -FIELDth field from the + end of the line. This command is useful for sorting tables. + + - Command: sort-columns reverse &optional start end + This command sorts the lines in the region between START and END, + comparing them alphabetically by a certain range of columns. The + column positions of START and END bound the range of columns to + sort on. + + If REVERSE is non-`nil', the sort is in reverse order. + + One unusual thing about this command is that the entire line + containing position START, and the entire line containing position + END, are included in the region sorted. + + Note that `sort-columns' uses the `sort' utility program, and so + cannot work properly on text containing tab characters. Use `M-x + `untabify'' to convert tabs to spaces before sorting. + + +File: lispref.info, Node: Columns, Next: Indentation, Prev: Sorting, Up: Text + +Counting Columns +================ + + The column functions convert between a character position (counting +characters from the beginning of the buffer) and a column position +(counting screen characters from the beginning of a line). + + A character counts according to the number of columns it occupies on +the screen. This means control characters count as occupying 2 or 4 +columns, depending upon the value of `ctl-arrow', and tabs count as +occupying a number of columns that depends on the value of `tab-width' +and on the column where the tab begins. *Note Usual Display::. + + Column number computations ignore the width of the window and the +amount of horizontal scrolling. Consequently, a column value can be +arbitrarily high. The first (or leftmost) column is numbered 0. + + - Function: current-column &optional buffer + This function returns the horizontal position of point, measured in + columns, counting from 0 at the left margin. + + This is calculated by adding together the widths of all the + displayed representations of the character between the start of + the previous line and point. (e.g. control characters will have a + width of 2 or 4, tabs will have a variable width.) + + Ignores the finite width of frame displaying the buffer, which + means that this function may return values greater than + `(frame-width)'. + + Whether the line is visible (if `selective-display' is t) has no + effect; however, ^M is treated as end of line when + `selective-display' is t. + + If BUFFER is nil, the current buffer is assumed. + + For an example of using `current-column', see the description of + `count-lines' in *Note Text Lines::. + + - Function: move-to-column column &optional force buffer + This function moves point to COLUMN in the current line. The + calculation of COLUMN takes into account the widths of the + displayed representations of the characters between the start of + the line and point. + + If column COLUMN is beyond the end of the line, point moves to the + end of the line. If COLUMN is negative, point moves to the + beginning of the line. + + If it is impossible to move to column COLUMN because that is in + the middle of a multicolumn character such as a tab, point moves + to the end of that character. However, if FORCE is non-`nil', and + COLUMN is in the middle of a tab, then `move-to-column' converts + the tab into spaces so that it can move precisely to column + COLUMN. Other multicolumn characters can cause anomalies despite + FORCE, since there is no way to split them. + + The argument FORCE also has an effect if the line isn't long + enough to reach column COLUMN; in that case, unless the value of + FORCE is the special value `coerce', it says to add whitespace at + the end of the line to reach that column. + + If COLUMN is not a non-negative integer, an error is signaled. + + The return value is the column number actually moved to. + + +File: lispref.info, Node: Indentation, Next: Case Changes, Prev: Columns, Up: Text + +Indentation +=========== + + The indentation functions are used to examine, move to, and change +whitespace that is at the beginning of a line. Some of the functions +can also change whitespace elsewhere on a line. Columns and indentation +count from zero at the left margin. + +* Menu: + +* Primitive Indent:: Functions used to count and insert indentation. +* Mode-Specific Indent:: Customize indentation for different modes. +* Region Indent:: Indent all the lines in a region. +* Relative Indent:: Indent the current line based on previous lines. +* Indent Tabs:: Adjustable, typewriter-like tab stops. +* Motion by Indent:: Move to first non-blank character. + + +File: lispref.info, Node: Primitive Indent, Next: Mode-Specific Indent, Up: Indentation + +Indentation Primitives +---------------------- + + This section describes the primitive functions used to count and +insert indentation. The functions in the following sections use these +primitives. + + - Function: current-indentation &optional buffer + This function returns the indentation of the current line, which is + the horizontal position of the first nonblank character. If the + contents are entirely blank, then this is the horizontal position + of the end of the line. + + - Command: indent-to column &optional minimum buffer + This function indents from point with tabs and spaces until COLUMN + is reached. If MINIMUM is specified and non-`nil', then at least + that many spaces are inserted even if this requires going beyond + COLUMN. Otherwise the function does nothing if point is already + beyond COLUMN. The value is the column at which the inserted + indentation ends. If BUFFER is `nil', the current buffer is + assumed. + + - User Option: indent-tabs-mode + If this variable is non-`nil', indentation functions can insert + tabs as well as spaces. Otherwise, they insert only spaces. + Setting this variable automatically makes it local to the current + buffer. + + +File: lispref.info, Node: Mode-Specific Indent, Next: Region Indent, Prev: Primitive Indent, Up: Indentation + +Indentation Controlled by Major Mode +------------------------------------ + + An important function of each major mode is to customize the +key to indent properly for the language being edited. This section +describes the mechanism of the key and how to control it. The +functions in this section return unpredictable values. + + - Variable: indent-line-function + This variable's value is the function to be used by (and + various commands) to indent the current line. The command + `indent-according-to-mode' does no more than call this function. + + In Lisp mode, the value is the symbol `lisp-indent-line'; in C + mode, `c-indent-line'; in Fortran mode, `fortran-indent-line'. In + Fundamental mode, Text mode, and many other modes with no standard + for indentation, the value is `indent-to-left-margin' (which is the + default value). + + - Command: indent-according-to-mode + This command calls the function in `indent-line-function' to + indent the current line in a way appropriate for the current major + mode. + + - Command: indent-for-tab-command &optional prefix-arg + This command calls the function in `indent-line-function' to indent + the current line; except that if that function is + `indent-to-left-margin', it calls `insert-tab' instead. (That is + a trivial command that inserts a tab character.) + + - Command: newline-and-indent + This function inserts a newline, then indents the new line (the one + following the newline just inserted) according to the major mode. + + It does indentation by calling the current `indent-line-function'. + In programming language modes, this is the same thing does, + but in some text modes, where inserts a tab, + `newline-and-indent' indents to the column specified by + `left-margin'. + + - Command: reindent-then-newline-and-indent + This command reindents the current line, inserts a newline at + point, and then reindents the new line (the one following the + newline just inserted). + + This command does indentation on both lines according to the + current major mode, by calling the current value of + `indent-line-function'. In programming language modes, this is + the same thing does, but in some text modes, where + inserts a tab, `reindent-then-newline-and-indent' indents to the + column specified by `left-margin'. + + +File: lispref.info, Node: Region Indent, Next: Relative Indent, Prev: Mode-Specific Indent, Up: Indentation + +Indenting an Entire Region +-------------------------- + + This section describes commands that indent all the lines in the +region. They return unpredictable values. + + - Command: indent-region start end to-column + This command indents each nonblank line starting between START + (inclusive) and END (exclusive). If TO-COLUMN is `nil', + `indent-region' indents each nonblank line by calling the current + mode's indentation function, the value of `indent-line-function'. + + If TO-COLUMN is non-`nil', it should be an integer specifying the + number of columns of indentation; then this function gives each + line exactly that much indentation, by either adding or deleting + whitespace. + + If there is a fill prefix, `indent-region' indents each line by + making it start with the fill prefix. + + - Variable: indent-region-function + The value of this variable is a function that can be used by + `indent-region' as a short cut. You should design the function so + that it will produce the same results as indenting the lines of the + region one by one, but presumably faster. + + If the value is `nil', there is no short cut, and `indent-region' + actually works line by line. + + A short-cut function is useful in modes such as C mode and Lisp + mode, where the `indent-line-function' must scan from the + beginning of the function definition: applying it to each line + would be quadratic in time. The short cut can update the scan + information as it moves through the lines indenting them; this + takes linear time. In a mode where indenting a line individually + is fast, there is no need for a short cut. + + `indent-region' with a non-`nil' argument TO-COLUMN has a + different meaning and does not use this variable. + + - Command: indent-rigidly start end count + This command indents all lines starting between START (inclusive) + and END (exclusive) sideways by COUNT columns. This "preserves + the shape" of the affected region, moving it as a rigid unit. + Consequently, this command is useful not only for indenting + regions of unindented text, but also for indenting regions of + formatted code. + + For example, if COUNT is 3, this command adds 3 columns of + indentation to each of the lines beginning in the region specified. + + In Mail mode, `C-c C-y' (`mail-yank-original') uses + `indent-rigidly' to indent the text copied from the message being + replied to. + + - Command: indent-code-rigidly start end columns &optional + nochange-regexp + This is like `indent-rigidly', except that it doesn't alter lines + that start within strings or comments. + + In addition, it doesn't alter a line if NOCHANGE-REGEXP matches at + the beginning of the line (if NOCHANGE-REGEXP is non-`nil'). + + +File: lispref.info, Node: Relative Indent, Next: Indent Tabs, Prev: Region Indent, Up: Indentation + +Indentation Relative to Previous Lines +-------------------------------------- + + This section describes two commands that indent the current line +based on the contents of previous lines. + + - Command: indent-relative &optional unindented-ok + This command inserts whitespace at point, extending to the same + column as the next "indent point" of the previous nonblank line. + An indent point is a non-whitespace character following + whitespace. The next indent point is the first one at a column + greater than the current column of point. For example, if point + is underneath and to the left of the first non-blank character of + a line of text, it moves to that column by inserting whitespace. + + If the previous nonblank line has no next indent point (i.e., none + at a great enough column position), `indent-relative' either does + nothing (if UNINDENTED-OK is non-`nil') or calls + `tab-to-tab-stop'. Thus, if point is underneath and to the right + of the last column of a short line of text, this command ordinarily + moves point to the next tab stop by inserting whitespace. + + The return value of `indent-relative' is unpredictable. + + In the following example, point is at the beginning of the second + line: + + This line is indented twelve spaces. + -!-The quick brown fox jumped. + + Evaluation of the expression `(indent-relative nil)' produces the + following: + + This line is indented twelve spaces. + -!-The quick brown fox jumped. + + In this example, point is between the `m' and `p' of `jumped': + + This line is indented twelve spaces. + The quick brown fox jum-!-ped. + + Evaluation of the expression `(indent-relative nil)' produces the + following: + + This line is indented twelve spaces. + The quick brown fox jum -!-ped. + + - Command: indent-relative-maybe + This command indents the current line like the previous nonblank + line. It calls `indent-relative' with `t' as the UNINDENTED-OK + argument. The return value is unpredictable. + + If the previous nonblank line has no indent points beyond the + current column, this command does nothing. + + +File: lispref.info, Node: Indent Tabs, Next: Motion by Indent, Prev: Relative Indent, Up: Indentation + +Adjustable "Tab Stops" +---------------------- + + This section explains the mechanism for user-specified "tab stops" +and the mechanisms that use and set them. The name "tab stops" is used +because the feature is similar to that of the tab stops on a +typewriter. The feature works by inserting an appropriate number of +spaces and tab characters to reach the next tab stop column; it does not +affect the display of tab characters in the buffer (*note Usual +Display::). Note that the character as input uses this tab stop +feature only in a few major modes, such as Text mode. + + - Command: tab-to-tab-stop + This command inserts spaces or tabs up to the next tab stop column + defined by `tab-stop-list'. It searches the list for an element + greater than the current column number, and uses that element as + the column to indent to. It does nothing if no such element is + found. + + - User Option: tab-stop-list + This variable is the list of tab stop columns used by + `tab-to-tab-stops'. The elements should be integers in increasing + order. The tab stop columns need not be evenly spaced. + + Use `M-x edit-tab-stops' to edit the location of tab stops + interactively. + + +File: lispref.info, Node: Motion by Indent, Prev: Indent Tabs, Up: Indentation + +Indentation-Based Motion Commands +--------------------------------- + + These commands, primarily for interactive use, act based on the +indentation in the text. + + - Command: back-to-indentation + This command moves point to the first non-whitespace character in + the current line (which is the line in which point is located). + It returns `nil'. + + - Command: backward-to-indentation arg + This command moves point backward ARG lines and then to the first + nonblank character on that line. It returns `nil'. + + - Command: forward-to-indentation arg + This command moves point forward ARG lines and then to the first + nonblank character on that line. It returns `nil'. + + +File: lispref.info, Node: Case Changes, Next: Text Properties, Prev: Indentation, Up: Text + +Case Changes +============ + + The case change commands described here work on text in the current +buffer. *Note Character Case::, for case conversion commands that work +on strings and characters. *Note Case Tables::, for how to customize +which characters are upper or lower case and how to convert them. + + - Command: capitalize-region start end &optional buffer + This function capitalizes all words in the region defined by START + and END. To capitalize means to convert each word's first + character to upper case and convert the rest of each word to lower + case. The function returns `nil'. + + If one end of the region is in the middle of a word, the part of + the word within the region is treated as an entire word. + + When `capitalize-region' is called interactively, START and END + are point and the mark, with the smallest first. + + ---------- Buffer: foo ---------- + This is the contents of the 5th foo. + ---------- Buffer: foo ---------- + + (capitalize-region 1 44) + => nil + + ---------- Buffer: foo ---------- + This Is The Contents Of The 5th Foo. + ---------- Buffer: foo ---------- + + - Command: downcase-region start end &optional buffer + This function converts all of the letters in the region defined by + START and END to lower case. The function returns `nil'. + + When `downcase-region' is called interactively, START and END are + point and the mark, with the smallest first. + + - Command: upcase-region start end &optional buffer + This function converts all of the letters in the region defined by + START and END to upper case. The function returns `nil'. + + When `upcase-region' is called interactively, START and END are + point and the mark, with the smallest first. + + - Command: capitalize-word count &optional buffer + This function capitalizes COUNT words after point, moving point + over as it does. To capitalize means to convert each word's first + character to upper case and convert the rest of each word to lower + case. If COUNT is negative, the function capitalizes the -COUNT + previous words but does not move point. The value is `nil'. + + If point is in the middle of a word, the part of the word before + point is ignored when moving forward. The rest is treated as an + entire word. + + When `capitalize-word' is called interactively, COUNT is set to + the numeric prefix argument. + + - Command: downcase-word count &optional buffer + This function converts the COUNT words after point to all lower + case, moving point over as it does. If COUNT is negative, it + converts the -COUNT previous words but does not move point. The + value is `nil'. + + When `downcase-word' is called interactively, COUNT is set to the + numeric prefix argument. + + - Command: upcase-word count &optional buffer + This function converts the COUNT words after point to all upper + case, moving point over as it does. If COUNT is negative, it + converts the -COUNT previous words but does not move point. The + value is `nil'. + + When `upcase-word' is called interactively, COUNT is set to the + numeric prefix argument. + + +File: lispref.info, Node: Text Properties, Next: Substitution, Prev: Case Changes, Up: Text + +Text Properties +=============== + + Text properties are an alternative interface to extents (*note +Extents::), and are built on top of them. They are useful when you +want to view textual properties as being attached to the characters +themselves rather than to intervals of characters. The text property +interface is compatible with FSF Emacs. + + Each character position in a buffer or a string can have a "text +property list", much like the property list of a symbol (*note Property +Lists::). The properties belong to a particular character at a +particular place, such as, the letter `T' at the beginning of this +sentence or the first `o' in `foo'--if the same character occurs in two +different places, the two occurrences generally have different +properties. + + Each property has a name and a value. Both of these can be any Lisp +object, but the name is normally a symbol. The usual way to access the +property list is to specify a name and ask what value corresponds to it. + + Note that FSF Emacs also looks at the `category' property to find +defaults for text properties. We consider this too bogus to implement. + + Copying text between strings and buffers preserves the properties +along with the characters; this includes such diverse functions as +`substring', `insert', and `buffer-substring'. + +* Menu: + +* Examining Properties:: Looking at the properties of one character. +* Changing Properties:: Setting the properties of a range of text. +* Property Search:: Searching for where a property changes value. +* Special Properties:: Particular properties with special meanings. +* 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 @@ -65,12 +739,12 @@ to examine the properties of a number of characters at once. positions in a string start from 0, whereas positions in a buffer start from 1.) - - Function: get-text-property pos prop &optional object + - Function: get-text-property pos prop &optional object at-flag 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 + - Function: get-char-property pos prop &optional object at-flag This function is like `get-text-property', except that it checks all extents, not just text-property extents. @@ -244,13 +918,13 @@ different properties. if LIMIT equals POS. - Function: previous-property-change pos &optional object limit - This is like `next-property-change', but scans back from POS + This is like `next-property-change', but scans backward 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 + This is like `next-single-property-change', but scans backward 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. @@ -462,20 +1136,20 @@ otherwise stated. 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: get-register register + This function returns the contents of the register REGISTER, or + `nil' if it has no contents. - - Function: set-register reg value - This function sets the contents of register REG to VALUE. A + - Function: set-register register value + This function sets the contents of register REGISTER 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: view-register register + This command displays what is contained in register REGISTER. - - Command: insert-register reg &optional beforep - This command inserts contents of register REG into the current + - Command: insert-register register &optional beforep + This command inserts contents of register REGISTER into the current buffer. Normally, this command puts point before the inserted text, and the @@ -514,653 +1188,3 @@ Transposition of Text 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 -============ - - These hook variables let you arrange to take notice of all changes in -all buffers (or in a particular buffer, if you make them buffer-local). - - The functions you use in these hooks should save and restore the -match data if they do anything that uses regular expressions; -otherwise, they will interfere in bizarre ways with the editing -operations that call them. - - Buffer changes made while executing the following hooks don't -themselves cause any change hooks to be invoked. - - - Variable: before-change-functions - This variable holds a list of a functions to call before any buffer - modification. Each function gets two arguments, the beginning and - end of the region that is about to change, represented as - integers. The buffer that is about to change is always the - current buffer. - - - Variable: after-change-functions - This variable holds a list of a functions to call after any buffer - modification. Each function receives three arguments: the - beginning and end of the region just changed, and the length of - the text that existed before the change. (To get the current - length, subtract the region beginning from the region end.) All - three arguments are integers. The buffer that's about to change - is always the current buffer. - - - Variable: before-change-function - This obsolete variable holds one function to call before any buffer - modification (or `nil' for no function). It is called just like - the functions in `before-change-functions'. - - - Variable: after-change-function - This obsolete variable holds one function to call after any buffer - modification (or `nil' for no function). It is called just like - the functions in `after-change-functions'. - - - Variable: first-change-hook - This variable is a normal hook that is run whenever a buffer is - changed that was previously in the unmodified state. - - -File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text - -Textual transformations--MD5 and base64 support -=============================================== - - Some textual operations inherently require examining each character -in turn, and performing arithmetic operations on them. Such operations -can, of course, be implemented in Emacs Lisp, but tend to be very slow -for large portions of text or data. This is why some of them are -implemented in C, with an appropriate interface for Lisp programmers. -Examples of algorithms thus provided are MD5 and base64 support. - - MD5 is an algorithm for calculating message digests, as described in -rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit -"fingerprint" ("message digest") corresponding to that message. It is -considered computationally infeasible to produce two messages having -the same MD5 digest, or to produce a message having a prespecified -target digest. MD5 is used heavily by various authentication schemes. - - Emacs Lisp interface to MD5 consists of a single function `md5': - - - Function: md5 object &optional start end - This function returns the MD5 message digest of OBJECT, a buffer - or string. - - Optional arguments START and END denote positions for computing - the digest of a portion of OBJECT. - - Some examples of usage: - - ;; Calculate the digest of the entire buffer - (md5 (current-buffer)) - => "8842b04362899b1cda8d2d126dc11712" - - ;; Calculate the digest of the current line - (md5 (current-buffer) (point-at-bol) (point-at-eol)) - => "60614d21e9dee27dfdb01fa4e30d6d00" - - ;; Calculate the digest of your name and email address - (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address))) - => "0a2188c40fd38922d941fe6032fce516" - - Base64 is a portable encoding for arbitrary sequences of octets, in a -form that need not be readable by humans. It uses a 65-character subset -of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode -binary bodies, and to encode binary characters in message headers. - - The Lisp interface to base64 consists of four functions: - - - Function: base64-encode-region beg end &optional no-line-break - This function encodes the region between BEG and END of the - current buffer to base64 format. This means that the original - region is deleted, and replaced with its base64 equivalent. - - Normally, encoded base64 output is multi-line, with 76-character - lines. If NO-LINE-BREAK is non-`nil', newlines will not be - inserted, resulting in single-line output. - - Mule note: you should make sure that you convert the multibyte - characters (those that do not fit into 0-255 range) to something - else, because they cannot be meaningfully converted to base64. If - the `base64-encode-region' encounters such characters, it will - signal an error. - - `base64-encode-region' returns the length of the encoded text. - - ;; Encode the whole buffer in base64 - (base64-encode-region (point-min) (point-max)) - - The function can also be used interactively, in which case it - works on the currently active region. - - - Function: base64-encode-string string - This function encodes STRING to base64, and returns the encoded - string. - - For Mule, the same considerations apply as for - `base64-encode-region'. - - (base64-encode-string "fubar") - => "ZnViYXI=" - - - Function: base64-decode-region beg end - This function decodes the region between BEG and END of the - current buffer. The region should be in base64 encoding. - - If the region was decoded correctly, `base64-decode-region' returns - the length of the decoded region. If the decoding failed, `nil' is - returned. - - ;; Decode a base64 buffer, and replace it with the decoded version - (base64-decode-region (point-min) (point-max)) - - - Function: base64-decode-string string - This function decodes STRING to base64, and returns the decoded - string. STRING should be valid base64-encoded text. - - If encoding was not possible, `nil' is returned. - - (base64-decode-string "ZnViYXI=") - => "fubar" - - (base64-decode-string "totally bogus") - => nil - - -File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top - -Searching and Matching -********************** - - XEmacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the "match data" to -determine which text matched the whole regular expression or various -portions of it. - -* Menu: - -* String Search:: Search for an exact match. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Search and Replace:: Internals of `query-replace'. -* Match Data:: Finding out which part of the text matched - various parts of a regexp, after regexp search. -* Searching and Case:: Case-independent or case-significant searching. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - - The `skip-chars...' functions also perform a kind of searching. -*Note Skipping Characters::. - - -File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching - -Searching for Strings -===================== - - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; LIMIT -and NOERROR are set to `nil', and REPEAT is set to 1. - - - Command: search-forward string &optional limit noerror repeat - This function searches forward from point for an exact match for - STRING. If successful, it sets point to the end of the occurrence - found, and returns the new value of point. If no match is found, - the value and side effects depend on NOERROR (see below). - - In the following example, point is initially at the beginning of - the line. Then `(search-forward "fox")' moves point after the last - letter of `fox': - - ---------- Buffer: foo ---------- - -!-The quick brown fox jumped over the lazy dog. - ---------- Buffer: foo ---------- - - (search-forward "fox") - => 20 - - ---------- Buffer: foo ---------- - The quick brown fox-!- jumped over the lazy dog. - ---------- Buffer: foo ---------- - - The argument LIMIT specifies the upper bound to the search. (It - must be a position in the current buffer.) No match extending - after that position is accepted. If LIMIT is omitted or `nil', it - defaults to the end of the accessible portion of the buffer. - - 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', `search-forward' returns `nil' and - does nothing. If NOERROR is neither `nil' nor `t', then - `search-forward' moves point to the upper bound and returns `nil'. - (It would be more consistent now to return the new position of - point in that case, but some programs may depend on a value of - `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. - - - Command: search-backward string &optional limit noerror repeat - This function searches backward from point for STRING. It is just - like `search-forward' except that it searches backwards and leaves - point at the beginning of the match. - - - Command: word-search-forward string &optional limit noerror repeat - This function searches forward from point for a "word" match for - STRING. If it finds a match, it sets point to the end of the - match found, and returns the new value of point. - - Word matching regards STRING as a sequence of words, disregarding - punctuation that separates them. It searches the buffer for the - same sequence of words. Each word must be distinct in the buffer - (searching for the word `ball' does not match the word `balls'), - but the details of punctuation and spacing are ignored (searching - for `ball boy' does match `ball. Boy!'). - - In this example, point is initially at the beginning of the - buffer; the search leaves it between the `y' and the `!'. - - ---------- Buffer: foo ---------- - -!-He said "Please! Find - the ball boy!" - ---------- Buffer: foo ---------- - - (word-search-forward "Please find the ball, boy.") - => 35 - - ---------- Buffer: foo ---------- - He said "Please! Find - the ball boy-!-!" - ---------- Buffer: foo ---------- - - If LIMIT is non-`nil' (it must be a position in the current - buffer), then it is the upper bound to the search. The match - found must not extend after that position. - - If NOERROR is `nil', then `word-search-forward' signals an error - if the search fails. If NOERROR is `t', then it returns `nil' - instead of signaling an error. If NOERROR is neither `nil' nor - `t', it moves point to LIMIT (or the end of the buffer) and - returns `nil'. - - If REPEAT is non-`nil', then the search is repeated that many - times. Point is positioned at the end of the last match. - - - Command: word-search-backward string &optional limit noerror repeat - This function searches backward from point for a word match to - STRING. This function is just like `word-search-forward' except - that it searches backward and normally leaves point at the - beginning of the match. - - -File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching - -Regular Expressions -=================== - - A "regular expression" ("regexp", for short) is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to -write regexps; the following section says how to search for them. - - To gain a thorough understanding of regular expressions and how to -use them to best advantage, we recommend that you study `Mastering -Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, -1997'. (It's known as the "Hip Owls" book, because of the picture on its -cover.) You might also read the manuals to *Note (gawk)Top::, *Note -(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note -(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of -regular expressions. - - The XEmacs regular expression syntax most closely resembles that of -`ed', or `grep', the GNU versions of which all utilize the GNU `regex' -library. XEmacs' version of `regex' has recently been extended with -some Perl-like capabilities, described in the next section. - -* Menu: - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. - - -File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions - -Syntax of Regular Expressions ------------------------------ - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are "ordinary". An ordinary character -is a simple regular expression that matches that character and nothing -else. The special characters are `.', `*', `+', `?', `[', `]', `^', -`$', and `\'; no new special characters will be defined in the future. -Any other character appearing in a regular expression is ordinary, -unless a `\' precedes it. - - For example, `f' is not a special character, so it is ordinary, and -therefore `f' is a regular expression that matches the string `f' and -no other string. (It does _not_ match the string `ff'.) Likewise, `o' -is a regular expression that matches only `o'. - - Any two regular expressions A and B can be concatenated. The result -is a regular expression that matches a string if A matches some amount -of the beginning of that string and B matches the rest of the string. - - As a simple example, we can concatenate the regular expressions `f' -and `o' to get the regular expression `fo', which matches only the -string `fo'. Still trivial. To do something more powerful, you need -to use one of the special characters. Here is a list of them: - -`. (Period)' - is a special character that matches any single character except a - newline. Using concatenation, we can make regular expressions - like `a.b', which matches any three-character string that begins - with `a' and ends with `b'. - -`*' - is not a construct by itself; it is a quantifying suffix operator - that means to repeat the preceding regular expression as many - times as possible. In `fo*', the `*' applies to the `o', so `fo*' - matches one `f' followed by any number of `o's. The case of zero - `o's is allowed: `fo*' does match `f'. - - `*' always applies to the _smallest_ possible preceding - expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. - - The matcher processes a `*' construct by matching, immediately, as - many repetitions as can be found; it is "greedy". Then it - continues with the rest of the pattern. If that fails, - backtracking occurs, discarding some of the matches of the - `*'-modified construct in case that makes it possible to match the - rest of the pattern. For example, in matching `ca*ar' against the - string `caaar', the `a*' first tries to match all three `a's; but - the rest of the pattern is `ar' and there is only `r' left to - match, so this try fails. The next alternative is for `a*' to - match only two `a's. With this choice, the rest of the regexp - matches successfully. - - Nested repetition operators can be extremely slow if they specify - backtracking loops. For example, it could take hours for the - regular expression `\(x+y*\)*a' to match the sequence - `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because - Emacs must try each imaginable way of grouping the 35 `x''s before - concluding that none of them can work. To make sure your regular - expressions run fast, check nested repetitions carefully. - -`+' - is a quantifying suffix operator similar to `*' except that the - preceding expression must match at least once. It is also - "greedy". So, for example, `ca+r' matches the strings `car' and - `caaaar' but not the string `cr', whereas `ca*r' matches all three - strings. - -`?' - is a quantifying suffix operator similar to `*', except that the - preceding expression can match either once or not at all. For - example, `ca?r' matches `car' or `cr', but does not match anything - else. - -`*?' - works just like `*', except that rather than matching the longest - match, it matches the shortest match. `*?' is known as a - "non-greedy" quantifier, a regexp construct borrowed from Perl. - - This construct is very useful for when you want to match the text - inside a pair of delimiters. For instance, `/\*.*?\*/' will match - C comments in a string. This could not easily be achieved without - the use of a non-greedy quantifier. - - This construct has not been available prior to XEmacs 20.4. It is - not available in FSF Emacs. - -`+?' - is the non-greedy version of `+'. - -`??' - is the non-greedy version of `?'. - -`\{n,m\}' - serves as an interval quantifier, analogous to `*' or `+', but - specifies that the expression must match at least N times, but no - more than M times. This syntax is supported by most Unix regexp - utilities, and has been introduced to XEmacs for the version 20.3. - - Unfortunately, the non-greedy version of this quantifier does not - exist currently, although it does in Perl. - -`[ ... ]' - `[' begins a "character set", which is terminated by a `]'. In - the simplest case, the characters between the two brackets form - the set. Thus, `[ad]' matches either one `a' or one `d', and - `[ad]*' matches any string composed of just `a's and `d's - (including the empty string), from which it follows that `c[ad]*r' - matches `cr', `car', `cdr', `caddaar', etc. - - The usual regular expression special characters are not special - inside a character set. A completely different set of special - characters exists inside character sets: `]', `-' and `^'. - - `-' is used for ranges of characters. To write a range, write two - characters with a `-' between them. Thus, `[a-z]' matches any - lower case letter. Ranges may be intermixed freely with individual - characters, as in `[a-z$%.]', which matches any lower case letter - or `$', `%', or a period. - - To include a `]' in a character set, make it the first character. - For example, `[]a]' matches `]' or `a'. To include a `-', write - `-' as the first character in the set, or put it immediately after - a range. (You can replace one individual character C with the - range `C-C' to make a place to put the `-'.) There is no way to - write a set containing just `-' and `]'. - - To include `^' in a set, put it anywhere but at the beginning of - the set. - -`[^ ... ]' - `[^' begins a "complement character set", which matches any - character except the ones specified. Thus, `[^a-z0-9A-Z]' matches - all characters _except_ letters and digits. - - `^' is not special in a character set unless it is the first - character. The character following the `^' is treated as if it - were first (thus, `-' and `]' are not special there). - - Note that a complement character set can match a newline, unless - newline is mentioned as one of the characters not to match. - -`^' - is a special character that matches the empty string, but only at - the beginning of a line in the text being matched. Otherwise it - fails to match anything. Thus, `^foo' matches a `foo' that occurs - at the beginning of a line. - - When matching a string instead of a buffer, `^' matches at the - beginning of the string or after a newline character `\n'. - -`$' - is similar to `^' but matches only at the end of a line. Thus, - `x+$' matches a string of one `x' or more at the end of a line. - - When matching a string instead of a buffer, `$' matches at the end - of the string or before a newline character `\n'. - -`\' - has two functions: it quotes the special characters (including - `\'), and it introduces additional special constructs. - - Because `\' quotes special characters, `\$' is a regular - expression that matches only `$', and `\[' is a regular expression - that matches only `[', and so on. - - Note that `\' also has special meaning in the read syntax of Lisp - strings (*note String Type::), and must be quoted with `\'. For - example, the regular expression that matches the `\' character is - `\\'. To write a Lisp string that contains the characters `\\', - Lisp syntax requires you to quote each `\' with another `\'. - Therefore, the read syntax for a regular expression matching `\' - is `"\\\\"'. - - *Please note:* For historical compatibility, special characters are -treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, `*foo' treats `*' as ordinary -since there is no preceding expression on which the `*' can act. It is -poor practice to depend on this behavior; quote the special character -anyway, regardless of where it appears. - - For the most part, `\' followed by any character matches only that -character. However, there are several exceptions: characters that, -when preceded by `\', are special constructs. Such characters are -always ordinary when encountered on their own. Here is a table of `\' -constructs: - -`\|' - specifies an alternative. Two regular expressions A and B with - `\|' in between form an expression that matches anything that - either A or B matches. - - Thus, `foo\|bar' matches either `foo' or `bar' but no other string. - - `\|' applies to the largest possible surrounding expressions. - Only a surrounding `\( ... \)' grouping can limit the grouping - power of `\|'. - - Full backtracking capability exists to handle multiple uses of - `\|'. - -`\( ... \)' - is a grouping construct that serves three purposes: - - 1. To enclose a set of `\|' alternatives for other operations. - Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. - - 2. To enclose an expression for a suffix operator such as `*' to - act on. Thus, `ba\(na\)*' matches `bananana', etc., with any - (zero or more) number of `na' strings. - - 3. To record a matched substring for future reference. - - This last application is not a consequence of the idea of a - parenthetical grouping; it is a separate feature that happens to be - assigned as a second meaning to the same `\( ... \)' construct - because there is no conflict in practice between the two meanings. - Here is an explanation of this feature: - -`\DIGIT' - matches the same text that matched the DIGITth occurrence of a `\( - ... \)' construct. - - In other words, after the end of a `\( ... \)' construct. the - matcher remembers the beginning and end of the text matched by that - construct. Then, later on in the regular expression, you can use - `\' followed by DIGIT to match that same text, whatever it may - have been. - - The strings matching the first nine `\( ... \)' constructs - appearing in a regular expression are assigned numbers 1 through 9 - in the order that the open parentheses appear in the regular - expression. So you can use `\1' through `\9' to refer to the text - matched by the corresponding `\( ... \)' constructs. - - For example, `\(.*\)\1' matches any newline-free string that is - composed of two identical halves. The `\(.*\)' matches the first - half, which may be anything, but the `\1' that follows must match - the same exact text. - -`\(?: ... \)' - is called a "shy" grouping operator, and it is used just like `\( - ... \)', except that it does not cause the matched substring to be - recorded for future reference. - - This is useful when you need a lot of grouping `\( ... \)' - constructs, but only want to remember one or two - or if you have - more than nine groupings and need to use backreferences to refer to - the groupings at the end. - - Using `\(?: ... \)' rather than `\( ... \)' when you don't need - the captured substrings ought to speed up your programs some, - since it shortens the code path followed by the regular expression - engine, as well as the amount of memory allocation and string - copying it must do. The actual performance gain to be observed - has not been measured or quantified as of this writing. - - The shy grouping operator has been borrowed from Perl, and has not - been available prior to XEmacs 20.3, nor is it available in FSF - Emacs. - -`\w' - matches any word-constituent character. The editor syntax table - determines which characters these are. *Note Syntax Tables::. - -`\W' - matches any character that is not a word constituent. - -`\sCODE' - matches any character whose syntax is CODE. Here CODE is a - character that represents a syntax code: thus, `w' for word - constituent, `-' for whitespace, `(' for open parenthesis, etc. - *Note Syntax Tables::, for a list of syntax codes and the - characters that stand for them. - -`\SCODE' - matches any character whose syntax is not CODE. - - The following regular expression constructs match the empty -string--that is, they don't use up any characters--but whether they -match depends on the context. - -`\`' - matches the empty string, but only at the beginning of the buffer - or string being matched against. - -`\'' - matches the empty string, but only at the end of the buffer or - string being matched against. - -`\=' - matches the empty string, but only at point. (This construct is - not defined when matching against a string.) - -`\b' - matches the empty string, but only at the beginning or end of a - word. Thus, `\bfoo\b' matches any occurrence of `foo' as a - separate word. `\bballs?\b' matches `ball' or `balls' as a - separate word. - -`\B' - matches the empty string, but _not_ at the beginning or end of a - word. - -`\<' - matches the empty string, but only at the beginning of a word. - -`\>' - matches the empty string, but only at the end of a word. - - Not every string is a valid regular expression. For example, a -string with unbalanced square brackets is invalid (with a few -exceptions, such as `[]]'), and so is a string that ends with a single -`\'. If an invalid regular expression is passed to any of the search -functions, an `invalid-regexp' error is signaled. - - - Function: regexp-quote string - This function returns a regular expression string that matches - exactly STRING and nothing else. This allows you to request an - exact string match when calling a function that wants a regular - expression. - - (regexp-quote "^The cat$") - => "\\^The cat\\$" - - One use of `regexp-quote' is to combine an exact string match with - context described as a regular expression. For example, this - searches for the string that is the value of `string', surrounded - by whitespace: - - (re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) - diff --git a/info/lispref.info-32 b/info/lispref.info-32 index fd9588b..2153849 100644 --- a/info/lispref.info-32 +++ b/info/lispref.info-32 @@ -50,6 +50,679 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Change Hooks, Next: Transformations, Prev: Transposition, Up: Text + +Change Hooks +============ + + These hook variables let you arrange to take notice of all changes in +all buffers (or in a particular buffer, if you make them buffer-local). + + The functions you use in these hooks should save and restore the +match data if they do anything that uses regular expressions; +otherwise, they will interfere in bizarre ways with the editing +operations that call them. + + Buffer changes made while executing the following hooks don't +themselves cause any change hooks to be invoked. + + - Variable: before-change-functions + This variable holds a list of a functions to call before any buffer + modification. Each function gets two arguments, the beginning and + end of the region that is about to change, represented as + integers. The buffer that is about to change is always the + current buffer. + + - Variable: after-change-functions + This variable holds a list of a functions to call after any buffer + modification. Each function receives three arguments: the + beginning and end of the region just changed, and the length of + the text that existed before the change. (To get the current + length, subtract the region beginning from the region end.) All + three arguments are integers. The buffer that's about to change + is always the current buffer. + + - Variable: before-change-function + This obsolete variable holds one function to call before any buffer + modification (or `nil' for no function). It is called just like + the functions in `before-change-functions'. + + - Variable: after-change-function + This obsolete variable holds one function to call after any buffer + modification (or `nil' for no function). It is called just like + the functions in `after-change-functions'. + + - Variable: first-change-hook + This variable is a normal hook that is run whenever a buffer is + changed that was previously in the unmodified state. + + +File: lispref.info, Node: Transformations, Prev: Change Hooks, Up: Text + +Textual transformations--MD5 and base64 support +=============================================== + + Some textual operations inherently require examining each character +in turn, and performing arithmetic operations on them. Such operations +can, of course, be implemented in Emacs Lisp, but tend to be very slow +for large portions of text or data. This is why some of them are +implemented in C, with an appropriate interface for Lisp programmers. +Examples of algorithms thus provided are MD5 and base64 support. + + MD5 is an algorithm for calculating message digests, as described in +rfc1321. Given a message of arbitrary length, MD5 produces an 128-bit +"fingerprint" ("message digest") corresponding to that message. It is +considered computationally infeasible to produce two messages having +the same MD5 digest, or to produce a message having a prespecified +target digest. MD5 is used heavily by various authentication schemes. + + Emacs Lisp interface to MD5 consists of a single function `md5': + + - Function: md5 object &optional start end coding noerror + This function returns the MD5 message digest of OBJECT, a buffer + or string. + + Optional arguments START and END denote positions for computing + the digest of a portion of OBJECT. + + The optional CODING argument specifies the coding system the text + is to be represented in while computing the digest. If + unspecified, it defaults to the current format of the data, or is + guessed. + + If NOERROR is non-`nil', silently assume binary coding if the + guesswork fails. Normally, an error is signaled in such case. + + CODING and NOERROR arguments are meaningful only in XEmacsen with + file-coding or Mule support. Otherwise, they are ignored. Some + examples of usage: + + ;; Calculate the digest of the entire buffer + (md5 (current-buffer)) + => "8842b04362899b1cda8d2d126dc11712" + + ;; Calculate the digest of the current line + (md5 (current-buffer) (point-at-bol) (point-at-eol)) + => "60614d21e9dee27dfdb01fa4e30d6d00" + + ;; Calculate the digest of your name and email address + (md5 (concat (format "%s <%s>" (user-full-name) user-mail-address))) + => "0a2188c40fd38922d941fe6032fce516" + + Base64 is a portable encoding for arbitrary sequences of octets, in a +form that need not be readable by humans. It uses a 65-character subset +of US-ASCII, as described in rfc2045. Base64 is used by MIME to encode +binary bodies, and to encode binary characters in message headers. + + The Lisp interface to base64 consists of four functions: + + - Command: base64-encode-region start end &optional no-line-break + This function encodes the region between START and END of the + current buffer to base64 format. This means that the original + region is deleted, and replaced with its base64 equivalent. + + Normally, encoded base64 output is multi-line, with 76-character + lines. If NO-LINE-BREAK is non-`nil', newlines will not be + inserted, resulting in single-line output. + + Mule note: you should make sure that you convert the multibyte + characters (those that do not fit into 0-255 range) to something + else, because they cannot be meaningfully converted to base64. If + the `base64-encode-region' encounters such characters, it will + signal an error. + + `base64-encode-region' returns the length of the encoded text. + + ;; Encode the whole buffer in base64 + (base64-encode-region (point-min) (point-max)) + + The function can also be used interactively, in which case it + works on the currently active region. + + - Function: base64-encode-string string &optional no-line-break + This function encodes STRING to base64, and returns the encoded + string. + + Normally, encoded base64 output is multi-line, with 76-character + lines. If NO-LINE-BREAK is non-`nil', newlines will not be + inserted, resulting in single-line output. + + For Mule, the same considerations apply as for + `base64-encode-region'. + + (base64-encode-string "fubar") + => "ZnViYXI=" + + - Command: base64-decode-region start end + This function decodes the region between START and END of the + current buffer. The region should be in base64 encoding. + + If the region was decoded correctly, `base64-decode-region' returns + the length of the decoded region. If the decoding failed, `nil' is + returned. + + ;; Decode a base64 buffer, and replace it with the decoded version + (base64-decode-region (point-min) (point-max)) + + - Function: base64-decode-string string + This function decodes STRING to base64, and returns the decoded + string. STRING should be valid base64-encoded text. + + If encoding was not possible, `nil' is returned. + + (base64-decode-string "ZnViYXI=") + => "fubar" + + (base64-decode-string "totally bogus") + => nil + + +File: lispref.info, Node: Searching and Matching, Next: Syntax Tables, Prev: Text, Up: Top + +Searching and Matching +********************** + + XEmacs provides two ways to search through a buffer for specified +text: exact string searches and regular expression searches. After a +regular expression search, you can examine the "match data" to +determine which text matched the whole regular expression or various +portions of it. + +* Menu: + +* String Search:: Search for an exact match. +* Regular Expressions:: Describing classes of strings. +* Regexp Search:: Searching for a match for a regexp. +* POSIX Regexps:: Searching POSIX-style for the longest match. +* Search and Replace:: Internals of `query-replace'. +* Match Data:: Finding out which part of the text matched + various parts of a regexp, after regexp search. +* Searching and Case:: Case-independent or case-significant searching. +* Standard Regexps:: Useful regexps for finding sentences, pages,... + + The `skip-chars...' functions also perform a kind of searching. +*Note Skipping Characters::. + + +File: lispref.info, Node: String Search, Next: Regular Expressions, Up: Searching and Matching + +Searching for Strings +===================== + + These are the primitive functions for searching through the text in a +buffer. They are meant for use in programs, but you may call them +interactively. If you do so, they prompt for the search string; LIMIT +and NOERROR are set to `nil', and COUNT is set to 1. + + - Command: search-forward string &optional limit noerror count buffer + This function searches forward from point for an exact match for + STRING. If successful, it sets point to the end of the occurrence + found, and returns the new value of point. If no match is found, + the value and side effects depend on NOERROR (see below). + + In the following example, point is initially at the beginning of + the line. Then `(search-forward "fox")' moves point after the last + letter of `fox': + + ---------- Buffer: foo ---------- + -!-The quick brown fox jumped over the lazy dog. + ---------- Buffer: foo ---------- + + (search-forward "fox") + => 20 + + ---------- Buffer: foo ---------- + The quick brown fox-!- jumped over the lazy dog. + ---------- Buffer: foo ---------- + + The argument LIMIT specifies the upper bound to the search. (It + must be a position in the current buffer.) No match extending + after that position is accepted. If LIMIT is omitted or `nil', it + defaults to the end of the accessible portion of the buffer. + + 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', `search-forward' returns `nil' and + does nothing. If NOERROR is neither `nil' nor `t', then + `search-forward' moves point to the upper bound and returns `nil'. + (It would be more consistent now to return the new position of + point in that case, but some programs may depend on a value of + `nil'.) + + If COUNT is supplied (it must be an integer), then the search is + repeated that many times (each time starting at the end of the + previous time's match). If COUNT is negative, the search + direction is backward. If the successive searches succeed, the + function succeeds, moving point and returning its new value. + Otherwise the search fails. + + BUFFER is the buffer to search in, and defaults to the current + buffer. + + - Command: search-backward string &optional limit noerror count buffer + This function searches backward from point for STRING. It is just + like `search-forward' except that it searches backwards and leaves + point at the beginning of the match. + + - Command: word-search-forward string &optional limit noerror count + buffer + This function searches forward from point for a "word" match for + STRING. If it finds a match, it sets point to the end of the + match found, and returns the new value of point. + + Word matching regards STRING as a sequence of words, disregarding + punctuation that separates them. It searches the buffer for the + same sequence of words. Each word must be distinct in the buffer + (searching for the word `ball' does not match the word `balls'), + but the details of punctuation and spacing are ignored (searching + for `ball boy' does match `ball. Boy!'). + + In this example, point is initially at the beginning of the + buffer; the search leaves it between the `y' and the `!'. + + ---------- Buffer: foo ---------- + -!-He said "Please! Find + the ball boy!" + ---------- Buffer: foo ---------- + + (word-search-forward "Please find the ball, boy.") + => 35 + + ---------- Buffer: foo ---------- + He said "Please! Find + the ball boy-!-!" + ---------- Buffer: foo ---------- + + If LIMIT is non-`nil' (it must be a position in the current + buffer), then it is the upper bound to the search. The match + found must not extend after that position. + + If NOERROR is `nil', then `word-search-forward' signals an error + if the search fails. If NOERROR is `t', then it returns `nil' + instead of signaling an error. If NOERROR is neither `nil' nor + `t', it moves point to LIMIT (or the end of the buffer) and + returns `nil'. + + If COUNT is non-`nil', then the search is repeated that many + times. Point is positioned at the end of the last match. + + BUFFER is the buffer to search in, and defaults to the current + buffer. + + - Command: word-search-backward string &optional limit noerror count + buffer + This function searches backward from point for a word match to + STRING. This function is just like `word-search-forward' except + that it searches backward and normally leaves point at the + beginning of the match. + + +File: lispref.info, Node: Regular Expressions, Next: Regexp Search, Prev: String Search, Up: Searching and Matching + +Regular Expressions +=================== + + A "regular expression" ("regexp", for short) is a pattern that +denotes a (possibly infinite) set of strings. Searching for matches for +a regexp is a very powerful operation. This section explains how to +write regexps; the following section says how to search for them. + + To gain a thorough understanding of regular expressions and how to +use them to best advantage, we recommend that you study `Mastering +Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, +1997'. (It's known as the "Hip Owls" book, because of the picture on its +cover.) You might also read the manuals to *Note (gawk)Top::, *Note +(ed)Top::, `sed', `grep', *Note (perl)Top::, *Note (regex)Top::, *Note +(rx)Top::, `pcre', and *Note (flex)Top::, which also make good use of +regular expressions. + + The XEmacs regular expression syntax most closely resembles that of +`ed', or `grep', the GNU versions of which all utilize the GNU `regex' +library. XEmacs' version of `regex' has recently been extended with +some Perl-like capabilities, described in the next section. + +* Menu: + +* Syntax of Regexps:: Rules for writing regular expressions. +* Regexp Example:: Illustrates regular expression syntax. + + +File: lispref.info, Node: Syntax of Regexps, Next: Regexp Example, Up: Regular Expressions + +Syntax of Regular Expressions +----------------------------- + + Regular expressions have a syntax in which a few characters are +special constructs and the rest are "ordinary". An ordinary character +is a simple regular expression that matches that character and nothing +else. The special characters are `.', `*', `+', `?', `[', `]', `^', +`$', and `\'; no new special characters will be defined in the future. +Any other character appearing in a regular expression is ordinary, +unless a `\' precedes it. + + For example, `f' is not a special character, so it is ordinary, and +therefore `f' is a regular expression that matches the string `f' and +no other string. (It does _not_ match the string `ff'.) Likewise, `o' +is a regular expression that matches only `o'. + + Any two regular expressions A and B can be concatenated. The result +is a regular expression that matches a string if A matches some amount +of the beginning of that string and B matches the rest of the string. + + As a simple example, we can concatenate the regular expressions `f' +and `o' to get the regular expression `fo', which matches only the +string `fo'. Still trivial. To do something more powerful, you need +to use one of the special characters. Here is a list of them: + +`. (Period)' + is a special character that matches any single character except a + newline. Using concatenation, we can make regular expressions + like `a.b', which matches any three-character string that begins + with `a' and ends with `b'. + +`*' + is not a construct by itself; it is a quantifying suffix operator + that means to repeat the preceding regular expression as many + times as possible. In `fo*', the `*' applies to the `o', so `fo*' + matches one `f' followed by any number of `o's. The case of zero + `o's is allowed: `fo*' does match `f'. + + `*' always applies to the _smallest_ possible preceding + expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. + + The matcher processes a `*' construct by matching, immediately, as + many repetitions as can be found; it is "greedy". Then it + continues with the rest of the pattern. If that fails, + backtracking occurs, discarding some of the matches of the + `*'-modified construct in case that makes it possible to match the + rest of the pattern. For example, in matching `ca*ar' against the + string `caaar', the `a*' first tries to match all three `a's; but + the rest of the pattern is `ar' and there is only `r' left to + match, so this try fails. The next alternative is for `a*' to + match only two `a's. With this choice, the rest of the regexp + matches successfully. + + Nested repetition operators can be extremely slow if they specify + backtracking loops. For example, it could take hours for the + regular expression `\(x+y*\)*a' to match the sequence + `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because + Emacs must try each imaginable way of grouping the 35 `x''s before + concluding that none of them can work. To make sure your regular + expressions run fast, check nested repetitions carefully. + +`+' + is a quantifying suffix operator similar to `*' except that the + preceding expression must match at least once. It is also + "greedy". So, for example, `ca+r' matches the strings `car' and + `caaaar' but not the string `cr', whereas `ca*r' matches all three + strings. + +`?' + is a quantifying suffix operator similar to `*', except that the + preceding expression can match either once or not at all. For + example, `ca?r' matches `car' or `cr', but does not match anything + else. + +`*?' + works just like `*', except that rather than matching the longest + match, it matches the shortest match. `*?' is known as a + "non-greedy" quantifier, a regexp construct borrowed from Perl. + + This construct is very useful for when you want to match the text + inside a pair of delimiters. For instance, `/\*.*?\*/' will match + C comments in a string. This could not easily be achieved without + the use of a non-greedy quantifier. + + This construct has not been available prior to XEmacs 20.4. It is + not available in FSF Emacs. + +`+?' + is the non-greedy version of `+'. + +`??' + is the non-greedy version of `?'. + +`\{n,m\}' + serves as an interval quantifier, analogous to `*' or `+', but + specifies that the expression must match at least N times, but no + more than M times. This syntax is supported by most Unix regexp + utilities, and has been introduced to XEmacs for the version 20.3. + + Unfortunately, the non-greedy version of this quantifier does not + exist currently, although it does in Perl. + +`[ ... ]' + `[' begins a "character set", which is terminated by a `]'. In + the simplest case, the characters between the two brackets form + the set. Thus, `[ad]' matches either one `a' or one `d', and + `[ad]*' matches any string composed of just `a's and `d's + (including the empty string), from which it follows that `c[ad]*r' + matches `cr', `car', `cdr', `caddaar', etc. + + The usual regular expression special characters are not special + inside a character set. A completely different set of special + characters exists inside character sets: `]', `-' and `^'. + + `-' is used for ranges of characters. To write a range, write two + characters with a `-' between them. Thus, `[a-z]' matches any + lower case letter. Ranges may be intermixed freely with individual + characters, as in `[a-z$%.]', which matches any lower case letter + or `$', `%', or a period. + + To include a `]' in a character set, make it the first character. + For example, `[]a]' matches `]' or `a'. To include a `-', write + `-' as the first character in the set, or put it immediately after + a range. (You can replace one individual character C with the + range `C-C' to make a place to put the `-'.) There is no way to + write a set containing just `-' and `]'. + + To include `^' in a set, put it anywhere but at the beginning of + the set. + +`[^ ... ]' + `[^' begins a "complement character set", which matches any + character except the ones specified. Thus, `[^a-z0-9A-Z]' matches + all characters _except_ letters and digits. + + `^' is not special in a character set unless it is the first + character. The character following the `^' is treated as if it + were first (thus, `-' and `]' are not special there). + + Note that a complement character set can match a newline, unless + newline is mentioned as one of the characters not to match. + +`^' + is a special character that matches the empty string, but only at + the beginning of a line in the text being matched. Otherwise it + fails to match anything. Thus, `^foo' matches a `foo' that occurs + at the beginning of a line. + + When matching a string instead of a buffer, `^' matches at the + beginning of the string or after a newline character `\n'. + +`$' + is similar to `^' but matches only at the end of a line. Thus, + `x+$' matches a string of one `x' or more at the end of a line. + + When matching a string instead of a buffer, `$' matches at the end + of the string or before a newline character `\n'. + +`\' + has two functions: it quotes the special characters (including + `\'), and it introduces additional special constructs. + + Because `\' quotes special characters, `\$' is a regular + expression that matches only `$', and `\[' is a regular expression + that matches only `[', and so on. + + Note that `\' also has special meaning in the read syntax of Lisp + strings (*note String Type::), and must be quoted with `\'. For + example, the regular expression that matches the `\' character is + `\\'. To write a Lisp string that contains the characters `\\', + Lisp syntax requires you to quote each `\' with another `\'. + Therefore, the read syntax for a regular expression matching `\' + is `"\\\\"'. + + *Please note:* For historical compatibility, special characters are +treated as ordinary ones if they are in contexts where their special +meanings make no sense. For example, `*foo' treats `*' as ordinary +since there is no preceding expression on which the `*' can act. It is +poor practice to depend on this behavior; quote the special character +anyway, regardless of where it appears. + + For the most part, `\' followed by any character matches only that +character. However, there are several exceptions: characters that, +when preceded by `\', are special constructs. Such characters are +always ordinary when encountered on their own. Here is a table of `\' +constructs: + +`\|' + specifies an alternative. Two regular expressions A and B with + `\|' in between form an expression that matches anything that + either A or B matches. + + Thus, `foo\|bar' matches either `foo' or `bar' but no other string. + + `\|' applies to the largest possible surrounding expressions. + Only a surrounding `\( ... \)' grouping can limit the grouping + power of `\|'. + + Full backtracking capability exists to handle multiple uses of + `\|'. + +`\( ... \)' + is a grouping construct that serves three purposes: + + 1. To enclose a set of `\|' alternatives for other operations. + Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. + + 2. To enclose an expression for a suffix operator such as `*' to + act on. Thus, `ba\(na\)*' matches `bananana', etc., with any + (zero or more) number of `na' strings. + + 3. To record a matched substring for future reference. + + This last application is not a consequence of the idea of a + parenthetical grouping; it is a separate feature that happens to be + assigned as a second meaning to the same `\( ... \)' construct + because there is no conflict in practice between the two meanings. + Here is an explanation of this feature: + +`\DIGIT' + matches the same text that matched the DIGITth occurrence of a `\( + ... \)' construct. + + In other words, after the end of a `\( ... \)' construct. the + matcher remembers the beginning and end of the text matched by that + construct. Then, later on in the regular expression, you can use + `\' followed by DIGIT to match that same text, whatever it may + have been. + + The strings matching the first nine `\( ... \)' constructs + appearing in a regular expression are assigned numbers 1 through 9 + in the order that the open parentheses appear in the regular + expression. So you can use `\1' through `\9' to refer to the text + matched by the corresponding `\( ... \)' constructs. + + For example, `\(.*\)\1' matches any newline-free string that is + composed of two identical halves. The `\(.*\)' matches the first + half, which may be anything, but the `\1' that follows must match + the same exact text. + +`\(?: ... \)' + is called a "shy" grouping operator, and it is used just like `\( + ... \)', except that it does not cause the matched substring to be + recorded for future reference. + + This is useful when you need a lot of grouping `\( ... \)' + constructs, but only want to remember one or two - or if you have + more than nine groupings and need to use backreferences to refer to + the groupings at the end. + + Using `\(?: ... \)' rather than `\( ... \)' when you don't need + the captured substrings ought to speed up your programs some, + since it shortens the code path followed by the regular expression + engine, as well as the amount of memory allocation and string + copying it must do. The actual performance gain to be observed + has not been measured or quantified as of this writing. + + The shy grouping operator has been borrowed from Perl, and has not + been available prior to XEmacs 20.3, nor is it available in FSF + Emacs. + +`\w' + matches any word-constituent character. The editor syntax table + determines which characters these are. *Note Syntax Tables::. + +`\W' + matches any character that is not a word constituent. + +`\sCODE' + matches any character whose syntax is CODE. Here CODE is a + character that represents a syntax code: thus, `w' for word + constituent, `-' for whitespace, `(' for open parenthesis, etc. + *Note Syntax Tables::, for a list of syntax codes and the + characters that stand for them. + +`\SCODE' + matches any character whose syntax is not CODE. + + The following regular expression constructs match the empty +string--that is, they don't use up any characters--but whether they +match depends on the context. + +`\`' + matches the empty string, but only at the beginning of the buffer + or string being matched against. + +`\'' + matches the empty string, but only at the end of the buffer or + string being matched against. + +`\=' + matches the empty string, but only at point. (This construct is + not defined when matching against a string.) + +`\b' + matches the empty string, but only at the beginning or end of a + word. Thus, `\bfoo\b' matches any occurrence of `foo' as a + separate word. `\bballs?\b' matches `ball' or `balls' as a + separate word. + +`\B' + matches the empty string, but _not_ at the beginning or end of a + word. + +`\<' + matches the empty string, but only at the beginning of a word. + +`\>' + matches the empty string, but only at the end of a word. + + Not every string is a valid regular expression. For example, a +string with unbalanced square brackets is invalid (with a few +exceptions, such as `[]]'), and so is a string that ends with a single +`\'. If an invalid regular expression is passed to any of the search +functions, an `invalid-regexp' error is signaled. + + - Function: regexp-quote string + This function returns a regular expression string that matches + exactly STRING and nothing else. This allows you to request an + exact string match when calling a function that wants a regular + expression. + + (regexp-quote "^The cat$") + => "\\^The cat\\$" + + One use of `regexp-quote' is to combine an exact string match with + context described as a regular expression. For example, this + searches for the string that is the value of `string', surrounded + by whitespace: + + (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 @@ -117,7 +790,8 @@ incrementally or not. Incremental search commands are described in the (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 + - Command: re-search-forward regexp &optional limit noerror count + buffer 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 @@ -135,7 +809,7 @@ useful in programs. The principal one is `re-search-forward'. `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 + If COUNT 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 @@ -158,7 +832,8 @@ useful in programs. The principal one is `re-search-forward'. comes back" twice. ---------- Buffer: foo ---------- - - Command: re-search-backward regexp &optional limit noerror repeat + - Command: re-search-backward regexp &optional limit noerror count + buffer 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. @@ -177,12 +852,16 @@ useful in programs. The principal one is `re-search-forward'. feature for matching regexps from end to beginning. It's not worth the trouble of implementing that. - - Function: string-match regexp string &optional start + - Function: string-match regexp string &optional start buffer 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. + Optional arg BUFFER controls how case folding is done (according + to the value of `case-fold-search' in BUFFER and BUFFER's case + tables) and defaults to the current buffer. + For example, (string-match @@ -230,7 +909,7 @@ useful in programs. The principal one is `re-search-forward'. `path-separator'. Under Unix, `path-separator' will normally be `:', while under Windows, it will be `;'. - - Function: looking-at regexp + - Function: looking-at regexp &optional buffer 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 @@ -274,26 +953,32 @@ 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 + - Command: posix-search-forward regexp &optional limit noerror count + buffer 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 + - Command: posix-search-backward regexp &optional limit noerror count + buffer 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 + - Function: posix-looking-at regexp &optional buffer 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 + - Function: posix-string-match regexp string &optional start buffer This is like `string-match' except that it performs the full backtracking specified by the POSIX standard for regular expression matching. + Optional arg BUFFER controls how case folding is done (according + to the value of `case-fold-search' in BUFFER and BUFFER's case + tables) and defaults to the current buffer. +  File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching @@ -512,696 +1197,3 @@ subexpression is at the 13th character (`c'). (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 -------------------------------- - - The functions `match-data' and `set-match-data' read or write the -entire match data, all at once. - - - Function: match-data - This function returns a newly constructed list containing all the - information on what text the last search matched. Element zero is - the position of the beginning of the match for the whole - expression; element one is the position of the end of the match - for the expression. The next two elements are the positions of - the beginning and end of the match for the first subexpression, - and so on. In general, element number 2N corresponds to - `(match-beginning N)'; and element number 2N + 1 corresponds to - `(match-end N)'. - - All the elements are markers or `nil' if matching was done on a - buffer, and all are integers or `nil' if matching was done on a - string with `string-match'. (In Emacs 18 and earlier versions, - markers were used even for matching on a string, except in the case - of the integer 0.) - - As always, there must be no possibility of intervening searches - between the call to a search function and the call to `match-data' - that is intended to access the match data for that search. - - (match-data) - => (# - # - # - #) - - - Function: set-match-data match-list - This function sets the match data from the elements of MATCH-LIST, - which should be a list that was the value of a previous call to - `match-data'. - - If MATCH-LIST refers to a buffer that doesn't exist, you don't get - an error; that sets the match data in a meaningless but harmless - way. - - `store-match-data' is an alias for `set-match-data'. - - -File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data - -Saving and Restoring the Match Data ------------------------------------ - - When you call a function that may do a search, you may need to save -and restore the match data around that call, if you want to preserve the -match data from an earlier search for later use. Here is an example -that shows the problem that arises if you fail to save the match data: - - (re-search-forward "The \\(cat \\)") - => 48 - (foo) ; Perhaps `foo' does - ; more searching. - (match-end 0) - => 61 ; Unexpected result--not 48! - - You can save and restore the match data with `save-match-data': - - - Macro: save-match-data body... - This special form executes BODY, saving and restoring the match - data around it. - - You can use `set-match-data' together with `match-data' to imitate -the effect of the special form `save-match-data'. This is useful for -writing code that can run in Emacs 18. Here is how: - - (let ((data (match-data))) - (unwind-protect - ... ; May change the original match data. - (set-match-data data))) - - Emacs automatically saves and restores the match data when it runs -process filter functions (*note Filter Functions::) and process -sentinels (*note Sentinels::). - - -File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching - -Searching and Case -================== - - By default, searches in Emacs ignore the case of the text they are -searching through; if you specify searching for `FOO', then `Foo' or -`foo' is also considered a match. Regexps, and in particular character -sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'. - - If you do not want this feature, set the variable `case-fold-search' -to `nil'. Then all letters must match exactly, including case. This -is a buffer-local variable; altering the variable affects only the -current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you -may change the value of `default-case-fold-search', which is the -default value of `case-fold-search' for buffers that do not override it. - - Note that the user-level incremental search feature handles case -distinctions differently. When given a lower case letter, it looks for -a match of either case, but when given an upper case letter, it looks -for an upper case letter only. But this has nothing to do with the -searching functions Lisp functions use. - - - User Option: case-replace - This variable determines whether the replacement functions should - preserve case. If the variable is `nil', that means to use the - replacement text verbatim. A non-`nil' value means to convert the - case of the replacement text according to the text being replaced. - - The function `replace-match' is where this variable actually has - its effect. *Note Replacing Match::. - - - User Option: case-fold-search - This buffer-local variable determines whether searches should - ignore case. If the variable is `nil' they do not ignore case; - otherwise they do ignore case. - - - Variable: default-case-fold-search - The value of this variable is the default value for - `case-fold-search' in buffers that do not override it. This is the - same as `(default-value 'case-fold-search)'. - - -File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching - -Standard Regular Expressions Used in Editing -============================================ - - This section describes some variables that hold regular expressions -used for certain purposes in editing: - - - Variable: page-delimiter - This is the regexp describing line-beginnings that separate pages. - The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this - matches a line that starts with a formfeed character. - - The following two regular expressions should _not_ assume the match -always starts at the beginning of a line; they should not use `^' to -anchor the match. Most often, the paragraph commands do check for a -match only at the beginning of a line, which means that `^' would be -superfluous. When there is a nonzero left margin, they accept matches -that start after the left margin. In that case, a `^' would be -incorrect. However, a `^' is harmless in modes where a left margin is -never used. - - - Variable: paragraph-separate - This is the regular expression for recognizing the beginning of a - line that separates paragraphs. (If you change this, you may have - to change `paragraph-start' also.) The default value is - `"[ \t\f]*$"', which matches a line that consists entirely of - spaces, tabs, and form feeds (after its left margin). - - - Variable: paragraph-start - This is the regular expression for recognizing the beginning of a - line that starts _or_ separates paragraphs. The default value is - `"[ \t\n\f]"', which matches a line starting with a space, tab, - newline, or form feed (after its left margin). - - - Variable: sentence-end - This is the regular expression describing the end of a sentence. - (All paragraph boundaries also end sentences, regardless.) The - default value is: - - "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" - - This means a period, question mark or exclamation mark, followed - optionally by a closing parenthetical character, followed by tabs, - spaces or new lines. - - For a detailed explanation of this regular expression, see *Note - Regexp Example::. - - -File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top - -Syntax Tables -************* - - A "syntax table" specifies the syntactic textual function of each -character. This information is used by the parsing commands, the -complex movement commands, and others to determine where words, symbols, -and other syntactic constructs begin and end. The current syntax table -controls the meaning of the word motion functions (*note Word Motion::) -and the list motion functions (*note List Motion::) as well as the -functions in this chapter. - -* Menu: - -* Basics: Syntax Basics. Basic concepts of syntax tables. -* Desc: Syntax Descriptors. How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. - - -File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables - -Syntax Table Concepts -===================== - - A "syntax table" provides Emacs with the information that determines -the syntactic use of each character in a buffer. This information is -used by the parsing commands, the complex movement commands, and others -to determine where words, symbols, and other syntactic constructs begin -and end. The current syntax table controls the meaning of the word -motion functions (*note Word Motion::) and the list motion functions -(*note List Motion::) as well as the functions in this chapter. - - Under XEmacs 20, a syntax table is a particular subtype of the -primitive char table type (*note Char Tables::), and each element of the -char table is an integer that encodes the syntax of the character in -question, or a cons of such an integer and a matching character (for -characters with parenthesis syntax). - - Under XEmacs 19, a syntax table is a vector of 256 elements; it -contains one entry for each of the 256 possible characters in an 8-bit -byte. Each element is an integer that encodes the syntax of the -character in question. (The matching character, if any, is embedded in -the bits of this integer.) - - Syntax tables are used only for moving across text, not for the Emacs -Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading -Lisp expressions, and these rules cannot be changed. - - Each buffer has its own major mode, and each major mode has its own -idea of the syntactic class of various characters. For example, in Lisp -mode, the character `;' begins a comment, but in C mode, it terminates -a statement. To support these variations, XEmacs makes the choice of -syntax table local to each buffer. Typically, each major mode has its -own syntax table and installs that table in each buffer that uses that -mode. Changing this table alters the syntax in all those buffers as -well as in any buffers subsequently put in that mode. Occasionally -several similar modes share one syntax table. *Note Example Major -Modes::, for an example of how to set up a syntax table. - - A syntax table can inherit the data for some characters from the -standard syntax table, while specifying other characters itself. The -"inherit" syntax class means "inherit this character's syntax from the -standard syntax table." Most major modes' syntax tables inherit the -syntax of character codes 0 through 31 and 128 through 255. This is -useful with character sets such as ISO Latin-1 that have additional -alphabetic characters in the range 128 to 255. Just changing the -standard syntax for these characters affects all major modes. - - - Function: syntax-table-p object - This function returns `t' if OBJECT is a vector of length 256 - elements. This means that the vector may be a syntax table. - However, according to this test, any vector of length 256 is - considered to be a syntax table, no matter what its contents. - - -File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables - -Syntax Descriptors -================== - - This section describes the syntax classes and flags that denote the -syntax of a character, and how they are represented as a "syntax -descriptor", which is a Lisp string that you pass to -`modify-syntax-entry' to specify the desired syntax. - - XEmacs defines a number of "syntax classes". Each syntax table puts -each character into one class. There is no necessary relationship -between the class of a character in one syntax table and its class in -any other table. - - Each class is designated by a mnemonic character, which serves as the -name of the class when you need to specify a class. Usually the -designator character is one that is frequently in that class; however, -its meaning as a designator is unvarying and independent of what syntax -that character currently has. - - A syntax descriptor is a Lisp string that specifies a syntax class, a -matching character (used only for the parenthesis classes) and flags. -The first character is the designator for a syntax class. The second -character is the character to match; if it is unused, put a space there. -Then come the characters for any desired flags. If no matching -character or flags are needed, one character is sufficient. - - For example, the descriptor for the character `*' in C mode is -`. 23' (i.e., punctuation, matching character slot unused, second -character of a comment-starter, first character of an comment-ender), -and the entry for `/' is `. 14' (i.e., punctuation, matching character -slot unused, first character of a comment-starter, second character of -a comment-ender). - -* Menu: - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - - -File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors - -Table of Syntax Classes ------------------------ - - Here is a table of syntax classes, the characters that stand for -them, their meanings, and examples of their use. - - - Syntax class: whitespace character - "Whitespace characters" (designated with ` ' or `-') separate - symbols and words from each other. Typically, whitespace - characters have no other syntactic significance, and multiple - whitespace characters are syntactically equivalent to a single - one. Space, tab, newline and formfeed are almost always - classified as whitespace. - - - Syntax class: word constituent - "Word constituents" (designated with `w') are parts of normal - English words and are typically used in variable and command names - in programs. All upper- and lower-case letters, and the digits, - are typically word constituents. - - - Syntax class: symbol constituent - "Symbol constituents" (designated with `_') are the extra - characters that are used in variable and command names along with - word constituents. For example, the symbol constituents class is - used in Lisp mode to indicate that certain characters may be part - of symbol names even though they are not part of English words. - These characters are `$&*+-_<>'. In standard C, the only - non-word-constituent character that is valid in symbols is - underscore (`_'). - - - Syntax class: punctuation character - "Punctuation characters" (`.') are those characters that are used - as punctuation in English, or are used in some way in a programming - language to separate symbols from one another. Most programming - language modes, including Emacs Lisp mode, have no characters in - this class since the few characters that are not symbol or word - constituents all have other uses. - - - Syntax class: open parenthesis character - - Syntax class: close parenthesis character - Open and close "parenthesis characters" are characters used in - dissimilar pairs to surround sentences or expressions. Such a - grouping is begun with an open parenthesis character and - terminated with a close. Each open parenthesis character matches - a particular close parenthesis character, and vice versa. - Normally, XEmacs indicates momentarily the matching open - parenthesis when you insert a close parenthesis. *Note Blinking::. - - The class of open parentheses is designated with `(', and that of - close parentheses with `)'. - - In English text, and in C code, the parenthesis pairs are `()', - `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and - vectors (`()' and `[]') are classified as parenthesis characters. - - - Syntax class: string quote - "String quote characters" (designated with `"') are used in many - languages, including Lisp and C, to delimit string constants. The - same string quote character appears at the beginning and the end - of a string. Such quoted strings do not nest. - - The parsing facilities of XEmacs consider a string as a single - token. The usual syntactic meanings of the characters in the - string are suppressed. - - The Lisp modes have two string quote characters: double-quote (`"') - and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is - used in Common Lisp. C also has two string quote characters: - double-quote for strings, and single-quote (`'') for character - constants. - - English text has no string quote characters because English is not - a programming language. Although quotation marks are used in - English, we do not want them to turn off the usual syntactic - properties of other characters in the quotation. - - - Syntax class: escape - An "escape character" (designated with `\') starts an escape - sequence such as is used in C string and character constants. The - character `\' belongs to this class in both C and Lisp. (In C, it - is used thus only inside strings, but it turns out to cause no - trouble to treat it this way throughout C code.) - - Characters in this class count as part of words if - `words-include-escapes' is non-`nil'. *Note Word Motion::. - - - Syntax class: character quote - A "character quote character" (designated with `/') quotes the - following character so that it loses its normal syntactic meaning. - This differs from an escape character in that only the character - immediately following is ever affected. - - Characters in this class count as part of words if - `words-include-escapes' is non-`nil'. *Note Word Motion::. - - This class is used for backslash in TeX mode. - - - Syntax class: paired delimiter - "Paired delimiter characters" (designated with `$') are like - string quote characters except that the syntactic properties of the - characters between the delimiters are not suppressed. Only TeX - mode uses a paired delimiter presently--the `$' that both enters - and leaves math mode. - - - Syntax class: expression prefix - An "expression prefix operator" (designated with `'') is used for - syntactic operators that are part of an expression if they appear - next to one. These characters in Lisp include the apostrophe, `'' - (used for quoting), the comma, `,' (used in macros), and `#' (used - in the read syntax for certain data types). - - - Syntax class: comment starter - - Syntax class: comment ender - The "comment starter" and "comment ender" characters are used in - various languages to delimit comments. These classes are - designated with `<' and `>', respectively. - - English text has no comment characters. In Lisp, the semicolon - (`;') starts a comment and a newline or formfeed ends one. - - - Syntax class: inherit - This syntax class does not specify a syntax. It says to look in - the standard syntax table to find the syntax of this character. - The designator for this syntax code is `@'. - - -File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors - -Syntax Flags ------------- - - In addition to the classes, entries for characters in a syntax table -can include flags. There are six possible flags, represented by the -characters `1', `2', `3', `4', `b' and `p'. - - All the flags except `p' are used to describe multi-character -comment delimiters. The digit flags indicate that a character can -_also_ be part of a comment sequence, in addition to the syntactic -properties associated with its character class. The flags are -independent of the class and each other for the sake of characters such -as `*' in C mode, which is a punctuation character, _and_ the second -character of a start-of-comment sequence (`/*'), _and_ the first -character of an end-of-comment sequence (`*/'). - - The flags for a character C are: - - * `1' means C is the start of a two-character comment-start sequence. - - * `2' means C is the second character of such a sequence. - - * `3' means C is the start of a two-character comment-end sequence. - - * `4' means C is the second character of such a sequence. - - * `b' means that C as a comment delimiter belongs to the alternative - "b" comment style. - - Emacs supports two comment styles simultaneously in any one syntax - table. This is for the sake of C++. Each style of comment syntax - has its own comment-start sequence and its own comment-end - sequence. Each comment must stick to one style or the other; - thus, if it starts with the comment-start sequence of style "b", - it must also end with the comment-end sequence of style "b". - - The two comment-start sequences must begin with the same - character; only the second character may differ. Mark the second - character of the "b"-style comment-start sequence with the `b' - flag. - - A comment-end sequence (one or two characters) applies to the "b" - style if its first character has the `b' flag set; otherwise, it - applies to the "a" style. - - The appropriate comment syntax settings for C++ are as follows: - - `/' - `124b' - - `*' - `23' - - newline - `>b' - - This defines four comment-delimiting sequences: - - `/*' - This is a comment-start sequence for "a" style because the - second character, `*', does not have the `b' flag. - - `//' - This is a comment-start sequence for "b" style because the - second character, `/', does have the `b' flag. - - `*/' - This is a comment-end sequence for "a" style because the first - character, `*', does not have the `b' flag - - newline - This is a comment-end sequence for "b" style, because the - newline character has the `b' flag. - - * `p' identifies an additional "prefix character" for Lisp syntax. - These characters are treated as whitespace when they appear between - expressions. When they appear within an expression, they are - handled according to their usual syntax codes. - - The function `backward-prefix-chars' moves back over these - characters, as well as over characters whose primary syntax class - is prefix (`''). *Note Motion and Syntax::. - - -File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables - -Syntax Table Functions -====================== - - In this section we describe functions for creating, accessing and -altering syntax tables. - - - Function: make-syntax-table &optional table - This function creates a new syntax table. Character codes 0 - through 31 and 128 through 255 are set up to inherit from the - standard syntax table. The other character codes are set up by - copying what the standard syntax table says about them. - - Most major mode syntax tables are created in this way. - - - Function: copy-syntax-table &optional table - This function constructs a copy of TABLE and returns it. If TABLE - is not supplied (or is `nil'), it returns a copy of the current - syntax table. Otherwise, an error is signaled if TABLE is not a - syntax table. - - - Command: modify-syntax-entry char syntax-descriptor &optional table - This function sets the syntax entry for CHAR according to - SYNTAX-DESCRIPTOR. The syntax is changed only for TABLE, which - defaults to the current buffer's syntax table, and not in any - other syntax table. The argument SYNTAX-DESCRIPTOR specifies the - desired syntax; this is a string beginning with a class designator - character, and optionally containing a matching character and - flags as well. *Note Syntax Descriptors::. - - This function always returns `nil'. The old syntax information in - the table for this character is discarded. - - An error is signaled if the first character of the syntax - descriptor is not one of the twelve syntax class designator - characters. An error is also signaled if CHAR is not a character. - - Examples: - - ;; Put the space character in class whitespace. - (modify-syntax-entry ?\ " ") - => nil - - ;; Make `$' an open parenthesis character, - ;; with `^' as its matching close. - (modify-syntax-entry ?$ "(^") - => nil - - ;; Make `^' a close parenthesis character, - ;; with `$' as its matching open. - (modify-syntax-entry ?^ ")$") - => nil - - ;; Make `/' a punctuation character, - ;; the first character of a start-comment sequence, - ;; and the second character of an end-comment sequence. - ;; This is used in C mode. - (modify-syntax-entry ?/ ". 14") - => nil - - - Function: char-syntax character - This function returns the syntax class of CHARACTER, represented - by its mnemonic designator character. This _only_ returns the - class, not any matching parenthesis or flags. - - An error is signaled if CHAR is not a character. - - The following examples apply to C mode. The first example shows - that the syntax class of space is whitespace (represented by a - space). The second example shows that the syntax of `/' is - punctuation. This does not show the fact that it is also part of - comment-start and -end sequences. The third example shows that - open parenthesis is in the class of open parentheses. This does - not show the fact that it has a matching character, `)'. - - (char-to-string (char-syntax ?\ )) - => " " - - (char-to-string (char-syntax ?/)) - => "." - - (char-to-string (char-syntax ?\()) - => "(" - - - Function: set-syntax-table table &optional buffer - This function makes TABLE the syntax table for BUFFER, which - defaults to the current buffer if omitted. It returns TABLE. - - - Function: syntax-table &optional buffer - This function returns the syntax table for BUFFER, which defaults - to the current buffer if omitted. - - -File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables - -Motion and Syntax -================= - - This section describes functions for moving across characters in -certain syntax classes. None of these functions exists in Emacs -version 18 or earlier. - - - Function: skip-syntax-forward syntaxes &optional limit buffer - This function moves point forward across characters having syntax - classes mentioned in SYNTAXES. It stops when it encounters the - end of the buffer, or position LIMIT (if specified), or a - character it is not supposed to skip. Optional argument BUFFER - defaults to the current buffer if omitted. - - - Function: skip-syntax-backward syntaxes &optional limit buffer - This function moves point backward across characters whose syntax - classes are mentioned in SYNTAXES. It stops when it encounters - the beginning of the buffer, or position LIMIT (if specified), or a - character it is not supposed to skip. Optional argument BUFFER - defaults to the current buffer if omitted. - - - - Function: backward-prefix-chars &optional buffer - This function moves point backward over any number of characters - with expression prefix syntax. This includes both characters in - the expression prefix syntax class, and characters with the `p' - flag. Optional argument BUFFER defaults to the current buffer if - omitted. - diff --git a/info/lispref.info-33 b/info/lispref.info-33 index 826fca3..0124e25 100644 --- a/info/lispref.info-33 +++ b/info/lispref.info-33 @@ -50,6 +50,719 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 strbuffer + 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 the fourth argument STRING is a string, fifth argument + STRBUFFER specifies the buffer to be used for syntax-table and + case-table lookup and defaults to the current buffer. When STRING + is not a string, the buffer that the match occurred in has + automatically been remembered and you do not need to specify it. + + 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 FIXEDCASE. *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 +------------------------------- + + The functions `match-data' and `set-match-data' read or write the +entire match data, all at once. + + - Function: match-data &optional integers reuse + This function returns a newly constructed list containing all the + information on what text the last search matched. Element zero is + the position of the beginning of the match for the whole + expression; element one is the position of the end of the match + for the expression. The next two elements are the positions of + the beginning and end of the match for the first subexpression, + and so on. In general, element number 2N corresponds to + `(match-beginning N)'; and element number 2N + 1 corresponds to + `(match-end N)'. + + All the elements are markers or `nil' if matching was done on a + buffer, and all are integers or `nil' if matching was done on a + string with `string-match'. However, if the optional first + argument INTEGERS is non-`nil', always use integers (rather than + markers) to represent buffer positions. + + If the optional second argument REUSE is a list, reuse it as part + of the value. If REUSE is long enough to hold all the values, and + if INTEGERS is non-`nil', no new lisp objects are created. + + As always, there must be no possibility of intervening searches + between the call to a search function and the call to `match-data' + that is intended to access the match data for that search. + + (match-data) + => (# + # + # + #) + + - Function: set-match-data match-list + This function sets the match data from the elements of MATCH-LIST, + which should be a list that was the value of a previous call to + `match-data'. + + If MATCH-LIST refers to a buffer that doesn't exist, you don't get + an error; that sets the match data in a meaningless but harmless + way. + + `store-match-data' is an alias for `set-match-data'. + + +File: lispref.info, Node: Saving Match Data, Prev: Entire Match Data, Up: Match Data + +Saving and Restoring the Match Data +----------------------------------- + + When you call a function that may do a search, you may need to save +and restore the match data around that call, if you want to preserve the +match data from an earlier search for later use. Here is an example +that shows the problem that arises if you fail to save the match data: + + (re-search-forward "The \\(cat \\)") + => 48 + (foo) ; Perhaps `foo' does + ; more searching. + (match-end 0) + => 61 ; Unexpected result--not 48! + + You can save and restore the match data with `save-match-data': + + - Special Form: save-match-data body... + This special form executes BODY, saving and restoring the match + data around it. + + You can use `set-match-data' together with `match-data' to imitate +the effect of the special form `save-match-data'. This is useful for +writing code that can run in Emacs 18. Here is how: + + (let ((data (match-data))) + (unwind-protect + ... ; May change the original match data. + (set-match-data data))) + + Emacs automatically saves and restores the match data when it runs +process filter functions (*note Filter Functions::) and process +sentinels (*note Sentinels::). + + +File: lispref.info, Node: Searching and Case, Next: Standard Regexps, Prev: Match Data, Up: Searching and Matching + +Searching and Case +================== + + By default, searches in Emacs ignore the case of the text they are +searching through; if you specify searching for `FOO', then `Foo' or +`foo' is also considered a match. Regexps, and in particular character +sets, are included: thus, `[aB]' would match `a' or `A' or `b' or `B'. + + If you do not want this feature, set the variable `case-fold-search' +to `nil'. Then all letters must match exactly, including case. This +is a buffer-local variable; altering the variable affects only the +current buffer. (*Note Intro to Buffer-Local::.) Alternatively, you +may change the value of `default-case-fold-search', which is the +default value of `case-fold-search' for buffers that do not override it. + + Note that the user-level incremental search feature handles case +distinctions differently. When given a lower case letter, it looks for +a match of either case, but when given an upper case letter, it looks +for an upper case letter only. But this has nothing to do with the +searching functions Lisp functions use. + + - User Option: case-replace + This variable determines whether the replacement functions should + preserve case. If the variable is `nil', that means to use the + replacement text verbatim. A non-`nil' value means to convert the + case of the replacement text according to the text being replaced. + + The function `replace-match' is where this variable actually has + its effect. *Note Replacing Match::. + + - User Option: case-fold-search + This buffer-local variable determines whether searches should + ignore case. If the variable is `nil' they do not ignore case; + otherwise they do ignore case. + + - Variable: default-case-fold-search + The value of this variable is the default value for + `case-fold-search' in buffers that do not override it. This is the + same as `(default-value 'case-fold-search)'. + + +File: lispref.info, Node: Standard Regexps, Prev: Searching and Case, Up: Searching and Matching + +Standard Regular Expressions Used in Editing +============================================ + + This section describes some variables that hold regular expressions +used for certain purposes in editing: + + - Variable: page-delimiter + This is the regexp describing line-beginnings that separate pages. + The default value is `"^\014"' (i.e., `"^^L"' or `"^\C-l"'); this + matches a line that starts with a formfeed character. + + The following two regular expressions should _not_ assume the match +always starts at the beginning of a line; they should not use `^' to +anchor the match. Most often, the paragraph commands do check for a +match only at the beginning of a line, which means that `^' would be +superfluous. When there is a nonzero left margin, they accept matches +that start after the left margin. In that case, a `^' would be +incorrect. However, a `^' is harmless in modes where a left margin is +never used. + + - Variable: paragraph-separate + This is the regular expression for recognizing the beginning of a + line that separates paragraphs. (If you change this, you may have + to change `paragraph-start' also.) The default value is + `"[ \t\f]*$"', which matches a line that consists entirely of + spaces, tabs, and form feeds (after its left margin). + + - Variable: paragraph-start + This is the regular expression for recognizing the beginning of a + line that starts _or_ separates paragraphs. The default value is + `"[ \t\n\f]"', which matches a line starting with a space, tab, + newline, or form feed (after its left margin). + + - Variable: sentence-end + This is the regular expression describing the end of a sentence. + (All paragraph boundaries also end sentences, regardless.) The + default value is: + + "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" + + This means a period, question mark or exclamation mark, followed + optionally by a closing parenthetical character, followed by tabs, + spaces or new lines. + + For a detailed explanation of this regular expression, see *Note + Regexp Example::. + + +File: lispref.info, Node: Syntax Tables, Next: Abbrevs, Prev: Searching and Matching, Up: Top + +Syntax Tables +************* + + A "syntax table" specifies the syntactic textual function of each +character. This information is used by the parsing commands, the +complex movement commands, and others to determine where words, symbols, +and other syntactic constructs begin and end. The current syntax table +controls the meaning of the word motion functions (*note Word Motion::) +and the list motion functions (*note List Motion::) as well as the +functions in this chapter. + +* Menu: + +* Basics: Syntax Basics. Basic concepts of syntax tables. +* Desc: Syntax Descriptors. How characters are classified. +* Syntax Table Functions:: How to create, examine and alter syntax tables. +* Motion and Syntax:: Moving over characters with certain syntaxes. +* Parsing Expressions:: Parsing balanced expressions + using the syntax table. +* Standard Syntax Tables:: Syntax tables used by various major modes. +* Syntax Table Internals:: How syntax table information is stored. + + +File: lispref.info, Node: Syntax Basics, Next: Syntax Descriptors, Up: Syntax Tables + +Syntax Table Concepts +===================== + + A "syntax table" provides Emacs with the information that determines +the syntactic use of each character in a buffer. This information is +used by the parsing commands, the complex movement commands, and others +to determine where words, symbols, and other syntactic constructs begin +and end. The current syntax table controls the meaning of the word +motion functions (*note Word Motion::) and the list motion functions +(*note List Motion::) as well as the functions in this chapter. + + Under XEmacs 20, a syntax table is a particular subtype of the +primitive char table type (*note Char Tables::), and each element of the +char table is an integer that encodes the syntax of the character in +question, or a cons of such an integer and a matching character (for +characters with parenthesis syntax). + + Under XEmacs 19, a syntax table is a vector of 256 elements; it +contains one entry for each of the 256 possible characters in an 8-bit +byte. Each element is an integer that encodes the syntax of the +character in question. (The matching character, if any, is embedded in +the bits of this integer.) + + Syntax tables are used only for moving across text, not for the Emacs +Lisp reader. XEmacs Lisp uses built-in syntactic rules when reading +Lisp expressions, and these rules cannot be changed. + + Each buffer has its own major mode, and each major mode has its own +idea of the syntactic class of various characters. For example, in Lisp +mode, the character `;' begins a comment, but in C mode, it terminates +a statement. To support these variations, XEmacs makes the choice of +syntax table local to each buffer. Typically, each major mode has its +own syntax table and installs that table in each buffer that uses that +mode. Changing this table alters the syntax in all those buffers as +well as in any buffers subsequently put in that mode. Occasionally +several similar modes share one syntax table. *Note Example Major +Modes::, for an example of how to set up a syntax table. + + A syntax table can inherit the data for some characters from the +standard syntax table, while specifying other characters itself. The +"inherit" syntax class means "inherit this character's syntax from the +standard syntax table." Most major modes' syntax tables inherit the +syntax of character codes 0 through 31 and 128 through 255. This is +useful with character sets such as ISO Latin-1 that have additional +alphabetic characters in the range 128 to 255. Just changing the +standard syntax for these characters affects all major modes. + + - Function: syntax-table-p object + This function returns `t' if OBJECT is a vector of length 256 + elements. This means that the vector may be a syntax table. + However, according to this test, any vector of length 256 is + considered to be a syntax table, no matter what its contents. + + +File: lispref.info, Node: Syntax Descriptors, Next: Syntax Table Functions, Prev: Syntax Basics, Up: Syntax Tables + +Syntax Descriptors +================== + + This section describes the syntax classes and flags that denote the +syntax of a character, and how they are represented as a "syntax +descriptor", which is a Lisp string that you pass to +`modify-syntax-entry' to specify the desired syntax. + + XEmacs defines a number of "syntax classes". Each syntax table puts +each character into one class. There is no necessary relationship +between the class of a character in one syntax table and its class in +any other table. + + Each class is designated by a mnemonic character, which serves as the +name of the class when you need to specify a class. Usually the +designator character is one that is frequently in that class; however, +its meaning as a designator is unvarying and independent of what syntax +that character currently has. + + A syntax descriptor is a Lisp string that specifies a syntax class, a +matching character (used only for the parenthesis classes) and flags. +The first character is the designator for a syntax class. The second +character is the character to match; if it is unused, put a space there. +Then come the characters for any desired flags. If no matching +character or flags are needed, one character is sufficient. + + For example, the descriptor for the character `*' in C mode is +`. 23' (i.e., punctuation, matching character slot unused, second +character of a comment-starter, first character of an comment-ender), +and the entry for `/' is `. 14' (i.e., punctuation, matching character +slot unused, first character of a comment-starter, second character of +a comment-ender). + +* Menu: + +* Syntax Class Table:: Table of syntax classes. +* Syntax Flags:: Additional flags each character can have. + + +File: lispref.info, Node: Syntax Class Table, Next: Syntax Flags, Up: Syntax Descriptors + +Table of Syntax Classes +----------------------- + + Here is a table of syntax classes, the characters that stand for +them, their meanings, and examples of their use. + + - Syntax class: whitespace character + "Whitespace characters" (designated with ` ' or `-') separate + symbols and words from each other. Typically, whitespace + characters have no other syntactic significance, and multiple + whitespace characters are syntactically equivalent to a single + one. Space, tab, newline and formfeed are almost always + classified as whitespace. + + - Syntax class: word constituent + "Word constituents" (designated with `w') are parts of normal + English words and are typically used in variable and command names + in programs. All upper- and lower-case letters, and the digits, + are typically word constituents. + + - Syntax class: symbol constituent + "Symbol constituents" (designated with `_') are the extra + characters that are used in variable and command names along with + word constituents. For example, the symbol constituents class is + used in Lisp mode to indicate that certain characters may be part + of symbol names even though they are not part of English words. + These characters are `$&*+-_<>'. In standard C, the only + non-word-constituent character that is valid in symbols is + underscore (`_'). + + - Syntax class: punctuation character + "Punctuation characters" (`.') are those characters that are used + as punctuation in English, or are used in some way in a programming + language to separate symbols from one another. Most programming + language modes, including Emacs Lisp mode, have no characters in + this class since the few characters that are not symbol or word + constituents all have other uses. + + - Syntax class: open parenthesis character + - Syntax class: close parenthesis character + Open and close "parenthesis characters" are characters used in + dissimilar pairs to surround sentences or expressions. Such a + grouping is begun with an open parenthesis character and + terminated with a close. Each open parenthesis character matches + a particular close parenthesis character, and vice versa. + Normally, XEmacs indicates momentarily the matching open + parenthesis when you insert a close parenthesis. *Note Blinking::. + + The class of open parentheses is designated with `(', and that of + close parentheses with `)'. + + In English text, and in C code, the parenthesis pairs are `()', + `[]', and `{}'. In XEmacs Lisp, the delimiters for lists and + vectors (`()' and `[]') are classified as parenthesis characters. + + - Syntax class: string quote + "String quote characters" (designated with `"') are used in many + languages, including Lisp and C, to delimit string constants. The + same string quote character appears at the beginning and the end + of a string. Such quoted strings do not nest. + + The parsing facilities of XEmacs consider a string as a single + token. The usual syntactic meanings of the characters in the + string are suppressed. + + The Lisp modes have two string quote characters: double-quote (`"') + and vertical bar (`|'). `|' is not used in XEmacs Lisp, but it is + used in Common Lisp. C also has two string quote characters: + double-quote for strings, and single-quote (`'') for character + constants. + + English text has no string quote characters because English is not + a programming language. Although quotation marks are used in + English, we do not want them to turn off the usual syntactic + properties of other characters in the quotation. + + - Syntax class: escape + An "escape character" (designated with `\') starts an escape + sequence such as is used in C string and character constants. The + character `\' belongs to this class in both C and Lisp. (In C, it + is used thus only inside strings, but it turns out to cause no + trouble to treat it this way throughout C code.) + + Characters in this class count as part of words if + `words-include-escapes' is non-`nil'. *Note Word Motion::. + + - Syntax class: character quote + A "character quote character" (designated with `/') quotes the + following character so that it loses its normal syntactic meaning. + This differs from an escape character in that only the character + immediately following is ever affected. + + Characters in this class count as part of words if + `words-include-escapes' is non-`nil'. *Note Word Motion::. + + This class is used for backslash in TeX mode. + + - Syntax class: paired delimiter + "Paired delimiter characters" (designated with `$') are like + string quote characters except that the syntactic properties of the + characters between the delimiters are not suppressed. Only TeX + mode uses a paired delimiter presently--the `$' that both enters + and leaves math mode. + + - Syntax class: expression prefix + An "expression prefix operator" (designated with `'') is used for + syntactic operators that are part of an expression if they appear + next to one. These characters in Lisp include the apostrophe, `'' + (used for quoting), the comma, `,' (used in macros), and `#' (used + in the read syntax for certain data types). + + - Syntax class: comment starter + - Syntax class: comment ender + The "comment starter" and "comment ender" characters are used in + various languages to delimit comments. These classes are + designated with `<' and `>', respectively. + + English text has no comment characters. In Lisp, the semicolon + (`;') starts a comment and a newline or formfeed ends one. + + - Syntax class: inherit + This syntax class does not specify a syntax. It says to look in + the standard syntax table to find the syntax of this character. + The designator for this syntax code is `@'. + + +File: lispref.info, Node: Syntax Flags, Prev: Syntax Class Table, Up: Syntax Descriptors + +Syntax Flags +------------ + + In addition to the classes, entries for characters in a syntax table +can include flags. There are six possible flags, represented by the +characters `1', `2', `3', `4', `b' and `p'. + + All the flags except `p' are used to describe multi-character +comment delimiters. The digit flags indicate that a character can +_also_ be part of a comment sequence, in addition to the syntactic +properties associated with its character class. The flags are +independent of the class and each other for the sake of characters such +as `*' in C mode, which is a punctuation character, _and_ the second +character of a start-of-comment sequence (`/*'), _and_ the first +character of an end-of-comment sequence (`*/'). + + The flags for a character C are: + + * `1' means C is the start of a two-character comment-start sequence. + + * `2' means C is the second character of such a sequence. + + * `3' means C is the start of a two-character comment-end sequence. + + * `4' means C is the second character of such a sequence. + + * `b' means that C as a comment delimiter belongs to the alternative + "b" comment style. + + Emacs supports two comment styles simultaneously in any one syntax + table. This is for the sake of C++. Each style of comment syntax + has its own comment-start sequence and its own comment-end + sequence. Each comment must stick to one style or the other; + thus, if it starts with the comment-start sequence of style "b", + it must also end with the comment-end sequence of style "b". + + The two comment-start sequences must begin with the same + character; only the second character may differ. Mark the second + character of the "b"-style comment-start sequence with the `b' + flag. + + A comment-end sequence (one or two characters) applies to the "b" + style if its first character has the `b' flag set; otherwise, it + applies to the "a" style. + + The appropriate comment syntax settings for C++ are as follows: + + `/' + `124b' + + `*' + `23' + + newline + `>b' + + This defines four comment-delimiting sequences: + + `/*' + This is a comment-start sequence for "a" style because the + second character, `*', does not have the `b' flag. + + `//' + This is a comment-start sequence for "b" style because the + second character, `/', does have the `b' flag. + + `*/' + This is a comment-end sequence for "a" style because the first + character, `*', does not have the `b' flag + + newline + This is a comment-end sequence for "b" style, because the + newline character has the `b' flag. + + * `p' identifies an additional "prefix character" for Lisp syntax. + These characters are treated as whitespace when they appear between + expressions. When they appear within an expression, they are + handled according to their usual syntax codes. + + The function `backward-prefix-chars' moves back over these + characters, as well as over characters whose primary syntax class + is prefix (`''). *Note Motion and Syntax::. + + +File: lispref.info, Node: Syntax Table Functions, Next: Motion and Syntax, Prev: Syntax Descriptors, Up: Syntax Tables + +Syntax Table Functions +====================== + + In this section we describe functions for creating, accessing and +altering syntax tables. + + - Function: make-syntax-table &optional oldtable + This function creates a new syntax table. Character codes 0 + through 31 and 128 through 255 are set up to inherit from the + standard syntax table. The other character codes are set up by + copying what the standard syntax table says about them. + + Most major mode syntax tables are created in this way. + + - Function: copy-syntax-table &optional syntax-table + This function constructs a copy of SYNTAX-TABLE and returns it. + If SYNTAX-TABLE is not supplied (or is `nil'), it returns a copy + of the current syntax table. Otherwise, an error is signaled if + SYNTAX-TABLE is not a syntax table. + + - Command: modify-syntax-entry char-range syntax-descriptor &optional + syntax-table + This function sets the syntax entry for CHAR-RANGE according to + SYNTAX-DESCRIPTOR. CHAR-RANGE is either a single character or a + range of characters, as used with `put-char-table'. The syntax is + changed only for SYNTAX-TABLE, which defaults to the current + buffer's syntax table, and not in any other syntax table. The + argument SYNTAX-DESCRIPTOR specifies the desired syntax; this is a + string beginning with a class designator character, and optionally + containing a matching character and flags as well. *Note Syntax + Descriptors::. + + This function always returns `nil'. The old syntax information in + the table for CHAR-RANGE is discarded. + + An error is signaled if the first character of the syntax + descriptor is not one of the twelve syntax class designator + characters. + + Examples: + + ;; Put the space character in class whitespace. + (modify-syntax-entry ?\ " ") + => nil + + ;; Make `$' an open parenthesis character, + ;; with `^' as its matching close. + (modify-syntax-entry ?$ "(^") + => nil + + ;; Make `^' a close parenthesis character, + ;; with `$' as its matching open. + (modify-syntax-entry ?^ ")$") + => nil + + ;; Make `/' a punctuation character, + ;; the first character of a start-comment sequence, + ;; and the second character of an end-comment sequence. + ;; This is used in C mode. + (modify-syntax-entry ?/ ". 14") + => nil + + - Function: char-syntax character &optional syntax-table + This function returns the syntax class of CHARACTER, represented + by its mnemonic designator character. This _only_ returns the + class, not any matching parenthesis or flags. + + An error is signaled if CHARACTER is not a character. + + The characters that correspond to various syntax codes are listed + in the documentation of `modify-syntax-entry'. + + Optional second argument SYNTAX-TABLE is the syntax table to be + used, and defaults to the current buffer's syntax table. + + The following examples apply to C mode. The first example shows + that the syntax class of space is whitespace (represented by a + space). The second example shows that the syntax of `/' is + punctuation. This does not show the fact that it is also part of + comment-start and -end sequences. The third example shows that + open parenthesis is in the class of open parentheses. This does + not show the fact that it has a matching character, `)'. + + (char-to-string (char-syntax ?\ )) + => " " + + (char-to-string (char-syntax ?/)) + => "." + + (char-to-string (char-syntax ?\()) + => "(" + + - Function: set-syntax-table syntax-table &optional buffer + This function makes SYNTAX-TABLE the syntax table for BUFFER, which + defaults to the current buffer if omitted. It returns + SYNTAX-TABLE. + + - Function: syntax-table &optional buffer + This function returns the syntax table for BUFFER, which defaults + to the current buffer if omitted. + + +File: lispref.info, Node: Motion and Syntax, Next: Parsing Expressions, Prev: Syntax Table Functions, Up: Syntax Tables + +Motion and Syntax +================= + + This section describes functions for moving across characters in +certain syntax classes. None of these functions exists in Emacs +version 18 or earlier. + + - Function: skip-syntax-forward syntaxes &optional limit buffer + This function moves point forward across characters having syntax + classes mentioned in SYNTAXES. It stops when it encounters the + end of the buffer, or position LIMIT (if specified), or a + character it is not supposed to skip. Optional argument BUFFER + defaults to the current buffer if omitted. + + - Function: skip-syntax-backward syntaxes &optional limit buffer + This function moves point backward across characters whose syntax + classes are mentioned in SYNTAXES. It stops when it encounters + the beginning of the buffer, or position LIMIT (if specified), or a + character it is not supposed to skip. Optional argument BUFFER + defaults to the current buffer if omitted. + + + - Function: backward-prefix-chars &optional buffer + This function moves point backward over any number of characters + with expression prefix syntax. This includes both characters in + the expression prefix syntax class, and characters with the `p' + 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 @@ -351,12 +1064,12 @@ Abbrev Tables 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'. + - Function: define-abbrev-table table-name definitions + This function defines TABLE-NAME (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. @@ -393,7 +1106,7 @@ used by commands that ask for information from the user. abbrev, or `nil' if the user declines to confirm redefining an existing abbrev. - - Function: define-abbrev table name expansion hook + - Function: define-abbrev table name &optional expansion hook count 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. @@ -433,7 +1146,7 @@ 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 + - Function: quietly-read-abbrev-file &optional 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. @@ -456,564 +1169,3 @@ in a file automatically, under the control of variables described here. 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 -******* - - An "extent" is a region of text (a start position and an end -position) that is displayed in a particular face and can have certain -other properties such as being read-only. Extents can overlap each -other. XEmacs efficiently handles buffers with large numbers of -extents in them. - - - Function: extentp object - This returns `t' if OBJECT is an extent. - -* Menu: - -* Intro to Extents:: Extents are regions over a buffer or string. -* Creating and Modifying Extents:: - Basic extent functions. -* Extent Endpoints:: Accessing and setting the bounds of an extent. -* Finding Extents:: Determining which extents are in an object. -* Mapping Over Extents:: More sophisticated functions for extent scanning. -* Extent Properties:: Extents have built-in and user-definable properties. -* Detached Extents:: Extents that are not in a buffer. -* Extent Parents:: Inheriting properties from another extent. -* Duplicable Extents:: Extents can be marked to be copied into strings. -* Extents and Events:: Extents can interact with the keyboard and mouse. -* Atomic Extents:: Treating a block of text as a single entity. - - -File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents - -Introduction to Extents -======================= - - An extent is a region of text within a buffer or string that has -certain properties associated with it. The properties of an extent -primarily affect the way the text contained in the extent is displayed. -Extents can freely overlap each other in a buffer or string. Extents -are invisible to functions that merely examine the text of a buffer or -string. - - _Please note:_ An alternative way to add properties to a buffer or -string is to use text properties. *Note Text Properties::. - - An extent is logically a Lisp object consisting of a start position, -an end position, a buffer or string to which these positions refer, and -a property list. As text is inserted into a buffer, the start and end -positions of the extent are automatically adjusted as necessary to keep -the extent referring to the same text in the buffer. If text is -inserted at the boundary of an extent, the extent's `start-open' and -`end-open' properties control whether the text is included as part of -the extent. If the text bounded by an extent is deleted, the extent -becomes "detached"; its start and end positions are no longer -meaningful, but it maintains all its other properties and can later be -reinserted into a buffer. (None of these considerations apply to -strings, because text cannot be inserted into or deleted from a string.) - - Each extent has a face or list of faces associated with it, which -controls the way in which the text bounded by the extent is displayed. -If an extent's face is `nil' or its properties are partially undefined, -the corresponding properties from the default face for the frame is -used. If two or more extents overlap, or if a list of more than one -face is specified for a particular extent, the corresponding faces are -merged to determine the text's displayed properties. Every extent has -a "priority" that determines which face takes precedence if the faces -conflict. (If two extents have the same priority, the one that comes -later in the display order takes precedence. *Note display order: -Extent Endpoints.) Higher-numbered priority values correspond to a -higher priority, and priority values can be negative. Every extent is -created with a priority of 0, but this can be changed with -`set-extent-priority'. Within a single extent with a list of faces, -faces earlier in the list have a higher priority than faces later in -the list. - - Extents can be set to respond specially to key and mouse events -within the extent. An extent's `keymap' property controls the effect of -key and mouse strokes within the extent's text, and the `mouse-face' -property controls whether the extent is highlighted when the mouse moves -over it. *Note Extents and Events::. - - An extent can optionally have a "begin-glyph" or "end-glyph" -associated with it. A begin-glyph or end-glyph is a pixmap or string -that will be displayed either at the start or end of an extent or in the -margin of the line that the start or end of the extent lies in, -depending on the extent's layout policy. Begin-glyphs and end-glyphs -are used to implement annotations, and you should use the annotation API -functions in preference to the lower-level extent functions. For more -information, *Note Annotations::. - - If an extent has its `detachable' property set, it will become -"detached" (i.e. no longer in the buffer) when all its text is deleted. -Otherwise, it will simply shrink down to zero-length and sit in the -same place in the buffer. By default, the `detachable' property is set -on newly-created extents. *Note Detached Extents::. - - If an extent has its `duplicable' property set, it will be -remembered when a string is created from text bounded by the extent. -When the string is re-inserted into a buffer, the extent will also be -re-inserted. This mechanism is used in the kill, yank, and undo -commands. *Note Duplicable Extents::. - - -File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents - -Creating and Modifying Extents -============================== - - - Function: make-extent from to &optional object - This function makes an extent for the range [FROM, TO) in OBJECT - (a buffer or string). OBJECT defaults to the current buffer. - Insertions at point TO will be outside of the extent; insertions - at FROM will be inside the extent, causing the extent to grow - (*note Extent Endpoints::). This is the same way that markers - behave. The extent is initially detached if both FROM and TO are - `nil', and in this case OBJECT defaults to `nil', meaning the - extent is in no buffer or string (*note Detached Extents::). - - - Function: delete-extent extent - This function removes EXTENT from its buffer and destroys it. - This does not modify the buffer's text, only its display - properties. The extent cannot be used thereafter. To remove an - extent in such a way that it can be re-inserted later, use - `detach-extent'. *Note Detached Extents::. - - - Function: extent-object extent - This function returns the buffer or string that EXTENT is in. If - the return value is `nil', this means that the extent is detached; - however, a detached extent will not necessarily return a value of - `nil'. - - - Function: extent-live-p extent - This function returns `nil' if EXTENT is deleted, and `t' - otherwise. - - -File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents - -Extent Endpoints -================ - - Every extent has a start position and an end position, and logically -affects the characters between those positions. Normally the start and -end positions must both be valid positions in the extent's buffer or -string. However, both endpoints can be `nil', meaning the extent is -detached. *Note Detached Extents::. - - Whether the extent overlaps its endpoints is governed by its -`start-open' and `end-open' properties. Insertion of a character at a -closed endpoint will expand the extent to include that character; -insertion at an open endpoint will not. Similarly, functions such as -`extent-at' that scan over all extents overlapping a particular -position will include extents with a closed endpoint at that position, -but not extents with an open endpoint. - - Note that the `start-closed' and `end-closed' properties are -equivalent to `start-open' and `end-open' with the opposite sense. - - Both endpoints can be equal, in which case the extent includes no -characters but still exists in the buffer or string. Zero-length -extents are used to represent annotations (*note Annotations::) and can -be used as a more powerful form of a marker. Deletion of all the -characters in an extent may or may not result in a zero-length extent; -this depends on the `detachable' property (*note Detached Extents::). -Insertion at the position of a zero-length extent expands the extent if -both endpoints are closed; goes before the extent if it has the -`start-open' property; and goes after the extent if it has the -`end-open' property. Zero-length extents with both the `start-open' -and `end-open' properties are treated as if their starting point were -closed. Deletion of a character on a side of a zero-length extent -whose corresponding endpoint is closed causes the extent to be detached -if its `detachable' property is set; if the corresponding endpoint is -open, the extent remains in the buffer, moving as necessary. - - Extents are ordered within a buffer or string by increasing start -position, and then by decreasing end position (this is called the -"display order"). - - - Function: extent-start-position extent - This function returns the start position of EXTENT. - - - Function: extent-end-position extent - This function returns the end position of EXTENT. - - - Function: extent-length extent - This function returns the length of EXTENT in characters. If the - extent is detached, this returns `0'. If the extent is not - detached, this is equivalent to - (- (extent-end-position EXTENT) (extent-start-position EXTENT)) - - - Function: set-extent-endpoints extent start end &optional - buffer-or-string - This function sets the start and end position of EXTENT to START - and END. If both are `nil', this is equivalent to `detach-extent'. - - BUFFER-OR-STRING specifies the new buffer or string that the - extent should be in, and defaults to EXTENT's buffer or string. - (If `nil', and EXTENT is in no buffer and no string, it defaults - to the current buffer.) - - See documentation on `detach-extent' for a discussion of undo - recording. - - -File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents - -Finding Extents -=============== - - The following functions provide a simple way of determining the -extents in a buffer or string. A number of more sophisticated -primitives for mapping over the extents in a range of a buffer or string -are also provided (*note Mapping Over Extents::). When reading through -this section, keep in mind the way that extents are ordered (*note -Extent Endpoints::). - - - Function: extent-list &optional buffer-or-string from to flags - This function returns a list of the extents in BUFFER-OR-STRING. - BUFFER-OR-STRING defaults to the current buffer if omitted. FROM - and TO can be used to limit the range over which extents are - returned; if omitted, all extents in the buffer or string are - returned. - - More specifically, if a range is specified using FROM and TO, only - extents that overlap the range (i.e. begin or end inside of the - range) are included in the list. FROM and TO default to the - beginning and end of BUFFER-OR-STRING, respectively. - - FLAGS controls how end cases are treated. For a discussion of - this, and exactly what "overlap" means, see `map-extents'. - - Functions that create extents must be prepared for the possibility -that there are other extents in the same area, created by other -functions. To deal with this, functions typically mark their own -extents by setting a particular property on them. The following -function makes it easier to locate those extents. - - - Function: extent-at pos &optional object property before at-flag - This function finds the "smallest" extent (i.e., the last one in - the display order) at (i.e., overlapping) POS in OBJECT (a buffer - or string) having PROPERTY set. OBJECT defaults to the current - buffer. PROPERTY defaults to `nil', meaning that any extent will - do. Returns `nil' if there is no matching extent at POS. If the - fourth argument BEFORE is not `nil', it must be an extent; any - returned extent will precede that extent. This feature allows - `extent-at' to be used by a loop over extents. - - AT-FLAG controls how end cases are handled (i.e. what "at" really - means), and should be one of: - - `nil' - - `after' - An extent is at POS if it covers the character after POS. - This is consistent with the way that text properties work. - - `before' - An extent is at POS if it covers the character before POS. - - `at' - An extent is at POS if it overlaps or abuts POS. This - includes all zero-length extents at POS. - - Note that in all cases, the start-openness and end-openness of the - extents considered is ignored. If you want to pay attention to - those properties, you should use `map-extents', which gives you - more control. - - The following low-level functions are provided for explicitly -traversing the extents in a buffer according to the display order. -These functions are mostly intended for debugging--in normal operation, -you should probably use `mapcar-extents' or `map-extents', or loop -using the BEFORE argument to `extent-at', rather than creating a loop -using `next-extent'. - - - Function: next-extent extent - Given an extent EXTENT, this function returns the next extent in - the buffer or string's display order. If EXTENT is a buffer or - string, this returns the first extent in the buffer or string. - - - Function: previous-extent extent - Given an extent EXTENT, this function returns the previous extent - in the buffer or string's display order. If EXTENT is a buffer or - string, this returns the last extent in the buffer or string. - - -File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents - -Mapping Over Extents -==================== - - The most basic and general function for mapping over extents is -called `map-extents'. You should read through the definition of this -function to familiarize yourself with the concepts and optional -arguments involved. However, in practice you may find it more -convenient to use the function `mapcar-extents' or to create a loop -using the `before' argument to `extent-at' (*note Finding Extents::). - - - Function: map-extents function &optional object from to maparg flags - property value - This function maps FUNCTION over the extents which overlap a - region in OBJECT. OBJECT is normally a buffer or string but could - be an extent (see below). The region is normally bounded by - [FROM, TO) (i.e. the beginning of the region is closed and the end - of the region is open), but this can be changed with the FLAGS - argument (see below for a complete discussion). - - FUNCTION is called with the arguments (extent, MAPARG). The - arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and - default to the current buffer, the beginning of OBJECT, the end of - OBJECT, NIL, and NIL, respectively. `map-extents' returns the - first non-`nil' result produced by FUNCTION, and no more calls to - FUNCTION are made after it returns non-`nil'. - - If OBJECT is an extent, FROM and TO default to the extent's - endpoints, and the mapping omits that extent and its predecessors. - This feature supports restarting a loop based on `map-extents'. - Note: OBJECT must be attached to a buffer or string, and the - mapping is done over that buffer or string. - - An extent overlaps the region if there is any point in the extent - that is also in the region. (For the purpose of overlap, - zero-length extents and regions are treated as closed on both ends - regardless of their endpoints' specified open/closedness.) Note - that the endpoints of an extent or region are considered to be in - that extent or region if and only if the corresponding end is - closed. For example, the extent [5,7] overlaps the region [2,5] - because 5 is in both the extent and the region. However, (5,7] - does not overlap [2,5] because 5 is not in the extent, and neither - [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the - region. - - The optional FLAGS can be a symbol or a list of one or more - symbols, modifying the behavior of `map-extents'. Allowed symbols - are: - - `end-closed' - The region's end is closed. - - `start-open' - The region's start is open. - - `all-extents-closed' - Treat all extents as closed on both ends for the purpose of - determining whether they overlap the region, irrespective of - their actual open- or closedness. - - `all-extents-open' - Treat all extents as open on both ends. - - `all-extents-closed-open' - Treat all extents as start-closed, end-open. - - `all-extents-open-closed' - Treat all extents as start-open, end-closed. - - `start-in-region' - In addition to the above conditions for extent overlap, the - extent's start position must lie within the specified region. - Note that, for this condition, open start positions are - treated as if 0.5 was added to the endpoint's value, and open - end positions are treated as if 0.5 was subtracted from the - endpoint's value. - - `end-in-region' - The extent's end position must lie within the region. - - `start-and-end-in-region' - Both the extent's start and end positions must lie within the - region. - - `start-or-end-in-region' - Either the extent's start or end position must lie within the - region. - - `negate-in-region' - The condition specified by a `*-in-region' flag must _not_ - hold for the extent to be considered. - - At most one of `all-extents-closed', `all-extents-open', - `all-extents-closed-open', and `all-extents-open-closed' may be - specified. - - At most one of `start-in-region', `end-in-region', - `start-and-end-in-region', and `start-or-end-in-region' may be - specified. - - If optional arg PROPERTY is non-`nil', only extents with that - property set on them will be visited. If optional arg VALUE is - non-`nil', only extents whose value for that property is `eq' to - VALUE will be visited. - - If you want to map over extents and accumulate a list of results, -the following function may be more convenient than `map-extents'. - - - Function: mapcar-extents function &optional predicate - buffer-or-string from to flags property value - This function applies FUNCTION to all extents which overlap a - region in BUFFER-OR-STRING. The region is delimited by FROM and - TO. FUNCTION is called with one argument, the extent. A list of - the values returned by FUNCTION is returned. An optional - PREDICATE may be used to further limit the extents over which - FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and - VALUE may also be used to control the extents passed to PREDICATE - or FUNCTION, and have the same meaning as in `map-extents'. - - - Function: map-extent-children function &optional object from to - maparg flags property value - This function is similar to `map-extents', but differs in that: - - * It only visits extents which start in the given region. - - * After visiting an extent E, it skips all other extents which - start inside E but end before E's end. - - Thus, this function may be used to walk a tree of extents in a - buffer: - (defun walk-extents (buffer &optional ignore) - (map-extent-children 'walk-extents buffer)) - - - Function: extent-in-region-p extent &optional from to flags - This function returns T if `map-extents' would visit EXTENT if - called with the given arguments. - diff --git a/info/lispref.info-34 b/info/lispref.info-34 index fb64927..aec041b 100644 --- a/info/lispref.info-34 +++ b/info/lispref.info-34 @@ -50,6 +50,578 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 +******* + + An "extent" is a region of text (a start position and an end +position) that is displayed in a particular face and can have certain +other properties such as being read-only. Extents can overlap each +other. XEmacs efficiently handles buffers with large numbers of +extents in them. + + - Function: extentp object + This returns `t' if OBJECT is an extent. + +* Menu: + +* Intro to Extents:: Extents are regions over a buffer or string. +* Creating and Modifying Extents:: + Basic extent functions. +* Extent Endpoints:: Accessing and setting the bounds of an extent. +* Finding Extents:: Determining which extents are in an object. +* Mapping Over Extents:: More sophisticated functions for extent scanning. +* Extent Properties:: Extents have built-in and user-definable properties. +* Detached Extents:: Extents that are not in a buffer. +* Extent Parents:: Inheriting properties from another extent. +* Duplicable Extents:: Extents can be marked to be copied into strings. +* Extents and Events:: Extents can interact with the keyboard and mouse. +* Atomic Extents:: Treating a block of text as a single entity. + + +File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents + +Introduction to Extents +======================= + + An extent is a region of text within a buffer or string that has +certain properties associated with it. The properties of an extent +primarily affect the way the text contained in the extent is displayed. +Extents can freely overlap each other in a buffer or string. Extents +are invisible to functions that merely examine the text of a buffer or +string. + + _Please note:_ An alternative way to add properties to a buffer or +string is to use text properties. *Note Text Properties::. + + An extent is logically a Lisp object consisting of a start position, +an end position, a buffer or string to which these positions refer, and +a property list. As text is inserted into a buffer, the start and end +positions of the extent are automatically adjusted as necessary to keep +the extent referring to the same text in the buffer. If text is +inserted at the boundary of an extent, the extent's `start-open' and +`end-open' properties control whether the text is included as part of +the extent. If the text bounded by an extent is deleted, the extent +becomes "detached"; its start and end positions are no longer +meaningful, but it maintains all its other properties and can later be +reinserted into a buffer. (None of these considerations apply to +strings, because text cannot be inserted into or deleted from a string.) + + Each extent has a face or list of faces associated with it, which +controls the way in which the text bounded by the extent is displayed. +If an extent's face is `nil' or its properties are partially undefined, +the corresponding properties from the default face for the frame is +used. If two or more extents overlap, or if a list of more than one +face is specified for a particular extent, the corresponding faces are +merged to determine the text's displayed properties. Every extent has +a "priority" that determines which face takes precedence if the faces +conflict. (If two extents have the same priority, the one that comes +later in the display order takes precedence. *Note display order: +Extent Endpoints.) Higher-numbered priority values correspond to a +higher priority, and priority values can be negative. Every extent is +created with a priority of 0, but this can be changed with +`set-extent-priority'. Within a single extent with a list of faces, +faces earlier in the list have a higher priority than faces later in +the list. + + Extents can be set to respond specially to key and mouse events +within the extent. An extent's `keymap' property controls the effect of +key and mouse strokes within the extent's text, and the `mouse-face' +property controls whether the extent is highlighted when the mouse moves +over it. *Note Extents and Events::. + + An extent can optionally have a "begin-glyph" or "end-glyph" +associated with it. A begin-glyph or end-glyph is a pixmap or string +that will be displayed either at the start or end of an extent or in the +margin of the line that the start or end of the extent lies in, +depending on the extent's layout policy. Begin-glyphs and end-glyphs +are used to implement annotations, and you should use the annotation API +functions in preference to the lower-level extent functions. For more +information, *Note Annotations::. + + If an extent has its `detachable' property set, it will become +"detached" (i.e. no longer in the buffer) when all its text is deleted. +Otherwise, it will simply shrink down to zero-length and sit in the +same place in the buffer. By default, the `detachable' property is set +on newly-created extents. *Note Detached Extents::. + + If an extent has its `duplicable' property set, it will be +remembered when a string is created from text bounded by the extent. +When the string is re-inserted into a buffer, the extent will also be +re-inserted. This mechanism is used in the kill, yank, and undo +commands. *Note Duplicable Extents::. + + +File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents + +Creating and Modifying Extents +============================== + + - Function: make-extent from to &optional buffer-or-string + This function makes an extent for the range [FROM, TO) in + BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults + to the current buffer. Insertions at point TO will be outside of + the extent; insertions at FROM will be inside the extent, causing + the extent to grow (*note Extent Endpoints::). This is the same + way that markers behave. The extent is initially detached if both + FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults + to `nil', meaning the extent is in no buffer or string (*note + Detached Extents::). + + - Function: delete-extent extent + This function removes EXTENT from its buffer and destroys it. + This does not modify the buffer's text, only its display + properties. The extent cannot be used thereafter. To remove an + extent in such a way that it can be re-inserted later, use + `detach-extent'. *Note Detached Extents::. + + - Function: extent-object extent + This function returns the buffer or string that EXTENT is in. If + the return value is `nil', this means that the extent is detached; + however, a detached extent will not necessarily return a value of + `nil'. + + - Function: extent-live-p object + This function returns `t' if OBJECT is an extent that has not been + deleted, and `nil' otherwise. + + +File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents + +Extent Endpoints +================ + + Every extent has a start position and an end position, and logically +affects the characters between those positions. Normally the start and +end positions must both be valid positions in the extent's buffer or +string. However, both endpoints can be `nil', meaning the extent is +detached. *Note Detached Extents::. + + Whether the extent overlaps its endpoints is governed by its +`start-open' and `end-open' properties. Insertion of a character at a +closed endpoint will expand the extent to include that character; +insertion at an open endpoint will not. Similarly, functions such as +`extent-at' that scan over all extents overlapping a particular +position will include extents with a closed endpoint at that position, +but not extents with an open endpoint. + + Note that the `start-closed' and `end-closed' properties are +equivalent to `start-open' and `end-open' with the opposite sense. + + Both endpoints can be equal, in which case the extent includes no +characters but still exists in the buffer or string. Zero-length +extents are used to represent annotations (*note Annotations::) and can +be used as a more powerful form of a marker. Deletion of all the +characters in an extent may or may not result in a zero-length extent; +this depends on the `detachable' property (*note Detached Extents::). +Insertion at the position of a zero-length extent expands the extent if +both endpoints are closed; goes before the extent if it has the +`start-open' property; and goes after the extent if it has the +`end-open' property. Zero-length extents with both the `start-open' +and `end-open' properties are treated as if their starting point were +closed. Deletion of a character on a side of a zero-length extent +whose corresponding endpoint is closed causes the extent to be detached +if its `detachable' property is set; if the corresponding endpoint is +open, the extent remains in the buffer, moving as necessary. + + Extents are ordered within a buffer or string by increasing start +position, and then by decreasing end position (this is called the +"display order"). + + - Function: extent-start-position extent + This function returns the start position of EXTENT. + + - Function: extent-end-position extent + This function returns the end position of EXTENT. + + - Function: extent-length extent + This function returns the length of EXTENT in characters. If the + extent is detached, this returns `0'. If the extent is not + detached, this is equivalent to + (- (extent-end-position EXTENT) (extent-start-position EXTENT)) + + - Function: set-extent-endpoints extent start end &optional + buffer-or-string + This function sets the start and end position of EXTENT to START + and END. If both are `nil', this is equivalent to `detach-extent'. + + BUFFER-OR-STRING specifies the new buffer or string that the + extent should be in, and defaults to EXTENT's buffer or string. + (If `nil', and EXTENT is in no buffer and no string, it defaults + to the current buffer.) + + See documentation on `detach-extent' for a discussion of undo + recording. + + +File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents + +Finding Extents +=============== + + The following functions provide a simple way of determining the +extents in a buffer or string. A number of more sophisticated +primitives for mapping over the extents in a range of a buffer or string +are also provided (*note Mapping Over Extents::). When reading through +this section, keep in mind the way that extents are ordered (*note +Extent Endpoints::). + + - Function: extent-list &optional buffer-or-string from to flags + property value + This function returns a list of the extents in BUFFER-OR-STRING. + BUFFER-OR-STRING defaults to the current buffer if omitted. FROM + and TO can be used to limit the range over which extents are + returned; if omitted, all extents in the buffer or string are + returned. + + More specifically, if a range is specified using FROM and TO, only + extents that overlap the range (i.e. begin or end inside of the + range) are included in the list. FROM and TO default to the + beginning and end of BUFFER-OR-STRING, respectively. + + FLAGS controls how end cases are treated. For a discussion of + this, and exactly what "overlap" means, see `map-extents'. + + The optional arguments PROPERTY and VALUE can be used to further + restrict which extents are returned. They have the same meaning + as for `map-extents'. + + If you want to map a function over the extents in a buffer or + string, consider using `map-extents' or `mapcar-extents' instead. + + See also the function `extents-at'. + + Functions that create extents must be prepared for the possibility +that there are other extents in the same area, created by other +functions. To deal with this, functions typically mark their own +extents by setting a particular property on them. The following +function makes it easier to locate those extents. + + - Function: extent-at pos &optional object property before at-flag + This function finds the "smallest" extent (i.e., the last one in + the display order) at (i.e., overlapping) POS in OBJECT (a buffer + or string) having PROPERTY set. OBJECT defaults to the current + buffer. PROPERTY defaults to `nil', meaning that any extent will + do. Returns `nil' if there is no matching extent at POS. If the + fourth argument BEFORE is not `nil', it must be an extent; any + returned extent will precede that extent. This feature allows + `extent-at' to be used by a loop over extents. + + AT-FLAG controls how end cases are handled (i.e. what "at" really + means), and should be one of: + + `nil' + + `after' + An extent is at POS if it covers the character after POS. + This is consistent with the way that text properties work. + + `before' + An extent is at POS if it covers the character before POS. + + `at' + An extent is at POS if it overlaps or abuts POS. This + includes all zero-length extents at POS. + + Note that in all cases, the start-openness and end-openness of the + extents considered is ignored. If you want to pay attention to + those properties, you should use `map-extents', which gives you + more control. + + The following low-level functions are provided for explicitly +traversing the extents in a buffer according to the display order. +These functions are mostly intended for debugging--in normal operation, +you should probably use `mapcar-extents' or `map-extents', or loop +using the BEFORE argument to `extent-at', rather than creating a loop +using `next-extent'. + + - Function: next-extent extent + Given an extent EXTENT, this function returns the next extent in + the buffer or string's display order. If EXTENT is a buffer or + string, this returns the first extent in the buffer or string. + + - Function: previous-extent extent + Given an extent EXTENT, this function returns the previous extent + in the buffer or string's display order. If EXTENT is a buffer or + string, this returns the last extent in the buffer or string. + + +File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents + +Mapping Over Extents +==================== + + The most basic and general function for mapping over extents is +called `map-extents'. You should read through the definition of this +function to familiarize yourself with the concepts and optional +arguments involved. However, in practice you may find it more +convenient to use the function `mapcar-extents' or to create a loop +using the `before' argument to `extent-at' (*note Finding Extents::). + + - Function: map-extents function &optional object from to maparg flags + property value + This function maps FUNCTION over the extents which overlap a + region in OBJECT. OBJECT is normally a buffer or string but could + be an extent (see below). The region is normally bounded by + [FROM, TO) (i.e. the beginning of the region is closed and the end + of the region is open), but this can be changed with the FLAGS + argument (see below for a complete discussion). + + FUNCTION is called with the arguments (extent, MAPARG). The + arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and + default to the current buffer, the beginning of OBJECT, the end of + OBJECT, `nil', and `nil', respectively. `map-extents' returns the + first non-`nil' result produced by FUNCTION, and no more calls to + FUNCTION are made after it returns non-`nil'. + + If OBJECT is an extent, FROM and TO default to the extent's + endpoints, and the mapping omits that extent and its predecessors. + This feature supports restarting a loop based on `map-extents'. + Note: OBJECT must be attached to a buffer or string, and the + mapping is done over that buffer or string. + + An extent overlaps the region if there is any point in the extent + that is also in the region. (For the purpose of overlap, + zero-length extents and regions are treated as closed on both ends + regardless of their endpoints' specified open/closedness.) Note + that the endpoints of an extent or region are considered to be in + that extent or region if and only if the corresponding end is + closed. For example, the extent [5,7] overlaps the region [2,5] + because 5 is in both the extent and the region. However, (5,7] + does not overlap [2,5] because 5 is not in the extent, and neither + [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the + region. + + The optional FLAGS can be a symbol or a list of one or more + symbols, modifying the behavior of `map-extents'. Allowed symbols + are: + + `end-closed' + The region's end is closed. + + `start-open' + The region's start is open. + + `all-extents-closed' + Treat all extents as closed on both ends for the purpose of + determining whether they overlap the region, irrespective of + their actual open- or closedness. + + `all-extents-open' + Treat all extents as open on both ends. + + `all-extents-closed-open' + Treat all extents as start-closed, end-open. + + `all-extents-open-closed' + Treat all extents as start-open, end-closed. + + `start-in-region' + In addition to the above conditions for extent overlap, the + extent's start position must lie within the specified region. + Note that, for this condition, open start positions are + treated as if 0.5 was added to the endpoint's value, and open + end positions are treated as if 0.5 was subtracted from the + endpoint's value. + + `end-in-region' + The extent's end position must lie within the region. + + `start-and-end-in-region' + Both the extent's start and end positions must lie within the + region. + + `start-or-end-in-region' + Either the extent's start or end position must lie within the + region. + + `negate-in-region' + The condition specified by a `*-in-region' flag must _not_ + hold for the extent to be considered. + + At most one of `all-extents-closed', `all-extents-open', + `all-extents-closed-open', and `all-extents-open-closed' may be + specified. + + At most one of `start-in-region', `end-in-region', + `start-and-end-in-region', and `start-or-end-in-region' may be + specified. + + If optional arg PROPERTY is non-`nil', only extents with that + property set on them will be visited. If optional arg VALUE is + non-`nil', only extents whose value for that property is `eq' to + VALUE will be visited. + + If you want to map over extents and accumulate a list of results, +the following function may be more convenient than `map-extents'. + + - Function: mapcar-extents function &optional predicate + buffer-or-string from to flags property value + This function applies FUNCTION to all extents which overlap a + region in BUFFER-OR-STRING. The region is delimited by FROM and + TO. FUNCTION is called with one argument, the extent. A list of + the values returned by FUNCTION is returned. An optional + PREDICATE may be used to further limit the extents over which + FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and + VALUE may also be used to control the extents passed to PREDICATE + or FUNCTION, and have the same meaning as in `map-extents'. + + - Function: map-extent-children function &optional object from to + maparg flags property value + This function is similar to `map-extents', but differs in that: + + * It only visits extents which start in the given region. + + * After visiting an extent E, it skips all other extents which + start inside E but end before E's end. + + Thus, this function may be used to walk a tree of extents in a + buffer: + (defun walk-extents (buffer &optional ignore) + (map-extent-children 'walk-extents buffer)) + + - Function: extent-in-region-p extent &optional from to flags + 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 @@ -72,9 +644,9 @@ 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-property extent property &optional default + This function returns EXTENT's value for PROPERTY, or DEFAULT if + no such property exists. - Function: extent-properties extent This function returns a list of all of EXTENT's properties that do @@ -259,8 +831,8 @@ particular properties of an extent. 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-priority extent priority + This function sets the `priority' property of EXTENT to PRIORITY. - Function: set-extent-face extent face This function sets the `face' property of EXTENT to FACE. @@ -584,487 +1156,3 @@ of the default face be * 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 -============================ - - Instancing of a specifier in a particular window domain proceeds as -follows: - - * First, XEmacs searches for a specification whose locale is the - same as the window. If that fails, the search is repeated, - looking for a locale that is the same as the window's buffer. If - that fails, the search is repeated using the window's frame, then - using the device that frame is on. Finally, the specification - whose locale is the symbol `global' (if there is such a - specification) is considered. - - * The inst-pairs contained in the specification that was found are - considered in their order in the inst-list, looking for one whose - tag set matches the device that is derived from the window domain. - (The tag set is an unordered list of zero or more tag symbols. - For all tags that have predicates associated with them, the - predicate must match the device.) - - * If a matching tag set is found, the corresponding instantiator is - passed to the specifier's instantiation method, which is specific - to the type of the specifier. If it succeeds, the resulting - instance object is returned as the result of the instancing and - the instancing is done. Otherwise, the operation continues, - looking for another matching inst-pair in the current - specification. - - * When there are no more inst-pairs to be considered in the current - specification, the search starts over, looking for another - specification as in the first step above. - - * If all specifications are exhausted and no instance object can be - derived, the instancing fails. (Actually, this is not completely - true. Some specifier objects for built-in properties have a - "fallback" value, which is either an inst-list or another - specifier object, that is consulted if the instancing is about to - fail. If it is an inst-list, the searching proceeds using the - inst-pairs in that list. If it is a specifier, the entire - instancing starts over using that specifier instead of the given - one. Fallback values are set by the C code and cannot be - modified, except perhaps indirectly, using any Lisp functions. - The purpose of them is to supply some values to make sure that - instancing of built-in properties can't fail and to implement some - basic specifier inheritance, such as the fact that faces inherit - their properties from the `default' face.) - - It is also possible to instance a specifier over a frame domain or -device domain instead of over a window domain. The C code, for example, -instances the `top-toolbar-height' variable over a frame domain in -order to determine the height of a frame's top toolbar. Instancing over -a frame or device is similar to instancing over a window except that -specifications for locales that cannot be derived from the domain are -ignored. Specifically, instancing over a frame looks first for frame -locales, then device locales, then the `global' locale. Instancing -over a device domain looks only for device locales and the `global' -locale. - - -File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers - -Specifier Types -=============== - - There are various different types of specifiers. The type of a -specifier controls what sorts of instantiators are valid, how an -instantiator is instantiated, etc. Here is a list of built-in specifier -types: - -`boolean' - The valid instantiators are the symbols `t' and `nil'. Instance - objects are the same as instantiators so no special instantiation - function is needed. - -`integer' - The valid instantiators are integers. Instance objects are the - same as instantiators so no special instantiation function is - needed. `modeline-shadow-thickness' is an example of an integer - specifier (negative thicknesses indicate that the shadow is drawn - recessed instead of raised). - -`natnum' - The valid instantiators are natnums (non-negative integers). - Instance objects are the same as instantiators so no special - instantiation function is needed. Natnum specifiers are used for - dimension variables such as `top-toolbar-height'. - -`generic' - All Lisp objects are valid instantiators. Instance objects are - the same as instantiators so no special instantiation function is - needed. - -`font' - The valid instantiators are strings describing fonts or vectors - indicating inheritance from the font of some face. Instance - objects are font-instance objects, which are specific to a - particular device. The instantiation method for font specifiers - can fail, unlike for integer, natnum, boolean, and generic - specifiers. - -`color' - The valid instantiators are strings describing colors or vectors - indicating inheritance from the foreground or background of some - face. Instance objects are color-instance objects, which are - specific to a particular device. The instantiation method for - color specifiers can fail, as for font specifiers. - -`image' - Images are perhaps the most complicated type of built-in - specifier. The valid instantiators are strings (a filename, - inline data for a pixmap, or text to be displayed in a text glyph) - or vectors describing inline data of various sorts or indicating - inheritance from the background-pixmap property of some face. - Instance objects are either strings (for text images), - image-instance objects (for pixmap images), or subwindow objects - (for subwindow images). The instantiation method for image - specifiers can fail, as for font and color specifiers. - -`face-boolean' - The valid instantiators are the symbols `t' and `nil' and vectors - indicating inheritance from a boolean property of some face. - Specifiers of this sort are used for all of the built-in boolean - properties of faces. Instance objects are either the symbol `t' - or the symbol `nil'. - -`toolbar' - The valid instantiators are toolbar descriptors, which are lists - of toolbar-button descriptors (each of which is a vector of two or - four elements). *Note Toolbar::, for more information. - - Color and font instance objects can also be used in turn as -instantiators for a new color or font instance object. Since these -instance objects are device-specific, the instantiator can be used -directly as the new instance object, but only if they are of the same -device. If the devices differ, the base color or font of the -instantiating object is effectively used instead as the instantiator. - - *Note Faces and Window-System Objects::, for more information on -fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more -information about image specifiers. *Note Toolbar::, for more -information on toolbar specifiers. - - - Function: specifier-type specifier - This function returns the type of SPECIFIER. The returned value - will be a symbol: one of `integer', `boolean', etc., as listed in - the above table. - - Functions are also provided to query whether an object is a -particular kind of specifier: - - - Function: boolean-specifier-p object - This function returns non-`nil' if OBJECT is a boolean specifier. - - - Function: integer-specifier-p object - This function returns non-`nil' if OBJECT is an integer specifier. - - - Function: natnum-specifier-p object - This function returns non-`nil' if OBJECT is a natnum specifier. - - - Function: generic-specifier-p object - This function returns non-`nil' if OBJECT is a generic specifier. - - - Function: face-boolean-specifier-p object - This function returns non-`nil' if OBJECT is a face-boolean - specifier. - - - Function: toolbar-specifier-p object - This function returns non-`nil' if OBJECT is a toolbar specifier. - - - Function: font-specifier-p object - This function returns non-`nil' if OBJECT is a font specifier. - - - Function: color-specifier-p object - This function returns non-`nil' if OBJECT is a color specifier. - - - Function: image-specifier-p object - This function returns non-`nil' if OBJECT is an image specifier. - - -File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers - -Adding specifications to a Specifier -==================================== - - - Function: add-spec-to-specifier specifier instantiator &optional - locale tag-set how-to-add - This function adds a specification to SPECIFIER. The - specification maps from LOCALE (which should be a window, buffer, - frame, device, or the symbol `global', and defaults to `global') - to INSTANTIATOR, whose allowed values depend on the type of the - specifier. Optional argument TAG-SET limits the instantiator to - apply only to the specified tag set, which should be a list of - tags all of which must match the device being instantiated over - (tags are a device type, a device class, or tags defined with - `define-specifier-tag'). Specifying a single symbol for TAG-SET - is equivalent to specifying a one-element list containing that - symbol. Optional argument HOW-TO-ADD specifies what to do if - there are already specifications in the specifier. It should be - one of - - `prepend' - Put at the beginning of the current list of instantiators for - LOCALE. - - `append' - Add to the end of the current list of instantiators for - LOCALE. - - `remove-tag-set-prepend' - This is the default. Remove any existing instantiators whose - tag set is the same as TAG-SET; then put the new instantiator - at the beginning of the current list. - - `remove-tag-set-append' - Remove any existing instantiators whose tag set is the same as - TAG-SET; then put the new instantiator at the end of the - current list. - - `remove-locale' - Remove all previous instantiators for this locale before - adding the new spec. - - `remove-locale-type' - Remove all specifications for all locales of the same type as - LOCALE (this includes LOCALE itself) before adding the new - spec. - - `remove-all' - Remove all specifications from the specifier before adding - the new spec. - - `remove-tag-set-prepend' is the default. - - You can retrieve the specifications for a particular locale or - locale type with the function `specifier-spec-list' or - `specifier-specs'. - - - Function: add-spec-list-to-specifier specifier spec-list &optional - how-to-add - This function adds a "spec-list" (a list of specifications) to - SPECIFIER. The format of a spec-list is - - `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' - - where - - * LOCALE := a window, a buffer, a frame, a device, or `global' - - * TAG-SET := an unordered list of zero or more TAGS, each of - which is a symbol - - * TAG := a device class (*note Consoles and Devices::), a - device type, or a tag defined with `define-specifier-tag' - - * INSTANTIATOR := format determined by the type of specifier - - The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A - list of inst-pairs is called an "inst-list". The pair `(LOCALE . - INST-LIST)' is called a "specification". A spec-list, then, can - be viewed as a list of specifications. - - HOW-TO-ADD specifies how to combine the new specifications with - the existing ones, and has the same semantics as for - `add-spec-to-specifier'. - - In many circumstances, the higher-level function `set-specifier' is - more convenient and should be used instead. - - - Macro: let-specifier specifier-list &rest body - This special form temporarily adds specifications to specifiers, - evaluates forms in BODY and restores the specifiers to their - previous states. The specifiers and their temporary - specifications are listed in SPECIFIER-LIST. - - The format of SPECIFIER-LIST is - - ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...) - - SPECIFIER is the specifier to be temporarily modified. VALUE is - the instantiator to be temporarily added to specifier in LOCALE. - LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in - `add-spec-to-specifier'. - - This special form is implemented as a macro; the code resulting - from macro expansion will add specifications to specifiers using - `add-spec-to-specifier'. After forms in BODY are evaluated, the - temporary specifications are removed and old specifier spec-lists - are restored. - - LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to - `nil'. The value of the last form in BODY is returned. - - NOTE: If you want the specifier's instance to change in all - circumstances, use `(selected-window)' as the LOCALE. If LOCALE - is `nil' or omitted, it defaults to `global'. - - The following example removes the 3D modeline effect in the - currently selected window for the duration of a second: - - (let-specifier ((modeline-shadow-thickness 0 (selected-window))) - (sit-for 1)) - - - Function: set-specifier specifier value &optional how-to-add - This function adds some specifications to SPECIFIER. VALUE can be - a single instantiator or tagged instantiator (added as a global - specification), a list of tagged and/or untagged instantiators - (added as a global specification), a cons of a locale and - instantiator or locale and instantiator list, a list of such - conses, or nearly any other reasonable form. More specifically, - VALUE can be anything accepted by `canonicalize-spec-list'. - - HOW-TO-ADD is the same as in `add-spec-to-specifier'. - - Note that `set-specifier' is exactly complementary to - `specifier-specs' except in the case where SPECIFIER has no specs - at all in it but `nil' is a valid instantiator (in that case, - `specifier-specs' will return `nil' (meaning no specs) and - `set-specifier' will interpret the `nil' as meaning "I'm adding a - global instantiator and its value is `nil'"), or in strange cases - where there is an ambiguity between a spec-list and an inst-list, - etc. (The built-in specifier types are designed in such a way as - to avoid any such ambiguities.) - - If you want to work with spec-lists, you should probably not use - these functions, but should use the lower-level functions - `specifier-spec-list' and `add-spec-list-to-specifier'. These - functions always work with fully-qualified spec-lists; thus, there - is no ambiguity. - - - Function: canonicalize-inst-pair inst-pair specifier-type &optional - noerror - This function canonicalizes the given INST-PAIR. - - SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST - will be used for. - - Canonicalizing means converting to the full form for an inst-pair, - i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator - is given a tag set of `nil' (the empty set), and a single tag is - converted into a tag set consisting only of that tag. - - If NOERROR is non-`nil', signal an error if the inst-pair is - invalid; otherwise return `t'. - - - Function: canonicalize-inst-list inst-list specifier-type &optional - noerror - This function canonicalizes the given INST-LIST (a list of - inst-pairs). - - SPECIFIER-TYPE specifies the type of specifier that this INST-LIST - will be used for. - - Canonicalizing means converting to the full form for an inst-list, - i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a - single inst-pair or any abbreviation thereof or a list of - (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) - - If NOERROR is non-`nil', signal an error if the inst-list is - invalid; otherwise return `t'. - - - Function: canonicalize-spec spec specifier-type &optional noerror - This function canonicalizes the given SPEC (a specification). - - SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST - will be used for. - - Canonicalizing means converting to the full form for a spec, i.e. - `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a - possibly abbreviated inst-list or a cons of a locale and a - possibly abbreviated inst-list. (See `canonicalize-inst-list'.) - - If NOERROR is `nil', signal an error if the specification is - invalid; otherwise return `t'. - - - Function: canonicalize-spec-list spec-list specifier-type &optional - noerror - This function canonicalizes the given SPEC-LIST (a list of - specifications). - - SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST - will be used for. - - Canonicalizing means converting to the full form for a spec-list, - i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This - function accepts a possibly abbreviated specification or a list of - such things. (See `canonicalize-spec'.) This is the function used - to convert spec-lists accepted by `set-specifier' and such into a - form suitable for `add-spec-list-to-specifier'. - - This function tries extremely hard to resolve any ambiguities, and - the built-in specifier types (font, image, toolbar, etc.) are - designed so that there won't be any ambiguities. - - If NOERROR is `nil', signal an error if the spec-list is invalid; - otherwise return `t'. - diff --git a/info/lispref.info-35 b/info/lispref.info-35 index db3eddf..7b1e8fa 100644 --- a/info/lispref.info-35 +++ b/info/lispref.info-35 @@ -50,6 +50,492 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 +============================ + + Instancing of a specifier in a particular window domain proceeds as +follows: + + * First, XEmacs searches for a specification whose locale is the + same as the window. If that fails, the search is repeated, + looking for a locale that is the same as the window's buffer. If + that fails, the search is repeated using the window's frame, then + using the device that frame is on. Finally, the specification + whose locale is the symbol `global' (if there is such a + specification) is considered. + + * The inst-pairs contained in the specification that was found are + considered in their order in the inst-list, looking for one whose + tag set matches the device that is derived from the window domain. + (The tag set is an unordered list of zero or more tag symbols. + For all tags that have predicates associated with them, the + predicate must match the device.) + + * If a matching tag set is found, the corresponding instantiator is + passed to the specifier's instantiation method, which is specific + to the type of the specifier. If it succeeds, the resulting + instance object is returned as the result of the instancing and + the instancing is done. Otherwise, the operation continues, + looking for another matching inst-pair in the current + specification. + + * When there are no more inst-pairs to be considered in the current + specification, the search starts over, looking for another + specification as in the first step above. + + * If all specifications are exhausted and no instance object can be + derived, the instancing fails. (Actually, this is not completely + true. Some specifier objects for built-in properties have a + "fallback" value, which is either an inst-list or another + specifier object, that is consulted if the instancing is about to + fail. If it is an inst-list, the searching proceeds using the + inst-pairs in that list. If it is a specifier, the entire + instancing starts over using that specifier instead of the given + one. Fallback values are set by the C code and cannot be + modified, except perhaps indirectly, using any Lisp functions. + The purpose of them is to supply some values to make sure that + instancing of built-in properties can't fail and to implement some + basic specifier inheritance, such as the fact that faces inherit + their properties from the `default' face.) + + It is also possible to instance a specifier over a frame domain or +device domain instead of over a window domain. The C code, for example, +instances the `top-toolbar-height' variable over a frame domain in +order to determine the height of a frame's top toolbar. Instancing over +a frame or device is similar to instancing over a window except that +specifications for locales that cannot be derived from the domain are +ignored. Specifically, instancing over a frame looks first for frame +locales, then device locales, then the `global' locale. Instancing +over a device domain looks only for device locales and the `global' +locale. + + +File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers + +Specifier Types +=============== + + There are various different types of specifiers. The type of a +specifier controls what sorts of instantiators are valid, how an +instantiator is instantiated, etc. Here is a list of built-in specifier +types: + +`boolean' + The valid instantiators are the symbols `t' and `nil'. Instance + objects are the same as instantiators so no special instantiation + function is needed. + +`integer' + The valid instantiators are integers. Instance objects are the + same as instantiators so no special instantiation function is + needed. `modeline-shadow-thickness' is an example of an integer + specifier (negative thicknesses indicate that the shadow is drawn + recessed instead of raised). + +`natnum' + The valid instantiators are natnums (non-negative integers). + Instance objects are the same as instantiators so no special + instantiation function is needed. Natnum specifiers are used for + dimension variables such as `top-toolbar-height'. + +`generic' + All Lisp objects are valid instantiators. Instance objects are + the same as instantiators so no special instantiation function is + needed. + +`font' + The valid instantiators are strings describing fonts or vectors + indicating inheritance from the font of some face. Instance + objects are font-instance objects, which are specific to a + particular device. The instantiation method for font specifiers + can fail, unlike for integer, natnum, boolean, and generic + specifiers. + +`color' + The valid instantiators are strings describing colors or vectors + indicating inheritance from the foreground or background of some + face. Instance objects are color-instance objects, which are + specific to a particular device. The instantiation method for + color specifiers can fail, as for font specifiers. + +`image' + Images are perhaps the most complicated type of built-in + specifier. The valid instantiators are strings (a filename, + inline data for a pixmap, or text to be displayed in a text glyph) + or vectors describing inline data of various sorts or indicating + inheritance from the background-pixmap property of some face. + Instance objects are either strings (for text images), + image-instance objects (for pixmap images), or subwindow objects + (for subwindow images). The instantiation method for image + specifiers can fail, as for font and color specifiers. + +`face-boolean' + The valid instantiators are the symbols `t' and `nil' and vectors + indicating inheritance from a boolean property of some face. + Specifiers of this sort are used for all of the built-in boolean + properties of faces. Instance objects are either the symbol `t' + or the symbol `nil'. + +`toolbar' + The valid instantiators are toolbar descriptors, which are lists + of toolbar-button descriptors (each of which is a vector of two or + four elements). *Note Toolbar::, for more information. + + Color and font instance objects can also be used in turn as +instantiators for a new color or font instance object. Since these +instance objects are device-specific, the instantiator can be used +directly as the new instance object, but only if they are of the same +device. If the devices differ, the base color or font of the +instantiating object is effectively used instead as the instantiator. + + *Note Faces and Window-System Objects::, for more information on +fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more +information about image specifiers. *Note Toolbar::, for more +information on toolbar specifiers. + + - Function: specifier-type specifier + This function returns the type of SPECIFIER. The returned value + will be a symbol: one of `integer', `boolean', etc., as listed in + the above table. + + Functions are also provided to query whether an object is a +particular kind of specifier: + + - Function: boolean-specifier-p object + This function returns non-`nil' if OBJECT is a boolean specifier. + + - Function: integer-specifier-p object + This function returns non-`nil' if OBJECT is an integer specifier. + + - Function: natnum-specifier-p object + This function returns non-`nil' if OBJECT is a natnum specifier. + + - Function: generic-specifier-p object + This function returns non-`nil' if OBJECT is a generic specifier. + + - Function: face-boolean-specifier-p object + This function returns non-`nil' if OBJECT is a face-boolean + specifier. + + - Function: toolbar-specifier-p object + This function returns non-`nil' if OBJECT is a toolbar specifier. + + - Function: font-specifier-p object + This function returns non-`nil' if OBJECT is a font specifier. + + - Function: color-specifier-p object + This function returns non-`nil' if OBJECT is a color specifier. + + - Function: image-specifier-p object + This function returns non-`nil' if OBJECT is an image specifier. + + +File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers + +Adding specifications to a Specifier +==================================== + + - Function: add-spec-to-specifier specifier instantiator &optional + locale tag-set how-to-add + This function adds a specification to SPECIFIER. The + specification maps from LOCALE (which should be a window, buffer, + frame, device, or the symbol `global', and defaults to `global') + to INSTANTIATOR, whose allowed values depend on the type of the + specifier. Optional argument TAG-SET limits the instantiator to + apply only to the specified tag set, which should be a list of + tags all of which must match the device being instantiated over + (tags are a device type, a device class, or tags defined with + `define-specifier-tag'). Specifying a single symbol for TAG-SET + is equivalent to specifying a one-element list containing that + symbol. Optional argument HOW-TO-ADD specifies what to do if + there are already specifications in the specifier. It should be + one of + + `prepend' + Put at the beginning of the current list of instantiators for + LOCALE. + + `append' + Add to the end of the current list of instantiators for + LOCALE. + + `remove-tag-set-prepend' + This is the default. Remove any existing instantiators whose + tag set is the same as TAG-SET; then put the new instantiator + at the beginning of the current list. + + `remove-tag-set-append' + Remove any existing instantiators whose tag set is the same as + TAG-SET; then put the new instantiator at the end of the + current list. + + `remove-locale' + Remove all previous instantiators for this locale before + adding the new spec. + + `remove-locale-type' + Remove all specifications for all locales of the same type as + LOCALE (this includes LOCALE itself) before adding the new + spec. + + `remove-all' + Remove all specifications from the specifier before adding + the new spec. + + `remove-tag-set-prepend' is the default. + + You can retrieve the specifications for a particular locale or + locale type with the function `specifier-spec-list' or + `specifier-specs'. + + - Function: add-spec-list-to-specifier specifier spec-list &optional + how-to-add + This function adds a "spec-list" (a list of specifications) to + SPECIFIER. The format of a spec-list is + + `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' + + where + + * LOCALE := a window, a buffer, a frame, a device, or `global' + + * TAG-SET := an unordered list of zero or more TAGS, each of + which is a symbol + + * TAG := a device class (*note Consoles and Devices::), a + device type, or a tag defined with `define-specifier-tag' + + * INSTANTIATOR := format determined by the type of specifier + + The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A + list of inst-pairs is called an "inst-list". The pair `(LOCALE . + INST-LIST)' is called a "specification". A spec-list, then, can + be viewed as a list of specifications. + + HOW-TO-ADD specifies how to combine the new specifications with + the existing ones, and has the same semantics as for + `add-spec-to-specifier'. + + In many circumstances, the higher-level function `set-specifier' is + more convenient and should be used instead. + + - Special Form: let-specifier specifier-list &rest body + This special form temporarily adds specifications to specifiers, + evaluates forms in BODY and restores the specifiers to their + previous states. The specifiers and their temporary + specifications are listed in SPECIFIER-LIST. + + The format of SPECIFIER-LIST is + + ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...) + + SPECIFIER is the specifier to be temporarily modified. VALUE is + the instantiator to be temporarily added to specifier in LOCALE. + LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in + `add-spec-to-specifier'. + + This special form is implemented as a macro; the code resulting + from macro expansion will add specifications to specifiers using + `add-spec-to-specifier'. After forms in BODY are evaluated, the + temporary specifications are removed and old specifier spec-lists + are restored. + + LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to + `nil'. The value of the last form in BODY is returned. + + NOTE: If you want the specifier's instance to change in all + circumstances, use `(selected-window)' as the LOCALE. If LOCALE + is `nil' or omitted, it defaults to `global'. + + The following example removes the 3D modeline effect in the + currently selected window for the duration of a second: + + (let-specifier ((modeline-shadow-thickness 0 (selected-window))) + (sit-for 1)) + + - Function: set-specifier specifier value &optional locale tag-set + how-to-add + This function adds some specifications to SPECIFIER. VALUE can be + a single instantiator or tagged instantiator (added as a global + specification), a list of tagged and/or untagged instantiators + (added as a global specification), a cons of a locale and + instantiator or locale and instantiator list, a list of such + conses, or nearly any other reasonable form. More specifically, + VALUE can be anything accepted by `canonicalize-spec-list'. + + LOCALE, TAG-SET, and HOW-TO-ADD are the same as in + `add-spec-to-specifier'. + + Note that `set-specifier' is exactly complementary to + `specifier-specs' except in the case where SPECIFIER has no specs + at all in it but `nil' is a valid instantiator (in that case, + `specifier-specs' will return `nil' (meaning no specs) and + `set-specifier' will interpret the `nil' as meaning "I'm adding a + global instantiator and its value is `nil'"), or in strange cases + where there is an ambiguity between a spec-list and an inst-list, + etc. (The built-in specifier types are designed in such a way as + to avoid any such ambiguities.) + + If you want to work with spec-lists, you should probably not use + these functions, but should use the lower-level functions + `specifier-spec-list' and `add-spec-list-to-specifier'. These + functions always work with fully-qualified spec-lists; thus, there + is no ambiguity. + + - Function: canonicalize-inst-pair inst-pair specifier-type &optional + noerror + This function canonicalizes the given INST-PAIR. + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + Canonicalizing means converting to the full form for an inst-pair, + i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator + is given a tag set of `nil' (the empty set), and a single tag is + converted into a tag set consisting only of that tag. + + If NOERROR is non-`nil', signal an error if the inst-pair is + invalid; otherwise return `t'. + + - Function: canonicalize-inst-list inst-list specifier-type &optional + noerror + This function canonicalizes the given INST-LIST (a list of + inst-pairs). + + SPECIFIER-TYPE specifies the type of specifier that this INST-LIST + will be used for. + + Canonicalizing means converting to the full form for an inst-list, + i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a + single inst-pair or any abbreviation thereof or a list of + (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) + + If NOERROR is non-`nil', signal an error if the inst-list is + invalid; otherwise return `t'. + + - Function: canonicalize-spec spec specifier-type &optional noerror + This function canonicalizes the given SPEC (a specification). + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + Canonicalizing means converting to the full form for a spec, i.e. + `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a + possibly abbreviated inst-list or a cons of a locale and a + possibly abbreviated inst-list. (See `canonicalize-inst-list'.) + + If NOERROR is `nil', signal an error if the specification is + invalid; otherwise return `t'. + + - Function: canonicalize-spec-list spec-list specifier-type &optional + noerror + This function canonicalizes the given SPEC-LIST (a list of + specifications). + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + Canonicalizing means converting to the full form for a spec-list, + i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This + function accepts a possibly abbreviated specification or a list of + such things. (See `canonicalize-spec'.) This is the function used + to convert spec-lists accepted by `set-specifier' and such into a + form suitable for `add-spec-list-to-specifier'. + + This function tries extremely hard to resolve any ambiguities, and + the built-in specifier types (font, image, toolbar, etc.) are + designed so that there won't be any ambiguities. + + 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 @@ -64,9 +550,9 @@ Retrieving the Specifications from a Specifier 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 a locale type (i.e. one of the symbols `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. @@ -77,7 +563,7 @@ Retrieving the Specifications from a Specifier 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, + 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. @@ -440,11 +926,11 @@ Functions for Checking the Validity of Specifier Components 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.) + 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 @@ -510,7 +996,7 @@ Other Functions for Working with Specifications in a Specifier 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 + 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'. @@ -607,515 +1093,3 @@ mark. * 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 ---------------- - - You can examine and modify the properties of an existing face with -the following functions. - - The following symbols have predefined meanings: - -`foreground' - The foreground color of the face. - -`background' - The background color of the face. - -`font' - The font used to display text covered by this face. - -`display-table' - The display table of the face. - -`background-pixmap' - The pixmap displayed in the background of the face. Only used by - faces on X devices. - -`underline' - Underline all text covered by this face. - -`highlight' - Highlight all text covered by this face. Only used by faces on TTY - devices. - -`dim' - Dim all text covered by this face. Only used by faces on TTY - devices. - -`blinking' - Blink all text covered by this face. Only used by faces on TTY - devices. - -`reverse' - Reverse the foreground and background colors. Only used by faces - on TTY devices. - -`doc-string' - Description of what the face's normal use is. NOTE: This is not a - specifier, unlike all the other built-in properties, and cannot - contain locale-specific values. - - - Function: set-face-property face property value &optional locale tag - how-to-add - This function changes a property of a FACE. - - 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 - font or color) 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 - `face-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 `face-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: remove-face-property face property &optional local tag-set - exact-p - This function removes a property of a FACE. - - For built-in properties, this is analogous to `remove-specifier'. - For more information, *Note Other Specification Functions::. - - When PROPERTY is not a built-in property, this function will just - remove its value if LOCALE is `nil' or `all'. However, if LOCALE - is other than that, this function will attempt to remove VALUE as - the instantiator for the given LOCALE with `remove-specifier'. If - the value of the property is not a specifier, it will be converted - into a `generic' specifier automatically. - - - Function: face-property face property &optional locale - This function returns FACE's value of the given PROPERTY. - - If LOCALE is omitted, the FACE'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 not or not may 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. strings - specifying a font or color name), 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 - `face-property-instance' actually does all this, and is used to - determine how to display the face. - - - Function: face-property-instance face property &optional domain - default no-fallback - This function returns the instance of FACE'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 will typically be a color-instance, - font-instance, or pixmap-instance object, and you can query it - using the appropriate object-specific functions. For example, you - could use `color-instance-rgb-components' to find out the RGB - (red, green, and blue) components of how the `background' property - of the `highlight' face is 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 color for - the frame that window is on; or perhaps the same color was - specified but the window is on a different X server, and that X - server has different RGB values for the color 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 a 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::. - - -File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces - -Face Convenience Functions --------------------------- - - - Function: set-face-foreground face color &optional locale tag - how-to-add - - Function: set-face-background face color &optional locale tag - how-to-add - These functions set the foreground (respectively, background) - color of face FACE to COLOR. The argument COLOR should be a - string (the name of a color) or a color object as returned by - `make-color' (*note Colors::). - - - Function: set-face-background-pixmap face pixmap &optional locale - tag how-to-add - This function sets the background pixmap of face FACE to PIXMAP. - The argument PIXMAP should be a string (the name of a bitmap or - pixmap file; the directories listed in the variable - `x-bitmap-file-path' will be searched) or a glyph object as - returned by `make-glyph' (*note Glyphs::). The argument may also - be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT - are the size in pixels, and DATA is a string, containing the raw - bits of the bitmap. - - - Function: set-face-font face font &optional locale tag how-to-add - This function sets the font of face FACE. The argument FONT - should be a string or a font object as returned by `make-font' - (*note Fonts::). - - - Function: set-face-underline-p face underline-p &optional locale tag - how-to-add - This function sets the underline property of face FACE. - - - Function: face-foreground face &optional locale - - Function: face-background face &optional locale - These functions return the foreground (respectively, background) - color specifier of face FACE. *Note Colors::. - - - Function: face-background-pixmap face &optional locale - This function return the background-pixmap glyph object of face - FACE. - - - Function: face-font face &optional locale - This function returns the font specifier of face FACE. (Note: - This is not the same as the function `face-font' in FSF Emacs.) - *Note Fonts::. - - - Function: face-font-name face &optional domain - This function returns the name of the font of face FACE, or `nil' - if it is unspecified. This is basically equivalent to `(font-name - (face-font FACE) DOMAIN)' except that it does not cause an error - if FACE's font is `nil'. (This function is named `face-font' in - FSF Emacs.) - - - Function: face-underline-p face &optional locale - This function returns the underline property of face FACE. - - - Function: face-foreground-instance face &optional domain - - Function: face-background-instance face &optional domain - These functions return the foreground (respectively, background) - color specifier of face FACE. *Note Colors::. - - - Function: face-background-pixmap-instance face &optional domain - This function return the background-pixmap glyph object of face - FACE. - - - Function: face-font-instance face &optional domain - This function returns the font specifier of face FACE. *Note - Fonts::. - - -File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces - -Other Face Display Functions ----------------------------- - - - Function: invert-face face &optional locale - Swap the foreground and background colors of face FACE. If the - face doesn't specify both foreground and background, then its - foreground and background are set to the default background and - foreground. - - - Function: face-equal face1 face2 &optional domain - This returns `t' if the faces FACE1 and FACE2 will display in the - same way. DOMAIN is as in `face-property-instance'. - - - Function: face-differs-from-default-p face &optional domain - This returns `t' if the face FACE displays differently from the - default face. DOMAIN is as in `face-property-instance'. - - -File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects - -Fonts -===== - - This section describes how to work with font specifier and font -instance objects, which encapsulate fonts in the window system. - -* Menu: - -* Font Specifiers:: Specifying how a font will appear. -* Font Instances:: What a font specifier gets instanced as. -* Font Instance Names:: The name of a font instance. -* Font Instance Size:: The size of a font instance. -* Font Instance Characteristics:: Display characteristics of font instances. -* Font Convenience Functions:: Convenience functions that automatically - instance and retrieve the properties - of a font specifier. - - -File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts - -Font Specifiers ---------------- - - - Function: font-specifier-p object - This predicate returns `t' if OBJECT is a font specifier, and - `nil' otherwise. - - - Function: make-font-specifier spec-list - Return a new `font' specifier object with the given specification - list. SPEC-LIST can be a list of specifications (each of which is - a cons of a locale and a list of instantiators), a single - instantiator, or a list of instantiators. *Note Specifiers::, for - more information about specifiers. - - Valid instantiators for font specifiers are: - - * A string naming a font (e.g. under X this might be - "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a - 14-point upright medium-weight Courier font). - - * A font instance (use that instance directly if the device - matches, or use the string that generated it). - - * A vector of no elements (only on TTY's; this means to set no - font at all, thus using the "natural" font of the terminal's - text). - - * A vector of one element (a face to inherit from). - - -File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts - -Font Instances --------------- - - - Function: font-instance-p object - This predicate returns `t' if OBJECT is a font instance, and `nil' - otherwise. - - - Function: make-font-instance name &optional device noerror - This function creates a new font-instance object of the specified - name. DEVICE specifies the device this object applies to and - defaults to the selected device. An error is signalled if the - font is unknown or cannot be allocated; however, if NOERROR is - non-`nil', `nil' is simply returned in this case. - - The returned object is a normal, first-class lisp object. The way - you "deallocate" the font is the way you deallocate any other lisp - object: you drop all pointers to it and allow it to be garbage - collected. When these objects are GCed, the underlying X data is - deallocated as well. - - -File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts - -Font Instance Names -------------------- - - - Function: list-fonts pattern &optional device - This function returns a list of font names matching the given - pattern. DEVICE specifies which device to search for names, and - defaults to the currently selected device. - - - Function: font-instance-name font-instance - This function returns the name used to allocate FONT-INSTANCE. - - - Function: font-instance-truename font-instance - This function returns the canonical name of the given font - instance. Font names are patterns which may match any number of - fonts, of which the first found is used. This returns an - unambiguous name for that font (but not necessarily its only - unambiguous name). - - -File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts - -Font Instance Size ------------------- - - - Function: x-font-size font - This function returns the nominal size of the given font. This is - done by parsing its name, so it's likely to lose. X fonts can be - specified (by the user) in either pixels or 10ths of points, and - this returns the first one it finds, so you have to decide which - units the returned value is measured in yourself ... - - - Function: x-find-larger-font font &optional device - This function loads a new, slightly larger version of the given - font (or font name). Returns the font if it succeeds, `nil' - otherwise. If scalable fonts are available, this returns a font - which is 1 point larger. Otherwise, it returns the next larger - version of this font that is defined. - - - Function: x-find-smaller-font font &optional device - This function loads a new, slightly smaller version of the given - font (or font name). Returns the font if it succeeds, `nil' - otherwise. If scalable fonts are available, this returns a font - which is 1 point smaller. Otherwise, it returns the next smaller - version of this font that is defined. - diff --git a/info/lispref.info-36 b/info/lispref.info-36 index e7c1c13..f80845e 100644 --- a/info/lispref.info-36 +++ b/info/lispref.info-36 @@ -50,12 +50,530 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 `t' if OBJECT is a face, else `nil'. + + - Function: copy-face old-face new-name &optional locale tag-set + exact-p 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, TAG-SET, EXACT-P 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 +--------------- + + You can examine and modify the properties of an existing face with +the following functions. + + The following symbols have predefined meanings: + +`foreground' + The foreground color of the face. + +`background' + The background color of the face. + +`font' + The font used to display text covered by this face. + +`display-table' + The display table of the face. + +`background-pixmap' + The pixmap displayed in the background of the face. Only used by + faces on X devices. + +`underline' + Underline all text covered by this face. + +`highlight' + Highlight all text covered by this face. Only used by faces on TTY + devices. + +`dim' + Dim all text covered by this face. Only used by faces on TTY + devices. + +`blinking' + Blink all text covered by this face. Only used by faces on TTY + devices. + +`reverse' + Reverse the foreground and background colors. Only used by faces + on TTY devices. + +`doc-string' + Description of what the face's normal use is. NOTE: This is not a + specifier, unlike all the other built-in properties, and cannot + contain locale-specific values. + + - Function: set-face-property face property value &optional locale + tag-set how-to-add + This function changes a property of a FACE. + + 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 + font or color) 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 + `face-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 `face-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: remove-face-property face property &optional locale + tag-set exact-p + This function removes a property of a FACE. + + For built-in properties, this is analogous to `remove-specifier'. + For more information, *Note Other Specification Functions::. + + When PROPERTY is not a built-in property, this function will just + remove its value if LOCALE is `nil' or `all'. However, if LOCALE + is other than that, this function will attempt to remove VALUE as + the instantiator for the given LOCALE with `remove-specifier'. If + the value of the property is not a specifier, it will be converted + into a `generic' specifier automatically. + + - Function: face-property face property &optional locale tag-set + exact-p + This function returns FACE's value of the given PROPERTY. + + If LOCALE is omitted, the FACE'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 not or not may 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. strings + specifying a font or color name), 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 + `face-property-instance' actually does all this, and is used to + determine how to display the face. + + - Function: face-property-instance face property &optional domain + default no-fallback + This function returns the instance of FACE'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 will typically be a color-instance, + font-instance, or pixmap-instance object, and you can query it + using the appropriate object-specific functions. For example, you + could use `color-instance-rgb-components' to find out the RGB + (red, green, and blue) components of how the `background' property + of the `highlight' face is 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 color for + the frame that window is on; or perhaps the same color was + specified but the window is on a different X server, and that X + server has different RGB values for the color 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 a 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::. + + +File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces + +Face Convenience Functions +-------------------------- + + - Command: set-face-foreground face color &optional locale tag-set + how-to-add + - Command: set-face-background face color &optional locale tag-set + how-to-add + These functions set the foreground (respectively, background) + color of face FACE to COLOR. The argument COLOR should be a + string (the name of a color) or a color object as returned by + `make-color' (*note Colors::). + + - Command: set-face-background-pixmap face pixmap &optional locale + tag-set how-to-add + This function sets the background pixmap of face FACE to PIXMAP. + The argument PIXMAP should be a string (the name of a bitmap or + pixmap file; the directories listed in the variable + `x-bitmap-file-path' will be searched) or a glyph object as + returned by `make-glyph' (*note Glyphs::). The argument may also + be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT + are the size in pixels, and DATA is a string, containing the raw + bits of the bitmap. + + - Command: set-face-font face font &optional locale tag-set how-to-add + This function sets the font of face FACE. The argument FONT + should be a string or a font object as returned by `make-font' + (*note Fonts::). + + - Command: set-face-underline-p face underline-p &optional locale + tag-set how-to-add + This function sets the underline property of face FACE. + + - Function: face-foreground face &optional locale tag-set exact-p + - Function: face-background face &optional locale tag-set exact-p + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap face &optional locale tag-set + exact-p + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font face &optional locale tag-set exact-p + This function returns the font specifier of face FACE. (Note: + This is not the same as the function `face-font' in FSF Emacs.) + + *Note Fonts::. + + - Function: face-font-name face &optional domain + This function returns the name of the font of face FACE, or `nil' + if it is unspecified. This is basically equivalent to `(font-name + (face-font FACE) DOMAIN)' except that it does not cause an error + if FACE's font is `nil'. (This function is named `face-font' in + FSF Emacs.) + + - Function: face-underline-p face &optional locale + This function returns the underline property of face FACE. + + - Function: face-foreground-instance face &optional domain + - Function: face-background-instance face &optional domain + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap-instance face &optional domain + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font-instance face &optional domain + This function returns the font specifier of face FACE. *Note + Fonts::. + + +File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces + +Other Face Display Functions +---------------------------- + + - Command: invert-face face &optional locale + Swap the foreground and background colors of face FACE. If the + face doesn't specify both foreground and background, then its + foreground and background are set to the default background and + foreground. + + - Function: face-equal face1 face2 &optional domain + This returns `t' if the faces FACE1 and FACE2 will display in the + same way. DOMAIN is as in `face-property-instance'. + + - Function: face-differs-from-default-p face &optional domain + This returns `t' if the face FACE displays differently from the + default face. DOMAIN is as in `face-property-instance'. + + +File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects + +Fonts +===== + + This section describes how to work with font specifier and font +instance objects, which encapsulate fonts in the window system. + +* Menu: + +* Font Specifiers:: Specifying how a font will appear. +* Font Instances:: What a font specifier gets instanced as. +* Font Instance Names:: The name of a font instance. +* Font Instance Size:: The size of a font instance. +* Font Instance Characteristics:: Display characteristics of font instances. +* Font Convenience Functions:: Convenience functions that automatically + instance and retrieve the properties + of a font specifier. + + +File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts + +Font Specifiers +--------------- + + - Function: font-specifier-p object + This predicate returns `t' if OBJECT is a font specifier, and + `nil' otherwise. + + - Function: make-font-specifier spec-list + Return a new `font' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Valid instantiators for font specifiers are: + + * A string naming a font (e.g. under X this might be + "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a + 14-point upright medium-weight Courier font). + + * A font instance (use that instance directly if the device + matches, or use the string that generated it). + + * A vector of no elements (only on TTY's; this means to set no + font at all, thus using the "natural" font of the terminal's + text). + + * A vector of one element (a face to inherit from). + + +File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts + +Font Instances +-------------- + + - Function: font-instance-p object + This predicate returns `t' if OBJECT is a font instance, and `nil' + otherwise. + + - Function: make-font-instance name &optional device noerror + This function creates a new font-instance object of the specified + name. DEVICE specifies the device this object applies to and + defaults to the selected device. An error is signalled if the + font is unknown or cannot be allocated; however, if NOERROR is + non-`nil', `nil' is simply returned in this case. + + The returned object is a normal, first-class lisp object. The way + you "deallocate" the font is the way you deallocate any other lisp + object: you drop all pointers to it and allow it to be garbage + collected. When these objects are GCed, the underlying X data is + deallocated as well. + + +File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts + +Font Instance Names +------------------- + + - Function: list-fonts pattern &optional device + This function returns a list of font names matching the given + pattern. DEVICE specifies which device to search for names, and + defaults to the currently selected device. + + - Function: font-instance-name font-instance + This function returns the name used to allocate FONT-INSTANCE. + + - Function: font-instance-truename font-instance + This function returns the canonical name of the given font + instance. Font names are patterns which may match any number of + fonts, of which the first found is used. This returns an + unambiguous name for that font (but not necessarily its only + unambiguous name). + + +File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts + +Font Instance Size +------------------ + + - Function: x-font-size font + This function returns the nominal size of the given font. This is + done by parsing its name, so it's likely to lose. X fonts can be + specified (by the user) in either pixels or 10ths of points, and + this returns the first one it finds, so you have to decide which + units the returned value is measured in yourself ... + + - Function: x-find-larger-font font &optional device + This function loads a new, slightly larger version of the given + font (or font name). Returns the font if it succeeds, `nil' + otherwise. If scalable fonts are available, this returns a font + which is 1 point larger. Otherwise, it returns the next larger + version of this font that is defined. + + - Function: x-find-smaller-font font &optional device + This function loads a new, slightly smaller version of the given + font (or font name). Returns the font if it succeeds, `nil' + otherwise. If scalable fonts are available, this returns a font + which is 1 point smaller. Otherwise, it returns the next smaller + version of this font that is defined. + + File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts Font Instance Characteristics ----------------------------- - - Function: font-instance-properties font + - Function: font-instance-properties font-instance This function returns the properties (an alist or `nil') of FONT-INSTANCE. @@ -172,7 +690,7 @@ Color Specifiers inherit from (if omitted, defaults to the same property that this face-boolean specifier is used for; if this specifier is not part of a face, the instantiator would not be valid), and - optionally a value which, if non-nil, means to invert the + optionally a value which, if non-`nil', means to invert the sense of the inherited property. @@ -511,312 +1029,3 @@ Creating Glyphs pointer glyph. Instead, you probably want to be calling `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'. - -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-37 b/info/lispref.info-37 index d4e9b21..1ba7a7d 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -50,6 +50,315 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 @@ -366,11 +675,15 @@ implies that the file must exist when the instantiator is added to the image, but does not need to exist at any other time (e.g. it may safely be a temporary file). - - Function: valid-image-instantiator-format-p format + - Function: valid-image-instantiator-format-p format &optional locale This function returns non-`nil' if FORMAT is a valid image - instantiator format. Note that the return value for many formats - listed above depends on whether XEmacs was compiled with support - for that format. + instantiator format. + + If LOCALE is non-`nil' then the format is checked in that locale. + If LOCALE is `nil' the current console is used. + + Note that the return value for many formats listed above depends on + whether XEmacs was compiled with support for that format. - Function: image-instantiator-format-list This function return a list of valid image-instantiator formats. @@ -391,10 +704,10 @@ be a temporary file). - Variable: x-bitmap-file-path A list of the directories in which X bitmap files may be found. - If nil, this is initialized from the `"*bitmapFilePath"' resource. - This is used by the `make-image-instance' function (however, note - that if the environment variable `XBMLANGPATH' is set, it is - consulted first). + If `nil', this is initialized from the `"*bitmapFilePath"' + resource. This is used by the `make-image-instance' function + (however, note that if the environment variable `XBMLANGPATH' is + set, it is consulted first).  File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images @@ -522,7 +835,7 @@ string, a mono pixmap, a color pixmap, etc. type `nothing'. - Function: widget-image-instance-p object - Return t if OBJECT is an image instance of type `widget'. + Return `t' if OBJECT is an image instance of type `widget'.  File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances @@ -531,7 +844,7 @@ Image Instance Functions ........................ - Function: make-image-instance data &optional domain dest-types - no-error + noerror This function creates a new image-instance object. DATA is an image instantiator, which describes the image (*note @@ -589,10 +902,10 @@ Image Instance Functions #### We should fix this.) n If omitted, DOMAIN defaults to the selected window. - NO-ERROR controls what happens when the image cannot be generated. - If NIL, an error message is generated. If T, no messages are - generated and this function returns NIL. If anything else, a - warning message is generated and this function returns NIL. + NOERROR controls what happens when the image cannot be generated. + If `nil', an error message is generated. If `t', no messages are + generated and this function returns `nil'. If anything else, a + warning message is generated and this function returns `nil'. - Function: colorize-image-instance image-instance foreground background @@ -852,364 +1165,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.) - diff --git a/info/lispref.info-38 b/info/lispref.info-38 index 289148a..85d95e3 100644 --- a/info/lispref.info-38 +++ b/info/lispref.info-38 @@ -50,6 +50,373 @@ 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 POSITION 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 POSITION 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 &optional frame no-preempt + This function clears and redisplays frame FRAME. + + FRAME defaults to the selected frame if omitted. + + Normally, redisplay is preempted as normal if input arrives. + However, if optional second arg NO-PREEMPT is non-`nil', redisplay + will not stop for input and is guaranteed to proceed to completion. + + 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 &optional frame + This function causes an immediate update of the cursor on FRAME, + which defaults to the selected frame. + + File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display Truncation @@ -201,7 +568,7 @@ the message stack. If a message remains at the head of the message-stack and NO-RESTORE is `nil', it will be displayed. The string which remains in the echo area will be returned, or `nil' if the - message-stack is now empty. If LABEL is nil, the entire + message-stack is now empty. If LABEL is `nil', the entire message-stack is cleared. ;; Show a message, wait for 2 seconds, and restore old minibuffer @@ -693,7 +1060,7 @@ open parenthesis when the user inserts a close parenthesis. gives good results, but the default is 1, which works on all systems. - - Function: blink-matching-open + - Command: blink-matching-open This function is the default value of `blink-paren-function'. It assumes that point follows a character with close parenthesis syntax and moves the cursor momentarily to the matching opening @@ -828,395 +1195,3 @@ effect of setting `ctl-arrow' to a non-`nil' value: (setq i (1+ i))) (aset disptab 127 "^?")) - -File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables - -Active Display Table --------------------- - - The active display table is controlled by the variable -`current-display-table'. This is a specifier, which means that you can -specify separate values for it in individual buffers, windows, frames, -and devices, as well as a global value. It also means that you cannot -set this variable using `setq'; use `set-specifier' instead. *Note -Specifiers::. (FSF Emacs uses `window-display-table', -`buffer-display-table', `standard-display-table', etc. to control the -display table. However, specifiers are a cleaner and more powerful way -of doing the same thing. FSF Emacs also uses a different format for -the contents of a display table, using additional indirection to a -"glyph table" and such. Note that "glyph" has a different meaning in -XEmacs.) - - - Variable: current-display-table - The display table currently in use. This is a specifier. - - Display tables are used to control how characters are displayed. - Each time that redisplay processes a character, it is looked up in - all the display tables that apply (obtained by calling - `specifier-instance' on `current-display-table' and any overriding - display tables specified in currently active faces). The first - entry found that matches the character determines how the - character is displayed. If there is no matching entry, the - default display method is used. (Non-control characters are - displayed as themselves and control characters are displayed - according to the buffer-local variable `ctl-arrow'. Control - characters are further affected by `control-arrow-glyph' and - `octal-escape-glyph'.) - - Each instantiator in this specifier and the display-table - specifiers in faces is a display table or a list of such tables. - If a list, each table will be searched in turn for an entry - matching a particular character. Each display table is one of - - * A vector, specifying values for characters starting at 0. - - * A char table, either of type `char' or `generic'. - - * A range table. - - Each entry in a display table should be one of - - * nil (this entry is ignored and the search continues). - - * A character (use this character; if it happens to be the same - as the original character, default processing happens, - otherwise redisplay attempts to display this character - directly; #### At some point recursive display-table lookup - will be implemented). - - * A string (display each character in the string directly; #### - At some point recursive display-table lookup will be - implemented). - - * A glyph (display the glyph; #### At some point recursive - display-table lookup will be implemented when a string glyph - is being processed). - - * A cons of the form (format "STRING") where STRING is a - printf-like spec used to process the character. #### - Unfortunately no formatting directives other than %% are - implemented. - - * A vector (each element of the vector is processed recursively; - in such a case, nil elements in the vector are simply - ignored). - - #### At some point in the near future, display tables are - likely to be expanded to include other features, such as - referencing characters in particular fonts and allowing the - character search to continue all the way up the chain of - specifier instantiators. These features are necessary to - properly display Unicode characters. - - Individual faces can also specify an overriding display table; this -is set using `set-face-display-table'. *Note Faces::. - - If no display table can be determined for a particular window, then -XEmacs uses the usual display conventions. *Note Usual Display::. - - -File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables - -Character Descriptors ---------------------- - - Each element of the display-table vector describes how to display a -particular character and is called a "character descriptor". A -character descriptor can be: - -a string - Display this particular string wherever the character is to be - displayed. - -a glyph - Display this particular glyph wherever the character is to be - displayed. - -a vector - The vector may contain strings and/or glyphs. Display the - elements of the vector one after another wherever the character is - to be displayed. - -`nil' - 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. - - Non-standard keyword `:weakness' can be `nil' (default), `t', - `key-and-value', `key', `value' or `key-or-value'. `t' is an - alias for `key-and-value'. - - A key-and-value-weak hash table, also known as a fully-weak or - simply as 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. - - A key-or-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 and the key remain unmarked outside of weak hash tables. - The pair will remain in the hash table if the value or key are - pointed to by something other than a weak hash table, even if the - other 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'. - diff --git a/info/lispref.info-39 b/info/lispref.info-39 index c94a1b1..892739d 100644 --- a/info/lispref.info-39 +++ b/info/lispref.info-39 @@ -50,6 +50,398 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables + +Active Display Table +-------------------- + + The active display table is controlled by the variable +`current-display-table'. This is a specifier, which means that you can +specify separate values for it in individual buffers, windows, frames, +and devices, as well as a global value. It also means that you cannot +set this variable using `setq'; use `set-specifier' instead. *Note +Specifiers::. (FSF Emacs uses `window-display-table', +`buffer-display-table', `standard-display-table', etc. to control the +display table. However, specifiers are a cleaner and more powerful way +of doing the same thing. FSF Emacs also uses a different format for +the contents of a display table, using additional indirection to a +"glyph table" and such. Note that "glyph" has a different meaning in +XEmacs.) + + - Variable: current-display-table + The display table currently in use. This is a specifier. + + Display tables are used to control how characters are displayed. + Each time that redisplay processes a character, it is looked up in + all the display tables that apply (obtained by calling + `specifier-instance' on `current-display-table' and any overriding + display tables specified in currently active faces). The first + entry found that matches the character determines how the + character is displayed. If there is no matching entry, the + default display method is used. (Non-control characters are + displayed as themselves and control characters are displayed + according to the buffer-local variable `ctl-arrow'. Control + characters are further affected by `control-arrow-glyph' and + `octal-escape-glyph'.) + + Each instantiator in this specifier and the display-table + specifiers in faces is a display table or a list of such tables. + If a list, each table will be searched in turn for an entry + matching a particular character. Each display table is one of + + * A vector, specifying values for characters starting at 0. + + * A char table, either of type `char' or `generic'. + + * A range table. + + Each entry in a display table should be one of + + * nil (this entry is ignored and the search continues). + + * A character (use this character; if it happens to be the same + as the original character, default processing happens, + otherwise redisplay attempts to display this character + directly; #### At some point recursive display-table lookup + will be implemented). + + * A string (display each character in the string directly; #### + At some point recursive display-table lookup will be + implemented). + + * A glyph (display the glyph; #### At some point recursive + display-table lookup will be implemented when a string glyph + is being processed). + + * A cons of the form (format "STRING") where STRING is a + printf-like spec used to process the character. #### + Unfortunately no formatting directives other than %% are + implemented. + + * A vector (each element of the vector is processed recursively; + in such a case, nil elements in the vector are simply + ignored). + + #### At some point in the near future, display tables are + likely to be expanded to include other features, such as + referencing characters in particular fonts and allowing the + character search to continue all the way up the chain of + specifier instantiators. These features are necessary to + properly display Unicode characters. + + Individual faces can also specify an overriding display table; this +is set using `set-face-display-table'. *Note Faces::. + + If no display table can be determined for a particular window, then +XEmacs uses the usual display conventions. *Note Usual Display::. + + +File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables + +Character Descriptors +--------------------- + + Each element of the display-table vector describes how to display a +particular character and is called a "character descriptor". A +character descriptor can be: + +a string + Display this particular string wherever the character is to be + displayed. + +a glyph + Display this particular glyph wherever the character is to be + displayed. + +a vector + The vector may contain strings and/or glyphs. Display the + elements of the vector one after another wherever the character is + to be displayed. + +`nil' + 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. + + Non-standard keyword `:weakness' can be `nil' (default), `t', + `key-and-value', `key', `value' or `key-or-value'. `t' is an + alias for `key-and-value'. + + A key-and-value-weak hash table, also known as a fully-weak or + simply as 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. + + A key-or-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 and the key remain unmarked outside of weak hash tables. + The pair will remain in the hash table if the value or key are + pointed to by something other than a weak hash table, even if the + other 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 @@ -162,10 +554,10 @@ 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. + - Function: copy-range-table range-table + This function returns a new range table which contains the same + values for the same ranges as RANGE-TABLE. The values will not + themselves be copied.  File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables @@ -173,23 +565,25 @@ File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Ran 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: get-range-table pos range-table &optional default + This function finds value for position POS in RANGE-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: put-range-table start end value range-table + This function sets the value for range (START, END) to be VALUE in + RANGE-TABLE. - - Function: remove-range-table start end table - This function removes the value for range (START, END) in TABLE. + - Function: remove-range-table start end range-table + This function removes the value for range (START, END) in + RANGE-TABLE. - - Function: clear-range-table table - This function flushes TABLE. + - Function: clear-range-table range-table + This function flushes RANGE-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 + - Function: map-range-table function range-table + This function maps FUNCTION over entries in RANGE-TABLE, calling + it with three args, the beginning and end of the range and the corresponding value.  @@ -230,11 +624,11 @@ Connecting to a Database available: `'hash', `'btree', and `'recno'. See the manpages for the Berkeley DB functions for more information about these types. - - Function: close-database obj - This function closes database OBJ. + - Function: close-database database + This function closes database DATABASE. - - Function: database-live-p obj - This function returns `t' iff OBJ is an active database, else + - Function: database-live-p object + This function returns `t' if OBJECT is an active database, else `nil'.  @@ -243,21 +637,21 @@ File: lispref.info, Node: Working With a Database, Next: Other Database Functi Working With a Database ======================= - - Function: get-database key dbase &optional default + - Function: get-database key database &optional default This function finds the value for KEY in DATABASE. If there is no corresponding value, DEFAULT is returned (`nil' if DEFAULT is omitted). - - Function: map-database function dbase + - Function: map-database function database This function maps FUNCTION over entries in DATABASE, calling it with two args, each key and value in the database. - - Function: put-database key val dbase &optional replace - This function stores KEY and VAL in DATABASE. If optional fourth - arg REPLACE is non-`nil', replace any existing entry in the + - Function: put-database key value database &optional replace + This function stores KEY and VALUE in DATABASE. If optional + fourth arg REPLACE is non-`nil', replace any existing entry in the database. - - Function: remove-database key dbase + - Function: remove-database key database This function removes KEY from DATABASE.  @@ -266,18 +660,17 @@ File: lispref.info, Node: Other Database Functions, Prev: Working With a Datab Other Database Functions ======================== - - Function: database-file-name obj - This function returns the filename associated with the database - OBJ. + - Function: database-file-name database + This function returns the filename associated with DATABASE. - - Function: database-last-error &optional obj - This function returns the last error associated with database OBJ. + - Function: database-last-error &optional database + This function returns the last error associated with DATABASE. - - Function: database-subtype obj - This function returns the subtype of database OBJ, if any. + - Function: database-subtype database + This function returns the subtype of DATABASE, if any. - - Function: database-type obj - This function returns the type of database OBJ. + - Function: database-type database + This function returns the type of DATABASE.  File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top @@ -336,7 +729,7 @@ The other two, `call-process' and `call-process-region', create a synchronous process and do not return a process object (*note Synchronous Processes::). - Synchronous and asynchronous processes are explained in following + Synchronous and asynchronous processes are explained in the following sections. Since the three functions are all called in a similar fashion, their common arguments are described here. @@ -368,6 +761,10 @@ passed directly to the specified program. program; it may not contain any command-line arguments. You must use ARGS to provide those. + If you want to use features of the shell, then invoke the shell +directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and +"COMMAND LINE...". + The subprocess gets its current directory from the value of `default-directory' (*note File Name Expansion::). @@ -501,14 +898,14 @@ In version 19, they return an indication of how the process terminated. (concat (file-name-as-directory file) ".") file)) - - Function: call-process-region start end program &optional delete - destination display &rest args + - Function: call-process-region start end program &optional deletep + destination displayp &rest args This function sends the text between START to END as standard input to a process running PROGRAM. It deletes the text sent if - DELETE is non-`nil'; this is useful when BUFFER is `t', to insert + DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert the output in the current buffer. - The arguments DESTINATION and DISPLAY control what to do with the + The arguments DESTINATION and DISPLAYP control what to do with the output from the subprocess, and whether to update the display as it comes in. For details, see the description of `call-process', above. If DESTINATION is the integer 0, `call-process-region' @@ -645,7 +1042,9 @@ how to create an asynchronous process with `start-process'. For subprocesses used for internal purposes by programs, it is often better to use a pipe, because they are more efficient. In addition, the total number of PTYs is limited on many systems and - it is good not to waste them. + it is good not to waste them. A rule of thumb is to use ptys for + processes the user interacts with directly, and pipes for + processes that are hidden from the user. The value `process-connection-type' is used when `start-process' is called. So you can specify how to communicate with one @@ -659,6 +1058,15 @@ how to create an asynchronous process with `start-process'. PTY, use the function `process-tty-name' (*note Process Information::). + Lisp functions that manipulate processes usually accept a PROCESS +argument. Besides using an actual process object for this argument, you +can use a process name, a buffer object, the name of a buffer, or +`nil'. Specifying a buffer or buffer name for the PROCESS argument +means use the process associated with the buffer (or the most recent +one, if there is more than one). `nil' means use the process +associated with the current buffer. *Note Process Information::. +*Note Process Buffers::. +  File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes @@ -723,9 +1131,12 @@ Process Information (process-list) => (# #) - - Function: get-process name - This function returns the process named NAME, or `nil' if there is - none. An error is signaled if NAME is not a string. + - Function: get-process process-name + This function returns the process named PROCESS-NAME. If + PROCESS-NAME is a string and there is no process with that name, + the value is `nil'. If PROCESS-NAME is actually a process, it is + returned as given. (That is not very useful, so the argument is + usually a name.) For example: (get-process "shell") => # @@ -749,9 +1160,9 @@ Process Information - Function: process-name process This function returns the name of PROCESS. - - Function: process-status process-name - This function returns the status of PROCESS-NAME as a symbol. The - argument PROCESS-NAME must be a process, a buffer, a process name + - Function: process-status process + This function returns the status of PROCESS as a symbol. The + argument PROCESS must be a process, a buffer, a process name (string) or a buffer name (string). The possible values for an actual subprocess are: @@ -777,7 +1188,7 @@ Process Information open a new connection to the same place. `nil' - if PROCESS-NAME is not the name of an existing process. + if PROCESS does not identify an existing process. (process-status "shell") => run @@ -812,398 +1223,3 @@ Process Information instead of a terminal (see `process-connection-type' in *Note Asynchronous Processes::). - -File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes - -Sending Input to Processes -========================== - - Asynchronous subprocesses receive input when it is sent to them by -XEmacs, which is done with the functions in this section. You must -specify the process to send input to, and the input data to send. The -data appears on the "standard input" of the subprocess. - - Some operating systems have limited space for buffered input in a -PTY. On these systems, Emacs sends an EOF periodically amidst the -other characters, to force them through. For most programs, these EOFs -do no harm. - - - Function: process-send-string process-name string - This function sends PROCESS-NAME the contents of STRING as - standard input. The argument PROCESS-NAME must be a process or - the name of a process. If it is `nil', the current buffer's - process is used. - - The function returns `nil'. - - (process-send-string "shell<1>" "ls\n") - => nil - - - ---------- Buffer: *shell* ---------- - ... - introduction.texi syntax-tables.texi~ - introduction.texi~ text.texi - introduction.txt text.texi~ - ... - ---------- Buffer: *shell* ---------- - - - Command: process-send-region process-name start end - This function sends the text in the region defined by START and - END as standard input to PROCESS-NAME, which is a process or a - process name. (If it is `nil', the current buffer's process is - used.) - - An error is signaled unless both START and END are integers or - markers that indicate positions in the current buffer. (It is - unimportant which number is larger.) - - - Function: process-send-eof &optional process-name - This function makes PROCESS-NAME see an end-of-file in its input. - The EOF comes after any text already sent to it. - - If PROCESS-NAME is not supplied, or if it is `nil', then this - function sends the EOF to the current buffer's process. An error - is signaled if the current buffer has no process. - - The function returns PROCESS-NAME. - - (process-send-eof "shell") - => "shell" - - -File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes - -Sending Signals to Processes -============================ - - "Sending a signal" to a subprocess is a way of interrupting its -activities. There are several different signals, each with its own -meaning. The set of signals and their names is defined by the operating -system. For example, the signal `SIGINT' means that the user has typed -`C-c', or that some analogous thing has happened. - - Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop or resume execution instead. Most -signals can optionally be handled by programs; if the program handles -the signal, then we can say nothing in general about its effects. - - The set of signals and their names is defined by the operating -system; XEmacs has facilities for sending only a few of the signals -that are defined. XEmacs can send signals only to its own subprocesses. - - You can send signals explicitly by calling the functions in this -section. XEmacs also sends signals automatically at certain times: -killing a buffer sends a `SIGHUP' signal to all its associated -processes; killing XEmacs sends a `SIGHUP' signal to all remaining -processes. (`SIGHUP' is a signal that indicates that the connection -between the user and the process is broken, for example if a connection -via a telephone line is hung up.) - - Each of the signal-sending functions takes two optional arguments: -PROCESS and CURRENT-GROUP. - - The argument PROCESS must be either a process or a buffer, the name -of one, or `nil'. If it is `nil', the process defaults to the process -associated with the current buffer. An error is signaled if PROCESS -does not identify a process. - - The argument CURRENT-GROUP is a flag that makes a difference when -you are running a job-control shell as an XEmacs subprocess. If it is -non-`nil', then the signal is sent to the current foreground process -group of the terminal that XEmacs uses to communicate with the -subprocess. If the process is a job-control shell, this means the -shell's current subjob. If it is `nil', the signal is sent to the -process group of the immediate subprocess of XEmacs. If the subprocess -is a job-control shell, this is the shell itself. - - The flag CURRENT-GROUP has no effect when a pipe is used to -communicate with the subprocess, because the operating system does not -support the distinction in the case of pipes. For the same reason, -job-control shells won't work when a pipe is used. See -`process-connection-type' in *Note Asynchronous Processes::. - - Some of the functions below take a SIGNAL argument, which identifies -a signal to be sent. It must be either an integer or a symbol which -names the signal, like `SIGSEGV'. - - - Function: process-send-signal signal &optional process current-group - This function sends the signal SIGNAL to the process PROCESS. The - following functions can be implemented in terms of - `process-send-signal'. - - - Function: interrupt-process &optional process current-group - This function interrupts the process PROCESS by sending the signal - `SIGINT'. Outside of XEmacs, typing the "interrupt character" - (normally `C-c') sends this signal. When the argument - CURRENT-GROUP is non-`nil', you can think of this function as - "typing `C-c'" on the terminal by which XEmacs talks to the - subprocess. - - - Function: kill-process &optional process current-group - This function kills the process PROCESS by sending the signal - `SIGKILL'. This signal kills the subprocess immediately, and - cannot be handled by the subprocess. - - - Function: quit-process &optional process current-group - This function sends the signal `SIGQUIT' to the process PROCESS. - This signal is the one sent by the "quit character" (usually - `C-\') when you are not inside XEmacs. - - - Function: stop-process &optional process current-group - This function stops the process PROCESS by sending the signal - `SIGTSTP'. Use `continue-process' to resume its execution. - - On systems with job control, the "stop character" (usually `C-z') - sends this signal (outside of XEmacs). When CURRENT-GROUP is - non-`nil', you can think of this function as "typing `C-z'" on the - terminal XEmacs uses to communicate with the subprocess. - - - Function: continue-process &optional process current-group - This function resumes execution of the process PROCESS by sending - it the signal `SIGCONT'. This presumes that PROCESS was stopped - previously. - - - Function: signal-process pid signal - This function sends a signal to the process with process id PID, - which need not be a child of XEmacs. The argument SIGNAL - specifies which signal to send. - - -File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes - -Receiving Output from Processes -=============================== - - There are two ways to receive the output that a subprocess writes to -its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process, or a function -called the "filter function" can be called to act on the output. If -the process has no buffer and no filter function, its output is -discarded. - -* Menu: - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* 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. - diff --git a/info/lispref.info-40 b/info/lispref.info-40 index 5c82aef..ea7b5d9 100644 --- a/info/lispref.info-40 +++ b/info/lispref.info-40 @@ -50,6 +50,411 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes + +Sending Input to Processes +========================== + + Asynchronous subprocesses receive input when it is sent to them by +XEmacs, which is done with the functions in this section. You must +specify the process to send input to, and the input data to send. The +data appears on the "standard input" of the subprocess. + + Some operating systems have limited space for buffered input in a +PTY. On these systems, XEmacs sends long input in chunks, with EOF +characters added amidst the other characters, to force the operating +system to periodically drain the input buffer. For most programs, +these EOFs do no harm. + + - Function: process-send-string process string &optional start end + This function sends PROCESS the contents of STRING as standard + input. + + The argument PROCESS may be a process or the name of a process, or + a buffer or the name of a buffer, in which case the buffer's + process is used. If it is `nil', the current buffer's process is + used. + + Optional arguments START and END specify part of STRING; see + `substring'. + + The function returns `nil'. + + (process-send-string "shell<1>" "ls\n") + => nil + + + ---------- Buffer: *shell* ---------- + ... + introduction.texi syntax-tables.texi~ + introduction.texi~ text.texi + introduction.txt text.texi~ + ... + ---------- Buffer: *shell* ---------- + + - Function: process-send-region process start end &optional buffer + This function sends the text in the region defined by START and + END as standard input to PROCESS. + + The argument PROCESS may be a process or the name of a process, or + a buffer or the name of a buffer, in which case the buffer's + process is used. If it is `nil', the current buffer's process is + used. + + An error is signaled unless both START and END are integers or + markers that indicate positions in the current buffer. (It is + unimportant which number is larger.) + + - Function: process-send-eof &optional process + This function makes PROCESS see an end-of-file in its input. The + EOF comes after any text already sent to it. + + PROCESS may be a process, a buffer, the name of a process or + buffer, or `nil', indicating the current buffer's process. An + error is signaled if PROCESS does not identify any process. + + The function returns the process object identified by PROCESS. + + (process-send-eof "shell") + => "shell" + + +File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes + +Sending Signals to Processes +============================ + + "Sending a signal" to a subprocess is a way of interrupting its +activities. There are several different signals, each with its own +meaning. The set of signals and their names is defined by the operating +system. For example, the signal `SIGINT' means that the user has typed +`C-c', or that some analogous thing has happened. + + Each signal has a standard effect on the subprocess. Most signals +kill the subprocess, but some stop or resume execution instead. Most +signals can optionally be handled by programs; if the program handles +the signal, then we can say nothing in general about its effects. + + The set of signals and their names is defined by the operating +system; XEmacs has facilities for sending only a few of the signals +that are defined. XEmacs can send signals only to its own subprocesses. + + You can send signals explicitly by calling the functions in this +section. XEmacs also sends signals automatically at certain times: +killing a buffer sends a `SIGHUP' signal to all its associated +processes; killing XEmacs sends a `SIGHUP' signal to all remaining +processes. (`SIGHUP' is a signal that indicates that the connection +between the user and the process is broken, for example if a connection +via a telephone line is hung up.) + + Each of the signal-sending functions takes two optional arguments: +PROCESS and CURRENT-GROUP. + + The argument PROCESS must be either a process or a buffer, the name +of one, or `nil'. If it is `nil', the process defaults to the process +associated with the current buffer. An error is signaled if PROCESS +does not identify a process. + + The argument CURRENT-GROUP is a flag that makes a difference when +you are running a job-control shell as an XEmacs subprocess. If it is +non-`nil', then the signal is sent to the current foreground process +group of the terminal that XEmacs uses to communicate with the +subprocess. If the process is a job-control shell, this means the +shell's current subjob. If it is `nil', the signal is sent to the +process group of the immediate subprocess of XEmacs. If the subprocess +is a job-control shell, this is the shell itself. + + The flag CURRENT-GROUP has no effect when a pipe is used to +communicate with the subprocess, because the operating system does not +support the distinction in the case of pipes. For the same reason, +job-control shells won't work when a pipe is used. See +`process-connection-type' in *Note Asynchronous Processes::. + + Some of the functions below take a SIGNAL argument, which identifies +a signal to be sent. It must be either an integer or a symbol which +names the signal, like `SIGSEGV'. + + - Function: process-send-signal signal &optional process current-group + This function sends the signal SIGNAL to the process PROCESS. The + following functions can be implemented in terms of + `process-send-signal'. + + - Function: interrupt-process &optional process current-group + This function interrupts the process PROCESS by sending the signal + `SIGINT'. Outside of XEmacs, typing the "interrupt character" + (normally `C-c') sends this signal. When the argument + CURRENT-GROUP is non-`nil', you can think of this function as + "typing `C-c'" on the terminal by which XEmacs talks to the + subprocess. + + - Function: kill-process &optional process current-group + This function kills the process PROCESS by sending the signal + `SIGKILL'. This signal kills the subprocess immediately, and + cannot be handled by the subprocess. + + - Function: quit-process &optional process current-group + This function sends the signal `SIGQUIT' to the process PROCESS. + This signal is the one sent by the "quit character" (usually + `C-\') when you are not inside XEmacs. + + - Function: stop-process &optional process current-group + This function stops the process PROCESS by sending the signal + `SIGTSTP'. Use `continue-process' to resume its execution. + + On systems with job control, the "stop character" (usually `C-z') + sends this signal (outside of XEmacs). When CURRENT-GROUP is + non-`nil', you can think of this function as "typing `C-z'" on the + terminal XEmacs uses to communicate with the subprocess. + + - Function: continue-process &optional process current-group + This function resumes execution of the process PROCESS by sending + it the signal `SIGCONT'. This presumes that PROCESS was stopped + previously. + + - Command: signal-process pid signal + This function sends a signal to the process with process id PID, + which need not be a child of XEmacs. The argument SIGNAL + specifies which signal to send. + + +File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes + +Receiving Output from Processes +=============================== + + There are two ways to receive the output that a subprocess writes to +its standard output stream. The output can be inserted in a buffer, +which is called the associated buffer of the process, or a function +called the "filter function" can be called to act on the output. If +the process has no buffer and no filter function, its output is +discarded. + +* Menu: + +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* 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 BUFFER-OR-NAME, + 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 (process string) + (let ((old-buffer (current-buffer))) + (unwind-protect + (let (moving) + (set-buffer (process-buffer process)) + (setq moving (= (point) (process-mark process))) + (save-excursion + ;; Insert the text, moving the process-marker. + (goto-char (process-mark process)) + (insert string) + (set-marker (process-mark process) (point))) + (if moving (goto-char (process-mark process)))) + (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 process)) + + 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 @@ -201,23 +606,39 @@ 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 + &optional protocol This function opens a TCP connection for a service to a host. It returns a process object to represent the connection. + Input and output work as for other process objects. + `delete-process' closes 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. + connection. It can be a buffer or the name of one. 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). + Optional fifth arg PROTOCOL is the network protocol to use. + Currently only `tcp' (Transmission Control Protocol) and `udp' + (User Datagram Protocol) are supported. When omitted, `tcp' is + assumed. + + Output via `process-send-string' and input via buffer or filter + (see `set-process-filter') are stream-oriented. That means UDP + datagrams are not guaranteed to be sent and received in discrete + packets. (But small datagrams around 500 bytes that are not + truncated by `process-send-string' are usually fine.) Note further + that the UDP protocol does not guard against lost packets. +  File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top @@ -584,7 +1005,7 @@ Killing XEmacs parent process normally resumes control. The low-level primitive for killing XEmacs is `kill-emacs'. - - Function: kill-emacs &optional exit-data + - Command: kill-emacs &optional exit-data This function exits the XEmacs process and kills it. If EXIT-DATA is an integer, then it is used as the exit status of @@ -638,15 +1059,15 @@ case you can give input to some other job such as a shell merely by moving to a different window. Therefore, suspending is not allowed when XEmacs is an X client. - - Function: suspend-emacs string + - Command: suspend-emacs &optional stuffstring This function stops XEmacs and returns control to the superior process. If and when the superior process resumes XEmacs, `suspend-emacs' returns `nil' to its caller in Lisp. - If STRING is non-`nil', its characters are sent to be read as - terminal input by XEmacs's superior shell. The characters in - STRING are not echoed by the superior shell; only the results - appear. + If optional arg STUFFSTRING is non-`nil', its characters are sent + to be read as terminal input by XEmacs's superior shell. The + characters in STUFFSTRING are not echoed by the superior shell; + only the results appear. Before suspending, `suspend-emacs' runs the normal hook `suspend-hook'. In Emacs version 18, `suspend-hook' was not a @@ -697,586 +1118,3 @@ when XEmacs is an X client. - Variable: suspend-resume-hook This variable is a normal hook run after suspending. - -File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface - -Operating System Environment -============================ - - XEmacs provides access to variables in the operating system -environment through various functions. These variables include the -name of the system, the user's UID, and so on. - - - Variable: system-type - The value of this variable is a symbol indicating the type of - operating system XEmacs is operating on. Here is a table of the - possible values: - - `aix-v3' - AIX. - - `berkeley-unix' - Berkeley BSD. - - `dgux' - Data General DGUX operating system. - - `gnu' - A GNU system using the GNU HURD and Mach. - - `hpux' - Hewlett-Packard HPUX operating system. - - `irix' - Silicon Graphics Irix system. - - `linux' - A GNU system using the Linux kernel. - - `ms-dos' - Microsoft MS-DOS "operating system." - - `next-mach' - NeXT Mach-based system. - - `rtu' - Masscomp RTU, UCB universe. - - `unisoft-unix' - UniSoft UniPlus. - - `usg-unix-v' - AT&T System V. - - `vax-vms' - VAX VMS. - - `windows-nt' - Microsoft windows NT. - - `xenix' - SCO Xenix 386. - - We do not wish to add new symbols to make finer distinctions - unless it is absolutely necessary! In fact, we hope to eliminate - some of these alternatives in the future. We recommend using - `system-configuration' to distinguish between different operating - systems. - - - Variable: system-configuration - This variable holds the three-part configuration name for the - hardware/software configuration of your system, as a string. The - convenient way to test parts of this string is with `string-match'. - - - Function: system-name - This function returns the name of the machine you are running on. - (system-name) - => "prep.ai.mit.edu" - - The symbol `system-name' is a variable as well as a function. In -fact, the function returns whatever value the variable `system-name' -currently holds. Thus, you can set the variable `system-name' in case -Emacs is confused about the name of your system. The variable is also -useful for constructing frame titles (*note Frame Titles::). - - - Variable: mail-host-address - If this variable is non-`nil', it is used instead of `system-name' - for purposes of generating email addresses. For example, it is - used when constructing the default value of `user-mail-address'. - *Note User Identification::. (Since this is done when XEmacs - starts up, the value actually used is the one saved when XEmacs - was dumped. *Note Building XEmacs::.) - - - Function: getenv var - This function returns the value of the environment variable VAR, - as a string. Within XEmacs, the environment variable values are - kept in the Lisp variable `process-environment'. - - (getenv "USER") - => "lewis" - - lewis@slug[10] % printenv - PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin - USER=lewis - TERM=ibmapa16 - SHELL=/bin/csh - HOME=/user/lewis - - - Command: setenv variable value - This command sets the value of the environment variable named - VARIABLE to VALUE. Both arguments should be strings. This - function works by modifying `process-environment'; binding that - variable with `let' is also reasonable practice. - - - Variable: process-environment - This variable is a list of strings, each describing one environment - variable. The functions `getenv' and `setenv' work by means of - this variable. - - process-environment - => ("l=/usr/stanford/lib/gnuemacs/lisp" - "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" - "USER=lewis" - "TERM=ibmapa16" - "SHELL=/bin/csh" - "HOME=/user/lewis") - - - Variable: path-separator - This variable holds a string which says which character separates - directories in a search path (as found in an environment - variable). Its value is `":"' for Unix and GNU systems, and `";"' - for MS-DOS and Windows NT. - - - Variable: invocation-name - This variable holds the program name under which Emacs was - invoked. The value is a string, and does not include a directory - name. - - - Variable: invocation-directory - This variable holds the directory from which the Emacs executable - was invoked, or perhaps `nil' if that directory cannot be - determined. - - - Variable: installation-directory - If non-`nil', this is a directory within which to look for the - `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs - can't find those directories in their standard installed - locations, but can find them in a directory related somehow to the - one containing the Emacs executable. - - - Function: load-average &optional use-floats - This function returns a list of the current 1-minute, 5-minute and - 15-minute load averages. The values are integers that are 100 - times the system load averages. (The load averages indicate the - number of processes trying to run.) - - When USE-FLOATS is non-`nil', floats will be returned instead of - integers. These floats are not multiplied by 100. - - (load-average) - => (169 158 164) - (load-average t) - => (1.69921875 1.58984375 1.640625) - - lewis@rocky[5] % uptime - 8:06pm up 16 day(s), 21:57, 40 users, - load average: 1.68, 1.59, 1.64 - - If the 5-minute or 15-minute load averages are not available, - return a shortened list, containing only those averages which are - available. - - On some systems, this function may require special privileges to - run, or it may be unimplemented for the particular system type. - In that case, the function will signal an error. - - - Function: emacs-pid - This function returns the process ID of the Emacs process. - - - Function: setprv privilege-name &optional setp getprv - This function sets or resets a VMS privilege. (It does not exist - on Unix.) The first arg is the privilege name, as a string. The - second argument, SETP, is `t' or `nil', indicating whether the - privilege is to be turned on or off. Its default is `nil'. The - function returns `t' if successful, `nil' otherwise. - - If the third argument, GETPRV, is non-`nil', `setprv' does not - change the privilege, but returns `t' or `nil' indicating whether - the privilege is currently enabled. - - -File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface - -User Identification -=================== - - - Variable: user-mail-address - This holds the nominal email address of the user who is using - Emacs. When Emacs starts up, it computes a default value that is - usually right, but users often set this themselves when the - default value is not right. - - - Function: user-login-name &optional uid - If you don't specify UID, this function returns the name under - which the user is logged in. If the environment variable `LOGNAME' - is set, that value is used. Otherwise, if the environment variable - `USER' is set, that value is used. Otherwise, the value is based - on the effective UID, not the real UID. - - If you specify UID, the value is the user name that corresponds to - UID (which should be an integer). - - (user-login-name) - => "lewis" - - - Function: user-real-login-name - This function returns the user name corresponding to Emacs's real - UID. This ignores the effective UID and ignores the environment - variables `LOGNAME' and `USER'. - - - Variable: user-full-name - This variable holds the name of the user running this Emacs. It is - initialized at startup time from the value of `NAME' environment - variable. You can change the value of this variable to alter the - result of the `user-full-name' function. - - - Function: user-full-name &optional user - This function returns the full name of USER. If USER is `nil', it - defaults to the user running this Emacs. In that case, the value - of `user-full-name' variable, if non-`nil', will be used. - - If USER is specified explicitly, `user-full-name' variable is - ignored. - - (user-full-name) - => "Hrvoje Niksic" - (setq user-full-name "Hrvoje \"Niksa\" Niksic") - (user-full-name) - => "Hrvoje \"Niksa\" Niksic" - (user-full-name "hniksic") - => "Hrvoje Niksic" - - The symbols `user-login-name', `user-real-login-name' and -`user-full-name' are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to "fake out" Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (*note Frame -Titles::). - - - Function: user-real-uid - This function returns the real UID of the user. - - (user-real-uid) - => 19 - - - Function: user-uid - This function returns the effective UID of the user. - - - Function: user-home-directory - This function returns the "`HOME'" directory of the user, and is - intended to replace occurrences of "`(getenv "HOME")'". Under - Unix systems, the following is done: - - 1. Return the value of "`(getenv "HOME")'", if set. - - 2. Return "/", as a fallback, but issue a warning. (Future - versions of XEmacs will also attempt to lookup the `HOME' - directory via `getpwent()', but this has not yet been - implemented.) - - Under MS Windows, this is done: - - 1. Return the value of "`(getenv "HOME")'", if set. - - 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are - both set, return the concatenation (the following description - uses MS Windows environment variable substitution syntax): - `%HOMEDRIVE%%HOMEDIR%'. - - 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. - diff --git a/info/lispref.info-41 b/info/lispref.info-41 index c4ba9dd..62e99b6 100644 --- a/info/lispref.info-41 +++ b/info/lispref.info-41 @@ -50,12 +50,589 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface + +Operating System Environment +============================ + + XEmacs provides access to variables in the operating system +environment through various functions. These variables include the +name of the system, the user's UID, and so on. + + - Variable: system-type + The value of this variable is a symbol indicating the type of + operating system XEmacs is operating on. Here is a table of the + possible values: + + `aix-v3' + AIX. + + `berkeley-unix' + Berkeley BSD. + + `dgux' + Data General DGUX operating system. + + `gnu' + A GNU system using the GNU HURD and Mach. + + `hpux' + Hewlett-Packard HPUX operating system. + + `irix' + Silicon Graphics Irix system. + + `linux' + A GNU system using the Linux kernel. + + `ms-dos' + Microsoft MS-DOS "operating system." + + `next-mach' + NeXT Mach-based system. + + `rtu' + Masscomp RTU, UCB universe. + + `unisoft-unix' + UniSoft UniPlus. + + `usg-unix-v' + AT&T System V. + + `windows-nt' + Microsoft windows NT. + + `xenix' + SCO Xenix 386. + + We do not wish to add new symbols to make finer distinctions + unless it is absolutely necessary! In fact, we hope to eliminate + some of these alternatives in the future. We recommend using + `system-configuration' to distinguish between different operating + systems. + + - Variable: system-configuration + This variable holds the three-part configuration name for the + hardware/software configuration of your system, as a string. The + convenient way to test parts of this string is with `string-match'. + + - Function: system-name + This function returns the name of the machine you are running on. + (system-name) + => "prep.ai.mit.edu" + + The symbol `system-name' is a variable as well as a function. In +fact, the function returns whatever value the variable `system-name' +currently holds. Thus, you can set the variable `system-name' in case +Emacs is confused about the name of your system. The variable is also +useful for constructing frame titles (*note Frame Titles::). + + - Variable: mail-host-address + If this variable is non-`nil', it is used instead of `system-name' + for purposes of generating email addresses. For example, it is + used when constructing the default value of `user-mail-address'. + *Note User Identification::. (Since this is done when XEmacs + starts up, the value actually used is the one saved when XEmacs + was dumped. *Note Building XEmacs::.) + + - Command: getenv var &optional interactivep + This function returns the value of the environment variable VAR, + as a string. Within XEmacs, the environment variable values are + kept in the Lisp variable `process-environment'. + + When invoked interactively, `getenv' prints the value in the echo + area. + + (getenv "USER") + => "lewis" + + lewis@slug[10] % printenv + PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin + USER=lewis + TERM=ibmapa16 + SHELL=/bin/csh + HOME=/user/lewis + + - Command: setenv variable &optional value unset + This command sets the value of the environment variable named + VARIABLE to VALUE. Both arguments should be strings. This + function works by modifying `process-environment'; binding that + variable with `let' is also reasonable practice. + + - Variable: process-environment + This variable is a list of strings, each describing one environment + variable. The functions `getenv' and `setenv' work by + manipulating this variable. + + process-environment + => ("l=/usr/stanford/lib/gnuemacs/lisp" + "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" + "USER=lewis" + "TERM=ibmapa16" + "SHELL=/bin/csh" + "HOME=/user/lewis") + + - Variable: path-separator + This variable holds a string which says which character separates + directories in a search path (as found in an environment + variable). Its value is `":"' for Unix and GNU systems, and `";"' + for MS-DOS and Windows NT. + + - Variable: invocation-name + This variable holds the program name under which Emacs was + invoked. The value is a string, and does not include a directory + name. + + - Variable: invocation-directory + This variable holds the directory from which the Emacs executable + was invoked, or perhaps `nil' if that directory cannot be + determined. + + - Variable: installation-directory + If non-`nil', this is a directory within which to look for the + `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs + can't find those directories in their standard installed + locations, but can find them in a directory related somehow to the + one containing the Emacs executable. + + - Function: load-average &optional use-floats + This function returns a list of the current 1-minute, 5-minute and + 15-minute load averages. The values are integers that are 100 + times the system load averages. (The load averages indicate the + number of processes trying to run.) + + When USE-FLOATS is non-`nil', floats will be returned instead of + integers. These floats are not multiplied by 100. + + (load-average) + => (169 158 164) + (load-average t) + => (1.69921875 1.58984375 1.640625) + + lewis@rocky[5] % uptime + 8:06pm up 16 day(s), 21:57, 40 users, + load average: 1.68, 1.59, 1.64 + + If the 5-minute or 15-minute load averages are not available, + return a shortened list, containing only those averages which are + available. + + On some systems, this function may require special privileges to + run, or it may be unimplemented for the particular system type. + In that case, the function will signal an error. + + - Function: emacs-pid + This function returns the process ID of the Emacs process. + + +File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface + +User Identification +=================== + + - Variable: user-mail-address + This holds the nominal email address of the user who is using + Emacs. When Emacs starts up, it computes a default value that is + usually right, but users often set this themselves when the + default value is not right. + + - Function: user-login-name &optional uid + If you don't specify UID, this function returns the name under + which the user is logged in. If the environment variable `LOGNAME' + is set, that value is used. Otherwise, if the environment variable + `USER' is set, that value is used. Otherwise, the value is based + on the effective UID, not the real UID. + + If you specify UID, the value is the user name that corresponds to + UID (which should be an integer). + + (user-login-name) + => "lewis" + + - Function: user-real-login-name + This function returns the user name corresponding to Emacs's real + UID. This ignores the effective UID and ignores the environment + variables `LOGNAME' and `USER'. + + - Variable: user-full-name + This variable holds the name of the user running this Emacs. It is + initialized at startup time from the value of `NAME' environment + variable. You can change the value of this variable to alter the + result of the `user-full-name' function. + + - Function: user-full-name &optional user + This function returns the full name of USER. If USER is `nil', it + defaults to the user running this Emacs. In that case, the value + of `user-full-name' variable, if non-`nil', will be used. + + If USER is specified explicitly, `user-full-name' variable is + ignored. + + (user-full-name) + => "Hrvoje Niksic" + (setq user-full-name "Hrvoje \"Niksa\" Niksic") + (user-full-name) + => "Hrvoje \"Niksa\" Niksic" + (user-full-name "hniksic") + => "Hrvoje Niksic" + + The symbols `user-login-name', `user-real-login-name' and +`user-full-name' are variables as well as functions. The functions +return the same values that the variables hold. These variables allow +you to "fake out" Emacs by telling the functions what to return. The +variables are also useful for constructing frame titles (*note Frame +Titles::). + + - Function: user-real-uid + This function returns the real UID of the user. + + (user-real-uid) + => 19 + + - Function: user-uid + This function returns the effective UID of the user. + + - Function: user-home-directory + This function returns the "`HOME'" directory of the user, and is + intended to replace occurrences of "`(getenv "HOME")'". Under + Unix systems, the following is done: + + 1. Return the value of "`(getenv "HOME")'", if set. + + 2. Return "/", as a fallback, but issue a warning. (Future + versions of XEmacs will also attempt to lookup the `HOME' + directory via `getpwent()', but this has not yet been + implemented.) + + Under MS Windows, this is done: + + 1. Return the value of "`(getenv "HOME")'", if set. + + 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are + both set, return the concatenation (the following description + uses MS Windows environment variable substitution syntax): + `%HOMEDRIVE%%HOMEDIR%'. + + 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 &optional specified-time + This function converts a time value into calendrical information. + The optional SPECIFIED-TIME should be a list of (HIGH LOW . + IGNORED) or (HIGH . LOW), as from `current-time' and + `file-attributes', or `nil' to use the current time. + + 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 + - Function: set-input-mode interrupt flow meta &optional quit-char + console 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 @@ -83,7 +660,7 @@ Input Modes The `current-input-mode' function returns the input mode settings XEmacs is currently using. - - Function: current-input-mode + - Function: current-input-mode &optional console 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: @@ -287,10 +864,10 @@ the proper value, but others do not. If XEmacs has the wrong value, it makes decisions that are less than optimal. To fix the problem, use `set-device-baud-rate'. - - Function: set-device-baud-rate &optional device + - Function: set-device-baud-rate device baud-rate This function sets the output speed of DEVICE. See `device-baud-rate'. DEVICE defaults to the selected device - (usually the only device) if omitted. + (usually the only device) if `nil'. - Function: send-string-to-terminal char-or-string &optional stdout-p device @@ -374,12 +951,16 @@ terminals, this problem is gradually being cured. For the mean time, XEmacs provides a convenient way of enabling flow control if you want it: call the function `enable-flow-control'. - - Function: enable-flow-control + - Command: enable-flow-control &optional argument This function enables use of `C-s' and `C-q' for output flow control, and provides the characters `C-\' and `C-^' as aliases for them using `keyboard-translate-table' (*note Translating Input::). + With optional argument ARGUMENT (interactively the prefix + argument), enable flow control mode if ARGUMENT is positive; else + disable it. + You can use the function `enable-flow-control-on' in your `.emacs' file to enable flow control automatically on certain terminal types. @@ -505,11 +1086,25 @@ clients that still use them. This function returns the contents of cut buffer number N. (This function is called `x-get-cut-buffer' in FSF Emacs.) - - Function: x-store-cutbuffer string + - Function: x-store-cutbuffer string &optional push This function stores STRING into the first cut buffer (cut buffer - 0), moving the other values down through the series of cut buffers, - kill-ring-style. (This function is called `x-set-cut-buffer' in FSF - Emacs.) + 0). + + Normally, the contents of the first cut buffer are simply replaced + by STRING. However, if optional argument PUSH is non-`nil', the + cut buffers are rotated. This means that the previous value of + the first cut buffer moves to the second cut buffer, and the + second to the third, and so on, moving the other values down + through the series of cut buffers, kill-ring-style. There are 8 + cut buffers altogether. + + Cut buffers are considered obsolete; you should use selections + instead. + + This function has no effect if support for cut buffers was not + compiled in. + + This function is called `x-set-cut-buffer' in FSF Emacs.  File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows @@ -644,7 +1239,7 @@ Resources XEmacs is dumped, or by setting it in the file `lisp/term/x-win.el'. - By default, this variable is nil at startup. When the connection + By default, this variable is `nil' at startup. When the connection to the X server is first initialized, the X resource database will be consulted and the value will be set according to whether any resources are found for the application class "XEmacs". @@ -677,495 +1272,3 @@ optional and defaults to the selected device. (Note that this is different from previous versions of XEmacs, which returned `StaticGray', `GrayScale', etc.) - -File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server - -Restricting Access to the Server by Other Apps ----------------------------------------------- - - - Function: x-grab-keyboard &optional device - This function grabs the keyboard on the given device (defaulting - to the selected one). So long as the keyboard is grabbed, all - keyboard events will be delivered to XEmacs--it is not possible - for other X clients to eavesdrop on them. Ungrab the keyboard - with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t' - if the grab was successful; `nil' otherwise. - - - Function: x-ungrab-keyboard &optional device - This function releases a keyboard grab made with `x-grab-keyboard'. - - - Function: x-grab-pointer &optional device cursor ignore-keyboard - This function grabs the pointer and restricts it to its current - window. If optional DEVICE argument is `nil', the selected device - will be used. If optional CURSOR argument is non-`nil', change - the pointer shape to that until `x-ungrab-pointer' is called (it - should be an object returned by the `make-cursor' function). If - the second optional argument IGNORE-KEYBOARD is non-`nil', ignore - all keyboard events during the grab. Returns `t' if the grab is - successful, `nil' otherwise. - - - Function: x-ungrab-pointer &optional device - This function releases a pointer grab made with `x-grab-pointer'. - If optional first arg DEVICE is `nil' the selected device is used. - If it is `t' the pointer will be released on all X devices. - - -File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows - -Miscellaneous X Functions and Variables -======================================= - - - Variable: x-bitmap-file-path - This variable holds a list of the directories in which X bitmap - files may be found. If `nil', this is initialized from the - `"*bitmapFilePath"' resource. This is used by the - `make-image-instance' function (however, note that if the - environment variable `XBMLANGPATH' is set, it is consulted first). - - - Variable: x-library-search-path - This variable holds the search path used by `read-color' to find - `rgb.txt'. - - - Function: x-valid-keysym-name-p keysym - This function returns true if KEYSYM names a keysym that the X - library knows about. Valid keysyms are listed in the files - `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or - whatever the equivalents are on your system. - - - Function: x-window-id &optional frame - This function returns the ID of the X11 window. This gives us a - chance to manipulate the Emacs window from within a different - program. Since the ID is an unsigned long, we return it as a - string. - - - Variable: x-allow-sendevents - If non-`nil', synthetic events are allowed. `nil' means they are - ignored. Beware: allowing XEmacs to process SendEvents opens a - big security hole. - - - Function: x-debug-mode arg &optional device - With a true arg, make the connection to the X server synchronous. - With false, make it asynchronous. Synchronous connections are - much slower, but are useful for debugging. (If you get X errors, - make the connection synchronous, and use a debugger to set a - breakpoint on `x_error_handler'. Your backtrace of the C stack - will now be useful. In asynchronous mode, the stack above - `x_error_handler' isn't helpful because of buffering.) If DEVICE - is not specified, the selected device is assumed. - - Calling this function is the same as calling the C function - `XSynchronize', or starting the program with the `-sync' command - line argument. - - - Variable: x-debug-events - If non-zero, debug information about events that XEmacs sees is - displayed. Information is displayed on stderr. Currently defined - values are: - - * 1 == non-verbose output - - * 2 == verbose output - - -File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top - -ToolTalk Support -**************** - -* Menu: - -* XEmacs ToolTalk API Summary:: -* Sending Messages:: -* Receiving Messages:: - - -File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support - -XEmacs ToolTalk API Summary -=========================== - - The XEmacs Lisp interface to ToolTalk is similar, at least in spirit, -to the standard C ToolTalk API. Only the message and pattern parts of -the API are supported at present; more of the API could be added if -needed. The Lisp interface departs from the C API in a few ways: - - * ToolTalk is initialized automatically at XEmacs startup-time. - Messages can only be sent other ToolTalk applications connected to - the same X11 server that XEmacs is running on. - - * There are fewer entry points; polymorphic functions with keyword - arguments are used instead. - - * The callback interface is simpler and marginally less functional. - A single callback may be associated with a message or a pattern; - the callback is specified with a Lisp symbol (the symbol should - have a function binding). - - * The session attribute for messages and patterns is always - initialized to the default session. - - * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one - can substitute the corresponding symbol, e.g. `'TT_SESSION'. This - simplifies building lists that represent messages and patterns. - - -File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support - -Sending Messages -================ - -* Menu: - -* Example of Sending Messages:: -* Elisp Interface for Sending Messages:: - - -File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages - -Example of Sending Messages ---------------------------- - - Here's a simple example that sends a query to another application -and then displays its reply. Both the query and the reply are stored -in the first argument of the message. - - (defun tooltalk-random-query-handler (msg) - (let ((state (get-tooltalk-message-attribute msg 'state))) - (cond - ((eq state 'TT_HANDLED) - (message (get-tooltalk-message-attribute msg arg_val 0))) - ((memq state '(TT_FAILED TT_REJECTED)) - (message "Random query turns up nothing"))))) - - (defvar random-query-message - '( class TT_REQUEST - scope TT_SESSION - address TT_PROCEDURE - op "random-query" - args '((TT_INOUT "?" "string")) - callback tooltalk-random-query-handler)) - - (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: PostgreSQL Support, 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.2 () - - * 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 auto-detects 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. - - The low-level API should be used directly for very specific purposes -(such as multiple operations on a connection) only. The higher-level -functions provide a more convenient way to access LDAP directories -hiding the subtleties of handling the connection, translating arguments -and ensuring compliance with LDAP internationalization rules and formats -(currently partly implemented only). - -* 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 -* LDAP Internationalization:: I18n variables and functions - diff --git a/info/lispref.info-42 b/info/lispref.info-42 index 8185761..5bebd1f 100644 --- a/info/lispref.info-42 +++ b/info/lispref.info-42 @@ -50,6 +50,502 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server + +Restricting Access to the Server by Other Apps +---------------------------------------------- + + - Function: x-grab-keyboard &optional device + This function grabs the keyboard on the given device (defaulting + to the selected one). So long as the keyboard is grabbed, all + keyboard events will be delivered to XEmacs--it is not possible + for other X clients to eavesdrop on them. Ungrab the keyboard + with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t' + if the grab was successful; `nil' otherwise. + + - Function: x-ungrab-keyboard &optional device + This function releases a keyboard grab made with `x-grab-keyboard'. + + - Function: x-grab-pointer &optional device cursor ignore-keyboard + This function grabs the pointer and restricts it to its current + window. If optional DEVICE argument is `nil', the selected device + will be used. If optional CURSOR argument is non-`nil', change + the pointer shape to that until `x-ungrab-pointer' is called (it + should be an object returned by the `make-cursor' function). If + the second optional argument IGNORE-KEYBOARD is non-`nil', ignore + all keyboard events during the grab. Returns `t' if the grab is + successful, `nil' otherwise. + + - Function: x-ungrab-pointer &optional device + This function releases a pointer grab made with `x-grab-pointer'. + If optional first arg DEVICE is `nil' the selected device is used. + If it is `t' the pointer will be released on all X devices. + + +File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows + +Miscellaneous X Functions and Variables +======================================= + + - Variable: x-bitmap-file-path + This variable holds a list of the directories in which X bitmap + files may be found. If `nil', this is initialized from the + `"*bitmapFilePath"' resource. This is used by the + `make-image-instance' function (however, note that if the + environment variable `XBMLANGPATH' is set, it is consulted first). + + - Variable: x-library-search-path + This variable holds the search path used by `read-color' to find + `rgb.txt'. + + - Function: x-valid-keysym-name-p keysym + This function returns true if KEYSYM names a keysym that the X + library knows about. Valid keysyms are listed in the files + `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or + whatever the equivalents are on your system. + + - Function: x-window-id &optional frame + This function returns the ID of the X11 window. This gives us a + chance to manipulate the Emacs window from within a different + program. Since the ID is an unsigned long, we return it as a + string. + + - Variable: x-allow-sendevents + If non-`nil', synthetic events are allowed. `nil' means they are + ignored. Beware: allowing XEmacs to process SendEvents opens a + big security hole. + + - Function: x-debug-mode arg &optional device + With a true arg, make the connection to the X server synchronous. + With false, make it asynchronous. Synchronous connections are + much slower, but are useful for debugging. (If you get X errors, + make the connection synchronous, and use a debugger to set a + breakpoint on `x_error_handler'. Your backtrace of the C stack + will now be useful. In asynchronous mode, the stack above + `x_error_handler' isn't helpful because of buffering.) If DEVICE + is not specified, the selected device is assumed. + + Calling this function is the same as calling the C function + `XSynchronize', or starting the program with the `-sync' command + line argument. + + - Variable: x-debug-events + If non-zero, debug information about events that XEmacs sees is + displayed. Information is displayed on stderr. Currently defined + values are: + + * 1 == non-verbose output + + * 2 == verbose output + + +File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top + +ToolTalk Support +**************** + +* Menu: + +* XEmacs ToolTalk API Summary:: +* Sending Messages:: +* Receiving Messages:: + + +File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support + +XEmacs ToolTalk API Summary +=========================== + + The XEmacs Lisp interface to ToolTalk is similar, at least in spirit, +to the standard C ToolTalk API. Only the message and pattern parts of +the API are supported at present; more of the API could be added if +needed. The Lisp interface departs from the C API in a few ways: + + * ToolTalk is initialized automatically at XEmacs startup-time. + Messages can only be sent other ToolTalk applications connected to + the same X11 server that XEmacs is running on. + + * There are fewer entry points; polymorphic functions with keyword + arguments are used instead. + + * The callback interface is simpler and marginally less functional. + A single callback may be associated with a message or a pattern; + the callback is specified with a Lisp symbol (the symbol should + have a function binding). + + * The session attribute for messages and patterns is always + initialized to the default session. + + * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one + can substitute the corresponding symbol, e.g. `'TT_SESSION'. This + simplifies building lists that represent messages and patterns. + + +File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support + +Sending Messages +================ + +* Menu: + +* Example of Sending Messages:: +* Elisp Interface for Sending Messages:: + + +File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages + +Example of Sending Messages +--------------------------- + + Here's a simple example that sends a query to another application +and then displays its reply. Both the query and the reply are stored +in the first argument of the message. + + (defun tooltalk-random-query-handler (msg) + (let ((state (get-tooltalk-message-attribute msg 'state))) + (cond + ((eq state 'TT_HANDLED) + (message (get-tooltalk-message-attribute msg arg_val 0))) + ((memq state '(TT_FAILED TT_REJECTED)) + (message "Random query turns up nothing"))))) + + (defvar random-query-message + '( class TT_REQUEST + scope TT_SESSION + address TT_PROCEDURE + op "random-query" + args '((TT_INOUT "?" "string")) + callback tooltalk-random-query-handler)) + + (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 &optional no-callback + 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. + + Optional arg NO-CALLBACK says don't add a C-level callback at all. + Normally don't do that; just don't specify the Lisp callback when + calling `make-tooltalk-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 pattern + XEmacs will begin receiving messages that match this pattern. + + - Function: unregister-tooltalk-pattern pattern + XEmacs will stop receiving messages that match this pattern. + + - Function: add-tooltalk-pattern-attribute value pattern 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 pattern mode vtype &optional value + Add one fully-specified argument to a ToolTalk pattern. MODE must + be one of `TT_IN', `TT_INOUT', or `TT_OUT'. VTYPE 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 pattern + 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: PostgreSQL Support, 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.2 () + + * 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 auto-detects 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. + + The low-level API should be used directly for very specific purposes +(such as multiple operations on a connection) only. The higher-level +functions provide a more convenient way to access LDAP directories +hiding the subtleties of handling the connection, translating arguments +and ensuring compliance with LDAP internationalization rules and formats +(currently partly implemented only). + +* 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 +* LDAP Internationalization:: I18n variables and functions + + File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API LDAP Variables @@ -145,7 +641,7 @@ function) or `ldap-search-entries' (high-level search function) according to the actual parameters. A direct call to one of these two functions is preferred since it is faster and unambiguous. - - Function: ldap-search-entries filter &optional host attributes + - Command: ldap-search-entries filter &optional host attributes attrsonly withdn Perform an LDAP search. FILTER is the search filter *note Syntax of Search Filters:: HOST is the LDAP host on which to perform the @@ -164,8 +660,8 @@ functions is preferred since it is faster and unambiguous. specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)' where DN the distinguished name of an entry to add, the following are cons cells containing attribute/value string pairs. HOST is - the LDAP host, defaulting to `ldap-default-host' BINDDN is the DN - to bind as to the server PASSWD is the corresponding password. + the LDAP host, defaulting to `ldap-default-host'. BINDDN is the + DN to bind as to the server. PASSWD is the corresponding password. - Function: ldap-modify-entries entry-mods &optional host binddn passwd Modify entries of an LDAP directory. ENTRY_MODS is a list of @@ -177,14 +673,14 @@ functions is preferred since it is faster and unambiguous. depending on MOD-OP. MOD-OP is the type of modification, one of the symbols `add', `delete' or `replace'. ATTR is the LDAP attribute type to modify. HOST is the LDAP host, defaulting to - `ldap-default-host' BINDDN is the DN to bind as to the server - PASSWD is the corresponding password" + `ldap-default-host'. BINDDN is the DN to bind as to the server. + PASSWD is the corresponding password. - Function: ldap-delete-entries dn &optional host binddn passwd Delete an entry from an LDAP directory. DN is the distinguished name of an entry to delete or a list of those. HOST is the LDAP - host, defaulting to `ldap-default-host' BINDDN is the DN to bind - as to the server PASSWD is the corresponding password. + host, defaulting to `ldap-default-host'. BINDDN is the DN to bind + as to the server. PASSWD is the corresponding password.  File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API @@ -220,10 +716,10 @@ The LDAP Lisp 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 + 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 + Return non-`nil' if LDAP is an active LDAP connection.  File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Low-level Operations on a LDAP Server, Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API @@ -257,17 +753,17 @@ Opening and Closing a LDAP Connection `always', `search' or `find' and defines how aliases are dereferenced. `never' - Aliases are never dereferenced + Aliases are never dereferenced. `always' - Aliases are always dereferenced + Aliases are always dereferenced. `search' - Aliases are dereferenced when searching + Aliases are dereferenced when searching. `find' Aliases are dereferenced when locating the base object - for the search The default is `never'. + for the search. The default is `never'. `timelimit' The timeout limit for the connection in seconds. @@ -277,7 +773,7 @@ Opening and Closing a LDAP Connection performed on this connection. - Function: ldap-close ldap - Close the connection represented by LDAP + Close the connection represented by LDAP.  File: lispref.info, Node: Low-level Operations on a LDAP Server, Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API @@ -291,23 +787,24 @@ 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-basic ldap filter base scope attrs attrsonly + - Function: ldap-search-basic ldap filter &optional base scope attrs + attrsonly withdn verbose 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 - If `withdn' is non-`nil' then each entry in the result is - prepended with its distinguished name DN If `verbose' is non-`nil' - then progress messages are echoed The function returns a list of + 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. + If WITHDN is non-`nil' then each entry in the result is prepended + with its distinguished name DN. If VERBOSE is non-`nil' then + progress messages are echoed The function returns a list of matching entries. Each entry is itself an alist of attribute/value pairs optionally preceded by the DN of the entry - according to the value of `withdn'. + according to the value of WITHDN. - Function: ldap-add ldap dn entry Add ENTRY to a LDAP directory which a connection LDAP has been @@ -323,12 +820,12 @@ made on the same connection, then the session must be closed with ...)' MOD-OP and ATTR are mandatory, VALUES are optional depending on MOD-OP. MOD-OP is the type of modification, one of the symbols `add', `delete' or `replace'. ATTR is the LDAP - attribute type to modify + attribute type to modify. - Function: ldap-delete ldap dn Delete an entry to an LDAP directory. LDAP is an LDAP connection object created with `ldap-open'. DN is the distinguished name of - the entry to delete + the entry to delete.  File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API @@ -372,7 +869,7 @@ LDAP Internationalization Variables - Variable: ldap-default-attribute-decoder Decoder function to use for attributes whose syntax is unknown. Such a function receives an encoded attribute value as a string - and should return the decoded value as a string + and should return the decoded value as a string. - Variable: ldap-attribute-syntax-encoders A vector of functions used to encode LDAP attribute values. The @@ -390,7 +887,7 @@ LDAP Internationalization Variables - Variable: ldap-attribute-syntaxes-alist A map of LDAP attribute names to their type object id minor number. - This table is built from RFC2252 Section 5 and RFC2256 Section 5 + This table is built from RFC2252 Section 5 and RFC2256 Section 5.  File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization @@ -400,27 +897,27 @@ Encoder/Decoder Functions - Function: ldap-encode-boolean bool A function that encodes an elisp boolean BOOL into a LDAP boolean - string representation + string representation. - Function: ldap-decode-boolean str A function that decodes a LDAP boolean string representation STR - into an elisp boolean + into an elisp boolean. - Function: ldap-decode-string str - Decode a string STR according to `ldap-coding-system' + Decode a string STR according to LDAP-CODING-SYSTEM. - Function: ldap-encode-string str - Encode a string STR according to `ldap-coding-system' + Encode a string STR according to LDAP-CODING-SYSTEM. - Function: ldap-decode-address str - Decode an address STR according to `ldap-coding-system' and + Decode an address STR according to LDAP-CODING-SYSTEM and replacing $ signs with newlines as specified by LDAP encoding - rules for addresses + rules for addresses. - Function: ldap-encode-address str - Encode an address STR according to `ldap-coding-system' and + Encode an address STR according to LDAP-CODING-SYSTEM and replacing newlines with $ signs as specified by LDAP encoding - rules for addresses + rules for addresses.  File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support @@ -633,661 +1130,3 @@ connection and when the `pq-setenv' call is made. Compatibility Note: This variable is not present in InfoDock. - -File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API - -libpq Lisp Symbols and Datatypes --------------------------------- - - The following set of symbols are used to represent the intermediate -states involved in the asynchronous interface. - - - Symbol: pgres::polling-failed - Undocumented. A fatal error has occurred during processing of an - asynchronous operation. - - - Symbol: pgres::polling-reading - An intermediate status return during an asynchronous operation. It - indicates that one may use `select' before polling again. - - - Symbol: pgres::polling-writing - An intermediate status return during an asynchronous operation. It - indicates that one may use `select' before polling again. - - - Symbol: pgres::polling-ok - An asynchronous operation has successfully completed. - - - Symbol: pgres::polling-active - An intermediate status return during an asynchronous operation. - One can call the poll function again immediately. - - - 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 - - `pq::user' - Database user name - - `pq::pass' - Database user's password - - `pq::host' - Hostname database server is running on - - `pq::port' - TCP port number used in the connection - - `pq::tty' - Debugging TTY - - Compatibility note: Debugging TTYs are not used in the - XEmacs Lisp API. - - `pq::options' - Additional server options - - `pq::status' - Connection status. Possible return values are shown in the - following table. - `pg::connection-ok' - The normal, connected status. - - `pg::connection-bad' - The connection is not open and the PGconn object needs - to be deleted by `pq-finish'. - - `pg::connection-started' - An asynchronous connection has been started, but is not - yet complete. - - `pg::connection-made' - An asynchronous connect has been made, and there is data - waiting to be sent. - - `pg::connection-awaiting-response' - Awaiting data from the backend during an asynchronous - connection. - - `pg::connection-auth-ok' - Received authentication, waiting for the backend to - start up. - - `pg::connection-setenv' - Negotiating environment during an asynchronous - connection. - - `pq::error-message' - The last error message that was delivered to this connection. - - `pq::backend-pid' - The process ID of the backend database server. - - 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: - - (setq R (pq-exec P "SELECT * FROM xemacs_test;")) - => # - - 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: - - (pq-exec P "CREATE TABLE a_new_table (i int);") - => # - - 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: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API - -Synchronous Interface Functions -------------------------------- - - - Function: pq-connectdb conninfo - Establish a (synchronous) database connection. CONNINFO A string - of blank separated options. Options are of the form "OPTION = - VALUE". If VALUE contains blanks, it must be single quoted. - Blanks around the equal sign are optional. Multiple option - assignments are blank separated. - (pq-connectdb "dbname=japanese port = 25432") - => # - 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. - - -File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API - -Asynchronous Interface Functions --------------------------------- - - Making command by command examples is too complex with the -asynchronous interface functions. See the examples section for -complete calling sequences. - - - 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: 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: pq-is-busy conn - Returns t if `pq-get-result' would block waiting for input. CONN - A database connection object. - - - Function: pq-consume-input conn - Consume any available input from the backend. CONN A database - connection object. - - Nil is returned if anything bad happens. - - - 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. - - - Function: pq-is-nonblocking conn - Return the blocking status of the database connection CONN A - database connection object. - - - Function: pq-flush conn - Force the write buffer to be written (or at least try) CONN A - database connection object. - - - Function: PQsetenvStart conn - Start asynchronously passing environment variables to a backend. - CONN A database connection object. - - Compatibility note: this function is only available with libpq-7.0. - - - Function: PQsetenvPoll conn - Check an asynchronous environment variables transfer for - completion. CONN A database connection object. - - 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: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API - -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. - - - 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: 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. - diff --git a/info/lispref.info-43 b/info/lispref.info-43 index 4b1d70b..18337d7 100644 --- a/info/lispref.info-43 +++ b/info/lispref.info-43 @@ -50,6 +50,664 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API + +libpq Lisp Symbols and Datatypes +-------------------------------- + + The following set of symbols are used to represent the intermediate +states involved in the asynchronous interface. + + - Symbol: pgres::polling-failed + Undocumented. A fatal error has occurred during processing of an + asynchronous operation. + + - Symbol: pgres::polling-reading + An intermediate status return during an asynchronous operation. It + indicates that one may use `select' before polling again. + + - Symbol: pgres::polling-writing + An intermediate status return during an asynchronous operation. It + indicates that one may use `select' before polling again. + + - Symbol: pgres::polling-ok + An asynchronous operation has successfully completed. + + - Symbol: pgres::polling-active + An intermediate status return during an asynchronous operation. + One can call the poll function again immediately. + + - 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 + + `pq::user' + Database user name + + `pq::pass' + Database user's password + + `pq::host' + Hostname database server is running on + + `pq::port' + TCP port number used in the connection + + `pq::tty' + Debugging TTY + + Compatibility note: Debugging TTYs are not used in the + XEmacs Lisp API. + + `pq::options' + Additional server options + + `pq::status' + Connection status. Possible return values are shown in the + following table. + `pg::connection-ok' + The normal, connected status. + + `pg::connection-bad' + The connection is not open and the PGconn object needs + to be deleted by `pq-finish'. + + `pg::connection-started' + An asynchronous connection has been started, but is not + yet complete. + + `pg::connection-made' + An asynchronous connect has been made, and there is data + waiting to be sent. + + `pg::connection-awaiting-response' + Awaiting data from the backend during an asynchronous + connection. + + `pg::connection-auth-ok' + Received authentication, waiting for the backend to + start up. + + `pg::connection-setenv' + Negotiating environment during an asynchronous + connection. + + `pq::error-message' + The last error message that was delivered to this connection. + + `pq::backend-pid' + The process ID of the backend database server. + + 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: + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + + 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: + + (pq-exec P "CREATE TABLE a_new_table (i int);") + => # + + 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: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API + +Synchronous Interface Functions +------------------------------- + + - Function: pq-connectdb conninfo + Establish a (synchronous) database connection. CONNINFO A string + of blank separated options. Options are of the form "OPTION = + VALUE". If VALUE contains blanks, it must be single quoted. + Blanks around the equal sign are optional. Multiple option + assignments are blank separated. + (pq-connectdb "dbname=japanese port = 25432") + => # + 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. + + +File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API + +Asynchronous Interface Functions +-------------------------------- + + Making command by command examples is too complex with the +asynchronous interface functions. See the examples section for +complete calling sequences. + + - 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: 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: pq-is-busy conn + Returns t if `pq-get-result' would block waiting for input. CONN + A database connection object. + + - Function: pq-consume-input conn + Consume any available input from the backend. CONN A database + connection object. + + Nil is returned if anything bad happens. + + - 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. + + - Function: pq-is-nonblocking conn + Return the blocking status of the database connection CONN A + database connection object. + + - Function: pq-flush conn + Force the write buffer to be written (or at least try) CONN A + database connection object. + + - Function: PQsetenvStart conn + Start asynchronously passing environment variables to a backend. + CONN A database connection object. + + Compatibility note: this function is only available with libpq-7.0. + + - Function: PQsetenvPoll conn + Check an asynchronous environment variables transfer for + completion. CONN A database connection object. + + 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: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API + +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. + + - 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: 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: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API Unimplemented libpq Functions @@ -492,14 +1150,9 @@ specify the domain after the documentation. Example: (defconst limbs 4 "Number of limbs" "emacs-gorilla") - 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: - - - Function: autoload symbol filename &optional docstring interactive - macro domain - Example: + - Function: autoload function filename &optional docstring interactive + type + This function defines FUNCTION to autoload from FILENAME Example: (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")  @@ -556,593 +1209,3 @@ on "MULE". * 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 extendible 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: Charsets, Next: MULE Characters, Prev: Internationalization Terminology, Up: MULE - -Charsets -======== - - 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. - - - Function: charsetp object - This function returns non-`nil' if OBJECT is a charset. - -* 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 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. - - -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: MULE Characters, Next: Composite Characters, Prev: Charsets, Up: MULE - -MULE Characters -=============== - - - Function: make-char charset arg1 &optional arg2 - This function makes a multi-byte character from CHARSET and octets - ARG1 and ARG2. - - - Function: char-charset ch - This function returns the character set of char CH. - - - 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. - - - 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. - - - Function: find-charset-string string - This function returns a list of the charsets in STRING. - - -File: lispref.info, Node: Composite Characters, Next: Coding Systems, Prev: MULE Characters, Up: MULE - -Composite Characters -==================== - - Composite characters are not yet completely implemented. - - - 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. - - - 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. - - -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. - diff --git a/info/lispref.info-44 b/info/lispref.info-44 index b3a5f6a..e1ddc4f 100644 --- a/info/lispref.info-44 +++ b/info/lispref.info-44 @@ -50,6 +50,596 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 extendible 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: Charsets, Next: MULE Characters, Prev: Internationalization Terminology, Up: MULE + +Charsets +======== + + 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. + + - Function: charsetp object + This function returns non-`nil' if OBJECT is a charset. + +* 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 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-description charset + This function returns the documentation 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-width 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-iso-final-char charset + This function returns the final byte of the ISO 2022 escape + sequence designating CHARSET. + + - Function: charset-iso-graphic-plane 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. + + +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: MULE Characters, Next: Composite Characters, Prev: Charsets, Up: MULE + +MULE Characters +=============== + + - Function: make-char charset arg1 &optional arg2 + This function makes a multi-byte character from CHARSET and octets + ARG1 and ARG2. + + - Function: char-charset character + This function returns the character set of char CHARACTER. + + - Function: char-octet character &optional n + This function returns the octet (i.e. position code) numbered N + (should be 0 or 1) of char CHARACTER. N defaults to 0 if omitted. + + - 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. + + - Function: find-charset-string string + This function returns a list of the charsets in STRING. + + +File: lispref.info, Node: Composite Characters, Next: Coding Systems, Prev: MULE Characters, Up: MULE + +Composite Characters +==================== + + Composite characters are not yet completely implemented. + + - 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. + + - Function: composite-char-string character + 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. + + +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. + + File: lispref.info, Node: Coding System Types, Next: ISO 2022, Up: Coding Systems Coding System Types @@ -442,839 +1032,3 @@ EOL Conversion subsidiary coding systems. (This value is converted to `nil' when stored internally, and `coding-system-property' will return `nil'.) - -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. - - -File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems - -Basic Coding System Functions ------------------------------ - - - Function: find-coding-system coding-system-or-name - This function retrieves the coding system of the given name. - - 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. - - - 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'. - - - Function: coding-system-list - This function returns a list of the names of all defined coding - systems. - - - Function: coding-system-name coding-system - This function returns the name of the given coding system. - - - Function: coding-system-base coding-system - Returns the base coding system (undecided EOL convention) coding - system. - - - Function: make-coding-system name type &optional doc-string props - This function registers symbol NAME as a coding system. - - TYPE describes the conversion method used and should be one of the - types listed in *Note Coding System Types::. - - DOC-STRING is a string describing the coding system. - - PROPS is a property list, describing the specific nature of the - character set. Recognized properties are as in *Note Coding - System Properties::. - - - 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. - - - Function: subsidiary-coding-system coding-system eol-type - This function returns the subsidiary coding system of - CODING-SYSTEM with eol type EOL-TYPE. - - -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 --------------------------------- - - - 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. - - -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. - diff --git a/info/lispref.info-45 b/info/lispref.info-45 index f5017ba..e4484ee 100644 --- a/info/lispref.info-45 +++ b/info/lispref.info-45 @@ -50,6 +50,842 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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, START 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, START 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. + + +File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems + +Basic Coding System Functions +----------------------------- + + - Function: find-coding-system coding-system-or-name + This function retrieves the coding system of the given name. + + 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. + + - 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'. + + - Function: coding-system-list + This function returns a list of the names of all defined coding + systems. + + - Function: coding-system-name coding-system + This function returns the name of the given coding system. + + - Function: coding-system-base coding-system + Returns the base coding system (undecided EOL convention) coding + system. + + - Function: make-coding-system name type &optional doc-string props + This function registers symbol NAME as a coding system. + + TYPE describes the conversion method used and should be one of the + types listed in *Note Coding System Types::. + + DOC-STRING is a string describing the coding system. + + PROPS is a property list, describing the specific nature of the + character set. Recognized properties are as in *Note Coding + System Properties::. + + - 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. + + - Function: subsidiary-coding-system coding-system eol-type + This function returns the subsidiary coding system of + CODING-SYSTEM with eol type EOL-TYPE. + + +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 +-------------------------------- + + - 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. + + +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 @@ -126,7 +962,7 @@ programs, and from Lisp using these functions: side-effect) to contain the ending values for the corresponding registers and IC. - - Function: ccl-execute-on-string ccl-program status str &optional + - Function: ccl-execute-on-string ccl-program status string &optional continue Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is a vector of compiled CCL code created by `ccl-compile'. STATUS @@ -135,7 +971,7 @@ programs, and from Lisp using these functions: `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 + 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 @@ -146,9 +982,9 @@ programs, and from Lisp using these functions: 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. + Register NAME for CCL program CCL-PROGRAM in `ccl-program-table'. + CCL-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: @@ -198,8 +1034,8 @@ 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-p object + This function returns `t' if OBJECT is a category table. - Function: category-table &optional buffer This function returns the current category table. This is the one @@ -209,23 +1045,21 @@ have to directly manipulate bit vectors. 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: copy-category-table &optional category-table + This function returns a new category table which is a copy of + CATEGORY-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: set-category-table category-table &optional buffer + This function selects CATEGORY-TABLE as the new category table for + BUFFER. 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-designator-p object + This function returns `t' if OBJECT 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. + - Function: category-table-value-p object + This function returns `t' if OBJECT 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 @@ -245,755 +1079,3 @@ described in the previous chapters. * 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: - -* 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. - - -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. - diff --git a/info/lispref.info-46 b/info/lispref.info-46 index a1767fa..2e76962 100644 --- a/info/lispref.info-46 +++ b/info/lispref.info-46 @@ -50,6 +50,763 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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: + +* 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 &optional arg + This function returns a string describing the version of XEmacs + that is running. It is useful to include this string in bug + reports. + + When called interactively with a prefix argument, insert string at + point. Don't use this function in programs to choose actions + according to the system configuration; look at + `system-configuration' instead. + + (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: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation Garbage Collection @@ -230,14 +987,6 @@ using `malloc' and `free'. 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 @@ -448,812 +1197,3 @@ mathematical functions. `"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:: - -`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:: - -`selective-display' - *note Selective Display:: - -`selective-display-ellipses' - *note Selective Display:: - -`tab-width' - *note Usual Display:: - -`truncate-lines' - *note Truncation:: - -`vc-mode' - *note Modeline Variables:: - - -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. - -`lisp-interaction-mode-map' - A keymap used by Lisp mode. - -`lisp-mode-map' - A keymap used by Lisp mode. - - A keymap for minibuffer input with completion. - -`minibuffer-local-isearch-map' - A keymap for editing isearch strings in the minibuffer. - -`minibuffer-local-map' - Default keymap to use when reading from the minibuffer. - -`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. - - -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' - -`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' - -`tooltalk-unprocessed-message-hook' - -`unmap-frame-hook' - -`vc-checkin-hook' - -`vc-checkout-writable-buffer-hook' - -`vc-log-after-operation-hook' - -`vc-make-buffer-writable-hook' - -`view-hook' - -`vm-arrived-message-hook' - -`vm-arrived-messages-hook' - -`vm-chop-full-name-function' - -`vm-display-buffer-hook' - -`vm-edit-message-hook' - -`vm-forward-message-hook' - -`vm-iconify-frame-hook' - -`vm-inhibit-write-file-hook' - -`vm-key-functions' - -`vm-mail-hook' - -`vm-mail-mode-hook' - -`vm-menu-setup-hook' - -`vm-mode-hook' - -`vm-quit-hook' - -`vm-rename-current-buffer-function' - -`vm-reply-hook' - -`vm-resend-bounced-message-hook' - -`vm-resend-message-hook' - -`vm-retrieved-spooled-mail-hook' - -`vm-select-message-hook' - -`vm-select-new-message-hook' - -`vm-select-unread-message-hook' - -`vm-send-digest-hook' - -`vm-summary-mode-hook' - -`vm-summary-pointer-update-hook' - -`vm-summary-redo-hook' - -`vm-summary-update-hook' - -`vm-undisplay-buffer-hook' - -`vm-visit-folder-hook' - -`window-setup-hook' - -`write-contents-hooks' - -`write-file-data-hooks' - -`write-file-hooks' - -`write-region-annotate-functions' - -`x-lost-selection-hooks' - -`x-sent-selection-hooks' - -`zmacs-activate-region-hook' - -`zmacs-deactivate-region-hook' - -`zmacs-update-region-hook' diff --git a/info/lispref.info-47 b/info/lispref.info-47 index 508ad82..196b605 100644 --- a/info/lispref.info-47 +++ b/info/lispref.info-47 @@ -50,3452 +50,811 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Index, Prev: Standard Hooks, Up: Top - -Index -***** - -* 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. -* *PQfn: Unimplemented libpq Functions. -* *PQoidStatus: Unimplemented libpq Functions. -* *PQsetdb: Unimplemented libpq Functions. -* *PQsetdbLogin: Unimplemented libpq Functions. -* *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 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-gutter: Specifying a Gutter. -* bottom-gutter-height: Other Gutter Variables. -* bottom-gutter-visible-p: Other Gutter Variables. -* 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-gutter-button-syntax: Gutter Descriptor Format. -* 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-base: Basic Coding System Functions. -* 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-display-table: Active Display Table. -* 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-gutter: Specifying a Gutter. -* default-gutter-height: Other Gutter Variables. -* default-gutter-position: Specifying a Gutter. -* default-gutter-visible-p: Other Gutter Variables. -* default-gutter-width: Other Gutter Variables. -* 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. -* gutter: Gutter. -* gutter-buttons-captioned-p: Other Gutter Variables. -* gutter-make-button-list: Gutter Descriptor Format. -* gutter-specifier-p: Specifying a Gutter. -* 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-domain: 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-gutter-spec: Other Gutter Variables. -* 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-add: Low-level Operations on a LDAP Server. -* ldap-add-entries: The High-Level LDAP API. -* ldap-attribute-syntax-decoders: LDAP Internationalization Variables. -* ldap-attribute-syntax-encoders: LDAP Internationalization Variables. -* ldap-attribute-syntaxes-alist: LDAP Internationalization Variables. -* ldap-close: Opening and Closing a LDAP Connection. -* ldap-coding-system: LDAP Internationalization Variables. -* ldap-decode-address: Encoder/Decoder Functions. -* ldap-decode-attribute: LDAP Internationalization. -* ldap-decode-boolean: Encoder/Decoder Functions. -* ldap-decode-string: Encoder/Decoder Functions. -* ldap-default-attribute-decoder: LDAP Internationalization Variables. -* ldap-default-base: LDAP Variables. -* ldap-default-host: LDAP Variables. -* ldap-default-port: LDAP Variables. -* ldap-delete: Low-level Operations on a LDAP Server. -* ldap-delete-entries: The High-Level LDAP API. -* ldap-encode-address: Encoder/Decoder Functions. -* ldap-encode-boolean: Encoder/Decoder Functions. -* ldap-encode-string: Encoder/Decoder Functions. -* ldap-host: The LDAP Lisp Object. -* ldap-host-parameters-alist: LDAP Variables. -* ldap-ignore-attribute-codings: LDAP Internationalization Variables. -* ldap-live-p: The LDAP Lisp Object. -* ldap-modify: Low-level Operations on a LDAP Server. -* ldap-modify-entries: The High-Level LDAP API. -* ldap-open: Opening and Closing a LDAP Connection. -* ldap-search-basic: Low-level Operations on a LDAP Server. -* ldap-search-entries: The High-Level LDAP API. -* ldap-verbose: LDAP Variables. -* ldapp: The LDAP Lisp Object. -* left-gutter: Specifying a Gutter. -* left-gutter-visible-p: Other Gutter Variables. -* left-gutter-width: Other Gutter Variables. -* 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-boolean-specifier: Creating Specifiers. -* 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-color-specifier: Color Specifiers. -* 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-display-table-specifier: Creating Specifiers. -* make-event: Working With Events. -* make-extent: Creating and Modifying Extents. -* make-face: Basic Face Functions. -* make-face-boolean-specifier: Color Specifiers. -* make-file-part: Creating a Partial File. -* make-font-instance: Font Instances. -* make-font-specifier: Font Specifiers. -* make-frame: Creating Frames. -* make-frame-invisible: Visibility of Frames. -* make-frame-visible: Visibility of Frames. -* make-generic-specifier: Creating Specifiers. -* make-glyph: Creating Glyphs. -* make-glyph-internal: Creating Glyphs. -* make-gutter-size-specifier: Creating Gutter. -* make-gutter-specifier: Creating Gutter. -* make-gutter-visible-specifier: Creating Gutter. -* 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-integer-specifier: Creating Specifiers. -* make-keymap: Creating Keymaps. -* make-list: Building Lists. -* make-local-hook: Hooks. -* make-local-variable: Creating Buffer-Local. -* make-marker: Creating Markers. -* make-natnum-specifier: Creating Specifiers. -* 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-toolbar-specifier: Creating Toolbar. -* 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. -* pg-coding-system: libpq Lisp Variables. -* pg:authtype: libpq Lisp Variables. -* pg:client-encoding: libpq Lisp Variables. -* pg:cost-heap: libpq Lisp Variables. -* pg:cost-index: libpq Lisp Variables. -* pg:database: libpq Lisp Variables. -* pg:date-style: libpq Lisp Variables. -* pg:geqo: libpq Lisp Variables. -* pg:host: libpq Lisp Variables. -* pg:options: libpq Lisp Variables. -* pg:port: libpq Lisp Variables. -* pg:realm: libpq Lisp Variables. -* pg:tty: libpq Lisp Variables. -* pg:tz: libpq Lisp Variables. -* pg:user: libpq Lisp Variables. -* pgres::polling-active: libpq Lisp Symbols and DataTypes. -* pgres::polling-failed: libpq Lisp Symbols and DataTypes. -* pgres::polling-ok: libpq Lisp Symbols and DataTypes. -* pgres::polling-reading: libpq Lisp Symbols and DataTypes. -* pgres::polling-writing: libpq Lisp Symbols and DataTypes. -* 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. -* PostgreSQL: PostgreSQL Support. -* pq-binary-tuples: libpq Lisp Symbols and DataTypes. -* pq-clear: Other libpq Functions. -* pq-client-encoding: Other libpq Functions. -* pq-cmd-status: libpq Lisp Symbols and DataTypes. -* pq-cmd-tuples: libpq Lisp Symbols and DataTypes. -* pq-conn-defaults: Other libpq Functions. -* pq-connect-poll: Asynchronous Interface Functions. -* pq-connect-start: Asynchronous Interface Functions. -* pq-connectdb: Synchronous Interface Functions. -* pq-consume-input: Asynchronous Interface Functions. -* pq-env-2-encoding: Other libpq Functions. -* pq-exec: Synchronous Interface Functions. -* pq-finish: Other libpq Functions. -* pq-flush: Asynchronous Interface Functions. -* pq-fmod: libpq Lisp Symbols and DataTypes. -* pq-fname: libpq Lisp Symbols and DataTypes. -* pq-fnumber: libpq Lisp Symbols and DataTypes. -* pq-fsize: libpq Lisp Symbols and DataTypes. -* pq-ftype: libpq Lisp Symbols and DataTypes. -* pq-get-is-null: libpq Lisp Symbols and DataTypes. -* pq-get-length: libpq Lisp Symbols and DataTypes. -* pq-get-result: Asynchronous Interface Functions. -* pq-get-value: libpq Lisp Symbols and DataTypes. -* pq-is-busy: Asynchronous Interface Functions. -* pq-is-nonblocking: Asynchronous Interface Functions. -* pq-lo-close: Unimplemented libpq Functions. -* pq-lo-creat: Unimplemented libpq Functions. -* pq-lo-export: Large Object Support. -* pq-lo-import: Large Object Support. -* pq-lo-lseek: Unimplemented libpq Functions. -* pq-lo-open: Unimplemented libpq Functions. -* pq-lo-read: Unimplemented libpq Functions. -* pq-lo-tell: Unimplemented libpq Functions. -* pq-lo-unlink: Unimplemented libpq Functions. -* pq-lo-write: Unimplemented libpq Functions. -* pq-make-empty-pgresult: libpq Lisp Symbols and DataTypes. -* pq-nfields: libpq Lisp Symbols and DataTypes. -* pq-notifies: Synchronous Interface Functions. -* pq-ntuples: libpq Lisp Symbols and DataTypes. -* pq-oid-value: libpq Lisp Symbols and DataTypes. -* pq-pgconn: libpq Lisp Symbols and DataTypes. -* pq-res-status: libpq Lisp Symbols and DataTypes. -* pq-reset: Synchronous Interface Functions. -* pq-reset-cancel: Asynchronous Interface Functions. -* pq-reset-poll: Asynchronous Interface Functions. -* pq-reset-start: Asynchronous Interface Functions. -* pq-result-error-message: libpq Lisp Symbols and DataTypes. -* pq-result-status: libpq Lisp Symbols and DataTypes. -* pq-send-query: Asynchronous Interface Functions. -* pq-set-client-encoding: Other libpq Functions. -* pq-set-nonblocking: Asynchronous Interface Functions. -* PQdisplayTuples: Unimplemented libpq Functions. -* PQmblen: Unimplemented libpq Functions. -* PQprint: Unimplemented libpq Functions. -* PQprintTuples: Unimplemented libpq Functions. -* PQsetenv: Synchronous Interface Functions. -* PQsetenvAbort: Asynchronous Interface Functions. -* PQsetenvPoll: Asynchronous Interface Functions. -* PQsetenvStart: Asynchronous Interface Functions. -* PQsocket: Unimplemented libpq Functions. -* PQtrace: Unimplemented libpq Functions. -* PQuntrace: Unimplemented libpq Functions. -* 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-signal: Signals 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: Object from Minibuffer. -* 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-gutter: Specifying a Gutter. -* right-gutter-visible-p: Other Gutter Variables. -* right-gutter-width: Other Gutter Variables. -* 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-gutter-position: Specifying a Gutter. -* 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-gutter: Specifying a Gutter. -* top-gutter-height: Other Gutter Variables. -* top-gutter-visible-p: Other Gutter Variables. -* 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. -* widget-image-instance-p: Image Instance Types. -* 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. +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:: + +`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:: + +`selective-display' + *note Selective Display:: + +`selective-display-ellipses' + *note Selective Display:: + +`tab-width' + *note Usual Display:: + +`truncate-lines' + *note Truncation:: + +`vc-mode' + *note Modeline Variables:: + + +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. + +`lisp-interaction-mode-map' + A keymap used by Lisp mode. + +`lisp-mode-map' + A keymap used by Lisp mode. + + A keymap for minibuffer input with completion. + +`minibuffer-local-isearch-map' + A keymap for editing isearch strings in the minibuffer. + +`minibuffer-local-map' + Default keymap to use when reading from the minibuffer. + +`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. + + +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' + +`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' + +`tooltalk-unprocessed-message-hook' + +`unmap-frame-hook' + +`vc-checkin-hook' + +`vc-checkout-writable-buffer-hook' + +`vc-log-after-operation-hook' + +`vc-make-buffer-writable-hook' + +`view-hook' + +`vm-arrived-message-hook' + +`vm-arrived-messages-hook' + +`vm-chop-full-name-function' + +`vm-display-buffer-hook' + +`vm-edit-message-hook' + +`vm-forward-message-hook' + +`vm-iconify-frame-hook' + +`vm-inhibit-write-file-hook' + +`vm-key-functions' + +`vm-mail-hook' + +`vm-mail-mode-hook' + +`vm-menu-setup-hook' + +`vm-mode-hook' + +`vm-quit-hook' + +`vm-rename-current-buffer-function' + +`vm-reply-hook' + +`vm-resend-bounced-message-hook' + +`vm-resend-message-hook' + +`vm-retrieved-spooled-mail-hook' + +`vm-select-message-hook' + +`vm-select-new-message-hook' + +`vm-select-unread-message-hook' + +`vm-send-digest-hook' + +`vm-summary-mode-hook' + +`vm-summary-pointer-update-hook' + +`vm-summary-redo-hook' + +`vm-summary-update-hook' + +`vm-undisplay-buffer-hook' + +`vm-visit-folder-hook' + +`window-setup-hook' + +`write-contents-hooks' + +`write-file-data-hooks' + +`write-file-hooks' + +`write-region-annotate-functions' + +`x-lost-selection-hooks' + +`x-sent-selection-hooks' + +`zmacs-activate-region-hook' + +`zmacs-deactivate-region-hook' + +`zmacs-update-region-hook' diff --git a/info/new-users-guide.info-2 b/info/new-users-guide.info-2 index 858df8e..f996446 100644 --- a/info/new-users-guide.info-2 +++ b/info/new-users-guide.info-2 @@ -542,7 +542,7 @@ saved by reading the text from the file again (called "reverting"). For more information on this option, *Note Reverting: (xemacs)Reverting. When you save a file in Emacs, it destroys its old contents. However, -if you set the variable MAKE-BACKUP-FILES to non-NIL i.e. `t', Emacs +if you set the variable MAKE-BACKUP-FILES to non-`nil' i.e. `t', Emacs will create a "backup" file. Select the Describe variable option from the Help menu and look at the documentation for this variable. Its default value should be `t'. However, if its not then use `M-x @@ -1096,7 +1096,7 @@ complete typing the whole string. All searches in Emacs ignore the case of the text they are searching, i.e. if you are searching for "String", then "string" will also be one of the selections. If you want a case sensitive search select the Case Sensitive Search from the Option menu. -You can also set the variable CASE-FOLD-SEARCH to NIL for making +You can also set the variable CASE-FOLD-SEARCH to `nil' for making searches case-sensitive. For information on setting variables, *Note Setting Variables::. The two commands for searching for strings in XEmacs are: diff --git a/info/xemacs-faq.info-3 b/info/xemacs-faq.info-3 index ec0f670..8fa7ecf 100644 --- a/info/xemacs-faq.info-3 +++ b/info/xemacs-faq.info-3 @@ -7,6 +7,68 @@ START-INFO-DIR-ENTRY END-INFO-DIR-ENTRY  +File: xemacs-faq.info, Node: Q3.1.7, Next: Q3.1.8, Prev: Q3.1.6, Up: Customization + +Q3.1.7: `xemacs -name junk' doesn't work? +----------------------------------------- + + When I run `xterm -name junk', I get an xterm whose class name +according to xprop, is `junk'. This is the way it's supposed to work, +I think. When I run `xemacs -name junk' the class name is not set to +`junk'. It's still `emacs'. What does `xemacs -name' really do? The +reason I ask is that my window manager (fvwm) will make a window sticky +and I use XEmacs to read my mail. I want that XEmacs window to be +sticky, without having to use the window manager's function to set the +window sticky. What gives? + + `xemacs -name' sets the application name for the program (that is, +the thing which normally comes from `argv[0]'). Using `-name' is the +same as making a copy of the executable with that new name. The +`WM_CLASS' property on each frame is set to the frame-name, and the +application-class. So, if you did `xemacs -name FOO' and then created +a frame named BAR, you'd get an X window with WM_CLASS = `( "BAR", +"Emacs")'. However, the resource hierarchy for this widget would be: + + Name: FOO .shell .container .BAR + Class: Emacs .TopLevelEmacsShell.EmacsManager.EmacsFrame + + instead of the default + + Name: xemacs.shell .container .emacs + Class: Emacs .TopLevelEmacsShell.EmacsManager.EmacsFrame + + It is arguable that the first element of WM_CLASS should be set to +the application-name instead of the frame-name, but I think that's less +flexible, since it does not give you the ability to have multiple frames +with different WM_CLASS properties. Another possibility would be for +the default frame name to come from the application name instead of +simply being `emacs'. However, at this point, making that change would +be troublesome: it would mean that many users would have to make yet +another change to their resource files (since the default frame name +would suddenly change from `emacs' to `xemacs', or whatever the +executable happened to be named), so we'd rather avoid it. + + To make a frame with a particular name use: + + (make-frame '((name . "the-name"))) + + +File: xemacs-faq.info, Node: Q3.1.8, Next: Q3.2.1, Prev: Q3.1.7, Up: Customization + +Q3.1.8: `-iconic' doesn't work. +------------------------------- + + When I start up XEmacs using `-iconic' it doesn't work right. Using +`-unmapped' on the command line, and setting the `initiallyUnmapped' X +Resource don't seem to help much either... + + Ben Wing writes: + + Ugh, this stuff is such an incredible mess that I've about given up + getting it to work. The principal problem is numerous + window-manager bugs... + + File: xemacs-faq.info, Node: Q3.2.1, Next: Q3.2.2, Prev: Q3.1.8, Up: Customization 3.2: Textual Fonts & Colors @@ -1331,86 +1393,3 @@ Q4.0.11: How do I make VM or mh-e display graphical smilies? (autoload 'smiley-buffer "smiley" nil t) (add-hook 'mime-viewer/plain-text-preview-hook 'smiley-buffer) - -File: xemacs-faq.info, Node: Q4.0.12, Next: Q4.1.1, Prev: Q4.0.11, Up: Subsystems - -Q4.0.12: Customization of VM not covered in the manual, or here. ----------------------------------------------------------------- - - giacomo boffi writes: - - The meta-answer is to look into the file `vm-vars.el', in the vm - directory of the lisp library. - - `vm-vars.el' contains, initializes and carefully describes, with - examples of usage, the plethora of user options that _fully_ - control VM's behavior. - - Enter vm-vars, `forward-search' for toolbar, find the variables - that control the toolbar placement, appearance, existence, copy to - your `.emacs' or `.vm' and modify according to the detailed - instructions. - - The above also applies to all the various features of VM: search - for some keywords, maybe the first you conjure isn't appropriate, - find the appropriate variables, copy and experiment. - - -File: xemacs-faq.info, Node: Q4.1.1, Next: Q4.1.2, Prev: Q4.0.12, Up: Subsystems - -4.1: Web browsing with W3 -========================= - -Q4.1.1: What is W3? -------------------- - - W3 is an advanced graphical browser written in Emacs lisp that runs -on XEmacs. It has full support for cascaded style sheets, and more... - - It has a home web page at -`http://www.cs.indiana.edu/elisp/w3/docs.html'. - - -File: xemacs-faq.info, Node: Q4.1.2, Next: Q4.1.3, Prev: Q4.1.1, Up: Subsystems - -Q4.1.2: How do I run W3 from behind a firewall? ------------------------------------------------ - - There is a long, well-written, detailed section in the W3 manual that -describes how to do this. Look in the section entitled "Firewalls". - - -File: xemacs-faq.info, Node: Q4.1.3, Next: Q4.2.1, Prev: Q4.1.2, Up: Subsystems - -Q4.1.3: Is it true that W3 supports style sheets and tables? ------------------------------------------------------------- - - Yes, and much more. W3, as distributed with the latest XEmacs is a -full-featured web browser. - - -File: xemacs-faq.info, Node: Q4.2.1, Next: Q4.2.2, Prev: Q4.1.3, Up: Subsystems - -4.2: Reading Netnews and Mail with Gnus -======================================= - -Q4.2.1: GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus, Quassia Gnus, argh! --------------------------------------------------------------------------------- - - The Gnus numbering issues are not meant for mere mortals to know -them. If you feel you _must_ enter the muddy waters of Gnus, visit the -excellent FAQ, maintained by Justin Sheehy, at: - - `http://www.ccs.neu.edu/software/contrib/gnus/' - - See also Gnus home page - `http://www.gnus.org/' - - -File: xemacs-faq.info, Node: Q4.2.2, Next: Q4.2.3, Prev: Q4.2.1, Up: Subsystems - -Q4.2.2: This question intentionally left blank. ------------------------------------------------ - - Obsolete question, left blank to avoid renumbering. - diff --git a/info/xemacs-faq.info-4 b/info/xemacs-faq.info-4 index 89a2b7d..7e671ec 100644 --- a/info/xemacs-faq.info-4 +++ b/info/xemacs-faq.info-4 @@ -7,6 +7,89 @@ START-INFO-DIR-ENTRY END-INFO-DIR-ENTRY  +File: xemacs-faq.info, Node: Q4.0.12, Next: Q4.1.1, Prev: Q4.0.11, Up: Subsystems + +Q4.0.12: Customization of VM not covered in the manual, or here. +---------------------------------------------------------------- + + giacomo boffi writes: + + The meta-answer is to look into the file `vm-vars.el', in the vm + directory of the lisp library. + + `vm-vars.el' contains, initializes and carefully describes, with + examples of usage, the plethora of user options that _fully_ + control VM's behavior. + + Enter vm-vars, `forward-search' for toolbar, find the variables + that control the toolbar placement, appearance, existence, copy to + your `.emacs' or `.vm' and modify according to the detailed + instructions. + + The above also applies to all the various features of VM: search + for some keywords, maybe the first you conjure isn't appropriate, + find the appropriate variables, copy and experiment. + + +File: xemacs-faq.info, Node: Q4.1.1, Next: Q4.1.2, Prev: Q4.0.12, Up: Subsystems + +4.1: Web browsing with W3 +========================= + +Q4.1.1: What is W3? +------------------- + + W3 is an advanced graphical browser written in Emacs lisp that runs +on XEmacs. It has full support for cascaded style sheets, and more... + + It has a home web page at +`http://www.cs.indiana.edu/elisp/w3/docs.html'. + + +File: xemacs-faq.info, Node: Q4.1.2, Next: Q4.1.3, Prev: Q4.1.1, Up: Subsystems + +Q4.1.2: How do I run W3 from behind a firewall? +----------------------------------------------- + + There is a long, well-written, detailed section in the W3 manual that +describes how to do this. Look in the section entitled "Firewalls". + + +File: xemacs-faq.info, Node: Q4.1.3, Next: Q4.2.1, Prev: Q4.1.2, Up: Subsystems + +Q4.1.3: Is it true that W3 supports style sheets and tables? +------------------------------------------------------------ + + Yes, and much more. W3, as distributed with the latest XEmacs is a +full-featured web browser. + + +File: xemacs-faq.info, Node: Q4.2.1, Next: Q4.2.2, Prev: Q4.1.3, Up: Subsystems + +4.2: Reading Netnews and Mail with Gnus +======================================= + +Q4.2.1: GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus, Quassia Gnus, argh! +-------------------------------------------------------------------------------- + + The Gnus numbering issues are not meant for mere mortals to know +them. If you feel you _must_ enter the muddy waters of Gnus, visit the +excellent FAQ, maintained by Justin Sheehy, at: + + `http://www.ccs.neu.edu/software/contrib/gnus/' + + See also Gnus home page + `http://www.gnus.org/' + + +File: xemacs-faq.info, Node: Q4.2.2, Next: Q4.2.3, Prev: Q4.2.1, Up: Subsystems + +Q4.2.2: This question intentionally left blank. +----------------------------------------------- + + Obsolete question, left blank to avoid renumbering. + + File: xemacs-faq.info, Node: Q4.2.3, Next: Q4.2.4, Prev: Q4.2.2, Up: Subsystems Q4.2.3: How do I make Gnus stay within a single frame? @@ -1241,68 +1324,3 @@ fact that it is an interpreter. Please try not to make your code much uglier to gain a very small speed gain. It's not usually worth it. - -File: xemacs-faq.info, Node: Q5.1.9, Next: Q5.1.10, Prev: Q5.1.8, Up: Miscellaneous - -Q5.1.9: How do I put a glyph as annotation in a buffer? -------------------------------------------------------- - - Here is a solution that will insert the glyph annotation at the -beginning of buffer: - - (make-annotation (make-glyph '([FORMAT :file FILE] - [string :data "fallback-text"])) - (point-min) - 'text - (current-buffer)) - - Replace `FORMAT' with an unquoted symbol representing the format of -the image (e.g. `xpm', `xbm', `gif', `jpeg', etc.) Instead of `FILE', -use the image file name (e.g. -`/usr/local/lib/xemacs-20.2/etc/recycle.xpm'). - - You can turn this to a function (that optionally prompts you for a -file name), and inserts the glyph at `(point)' instead of `(point-min)'. - - -File: xemacs-faq.info, Node: Q5.1.10, Next: Q5.1.11, Prev: Q5.1.9, Up: Miscellaneous - -Q5.1.10: `map-extents' won't traverse all of my extents! --------------------------------------------------------- - - I tried to use `map-extents' to do an operation on all the extents -in a region. However, it seems to quit after processing a random number -of extents. Is it buggy? - - No. The documentation of `map-extents' states that it will iterate -across the extents as long as FUNCTION returns `nil'. Unexperienced -programmers often forget to return `nil' explicitly, which results in -buggy code. For instance, the following code is supposed to delete all -the extents in a buffer, and issue as many `fubar!' messages. - - (map-extents (lambda (ext ignore) - (delete-extent ext) - (message "fubar!"))) - - Instead, it will delete only the first extent, and stop right there - -because `message' will return a non-nil value. The correct code is: - - (map-extents (lambda (ext ignore) - (delete-extent ext) - (message "fubar!") - nil)) - - -File: xemacs-faq.info, Node: Q5.1.11, Next: Q5.2.1, Prev: Q5.1.10, Up: Miscellaneous - -Q5.1.11: My elisp program is horribly slow. Is there ------------------------------------------------------ - - an easy way to find out where it spends time? - - zHrvoje Niksic writes: - Under XEmacs 20.4 and later you can use `M-x - profile-key-sequence', press a key (say in the Gnus Group - buffer), and get the results using `M-x profile-results'. It - should give you an idea of where the time is being spent. - diff --git a/info/xemacs-faq.info-5 b/info/xemacs-faq.info-5 index b6a080c..ccfd040 100644 --- a/info/xemacs-faq.info-5 +++ b/info/xemacs-faq.info-5 @@ -7,6 +7,71 @@ START-INFO-DIR-ENTRY END-INFO-DIR-ENTRY  +File: xemacs-faq.info, Node: Q5.1.9, Next: Q5.1.10, Prev: Q5.1.8, Up: Miscellaneous + +Q5.1.9: How do I put a glyph as annotation in a buffer? +------------------------------------------------------- + + Here is a solution that will insert the glyph annotation at the +beginning of buffer: + + (make-annotation (make-glyph '([FORMAT :file FILE] + [string :data "fallback-text"])) + (point-min) + 'text + (current-buffer)) + + Replace `FORMAT' with an unquoted symbol representing the format of +the image (e.g. `xpm', `xbm', `gif', `jpeg', etc.) Instead of `FILE', +use the image file name (e.g. +`/usr/local/lib/xemacs-20.2/etc/recycle.xpm'). + + You can turn this to a function (that optionally prompts you for a +file name), and inserts the glyph at `(point)' instead of `(point-min)'. + + +File: xemacs-faq.info, Node: Q5.1.10, Next: Q5.1.11, Prev: Q5.1.9, Up: Miscellaneous + +Q5.1.10: `map-extents' won't traverse all of my extents! +-------------------------------------------------------- + + I tried to use `map-extents' to do an operation on all the extents +in a region. However, it seems to quit after processing a random number +of extents. Is it buggy? + + No. The documentation of `map-extents' states that it will iterate +across the extents as long as FUNCTION returns `nil'. Unexperienced +programmers often forget to return `nil' explicitly, which results in +buggy code. For instance, the following code is supposed to delete all +the extents in a buffer, and issue as many `fubar!' messages. + + (map-extents (lambda (ext ignore) + (delete-extent ext) + (message "fubar!"))) + + Instead, it will delete only the first extent, and stop right there - +because `message' will return a non-nil value. The correct code is: + + (map-extents (lambda (ext ignore) + (delete-extent ext) + (message "fubar!") + nil)) + + +File: xemacs-faq.info, Node: Q5.1.11, Next: Q5.2.1, Prev: Q5.1.10, Up: Miscellaneous + +Q5.1.11: My elisp program is horribly slow. Is there +----------------------------------------------------- + + an easy way to find out where it spends time? + + zHrvoje Niksic writes: + Under XEmacs 20.4 and later you can use `M-x + profile-key-sequence', press a key (say in the Gnus Group + buffer), and get the results using `M-x profile-results'. It + should give you an idea of where the time is being spent. + + File: xemacs-faq.info, Node: Q5.2.1, Next: Q5.2.2, Prev: Q5.1.11, Up: Miscellaneous Q5.2.1: How do I turn off the sound? diff --git a/info/xemacs.info-12 b/info/xemacs.info-12 index 6c87c0a..ce1f2c4 100644 --- a/info/xemacs.info-12 +++ b/info/xemacs.info-12 @@ -486,7 +486,7 @@ defines these commands: comments in assembler syntax.  -File: xemacs.info, Node: Running, Next: Packages, Prev: Programs, Up: Top +File: xemacs.info, Node: Running, Next: Abbrevs, Prev: Programs, Up: Top Compiling and Testing Programs ****************************** @@ -558,7 +558,7 @@ the word `run' or `exit' in the parentheses to tell you whether compilation is finished. You do not have to keep this buffer visible; compilation continues in any case. - To kill the compilation process, type `M-x-kill-compilation'. The + To kill the compilation process, type `M-x kill-compilation'. The mode line of the `*compilation*' buffer changes to say `signal' instead of `run'. Starting a new compilation also kills any running compilation, as only one can occur at any time. Starting a new @@ -1096,7 +1096,7 @@ doing so is different according to where the relevant Lisp environment is found. *Note Lisp Modes::.  -File: xemacs.info, Node: Packages, Next: Abbrevs, Prev: Running, Up: Top +File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top Packages ======== @@ -1114,6 +1114,7 @@ local needs with safe removal of unnecessary code. * Package Terminology:: Understanding different kinds of packages. * Using Packages:: How to install and use packages. * Building Packages:: Building packages from sources. +* Available Packages:: A brief, out-of-date, directory of packaged LISP.  File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index 7e83eef..bfce027 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -271,7 +271,7 @@ it's best to exit XEmacs before upgrading an existing package.  -File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages +File: xemacs.info, Node: Building Packages, Next: Available Packages, Prev: Using Packages, Up: Packages Source packages are available from the `packages/source-packages' subdirectory of your favorite XEmacs distribution site. Alternatively, @@ -334,7 +334,270 @@ to others. of use by XEmacs maintainers producing files for distribution.  -File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top +File: xemacs.info, Node: Available Packages, Prev: Building Packages, Up: Packages + + This section is surely out-of-date. If you're sure that XEmacs is +able to do something, but your installed XEmacs won't do it for you, +it's probably in a package. If you can't find it in this section, +that's a bug--please report it. It is very hard to keep this section +up-to-date; your reports, comments, and questions will help a lot. + + This data is up-to-date as of 10 February 1999. (Ouch! I told you!) + +Library Packages (libs) +----------------------- + + These packages are required to build and support most of the rest of +XEmacs. By design, xemacs-base is a `regular' package. Use restraint +when adding new files there as it is required by almost everything. + +`Sun' + Support for Sparcworks. + +`apel' + A Portable Emacs Library. Used by XEmacs MIME support. + +`edebug' + A Lisp debugger. + +`dired' + The DIRectory EDitor is for manipulating, and running commands on + files in a directory. + +`efs' + Treat files on remote systems the same as local files. + +`mail-lib' + Fundamental lisp files for providing email support. + +`tooltalk' + Support for building with Tooltalk. + +`xemacs-base' + Fundamental XEmacs support. Install this unless you wish a totally + naked XEmacs. + +`xemacs-devel' + XEmacs Lisp developer support. This package contains utilities for + supporting Lisp development. It is a single-file package so it + may be tailored. + +Communications Packages (comm) +------------------------------ + + These packages provide support for various communications, primarily +email and usenet. + +`footnote' + Footnoting in mail message editing modes. + +`gnats' + XEmacs bug reports. + +`gnus' + The Gnus Newsreader and Mailreader. + +`mailcrypt' + Support for messaging encryption with PGP. + +`mh-e' + Front end support for MH. + +`net-utils' + Miscellaneous Networking Utilities. This is a single-file package + and files may be deleted at will. + +`ph' + Emacs implementation of the ph client to CCSO/qi directory servers. + +`rmail' + An obsolete Emacs mailer. If you do not already use it don't + start. + +`supercite' + An Emacs citation tool. Useful with all Emacs Mailers and + Newsreaders. + +`tm' + Emacs MIME support. + +`vm' + An Emacs mailer. + +`w3' + A Web browser. + +Games and Amusements (games) +---------------------------- + +`cookie' + Spook and Yow (Zippy quotes). + +`games' + Tetris, Sokoban, and Snake. + +`mine' + Minehunt. + +`misc-games' + Other amusements and diversions. + +Mule Support (mule) +------------------- + +`egg-its' + Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to + XEmacs build. + +`leim' + Quail. Used for everything other than English and Japanese. + +`locale' + Used for localized menubars (French and Japanese) and localized + splash screens (Japanese). + +`mule-base' + Basic Mule support. Must be installed prior to building with Mule. + +`skk' + Another Japanese Language Input Method. Can be used without a + separate process running as a dictionary server. + +Productivity Packages (oa) +-------------------------- + +`calendar' + Calendar and diary support. + +`edit-utils' + Single file lisp packages for various XEmacs goodies. Load this + and weed out the junk you don't want. + +`forms' + Forms editing support (obsolete, use the builtin Widget instead). + +`frame-icon' + Provide a WM icon based on major mode. + +`hm--html-menus' + HTML editing. + +`ispell' + Spell-checking with ispell. + +`pc' + PC style interface emulation. + +`psgml' + Validated HTML/SGML editing. + +`sgml' + SGML/Linuxdoc-SGML editing. + +`slider' + User interface tool. + +`speedbar' + ??? Document me. + +`strokes' + Mouse enhancement utility. + +`text-modes' + Various single file lisp packages for editing text files. + +`time' + Display time & date on the modeline. + +Operating System Utilities (os) +------------------------------- + +`eterm' + Terminal emulator. + +`igrep' + Enhanced front-end for Grep. + +`ilisp' + Front-end for Inferior Lisp. + +`os-utils' + Miscellaneous single-file O/S utilities, for printing, archiving, + compression, remote shells, etc. + +`view-process' + A Unix process browsing tool. + +Program Editing Support (prog) +------------------------------ + +`ada' + Ada language support. + +`c-support' + Basic single-file add-ons for editing C code. + +`cc-mode' + C, C++ and Java language support. + +`debug' + GUD, gdb, dbx debugging support. + +`ediff' + Interface over patch. + +`emerge' + Another interface over patch. + +`pcl-cvs' + CVS frontend. + +`prog-modes' + Miscellaneous single-file lisp files for various programming + languages. + +`scheme' + Front-end support for Inferior Scheme. + +`sh-script' + Support for editing shell scripts. + +`vc' + Version Control for Free systems. + +`vc-cc' + Version Control for ClearCase. This package must be installed + prior to building XEmacs [broken as of XEmacs 20.5-beta19]. + +`vhdl' + Support for VHDL. + +Word Processing (wp) +-------------------- + +`auctex' + Basic TeX/LaTeX support. + +`crisp' + Crisp/Brief emulation. + +`edt' + DEC EDIT/EDT emulation. + +`texinfo' + XEmacs TeXinfo support. + +`textools' + Single-file TeX support. + +`tpu' + DEC EDIT/TPU support. + +`viper' + VI emulation support. + + +File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Running, Up: Top Abbrevs ******* @@ -1073,161 +1336,3 @@ a string naming a file. Each time you start to edit a message to send, an `FCC' field is entered for that file. Unless you remove the `FCC' field, every message is written into that file when it is sent. - -File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail - -Mail Mode -========= - - The major mode used in the `*mail*' buffer is Mail mode. Mail mode -is similar to Text mode, but several commands are provided on the `C-c' -prefix. These commands all deal specifically with editing or sending -the message. - -`C-c C-s' - Send the message, and leave the `*mail*' buffer selected - (`mail-send'). - -`C-c C-c' - Send the message, and select some other buffer - (`mail-send-and-exit'). - -`C-c C-f C-t' - Move to the `To' header field, creating one if there is none - (`mail-to'). - -`C-c C-f C-s' - Move to the `Subject' header field, creating one if there is none - (`mail-subject'). - -`C-c C-f C-c' - Move to the `CC' header field, creating one if there is none - (`mail-cc'). - -`C-c C-w' - Insert the file `~/.signature' at the end of the message text - (`mail-signature'). - -`C-c C-y' - Yank the selected message (`mail-yank-original'). - -`C-c C-q' - Fill all paragraphs of yanked old messages, each individually - (`mail-fill-yanked-message'). - -`' - Pops up a menu of useful mail-mode commands. - - There are two ways to send a message. `C-c C-c' -(`mail-send-and-exit') is the usual way to send the message. It sends -the message and then deletes the window (if there is another window) or -switches to another buffer. It puts the `*mail*' buffer at the lowest -priority for automatic reselection, since you are finished with using -it. `C-c C-s' (`mail-send') sends the message and marks the `*mail*' -buffer unmodified, but leaves that buffer selected so that you can -modify the message (perhaps with new recipients) and send it again. - - Mail mode provides some other special commands that are useful for -editing the headers and text of the message before you send it. There -are three commands defined to move point to particular header fields, -all based on the prefix `C-c C-f' (`C-f' is for "field"). They are -`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s' -(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc') -for the `CC' field. These fields have special motion commands because -they are edited most frequently. - - `C-c C-w' (`mail-signature') adds a standard piece of text at the -end of the message to say more about who you are. The text comes from -the file `.signature' in your home directory. - - When you use an Rmail command to send mail from the Rmail mail -reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*' -buffer to insert the text of the message you are replying to. Normally -Rmail indents each line of that message four spaces and eliminates most -header fields. A numeric argument specifies the number of spaces to -indent. An argument of just `C-u' says not to indent at all and not to -eliminate anything. `C-c C-y' always uses the current message from the -`RMAIL' buffer, so you can insert several old messages by selecting one -in `RMAIL', switching to `*mail*' and yanking it, then switching back -to `RMAIL' to select another. - - After using `C-c C-y', you can use the command `C-c C-q' -(`mail-fill-yanked-message') to fill the paragraphs of the yanked old -message or messages. One use of `C-c C-q' fills all such paragraphs, -each one separately. - - Clicking the right mouse button in a mail buffer pops up a menu of -the above commands, for easy access. - - Turning on Mail mode (which `C-x m' does automatically) calls the -value of `text-mode-hook', if it is not void or `nil', and then calls -the value of `mail-mode-hook' if that is not void or `nil'. - - -File: xemacs.info, Node: Reading Mail, Next: Calendar/Diary, Prev: Sending Mail, Up: Top - -Reading Mail -************ - - XEmacs provides three separate mail-reading packages. Each one -comes with its own manual, which is included standard with the XEmacs -distribution. - - The recommended mail-reading package for new users is VM. VM works -with standard Unix-mail-format folders and was designed as a replacement -for the older Rmail. - - XEmacs also provides a sophisticated and comfortable front-end to the -MH mail-processing system, called `mh-e'. Unlike in other mail -programs, folders in MH are stored as file-system directories, with -each message occupying one (numbered) file. This facilitates working -with mail using shell commands, and many other features of MH are also -designed to integrate well with the shell and with shell scripts. Keep -in mind, however, that in order to use mh-e you must have the MH -mail-processing system installed on your computer. - - Finally, XEmacs provides the Rmail package. Rmail is (currently) the -only mail reading package distributed with FSF GNU Emacs, and is -powerful in its own right. However, it stores mail folders in a special -format called `Babyl', that is incompatible with all other -frequently-used mail programs. A utility program is provided for -converting Babyl folders to standard Unix-mail format; however, unless -you already have mail in Babyl-format folders, you should consider -using VM or mh-e instead. (If at times you have to use FSF Emacs, it is -not hard to obtain and install VM for that editor.) - - -File: xemacs.info, Node: Calendar/Diary, Next: Sorting, Prev: Reading Mail, Up: Top - -Calendar Mode and the Diary -=========================== - - Emacs provides the functions of a desk calendar, with a diary of -planned or past events. To enter the calendar, type `M-x calendar'; -this displays a three-month calendar centered on the current month, with -point on the current date. With a numeric argument, as in `C-u M-x -calendar', it prompts you for the month and year to be the center of the -three-month calendar. The calendar uses its own buffer, whose major -mode is Calendar mode. - - `Button2' in the calendar brings up a menu of operations on a -particular date; `Buttons3' brings up a menu of commonly used calendar -features that are independent of any particular date. To exit the -calendar, type `q'. *Note Customizing the Calendar and Diary: -(elisp)Calendar, for customization information about the calendar and -diary. - -* Menu: - -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Mark and Region:: Remembering dates, the mark ring. -* General Calendar:: Exiting or recomputing the calendar. -* LaTeX Calendar:: Print a calendar using LaTeX. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Calendar Customization:: Altering the behavior of the features above. - diff --git a/info/xemacs.info-14 b/info/xemacs.info-14 index d071965..f3b8478 100644 --- a/info/xemacs.info-14 +++ b/info/xemacs.info-14 @@ -30,6 +30,164 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail + +Mail Mode +========= + + The major mode used in the `*mail*' buffer is Mail mode. Mail mode +is similar to Text mode, but several commands are provided on the `C-c' +prefix. These commands all deal specifically with editing or sending +the message. + +`C-c C-s' + Send the message, and leave the `*mail*' buffer selected + (`mail-send'). + +`C-c C-c' + Send the message, and select some other buffer + (`mail-send-and-exit'). + +`C-c C-f C-t' + Move to the `To' header field, creating one if there is none + (`mail-to'). + +`C-c C-f C-s' + Move to the `Subject' header field, creating one if there is none + (`mail-subject'). + +`C-c C-f C-c' + Move to the `CC' header field, creating one if there is none + (`mail-cc'). + +`C-c C-w' + Insert the file `~/.signature' at the end of the message text + (`mail-signature'). + +`C-c C-y' + Yank the selected message (`mail-yank-original'). + +`C-c C-q' + Fill all paragraphs of yanked old messages, each individually + (`mail-fill-yanked-message'). + +`' + Pops up a menu of useful mail-mode commands. + + There are two ways to send a message. `C-c C-c' +(`mail-send-and-exit') is the usual way to send the message. It sends +the message and then deletes the window (if there is another window) or +switches to another buffer. It puts the `*mail*' buffer at the lowest +priority for automatic reselection, since you are finished with using +it. `C-c C-s' (`mail-send') sends the message and marks the `*mail*' +buffer unmodified, but leaves that buffer selected so that you can +modify the message (perhaps with new recipients) and send it again. + + Mail mode provides some other special commands that are useful for +editing the headers and text of the message before you send it. There +are three commands defined to move point to particular header fields, +all based on the prefix `C-c C-f' (`C-f' is for "field"). They are +`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s' +(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc') +for the `CC' field. These fields have special motion commands because +they are edited most frequently. + + `C-c C-w' (`mail-signature') adds a standard piece of text at the +end of the message to say more about who you are. The text comes from +the file `.signature' in your home directory. + + When you use an Rmail command to send mail from the Rmail mail +reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*' +buffer to insert the text of the message you are replying to. Normally +Rmail indents each line of that message four spaces and eliminates most +header fields. A numeric argument specifies the number of spaces to +indent. An argument of just `C-u' says not to indent at all and not to +eliminate anything. `C-c C-y' always uses the current message from the +`RMAIL' buffer, so you can insert several old messages by selecting one +in `RMAIL', switching to `*mail*' and yanking it, then switching back +to `RMAIL' to select another. + + After using `C-c C-y', you can use the command `C-c C-q' +(`mail-fill-yanked-message') to fill the paragraphs of the yanked old +message or messages. One use of `C-c C-q' fills all such paragraphs, +each one separately. + + Clicking the right mouse button in a mail buffer pops up a menu of +the above commands, for easy access. + + Turning on Mail mode (which `C-x m' does automatically) calls the +value of `text-mode-hook', if it is not void or `nil', and then calls +the value of `mail-mode-hook' if that is not void or `nil'. + + +File: xemacs.info, Node: Reading Mail, Next: Calendar/Diary, Prev: Sending Mail, Up: Top + +Reading Mail +************ + + XEmacs provides three separate mail-reading packages. Each one +comes with its own manual, which is included standard with the XEmacs +distribution. + + The recommended mail-reading package for new users is VM. VM works +with standard Unix-mail-format folders and was designed as a replacement +for the older Rmail. + + XEmacs also provides a sophisticated and comfortable front-end to the +MH mail-processing system, called `mh-e'. Unlike in other mail +programs, folders in MH are stored as file-system directories, with +each message occupying one (numbered) file. This facilitates working +with mail using shell commands, and many other features of MH are also +designed to integrate well with the shell and with shell scripts. Keep +in mind, however, that in order to use mh-e you must have the MH +mail-processing system installed on your computer. + + Finally, XEmacs provides the Rmail package. Rmail is (currently) the +only mail reading package distributed with FSF GNU Emacs, and is +powerful in its own right. However, it stores mail folders in a special +format called `Babyl', that is incompatible with all other +frequently-used mail programs. A utility program is provided for +converting Babyl folders to standard Unix-mail format; however, unless +you already have mail in Babyl-format folders, you should consider +using VM or mh-e instead. (If at times you have to use FSF Emacs, it is +not hard to obtain and install VM for that editor.) + + +File: xemacs.info, Node: Calendar/Diary, Next: Sorting, Prev: Reading Mail, Up: Top + +Calendar Mode and the Diary +=========================== + + Emacs provides the functions of a desk calendar, with a diary of +planned or past events. To enter the calendar, type `M-x calendar'; +this displays a three-month calendar centered on the current month, with +point on the current date. With a numeric argument, as in `C-u M-x +calendar', it prompts you for the month and year to be the center of the +three-month calendar. The calendar uses its own buffer, whose major +mode is Calendar mode. + + `Button2' in the calendar brings up a menu of operations on a +particular date; `Buttons3' brings up a menu of commonly used calendar +features that are independent of any particular date. To exit the +calendar, type `q'. *Note Customizing the Calendar and Diary: +(elisp)Calendar, for customization information about the calendar and +diary. + +* Menu: + +* Calendar Motion:: Moving through the calendar; selecting a date. +* Scroll Calendar:: Bringing earlier or later months onto the screen. +* Mark and Region:: Remembering dates, the mark ring. +* General Calendar:: Exiting or recomputing the calendar. +* LaTeX Calendar:: Print a calendar using LaTeX. +* Holidays:: Displaying dates of holidays. +* Sunrise/Sunset:: Displaying local times of sunrise and sunset. +* Lunar Phases:: Displaying phases of the moon. +* Other Calendars:: Converting dates to other calendar systems. +* Diary:: Displaying events from your diary. +* Calendar Customization:: Altering the behavior of the features above. + + File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary Movement in the Calendar @@ -1099,168 +1257,3 @@ applies to any date falling on that day of the week. You can abbreviate the day of the week to three letters (with or without a period) or spell it in full; case is not significant. - -File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary - -Commands to Add to the Diary ----------------------------- - - While in the calendar, there are several commands to create diary -entries: - -`i d' - Add a diary entry for the selected date (`insert-diary-entry'). - -`i w' - Add a diary entry for the selected day of the week - (`insert-weekly-diary-entry'). - -`i m' - Add a diary entry for the selected day of the month - (`insert-monthly-diary-entry'). - -`i y' - Add a diary entry for the selected day of the year - (`insert-yearly-diary-entry'). - - You can make a diary entry for a specific date by selecting that date -in the calendar window and typing the `i d' command. This command -displays the end of your diary file in another window and inserts the -date; you can then type the rest of the diary entry. - - If you want to make a diary entry that applies to a specific day of -the week, select that day of the week (any occurrence will do) and type -`i w'. This inserts the day-of-week as a generic date; you can then -type the rest of the diary entry. You can make a monthly diary entry in -the same fashion. Select the day of the month, use the `i m' command, -and type rest of the entry. Similarly, you can insert a yearly diary -entry with the `i y' command. - - All of the above commands make marking diary entries by default. To -make a nonmarking diary entry, give a numeric argument to the command. -For example, `C-u i w' makes a nonmarking weekly diary entry. - - When you modify the diary file, be sure to save the file before -exiting Emacs. - - -File: xemacs.info, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary - -Special Diary Entries ---------------------- - - In addition to entries based on calendar dates, the diary file can -contain "sexp entries" for regular events such as anniversaries. These -entries are based on Lisp expressions (sexps) that Emacs evaluates as -it scans the diary file. Instead of a date, a sexp entry contains `%%' -followed by a Lisp expression which must begin and end with -parentheses. The Lisp expression determines which dates the entry -applies to. - - Calendar mode provides commands to insert certain commonly used sexp -entries: - -`i a' - Add an anniversary diary entry for the selected date - (`insert-anniversary-diary-entry'). - -`i b' - Add a block diary entry for the current region - (`insert-block-diary-entry'). - -`i c' - Add a cyclic diary entry starting at the date - (`insert-cyclic-diary-entry'). - - If you want to make a diary entry that applies to the anniversary of -a specific date, move point to that date and use the `i a' command. -This displays the end of your diary file in another window and inserts -the anniversary description; you can then type the rest of the diary -entry. The entry looks like this: - - The effect of `i a' is to add a `diary-anniversary' sexp to your -diary file. You can also add one manually, for instance: - - %%(diary-anniversary 10 31 1948) Arthur's birthday - -This entry applies to October 31 in any year after 1948; `10 31 1948' -specifies the date. (If you are using the European calendar style, the -month and day are interchanged.) The reason this expression requires a -beginning year is that advanced diary functions can use it to calculate -the number of elapsed years. - - A "block" diary entry applies to a specified range of consecutive -dates. Here is a block diary entry that applies to all dates from June -24, 1990 through July 10, 1990: - - %%(diary-block 6 24 1990 7 10 1990) Vacation - -The `6 24 1990' indicates the starting date and the `7 10 1990' -indicates the stopping date. (Again, if you are using the European -calendar style, the month and day are interchanged.) - - To insert a block entry, place point and the mark on the two dates -that begin and end the range, and type `i b'. This command displays -the end of your diary file in another window and inserts the block -description; you can then type the diary entry. - - "Cyclic" diary entries repeat after a fixed interval of days. To -create one, select the starting date and use the `i c' command. The -command prompts for the length of interval, then inserts the entry, -which looks like this: - - %%(diary-cyclic 50 3 1 1990) Renew medication - -This entry applies to March 1, 1990 and every 50th day following; `3 1 -1990' specifies the starting date. (If you are using the European -calendar style, the month and day are interchanged.) - - All three of these commands make marking diary entries. To insert a -nonmarking entry, give a numeric argument to the command. For example, -`C-u i a' makes a nonmarking anniversary diary entry. - - Marking sexp diary entries in the calendar is _extremely_ -time-consuming, since every date visible in the calendar window must be -individually checked. So it's a good idea to make sexp diary entries -nonmarking (with `&') when possible. - - Another sophisticated kind of sexp entry, a "floating" diary entry, -specifies a regularly occurring event by offsets specified in days, -weeks, and months. It is comparable to a crontab entry interpreted by -the `cron' utility. Here is a nonmarking, floating diary entry that -applies to the last Thursday in November: - - &%%(diary-float 11 4 -1) American Thanksgiving - -The 11 specifies November (the eleventh month), the 4 specifies Thursday -(the fourth day of the week, where Sunday is numbered zero), and the -1 -specifies "last" (1 would mean "first", 2 would mean "second", -2 would -mean "second-to-last", and so on). The month can be a single month or -a list of months. Thus you could change the 11 above to `'(1 2 3)' and -have the entry apply to the last Thursday of January, February, and -March. If the month is `t', the entry applies to all months of the -year. - - The sexp feature of the diary allows you to specify diary entries -based on any Emacs Lisp expression. You can use the library of built-in -functions or you can write your own functions. The built-in functions -include the ones shown in this section, plus a few others (*note Sexp -Diary Entries::). - - The generality of sexps lets you specify any diary entry that you can -describe algorithmically. Suppose you get paid on the 21st of the month -if it is a weekday, and to the Friday before if the 21st is on a -weekend. The diary entry - - &%%(let ((dayname (calendar-day-of-week date)) - (day (car (cdr date)))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited - -to just those dates. This example illustrates how the sexp can depend -on the variable `date'; this variable is a list (MONTH DAY YEAR) that -gives the Gregorian date for which the diary entries are being found. -If the value of the sexp is `t', the entry applies to that date. If -the sexp evaluates to `nil', the entry does _not_ apply to that date. - diff --git a/info/xemacs.info-15 b/info/xemacs.info-15 index 08b6d30..e790bcd 100644 --- a/info/xemacs.info-15 +++ b/info/xemacs.info-15 @@ -30,6 +30,171 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary + +Commands to Add to the Diary +---------------------------- + + While in the calendar, there are several commands to create diary +entries: + +`i d' + Add a diary entry for the selected date (`insert-diary-entry'). + +`i w' + Add a diary entry for the selected day of the week + (`insert-weekly-diary-entry'). + +`i m' + Add a diary entry for the selected day of the month + (`insert-monthly-diary-entry'). + +`i y' + Add a diary entry for the selected day of the year + (`insert-yearly-diary-entry'). + + You can make a diary entry for a specific date by selecting that date +in the calendar window and typing the `i d' command. This command +displays the end of your diary file in another window and inserts the +date; you can then type the rest of the diary entry. + + If you want to make a diary entry that applies to a specific day of +the week, select that day of the week (any occurrence will do) and type +`i w'. This inserts the day-of-week as a generic date; you can then +type the rest of the diary entry. You can make a monthly diary entry in +the same fashion. Select the day of the month, use the `i m' command, +and type rest of the entry. Similarly, you can insert a yearly diary +entry with the `i y' command. + + All of the above commands make marking diary entries by default. To +make a nonmarking diary entry, give a numeric argument to the command. +For example, `C-u i w' makes a nonmarking weekly diary entry. + + When you modify the diary file, be sure to save the file before +exiting Emacs. + + +File: xemacs.info, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary + +Special Diary Entries +--------------------- + + In addition to entries based on calendar dates, the diary file can +contain "sexp entries" for regular events such as anniversaries. These +entries are based on Lisp expressions (sexps) that Emacs evaluates as +it scans the diary file. Instead of a date, a sexp entry contains `%%' +followed by a Lisp expression which must begin and end with +parentheses. The Lisp expression determines which dates the entry +applies to. + + Calendar mode provides commands to insert certain commonly used sexp +entries: + +`i a' + Add an anniversary diary entry for the selected date + (`insert-anniversary-diary-entry'). + +`i b' + Add a block diary entry for the current region + (`insert-block-diary-entry'). + +`i c' + Add a cyclic diary entry starting at the date + (`insert-cyclic-diary-entry'). + + If you want to make a diary entry that applies to the anniversary of +a specific date, move point to that date and use the `i a' command. +This displays the end of your diary file in another window and inserts +the anniversary description; you can then type the rest of the diary +entry. The entry looks like this: + + The effect of `i a' is to add a `diary-anniversary' sexp to your +diary file. You can also add one manually, for instance: + + %%(diary-anniversary 10 31 1948) Arthur's birthday + +This entry applies to October 31 in any year after 1948; `10 31 1948' +specifies the date. (If you are using the European calendar style, the +month and day are interchanged.) The reason this expression requires a +beginning year is that advanced diary functions can use it to calculate +the number of elapsed years. + + A "block" diary entry applies to a specified range of consecutive +dates. Here is a block diary entry that applies to all dates from June +24, 1990 through July 10, 1990: + + %%(diary-block 6 24 1990 7 10 1990) Vacation + +The `6 24 1990' indicates the starting date and the `7 10 1990' +indicates the stopping date. (Again, if you are using the European +calendar style, the month and day are interchanged.) + + To insert a block entry, place point and the mark on the two dates +that begin and end the range, and type `i b'. This command displays +the end of your diary file in another window and inserts the block +description; you can then type the diary entry. + + "Cyclic" diary entries repeat after a fixed interval of days. To +create one, select the starting date and use the `i c' command. The +command prompts for the length of interval, then inserts the entry, +which looks like this: + + %%(diary-cyclic 50 3 1 1990) Renew medication + +This entry applies to March 1, 1990 and every 50th day following; `3 1 +1990' specifies the starting date. (If you are using the European +calendar style, the month and day are interchanged.) + + All three of these commands make marking diary entries. To insert a +nonmarking entry, give a numeric argument to the command. For example, +`C-u i a' makes a nonmarking anniversary diary entry. + + Marking sexp diary entries in the calendar is _extremely_ +time-consuming, since every date visible in the calendar window must be +individually checked. So it's a good idea to make sexp diary entries +nonmarking (with `&') when possible. + + Another sophisticated kind of sexp entry, a "floating" diary entry, +specifies a regularly occurring event by offsets specified in days, +weeks, and months. It is comparable to a crontab entry interpreted by +the `cron' utility. Here is a nonmarking, floating diary entry that +applies to the last Thursday in November: + + &%%(diary-float 11 4 -1) American Thanksgiving + +The 11 specifies November (the eleventh month), the 4 specifies Thursday +(the fourth day of the week, where Sunday is numbered zero), and the -1 +specifies "last" (1 would mean "first", 2 would mean "second", -2 would +mean "second-to-last", and so on). The month can be a single month or +a list of months. Thus you could change the 11 above to `'(1 2 3)' and +have the entry apply to the last Thursday of January, February, and +March. If the month is `t', the entry applies to all months of the +year. + + The sexp feature of the diary allows you to specify diary entries +based on any Emacs Lisp expression. You can use the library of built-in +functions or you can write your own functions. The built-in functions +include the ones shown in this section, plus a few others (*note Sexp +Diary Entries::). + + The generality of sexps lets you specify any diary entry that you can +describe algorithmically. Suppose you get paid on the 21st of the month +if it is a weekday, and to the Friday before if the 21st is on a +weekend. The diary entry + + &%%(let ((dayname (calendar-day-of-week date)) + (day (car (cdr date)))) + (or (and (= day 21) (memq dayname '(1 2 3 4 5))) + (and (memq day '(19 20)) (= dayname 5))) + ) Pay check deposited + +to just those dates. This example illustrates how the sexp can depend +on the variable `date'; this variable is a list (MONTH DAY YEAR) that +gives the Gregorian date for which the diary entries are being found. +If the value of the sexp is `t', the entry applies to that date. If +the sexp evaluates to `nil', the entry does _not_ apply to that date. + + File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary Customizing the Calendar and Diary @@ -988,194 +1153,3 @@ initializations in your init file. *Note Init File::. command completes. You can quit with `C-g'; that terminates the shell command. - -File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell - -Interactive Inferior Shell --------------------------- - - To run a subshell interactively with its typescript in an XEmacs -buffer, use `M-x shell'. This creates (or reuses) a buffer named -`*shell*' and runs a subshell with input coming from and output going -to that buffer. That is to say, any "terminal output" from the subshell -will go into the buffer, advancing point, and any "terminal input" for -the subshell comes from text in the buffer. To give input to the -subshell, go to the end of the buffer and type the input, terminated by -. - - XEmacs does not wait for the subshell to do anything. You can switch -windows or buffers and edit them while the shell is waiting, or while -it is running a command. Output from the subshell waits until XEmacs -has time to process it; this happens whenever XEmacs is waiting for -keyboard input or for time to elapse. - - To get multiple subshells, change the name of buffer `*shell*' to -something different by using `M-x rename-buffer'. The next use of `M-x -shell' creates a new buffer `*shell*' with its own subshell. By -renaming this buffer as well you can create a third one, and so on. -All the subshells run independently and in parallel. - - The file name used to load the subshell is the value of the variable -`explicit-shell-file-name', if that is non-`nil'. Otherwise, the -environment variable `ESHELL' is used, or the environment variable -`SHELL' if there is no `ESHELL'. If the file name specified is -relative, the directories in the list `exec-path' are searched (*note -Single Shell Commands: Single Shell.). - - As soon as the subshell is started, it is sent as input the contents -of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME -is the name of the file that the shell was loaded from. For example, -if you use `csh', the file sent to it is `~/.emacs_csh'. - - `cd', `pushd', and `popd' commands given to the inferior shell are -watched by XEmacs so it can keep the `*shell*' buffer's default -directory the same as the shell's working directory. These commands -are recognized syntactically by examining lines of input that are sent. -If you use aliases for these commands, you can tell XEmacs to -recognize them also. For example, if the value of the variable -`shell-pushd-regexp' matches the beginning of a shell command line, -that line is regarded as a `pushd' command. Change this variable when -you add aliases for `pushd'. Likewise, `shell-popd-regexp' and -`shell-cd-regexp' are used to recognize commands with the meaning of -`popd' and `cd'. - - `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs' -idea of what the current directory stack is. `M-x -shell-dirtrack-toggle' turns directory tracking on and off. - - XEmacs keeps a history of the most recent commands you have typed in -the `*shell*' buffer. If you are at the beginning of a shell command -line and type , the previous shell input is inserted into the -buffer before point. Immediately typing again deletes that input -and inserts the one before it. By repeating you can move -backward through your commands until you find one you want to repeat. -You may then edit the command before typing if you wish. -moves forward through the command history, in case you moved backward -past the one you wanted while using . If you type the first few -characters of a previous command and then type , the most recent -shell input starting with those characters is inserted. This can be -very convenient when you are repeating a sequence of shell commands. -The variable `input-ring-size' controls how many commands are saved in -your input history. The default is 30. - - -File: xemacs.info, Node: Shell Mode, Next: Terminal emulator, Prev: Interactive Shell, Up: Shell - -Shell Mode ----------- - - The shell buffer uses Shell mode, which defines several special keys -attached to the `C-c' prefix. They are chosen to resemble the usual -editing and job control characters present in shells that are not under -XEmacs, except that you must type `C-c' first. Here is a list of the -special key bindings of Shell mode: - -`' - At end of buffer send line as input; otherwise, copy current line - to end of buffer and send it (`send-shell-input'). When a line is - copied, any text at the beginning of the line that matches the - variable `shell-prompt-pattern' is left out; this variable's value - should be a regexp string that matches the prompts that you use in - your subshell. - -`C-c C-d' - Send end-of-file as input, probably causing the shell or its - current subjob to finish (`shell-send-eof'). - -`C-d' - If point is not at the end of the buffer, delete the next - character just like most other modes. If point is at the end of - the buffer, send end-of-file as input, instead of generating an - error as in other modes (`comint-delchar-or-maybe-eof'). - -`C-c C-u' - Kill all text that has yet to be sent as input - (`kill-shell-input'). - -`C-c C-w' - Kill a word before point (`backward-kill-word'). - -`C-c C-c' - Interrupt the shell or its current subjob if any - (`interrupt-shell-subjob'). - -`C-c C-z' - Stop the shell or its current subjob if any (`stop-shell-subjob'). - -`C-c C-\' - Send quit signal to the shell or its current subjob if any - (`quit-shell-subjob'). - -`C-c C-o' - Delete last batch of output from shell (`kill-output-from-shell'). - -`C-c C-r' - Scroll top of last batch of output to top of window - (`show-output-from-shell'). - -`C-c C-y' - Copy the previous bunch of shell input and insert it into the - buffer before point (`copy-last-shell-input'). No final newline - is inserted, and the input copied is not resubmitted until you type - . - -`M-p' - Move backward through the input history. Search for a matching - command if you have typed the beginning of a command - (`comint-previous-input'). - -`M-n' - Move forward through the input history. Useful when you are using - quickly and go past the desired command - (`comint-next-input'). - -`' - Complete the file name preceding point (`comint-dynamic-complete'). - - -File: xemacs.info, Node: Terminal emulator, Next: Term Mode, Prev: Shell Mode, Up: Shell - -Interactive Inferior Shell with Terminal Emulator -------------------------------------------------- - - To run a subshell in a terminal emulator, putting its typescript in -an XEmacs buffer, use `M-x term'. This creates (or reuses) a buffer -named `*term*' and runs a subshell with input coming from your keyboard -and output going to that buffer. - - All the normal keys that you type are sent without any interpretation -by XEmacs directly to the subshell, as "terminal input." Any "echo" of -your input is the responsibility of the subshell. (The exception is -the terminal escape character, which by default is `C-c'. *note Term -Mode::.) Any "terminal output" from the subshell goes into the buffer, -advancing point. - - Some programs (such as XEmacs itself) need to control the appearance -on the terminal screen in detail. They do this by sending special -control codes. The exact control codes needed vary from terminal to -terminal, but nowadays most terminals and terminal emulators (including -xterm) understand the so-called "ANSI escape sequences" (first -popularized by the Digital's VT100 family of terminal). The term mode -also understands these escape sequences, and for each control code does -the appropriate thing to change the buffer so that the appearance of -the window will match what it would be on a real terminal. Thus you -can actually run XEmacs inside an XEmacs Term window! - - XEmacs does not wait for the subshell to do anything. You can switch -windows or buffers and edit them while the shell is waiting, or while -it is running a command. Output from the subshell waits until XEmacs -has time to process it; this happens whenever XEmacs is waiting for -keyboard input or for time to elapse. - - To make multiple terminal emulators, rename the buffer `*term*' to -something different using `M-x rename-uniquely', just as with Shell -mode. - - The file name used to load the subshell is determined the same way -as for Shell mode. - - Unlike Shell mode, Term mode does not track the current directory by -examining your input. Instead, if you use a programmable shell, you -can have it tell Term what the current directory is. This is done -automatically by bash for version 1.15 and later. - diff --git a/info/xemacs.info-16 b/info/xemacs.info-16 index dbcc287..07d3445 100644 --- a/info/xemacs.info-16 +++ b/info/xemacs.info-16 @@ -30,6 +30,197 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell + +Interactive Inferior Shell +-------------------------- + + To run a subshell interactively with its typescript in an XEmacs +buffer, use `M-x shell'. This creates (or reuses) a buffer named +`*shell*' and runs a subshell with input coming from and output going +to that buffer. That is to say, any "terminal output" from the subshell +will go into the buffer, advancing point, and any "terminal input" for +the subshell comes from text in the buffer. To give input to the +subshell, go to the end of the buffer and type the input, terminated by +. + + XEmacs does not wait for the subshell to do anything. You can switch +windows or buffers and edit them while the shell is waiting, or while +it is running a command. Output from the subshell waits until XEmacs +has time to process it; this happens whenever XEmacs is waiting for +keyboard input or for time to elapse. + + To get multiple subshells, change the name of buffer `*shell*' to +something different by using `M-x rename-buffer'. The next use of `M-x +shell' creates a new buffer `*shell*' with its own subshell. By +renaming this buffer as well you can create a third one, and so on. +All the subshells run independently and in parallel. + + The file name used to load the subshell is the value of the variable +`explicit-shell-file-name', if that is non-`nil'. Otherwise, the +environment variable `ESHELL' is used, or the environment variable +`SHELL' if there is no `ESHELL'. If the file name specified is +relative, the directories in the list `exec-path' are searched (*note +Single Shell Commands: Single Shell.). + + As soon as the subshell is started, it is sent as input the contents +of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME +is the name of the file that the shell was loaded from. For example, +if you use `csh', the file sent to it is `~/.emacs_csh'. + + `cd', `pushd', and `popd' commands given to the inferior shell are +watched by XEmacs so it can keep the `*shell*' buffer's default +directory the same as the shell's working directory. These commands +are recognized syntactically by examining lines of input that are sent. +If you use aliases for these commands, you can tell XEmacs to +recognize them also. For example, if the value of the variable +`shell-pushd-regexp' matches the beginning of a shell command line, +that line is regarded as a `pushd' command. Change this variable when +you add aliases for `pushd'. Likewise, `shell-popd-regexp' and +`shell-cd-regexp' are used to recognize commands with the meaning of +`popd' and `cd'. + + `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs' +idea of what the current directory stack is. `M-x +shell-dirtrack-toggle' turns directory tracking on and off. + + XEmacs keeps a history of the most recent commands you have typed in +the `*shell*' buffer. If you are at the beginning of a shell command +line and type , the previous shell input is inserted into the +buffer before point. Immediately typing again deletes that input +and inserts the one before it. By repeating you can move +backward through your commands until you find one you want to repeat. +You may then edit the command before typing if you wish. +moves forward through the command history, in case you moved backward +past the one you wanted while using . If you type the first few +characters of a previous command and then type , the most recent +shell input starting with those characters is inserted. This can be +very convenient when you are repeating a sequence of shell commands. +The variable `input-ring-size' controls how many commands are saved in +your input history. The default is 30. + + +File: xemacs.info, Node: Shell Mode, Next: Terminal emulator, Prev: Interactive Shell, Up: Shell + +Shell Mode +---------- + + The shell buffer uses Shell mode, which defines several special keys +attached to the `C-c' prefix. They are chosen to resemble the usual +editing and job control characters present in shells that are not under +XEmacs, except that you must type `C-c' first. Here is a list of the +special key bindings of Shell mode: + +`' + At end of buffer send line as input; otherwise, copy current line + to end of buffer and send it (`send-shell-input'). When a line is + copied, any text at the beginning of the line that matches the + variable `shell-prompt-pattern' is left out; this variable's value + should be a regexp string that matches the prompts that you use in + your subshell. + +`C-c C-d' + Send end-of-file as input, probably causing the shell or its + current subjob to finish (`shell-send-eof'). + +`C-d' + If point is not at the end of the buffer, delete the next + character just like most other modes. If point is at the end of + the buffer, send end-of-file as input, instead of generating an + error as in other modes (`comint-delchar-or-maybe-eof'). + +`C-c C-u' + Kill all text that has yet to be sent as input + (`kill-shell-input'). + +`C-c C-w' + Kill a word before point (`backward-kill-word'). + +`C-c C-c' + Interrupt the shell or its current subjob if any + (`interrupt-shell-subjob'). + +`C-c C-z' + Stop the shell or its current subjob if any (`stop-shell-subjob'). + +`C-c C-\' + Send quit signal to the shell or its current subjob if any + (`quit-shell-subjob'). + +`C-c C-o' + Delete last batch of output from shell (`kill-output-from-shell'). + +`C-c C-r' + Scroll top of last batch of output to top of window + (`show-output-from-shell'). + +`C-c C-y' + Copy the previous bunch of shell input and insert it into the + buffer before point (`copy-last-shell-input'). No final newline + is inserted, and the input copied is not resubmitted until you type + . + +`M-p' + Move backward through the input history. Search for a matching + command if you have typed the beginning of a command + (`comint-previous-input'). + +`M-n' + Move forward through the input history. Useful when you are using + quickly and go past the desired command + (`comint-next-input'). + +`' + Complete the file name preceding point (`comint-dynamic-complete'). + + +File: xemacs.info, Node: Terminal emulator, Next: Term Mode, Prev: Shell Mode, Up: Shell + +Interactive Inferior Shell with Terminal Emulator +------------------------------------------------- + + To run a subshell in a terminal emulator, putting its typescript in +an XEmacs buffer, use `M-x term'. This creates (or reuses) a buffer +named `*term*' and runs a subshell with input coming from your keyboard +and output going to that buffer. + + All the normal keys that you type are sent without any interpretation +by XEmacs directly to the subshell, as "terminal input." Any "echo" of +your input is the responsibility of the subshell. (The exception is +the terminal escape character, which by default is `C-c'. *note Term +Mode::.) Any "terminal output" from the subshell goes into the buffer, +advancing point. + + Some programs (such as XEmacs itself) need to control the appearance +on the terminal screen in detail. They do this by sending special +control codes. The exact control codes needed vary from terminal to +terminal, but nowadays most terminals and terminal emulators (including +xterm) understand the so-called "ANSI escape sequences" (first +popularized by the Digital's VT100 family of terminal). The term mode +also understands these escape sequences, and for each control code does +the appropriate thing to change the buffer so that the appearance of +the window will match what it would be on a real terminal. Thus you +can actually run XEmacs inside an XEmacs Term window! + + XEmacs does not wait for the subshell to do anything. You can switch +windows or buffers and edit them while the shell is waiting, or while +it is running a command. Output from the subshell waits until XEmacs +has time to process it; this happens whenever XEmacs is waiting for +keyboard input or for time to elapse. + + To make multiple terminal emulators, rename the buffer `*term*' to +something different using `M-x rename-uniquely', just as with Shell +mode. + + The file name used to load the subshell is determined the same way +as for Shell mode. + + Unlike Shell mode, Term mode does not track the current directory by +examining your input. Instead, if you use a programmable shell, you +can have it tell Term what the current directory is. This is done +automatically by bash for version 1.15 and later. + + File: xemacs.info, Node: Term Mode, Next: Paging in Term, Prev: Terminal emulator, Up: Shell Term Mode @@ -976,198 +1167,3 @@ explicitly, as in the case of: (default-value 'fill-column) - -File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables - -Local Variables in Files ------------------------- - - A file can contain a "local variables list", which specifies the -values to use for certain Emacs variables when that file is edited. -Visiting the file checks for a local variables list and makes each -variable in the list local to the buffer in which the file is visited, -with the value specified in the file. - - A local variables list goes near the end of the file, in the last -page. (It is often best to put it on a page by itself.) The local -variables list starts with a line containing the string `Local -Variables:', and ends with a line containing the string `End:'. In -between come the variable names and values, one set per line, as -`VARIABLE: VALUE'. The VALUEs are not evaluated; they are used -literally. - - The line which starts the local variables list does not have to say -just `Local Variables:'. If there is other text before `Local -Variables:', that text is called the "prefix", and if there is other -text after, that is called the "suffix". If a prefix or suffix are -present, each entry in the local variables list should have the prefix -before it and the suffix after it. This includes the `End:' line. The -prefix and suffix are included to disguise the local variables list as -a comment so the compiler or text formatter will ignore it. If you do -not need to disguise the local variables list as a comment in this way, -there is no need to include a prefix or a suffix. - - Two "variable" names are special in a local variables list: a value -for the variable `mode' sets the major mode, and a value for the -variable `eval' is simply evaluated as an expression and the value is -ignored. These are not real variables; setting them in any other -context does not have the same effect. If `mode' is used in a local -variables list, it should be the first entry in the list. - - Here is an example of a local variables list: - ;;; Local Variables: *** - ;;; mode:lisp *** - ;;; comment-column:0 *** - ;;; comment-start: ";;; " *** - ;;; comment-end:"***" *** - ;;; End: *** - - Note that the prefix is `;;; ' and the suffix is ` ***'. Note also -that comments in the file begin with and end with the same strings. -Presumably the file contains code in a language which is enough like -Lisp for Lisp mode to be useful but in which comments start and end -differently. The prefix and suffix are used in the local variables -list to make the list look like several lines of comments when the -compiler or interpreter for that language reads the file. - - The start of the local variables list must be no more than 3000 -characters from the end of the file, and must be in the last page if the -file is divided into pages. Otherwise, Emacs will not notice it is -there. The purpose is twofold: a stray `Local Variables:' not in the -last page does not confuse Emacs, and Emacs never needs to search a -long file that contains no page markers and has no local variables list. - - You may be tempted to turn on Auto Fill mode with a local variable -list. That is inappropriate. Whether you use Auto Fill mode or not is -a matter of personal taste, not a matter of the contents of particular -files. If you want to use Auto Fill, set up major mode hooks with your -init file to turn it on (when appropriate) for you alone (*note Init -File::). Don't try to use a local variable list that would impose your -taste on everyone working with the file. - - XEmacs allows you to specify local variables in the first line of a -file, in addition to specifying them in the `Local Variables' section -at the end of a file. - - If the first line of a file contains two occurrences of ``-*-'', -XEmacs uses the information between them to determine what the major -mode and variable settings should be. For example, these are all legal: - - ;;; -*- mode: emacs-lisp -*- - ;;; -*- mode: postscript; version-control: never -*- - ;;; -*- tags-file-name: "/foo/bar/TAGS" -*- - - For historical reasons, the syntax ``-*- modename -*-'' is allowed -as well; for example, you can use: - - ;;; -*- emacs-lisp -*- - - The variable `enable-local-variables' controls the use of local -variables lists in files you visit. The value can be `t', `nil', or -something else. A value of `t' means local variables lists are obeyed; -`nil' means they are ignored; anything else means query. - - The command `M-x normal-mode' always obeys local variables lists and -ignores this variable. - - -File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization - -Keyboard Macros -=============== - - A "keyboard macro" is a command defined by the user to abbreviate a -sequence of keys. For example, if you discover that you are about to -type `C-n C-d' forty times, you can speed your work by defining a -keyboard macro to invoke `C-n C-d' and calling it with a repeat count -of forty. - -`C-x (' - Start defining a keyboard macro (`start-kbd-macro'). - -`C-x )' - End the definition of a keyboard macro (`end-kbd-macro'). - -`C-x e' - Execute the most recent keyboard macro (`call-last-kbd-macro'). - -`C-u C-x (' - Re-execute last keyboard macro, then add more keys to its - definition. - -`C-x q' - When this point is reached during macro execution, ask for - confirmation (`kbd-macro-query'). - -`M-x name-last-kbd-macro' - Give a command name (for the duration of the session) to the most - recently defined keyboard macro. - -`M-x insert-kbd-macro' - Insert in the buffer a keyboard macro's definition, as Lisp code. - - Keyboard macros differ from other Emacs commands in that they are -written in the Emacs command language rather than in Lisp. This makes -it easier for the novice to write them and makes them more convenient as -temporary hacks. However, the Emacs command language is not powerful -enough as a programming language to be useful for writing anything -general or complex. For such things, Lisp must be used. - - You define a keyboard macro by executing the commands which are its -definition. Put differently, as you are defining a keyboard macro, the -definition is being executed for the first time. This way, you see -what the effects of your commands are, and don't have to figure them -out in your head. When you are finished, the keyboard macro is defined -and also has been executed once. You can then execute the same set of -commands again by invoking the macro. - -* Menu: - -* Basic Kbd Macro:: Defining and running keyboard macros. -* Save Kbd Macro:: Giving keyboard macros names; saving them in files. -* Kbd Macro Query:: Keyboard macros that do different things each use. - - -File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros - -Basic Use ---------- - - To start defining a keyboard macro, type `C-x (' -(`start-kbd-macro'). From then on, anything you type continues to be -executed, but also becomes part of the definition of the macro. `Def' -appears in the mode line to remind you of what is going on. When you -are finished, the `C-x )' command (`end-kbd-macro') terminates the -definition, without becoming part of it. - - For example, - - C-x ( M-f foo C-x ) - -defines a macro to move forward a word and then insert `foo'. - - You can give `C-x )' a repeat count as an argument, in which case it -repeats the macro that many times right after defining it, but defining -the macro counts as the first repetition (since it is executed as you -define it). If you give `C-x )' an argument of 4, it executes the -macro immediately 3 additional times. An argument of zero to `C-x e' -or `C-x )' means repeat the macro indefinitely (until it gets an error -or you type `C-g'). - - Once you have defined a macro, you can invoke it again with the `C-x -e' command (`call-last-kbd-macro'). You can give the command a repeat -count numeric argument to execute the macro many times. - - To repeat an operation at regularly spaced places in the text, -define a macro and include as part of the macro the commands to move to -the next place you want to use it. For example, if you want to change -each line, you should position point at the start of a line, and define -a macro to change that line and leave point at the start of the next -line. Repeating the macro will then operate on successive lines. - - After you have terminated the definition of a keyboard macro, you -can add to the end of its definition by typing `C-u C-x ('. This is -equivalent to plain `C-x (' followed by retyping the whole definition -so far. As a consequence it re-executes the macro as previously -defined. - diff --git a/info/xemacs.info-17 b/info/xemacs.info-17 index 8326642..0b7a7a7 100644 --- a/info/xemacs.info-17 +++ b/info/xemacs.info-17 @@ -30,6 +30,201 @@ 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 Variables, Prev: Locals, Up: Variables + +Local Variables in Files +------------------------ + + A file can contain a "local variables list", which specifies the +values to use for certain Emacs variables when that file is edited. +Visiting the file checks for a local variables list and makes each +variable in the list local to the buffer in which the file is visited, +with the value specified in the file. + + A local variables list goes near the end of the file, in the last +page. (It is often best to put it on a page by itself.) The local +variables list starts with a line containing the string `Local +Variables:', and ends with a line containing the string `End:'. In +between come the variable names and values, one set per line, as +`VARIABLE: VALUE'. The VALUEs are not evaluated; they are used +literally. + + The line which starts the local variables list does not have to say +just `Local Variables:'. If there is other text before `Local +Variables:', that text is called the "prefix", and if there is other +text after, that is called the "suffix". If a prefix or suffix are +present, each entry in the local variables list should have the prefix +before it and the suffix after it. This includes the `End:' line. The +prefix and suffix are included to disguise the local variables list as +a comment so the compiler or text formatter will ignore it. If you do +not need to disguise the local variables list as a comment in this way, +there is no need to include a prefix or a suffix. + + Two "variable" names are special in a local variables list: a value +for the variable `mode' sets the major mode, and a value for the +variable `eval' is simply evaluated as an expression and the value is +ignored. These are not real variables; setting them in any other +context does not have the same effect. If `mode' is used in a local +variables list, it should be the first entry in the list. + + Here is an example of a local variables list: + ;;; Local Variables: *** + ;;; mode:lisp *** + ;;; comment-column:0 *** + ;;; comment-start: ";;; " *** + ;;; comment-end:"***" *** + ;;; End: *** + + Note that the prefix is `;;; ' and the suffix is ` ***'. Note also +that comments in the file begin with and end with the same strings. +Presumably the file contains code in a language which is enough like +Lisp for Lisp mode to be useful but in which comments start and end +differently. The prefix and suffix are used in the local variables +list to make the list look like several lines of comments when the +compiler or interpreter for that language reads the file. + + The start of the local variables list must be no more than 3000 +characters from the end of the file, and must be in the last page if the +file is divided into pages. Otherwise, Emacs will not notice it is +there. The purpose is twofold: a stray `Local Variables:' not in the +last page does not confuse Emacs, and Emacs never needs to search a +long file that contains no page markers and has no local variables list. + + You may be tempted to turn on Auto Fill mode with a local variable +list. That is inappropriate. Whether you use Auto Fill mode or not is +a matter of personal taste, not a matter of the contents of particular +files. If you want to use Auto Fill, set up major mode hooks with your +init file to turn it on (when appropriate) for you alone (*note Init +File::). Don't try to use a local variable list that would impose your +taste on everyone working with the file. + + XEmacs allows you to specify local variables in the first line of a +file, in addition to specifying them in the `Local Variables' section +at the end of a file. + + If the first line of a file contains two occurrences of ``-*-'', +XEmacs uses the information between them to determine what the major +mode and variable settings should be. For example, these are all legal: + + ;;; -*- mode: emacs-lisp -*- + ;;; -*- mode: postscript; version-control: never -*- + ;;; -*- tags-file-name: "/foo/bar/TAGS" -*- + + For historical reasons, the syntax ``-*- modename -*-'' is allowed +as well; for example, you can use: + + ;;; -*- emacs-lisp -*- + + The variable `enable-local-variables' controls the use of local +variables lists in files you visit. The value can be `t', `nil', or +something else. A value of `t' means local variables lists are obeyed; +`nil' means they are ignored; anything else means query. + + The command `M-x normal-mode' always obeys local variables lists and +ignores this variable. + + +File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization + +Keyboard Macros +=============== + + A "keyboard macro" is a command defined by the user to abbreviate a +sequence of keys. For example, if you discover that you are about to +type `C-n C-d' forty times, you can speed your work by defining a +keyboard macro to invoke `C-n C-d' and calling it with a repeat count +of forty. + +`C-x (' + Start defining a keyboard macro (`start-kbd-macro'). + +`C-x )' + End the definition of a keyboard macro (`end-kbd-macro'). + +`C-x e' + Execute the most recent keyboard macro (`call-last-kbd-macro'). + +`C-u C-x (' + Re-execute last keyboard macro, then add more keys to its + definition. + +`C-x q' + When this point is reached during macro execution, ask for + confirmation (`kbd-macro-query'). + +`M-x name-last-kbd-macro' + Give a command name (for the duration of the session) to the most + recently defined keyboard macro. + +`M-x insert-kbd-macro' + Insert in the buffer a keyboard macro's definition, as Lisp code. + + Keyboard macros differ from other Emacs commands in that they are +written in the Emacs command language rather than in Lisp. This makes +it easier for the novice to write them and makes them more convenient as +temporary hacks. However, the Emacs command language is not powerful +enough as a programming language to be useful for writing anything +general or complex. For such things, Lisp must be used. + + You define a keyboard macro by executing the commands which are its +definition. Put differently, as you are defining a keyboard macro, the +definition is being executed for the first time. This way, you see +what the effects of your commands are, and don't have to figure them +out in your head. When you are finished, the keyboard macro is defined +and also has been executed once. You can then execute the same set of +commands again by invoking the macro. + +* Menu: + +* Basic Kbd Macro:: Defining and running keyboard macros. +* Save Kbd Macro:: Giving keyboard macros names; saving them in files. +* Kbd Macro Query:: Keyboard macros that do different things each use. + + +File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros + +Basic Use +--------- + + To start defining a keyboard macro, type `C-x (' +(`start-kbd-macro'). From then on, anything you type continues to be +executed, but also becomes part of the definition of the macro. `Def' +appears in the mode line to remind you of what is going on. When you +are finished, the `C-x )' command (`end-kbd-macro') terminates the +definition, without becoming part of it. + + For example, + + C-x ( M-f foo C-x ) + +defines a macro to move forward a word and then insert `foo'. + + You can give `C-x )' a repeat count as an argument, in which case it +repeats the macro that many times right after defining it, but defining +the macro counts as the first repetition (since it is executed as you +define it). If you give `C-x )' an argument of 4, it executes the +macro immediately 3 additional times. An argument of zero to `C-x e' +or `C-x )' means repeat the macro indefinitely (until it gets an error +or you type `C-g'). + + Once you have defined a macro, you can invoke it again with the `C-x +e' command (`call-last-kbd-macro'). You can give the command a repeat +count numeric argument to execute the macro many times. + + To repeat an operation at regularly spaced places in the text, +define a macro and include as part of the macro the commands to move to +the next place you want to use it. For example, if you want to change +each line, you should position point at the start of a line, and define +a macro to change that line and leave point at the start of the next +line. Repeating the macro will then operate on successive lines. + + After you have terminated the definition of a keyboard macro, you +can add to the end of its definition by typing `C-u C-x ('. This is +equivalent to plain `C-x (' followed by retyping the whole definition +so far. As a consequence it re-executes the macro as previously +defined. + + File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros Naming and Saving Keyboard Macros @@ -978,254 +1173,3 @@ kernel of Emacs uses. `yes-or-no-p' You type something other than `yes' or `no' - -File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization - -Faces -===== - - XEmacs has objects called extents and faces. An "extent" is a -region of text and a "face" is a collection of textual attributes, such -as fonts and colors. Every extent is displayed in some face; -therefore, changing the properties of a face immediately updates the -display of all associated extents. Faces can be frame-local: you can -have a region of text that displays with completely different -attributes when its buffer is viewed from a different X window. - - The display attributes of faces may be specified either in Lisp or -through the X resource manager. - -Customizing Faces ------------------ - - You can change the face of an extent with the functions in this -section. All the functions prompt for a FACE as an argument; use -completion for a list of possible values. - -`M-x invert-face' - Swap the foreground and background colors of the given FACE. - -`M-x make-face-bold' - Make the font of the given FACE bold. When called from a program, - returns `nil' if this is not possible. - -`M-x make-face-bold-italic' - Make the font of the given FACE bold italic. When called from a - program, returns `nil' if not possible. - -`M-x make-face-italic' - Make the font of the given FACE italic. When called from a - program, returns `nil' if not possible. - -`M-x make-face-unbold' - Make the font of the given FACE non-bold. When called from a - program, returns `nil' if not possible. - -`M-x make-face-unitalic' - Make the font of the given FACE non-italic. When called from a - program, returns `nil' if not possible. - -`M-x make-face-larger' - Make the font of the given FACE a little larger. When called from - a program, returns `nil' if not possible. - -`M-x make-face-smaller' - Make the font of the given FACE a little smaller. When called - from a program, returns `nil' if not possible. - -`M-x set-face-background' - Change the background color of the given FACE. - -`M-x set-face-background-pixmap' - Change the background pixmap of the given FACE. - -`M-x set-face-font' - Change the font of the given FACE. - -`M-x set-face-foreground' - Change the foreground color of the given FACE. - -`M-x set-face-underline-p' - Change whether the given FACE is underlined. - - You can exchange the foreground and background color of the selected -FACE with the function `invert-face'. If the face does not specify both -foreground and background, then its foreground and background are set -to the background and foreground of the default face. When calling -this from a program, you can supply the optional argument FRAME to -specify which frame is affected; otherwise, all frames are affected. - - You can set the background color of the specified FACE with the -function `set-face-background'. The argument `color' should be a -string, the name of a color. When called from a program, if the -optional FRAME argument is provided, the face is changed only in that -frame; otherwise, it is changed in all frames. - - You can set the background pixmap of the specified FACE with the -function `set-face-background-pixmap'. The pixmap argument NAME should -be a string, the name of a file of pixmap data. The directories listed -in the `x-bitmap-file-path' variable are searched. The bitmap may also -be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are -the size in pixels, and DATA is a string containing the raw bits of the -bitmap. If the optional FRAME argument is provided, the face is -changed only in that frame; otherwise, it is changed in all frames. - - The variable `x-bitmap-file-path' takes as a value a list of the -directories in which X bitmap files may be found. If the value is -`nil', the list is initialized from the `*bitmapFilePath' resource. - - If the environment variable XBMLANGPATH is set, then it is consulted -before the `x-bitmap-file-path' variable. - - You can set the font of the specified FACE with the function -`set-face-font'. The FONT argument should be a string, the name of a -font. When called from a program, if the optional FRAME argument is -provided, the face is changed only in that frame; otherwise, it is -changed in all frames. - - You can set the foreground color of the specified FACE with the -function `set-face-foreground'. The argument COLOR should be a string, -the name of a color. If the optional FRAME argument is provided, the -face is changed only in that frame; otherwise, it is changed in all -frames. - - You can set underline the specified FACE with the function -`set-face-underline-p'. The argument UNDERLINE-P can be used to make -underlining an attribute of the face or not. If the optional FRAME -argument is provided, the face is changed only in that frame; -otherwise, it is changed in all frames. - - -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 -=========== - - Historically, XEmacs has used the X resource application class -`Emacs' for its resources. Unfortunately, GNU Emacs uses the same -application class, and resources are not compatible between the two -Emacsen. This sharing of the application class often leads to trouble -if you want to run both variants. - - Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds -any XEmacs resources in the resource database when the X connection is -initialized. Otherwise, it will use the class `Emacs' for backwards -compatibility. The variable X-EMACS-APPLICATION-CLASS may be consulted -to determine the application class being used. - - The examples in this section assume the application class is `Emacs'. - - The Emacs resources are generally set per-frame. Each Emacs frame -can have its own name or the same name as another, depending on the -name passed to the `make-frame' function. - - You can specify resources for all frames with the syntax: - - Emacs*parameter: value - -or - - Emacs*EmacsFrame.parameter:value - -You can specify resources for a particular frame with the syntax: - - Emacs*FRAME-NAME.parameter: value - -* Menu: - -* Geometry Resources:: Controlling the size and position of frames. -* Iconic Resources:: Controlling whether frames come up iconic. -* Resource List:: List of resources settable on a frame or device. -* Face Resources:: Controlling faces using resources. -* Widgets:: The widget hierarchy for XEmacs. -* Menubar Resources:: Specifying resources for the menubar. - - -File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources - -Geometry Resources ------------------- - - To make the default size of all Emacs frames be 80 columns by 55 -lines, do this: - - Emacs*EmacsFrame.geometry: 80x55 - -To set the geometry of a particular frame named `fred', do this: - - Emacs*fred.geometry: 80x55 - -Important! Do not use the following syntax: - - Emacs*geometry: 80x55 - -You should never use `*geometry' with any X application. It does not -say "make the geometry of Emacs be 80 columns by 55 lines." It really -says, "make Emacs and all subwindows thereof be 80x55 in whatever units -they care to measure in." In particular, that is both telling the -Emacs text pane to be 80x55 in characters, and telling the menubar pane -to be 80x55 pixels, which is surely not what you want. - - As a special case, this geometry specification also works (and sets -the default size of all Emacs frames to 80 columns by 55 lines): - - Emacs.geometry: 80x55 - -since that is the syntax used with most other applications (since most -other applications have only one top-level window, unlike Emacs). In -general, however, the top-level shell (the unmapped ApplicationShell -widget named `Emacs' that is the parent of the shell widgets that -actually manage the individual frames) does not have any interesting -resources on it, and you should set the resources on the frames instead. - - The `-geometry' command-line argument sets only the geometry of the -initial frame created by Emacs. - - A more complete explanation of geometry-handling is - - * The `-geometry' command-line option sets the `Emacs.geometry' - resource, that is, the geometry of the ApplicationShell. - - * For the first frame created, the size of the frame is taken from - the ApplicationShell if it is specified, otherwise from the - geometry of the frame. - - * For subsequent frames, the order is reversed: First the frame, and - then the ApplicationShell. - - * For the first frame created, the position of the frame is taken - from the ApplicationShell (`Emacs.geometry') if it is specified, - otherwise from the geometry of the frame. - - * For subsequent frames, the position is taken only from the frame, - and never from the ApplicationShell. - - This is rather complicated, but it does seem to provide the most -intuitive behavior with respect to the default sizes and positions of -frames created in various ways. - - -File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources - -Iconic Resources ----------------- - - Analogous to `-geometry', the `-iconic' command-line option sets the -iconic flag of the ApplicationShell (`Emacs.iconic') and always applies -to the first frame created regardless of its name. However, it is -possible to set the iconic flag on particular frames (by name) by using -the `Emacs*FRAME-NAME.iconic' resource. - diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index 48e15c5..1983b65 100644 --- a/info/xemacs.info-18 +++ b/info/xemacs.info-18 @@ -30,6 +30,257 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization + +Faces +===== + + XEmacs has objects called extents and faces. An "extent" is a +region of text and a "face" is a collection of textual attributes, such +as fonts and colors. Every extent is displayed in some face; +therefore, changing the properties of a face immediately updates the +display of all associated extents. Faces can be frame-local: you can +have a region of text that displays with completely different +attributes when its buffer is viewed from a different X window. + + The display attributes of faces may be specified either in Lisp or +through the X resource manager. + +Customizing Faces +----------------- + + You can change the face of an extent with the functions in this +section. All the functions prompt for a FACE as an argument; use +completion for a list of possible values. + +`M-x invert-face' + Swap the foreground and background colors of the given FACE. + +`M-x make-face-bold' + Make the font of the given FACE bold. When called from a program, + returns `nil' if this is not possible. + +`M-x make-face-bold-italic' + Make the font of the given FACE bold italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-italic' + Make the font of the given FACE italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-unbold' + Make the font of the given FACE non-bold. When called from a + program, returns `nil' if not possible. + +`M-x make-face-unitalic' + Make the font of the given FACE non-italic. When called from a + program, returns `nil' if not possible. + +`M-x make-face-larger' + Make the font of the given FACE a little larger. When called from + a program, returns `nil' if not possible. + +`M-x make-face-smaller' + Make the font of the given FACE a little smaller. When called + from a program, returns `nil' if not possible. + +`M-x set-face-background' + Change the background color of the given FACE. + +`M-x set-face-background-pixmap' + Change the background pixmap of the given FACE. + +`M-x set-face-font' + Change the font of the given FACE. + +`M-x set-face-foreground' + Change the foreground color of the given FACE. + +`M-x set-face-underline-p' + Change whether the given FACE is underlined. + + You can exchange the foreground and background color of the selected +FACE with the function `invert-face'. If the face does not specify both +foreground and background, then its foreground and background are set +to the background and foreground of the default face. When calling +this from a program, you can supply the optional argument FRAME to +specify which frame is affected; otherwise, all frames are affected. + + You can set the background color of the specified FACE with the +function `set-face-background'. The argument `color' should be a +string, the name of a color. When called from a program, if the +optional FRAME argument is provided, the face is changed only in that +frame; otherwise, it is changed in all frames. + + You can set the background pixmap of the specified FACE with the +function `set-face-background-pixmap'. The pixmap argument NAME should +be a string, the name of a file of pixmap data. The directories listed +in the `x-bitmap-file-path' variable are searched. The bitmap may also +be a list of the form `(WIDTH HEIGHT DATA)', where WIDTH and HEIGHT are +the size in pixels, and DATA is a string containing the raw bits of the +bitmap. If the optional FRAME argument is provided, the face is +changed only in that frame; otherwise, it is changed in all frames. + + The variable `x-bitmap-file-path' takes as a value a list of the +directories in which X bitmap files may be found. If the value is +`nil', the list is initialized from the `*bitmapFilePath' resource. + + If the environment variable XBMLANGPATH is set, then it is consulted +before the `x-bitmap-file-path' variable. + + You can set the font of the specified FACE with the function +`set-face-font'. The FONT argument should be a string, the name of a +font. When called from a program, if the optional FRAME argument is +provided, the face is changed only in that frame; otherwise, it is +changed in all frames. + + You can set the foreground color of the specified FACE with the +function `set-face-foreground'. The argument COLOR should be a string, +the name of a color. If the optional FRAME argument is provided, the +face is changed only in that frame; otherwise, it is changed in all +frames. + + You can set underline the specified FACE with the function +`set-face-underline-p'. The argument UNDERLINE-P can be used to make +underlining an attribute of the face or not. If the optional FRAME +argument is provided, the face is changed only in that frame; +otherwise, it is changed in all frames. + + +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 +=========== + + Historically, XEmacs has used the X resource application class +`Emacs' for its resources. Unfortunately, GNU Emacs uses the same +application class, and resources are not compatible between the two +Emacsen. This sharing of the application class often leads to trouble +if you want to run both variants. + + Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds +any XEmacs resources in the resource database when the X connection is +initialized. Otherwise, it will use the class `Emacs' for backwards +compatibility. The variable X-EMACS-APPLICATION-CLASS may be consulted +to determine the application class being used. + + The examples in this section assume the application class is `Emacs'. + + The Emacs resources are generally set per-frame. Each Emacs frame +can have its own name or the same name as another, depending on the +name passed to the `make-frame' function. + + You can specify resources for all frames with the syntax: + + Emacs*parameter: value + +or + + Emacs*EmacsFrame.parameter:value + +You can specify resources for a particular frame with the syntax: + + Emacs*FRAME-NAME.parameter: value + +* Menu: + +* Geometry Resources:: Controlling the size and position of frames. +* Iconic Resources:: Controlling whether frames come up iconic. +* Resource List:: List of resources settable on a frame or device. +* Face Resources:: Controlling faces using resources. +* Widgets:: The widget hierarchy for XEmacs. +* Menubar Resources:: Specifying resources for the menubar. + + +File: xemacs.info, Node: Geometry Resources, Next: Iconic Resources, Up: X Resources + +Geometry Resources +------------------ + + To make the default size of all Emacs frames be 80 columns by 55 +lines, do this: + + Emacs*EmacsFrame.geometry: 80x55 + +To set the geometry of a particular frame named `fred', do this: + + Emacs*fred.geometry: 80x55 + +Important! Do not use the following syntax: + + Emacs*geometry: 80x55 + +You should never use `*geometry' with any X application. It does not +say "make the geometry of Emacs be 80 columns by 55 lines." It really +says, "make Emacs and all subwindows thereof be 80x55 in whatever units +they care to measure in." In particular, that is both telling the +Emacs text pane to be 80x55 in characters, and telling the menubar pane +to be 80x55 pixels, which is surely not what you want. + + As a special case, this geometry specification also works (and sets +the default size of all Emacs frames to 80 columns by 55 lines): + + Emacs.geometry: 80x55 + +since that is the syntax used with most other applications (since most +other applications have only one top-level window, unlike Emacs). In +general, however, the top-level shell (the unmapped ApplicationShell +widget named `Emacs' that is the parent of the shell widgets that +actually manage the individual frames) does not have any interesting +resources on it, and you should set the resources on the frames instead. + + The `-geometry' command-line argument sets only the geometry of the +initial frame created by Emacs. + + A more complete explanation of geometry-handling is + + * The `-geometry' command-line option sets the `Emacs.geometry' + resource, that is, the geometry of the ApplicationShell. + + * For the first frame created, the size of the frame is taken from + the ApplicationShell if it is specified, otherwise from the + geometry of the frame. + + * For subsequent frames, the order is reversed: First the frame, and + then the ApplicationShell. + + * For the first frame created, the position of the frame is taken + from the ApplicationShell (`Emacs.geometry') if it is specified, + otherwise from the geometry of the frame. + + * For subsequent frames, the position is taken only from the frame, + and never from the ApplicationShell. + + This is rather complicated, but it does seem to provide the most +intuitive behavior with respect to the default sizes and positions of +frames created in various ways. + + +File: xemacs.info, Node: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources + +Iconic Resources +---------------- + + Analogous to `-geometry', the `-iconic' command-line option sets the +iconic flag of the ApplicationShell (`Emacs.iconic') and always applies +to the first frame created regardless of its name. However, it is +possible to set the iconic flag on particular frames (by name) by using +the `Emacs*FRAME-NAME.iconic' resource. + + File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources Resource List diff --git a/info/xemacs.info-7 b/info/xemacs.info-7 index 3cdf13a..ceaf16b 100644 --- a/info/xemacs.info-7 +++ b/info/xemacs.info-7 @@ -343,9 +343,11 @@ symbolic link anywhere in its directory path. In other words, the the `find-file' command will check the `buffer-file-truename' of all visited files when deciding whether a given file is already in a buffer, instead of just `buffer-file-name'. If you attempt to visit -another file which is a hard-link or symbolic-link to a file that is -already in a buffer, the existing buffer will be found instead of a -newly created one. +another file which is a symbolic link to a file that is already in a +buffer, the existing buffer will be found instead of a newly created +one. This works if any component of the pathname (including a +non-terminal component) is a symbolic link as well, but doesn't work +with hard links (nothing does). If you want to create a file, just visit it. Emacs prints `(New File)' in the echo area, but in other respects behaves as if you had diff --git a/info/xemacs.info-9 b/info/xemacs.info-9 index 9d4fa44..fd04303 100644 --- a/info/xemacs.info-9 +++ b/info/xemacs.info-9 @@ -56,8 +56,8 @@ top to bottom and left to right. From the rightmost and bottommost window, it goes back to the one at the upper left corner. A numeric argument, N, moves several steps in the cyclic order of windows. A negative numeric argument moves around the cycle in the opposite order. -If the optional second argument ALL-FRAMES is non-`nil', the function -cycles through all frames. When the minibuffer is active, the +If the optional second argument WHICH-FRAMES is non-`nil', the +function cycles through all frames. When the minibuffer is active, the minibuffer is the last window in the cycle; you can switch from the minibuffer window to one of the other windows, and later switch back and finish supplying the minibuffer argument that is requested. *Note -- 1.7.10.4