--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+Indirect:
+cl.info-1: 1190
+cl.info-2: 46365
+cl.info-3: 89150
+cl.info-4: 138909
+cl.info-5: 176907
+cl.info-6: 219515
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f1190
+Node: Overview\7f2742
+Node: Usage\7f5021
+Node: Organization\7f5671
+Node: Installation\7f7494
+Node: Naming Conventions\7f8647
+Node: Program Structure\7f10786
+Node: Argument Lists\7f11254
+Node: Time of Evaluation\7f21039
+Node: Function Aliases\7f27019
+Node: Predicates\7f27603
+Node: Type Predicates\7f27923
+Node: Equality Predicates\7f32966
+Node: Control Structure\7f35742
+Node: Assignment\7f36546
+Node: Generalized Variables\7f37788
+Node: Basic Setf\7f39095
+Node: Modify Macros\7f46365
+Node: Customizing Setf\7f53575
+Node: Variable Bindings\7f60865
+Node: Dynamic Bindings\7f61446
+Node: Lexical Bindings\7f62336
+Node: Function Bindings\7f66440
+Node: Macro Bindings\7f68827
+Node: Conditionals\7f71751
+Node: Blocks and Exits\7f74834
+Node: Iteration\7f77890
+Node: Loop Facility\7f83364
+Node: Loop Basics\7f84291
+Node: Loop Examples\7f86891
+Node: For Clauses\7f89150
+Node: Iteration Clauses\7f101028
+Node: Accumulation Clauses\7f102869
+Node: Other Clauses\7f105213
+Node: Multiple Values\7f111282
+Node: Macros\7f113175
+Node: Declarations\7f116393
+Node: Symbols\7f124885
+Node: Property Lists\7f125185
+Node: Creating Symbols\7f128386
+Node: Numbers\7f130464
+Node: Predicates on Numbers\7f130944
+Node: Numerical Functions\7f131973
+Node: Random Numbers\7f136200
+Node: Implementation Parameters\7f138909
+Node: Sequences\7f142481
+Node: Sequence Basics\7f143154
+Node: Mapping over Sequences\7f146733
+Node: Sequence Functions\7f152587
+Node: Searching Sequences\7f158762
+Node: Sorting Sequences\7f161800
+Node: Lists\7f164348
+Node: List Functions\7f164773
+Node: Substitution of Expressions\7f169036
+Node: Lists as Sets\7f170922
+Node: Association Lists\7f174984
+Node: Hash Tables\7f176687
+Node: Structures\7f176907
+Node: Assertions\7f191690
+Node: Efficiency Concerns\7f194633
+Node: Common Lisp Compatibility\7f200960
+Node: Old CL Compatibility\7f204118
+Node: Porting Common Lisp\7f208501
+Node: Function Index\7f219515
+Node: Variable Index\7f230778
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+File: cl.info, Node: Top, Next: Overview, Up: (dir)
+
+Common Lisp Extensions
+**********************
+
+This document describes a set of Emacs Lisp facilities borrowed from
+Common Lisp. All the facilities are described here in detail; for more
+discussion and examples, Guy L. Steele's `Common Lisp, the Language',
+second edition, is the definitive book on Common Lisp. While this
+document does not assume any prior knowledge of Common Lisp, it does
+assume a basic familiarity with Emacs Lisp.
+
+* Menu:
+
+* Overview:: Installation, usage, etc.
+* Program Structure:: Arglists, `eval-when', `defalias'
+* Predicates:: `typep', `eql', and `equalp'
+* Control Structure:: `setf', `when', `do', `loop', etc.
+* Macros:: Destructuring, `define-compiler-macro'
+* Declarations:: `proclaim', `declare', etc.
+* Symbols:: Property lists, `gensym'
+* Numbers:: Predicates, functions, random numbers
+* Sequences:: Mapping, functions, searching, sorting
+* Lists:: `cadr', `sublis', `member*', `assoc*', etc.
+* Hash Tables:: `make-hash-table', `gethash', etc.
+* Structures:: `defstruct'
+* Assertions:: `check-type', `assert', `ignore-errors'.
+
+* Efficiency Concerns:: Hints and techniques
+* Common Lisp Compatibility:: All known differences with Steele
+* Old CL Compatibility:: All known differences with old cl.el
+* Porting Common Lisp:: Hints for porting Common Lisp code
+
+* Function Index::
+* Variable Index::
+
+\1f
+File: cl.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top
+
+Overview
+********
+
+Common Lisp is a huge language, and Common Lisp systems tend to be
+massive and extremely complex. Emacs Lisp, by contrast, is rather
+minimalist in the choice of Lisp features it offers the programmer. As
+Emacs Lisp programmers have grown in number, and the applications they
+write have grown more ambitious, it has become clear that Emacs Lisp
+could benefit from many of the conveniences of Common Lisp.
+
+ The "CL" package adds a number of Common Lisp functions and control
+structures to Emacs Lisp. While not a 100% complete implementation of
+Common Lisp, "CL" adds enough functionality to make Emacs Lisp
+programming significantly more convenient.
+
+ Some Common Lisp features have been omitted from this package for
+various reasons:
+
+ * Some features are too complex or bulky relative to their benefit
+ to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
+ examples of this group.
+
+ * Other features cannot be implemented without modification to the
+ Emacs Lisp interpreter itself, such as multiple return values,
+ lexical scoping, case-insensitive symbols, and complex numbers.
+ The "CL" package generally makes no attempt to emulate these
+ features.
+
+ * Some features conflict with existing things in Emacs Lisp. For
+ example, Emacs' `assoc' function is incompatible with the Common
+ Lisp `assoc'. In such cases, this package usually adds the suffix
+ `*' to the function name of the Common Lisp version of the
+ function (e.g., `assoc*').
+
+ The package described here was written by Dave Gillespie,
+`daveg@synaptics.com'. It is a total rewrite of the original 1986
+`cl.el' package by Cesar Quiroz. Most features of the Quiroz package
+have been retained; any incompatibilities are noted in the descriptions
+below. Care has been taken in this version to ensure that each
+function is defined efficiently, concisely, and with minimal impact on
+the rest of the Emacs environment.
+
+* Menu:
+
+* Usage:: How to use the CL package
+* Organization:: The package's five component files
+* Installation:: Compiling and installing CL
+* Naming Conventions:: Notes on CL function names
+
+\1f
+File: cl.info, Node: Usage, Next: Organization, Prev: Overview, Up: Overview
+
+Usage
+=====
+
+Lisp code that uses features from the "CL" package should include at
+the beginning:
+
+ (require 'cl)
+
+If you want to ensure that the new (Gillespie) version of "CL" is the
+one that is present, add an additional `(require 'cl-19)' call:
+
+ (require 'cl)
+ (require 'cl-19)
+
+The second call will fail (with "`cl-19.el' not found") if the old
+`cl.el' package was in use.
+
+ It is safe to arrange to load "CL" at all times, e.g., in your
+`.emacs' file. But it's a good idea, for portability, to `(require
+'cl)' in your code even if you do this.
+
+\1f
+File: cl.info, Node: Organization, Next: Installation, Prev: Usage, Up: Overview
+
+Organization
+============
+
+The Common Lisp package is organized into four files:
+
+`cl.el'
+ This is the "main" file, which contains basic functions and
+ information about the package. This file is relatively
+ compact--about 700 lines.
+
+`cl-extra.el'
+ This file contains the larger, more complex or unusual functions.
+ It is kept separate so that packages which only want to use Common
+ Lisp fundamentals like the `cadr' function won't need to pay the
+ overhead of loading the more advanced functions.
+
+`cl-seq.el'
+ This file contains most of the advanced functions for operating on
+ sequences or lists, such as `delete-if' and `assoc*'.
+
+`cl-macs.el'
+ This file contains the features of the packages which are macros
+ instead of functions. Macros expand when the caller is compiled,
+ not when it is run, so the macros generally only need to be
+ present when the byte-compiler is running (or when the macros are
+ used in uncompiled code such as a `.emacs' file). Most of the
+ macros of this package are isolated in `cl-macs.el' so that they
+ won't take up memory unless you are compiling.
+
+ The file `cl.el' includes all necessary `autoload' commands for the
+functions and macros in the other three files. All you have to do is
+`(require 'cl)', and `cl.el' will take care of pulling in the other
+files when they are needed.
+
+ There is another file, `cl-compat.el', which defines some routines
+from the older `cl.el' package that are no longer present in the new
+package. This includes internal routines like `setelt' and
+`zip-lists', deprecated features like `defkeyword', and an emulation of
+the old-style multiple-values feature. *Note Old CL Compatibility::.
+
+\1f
+File: cl.info, Node: Installation, Next: Naming Conventions, Prev: Organization, Up: Overview
+
+Installation
+============
+
+Installation of the "CL" package is simple: Just put the byte-compiled
+files `cl.elc', `cl-extra.elc', `cl-seq.elc', `cl-macs.elc', and
+`cl-compat.elc' into a directory on your `load-path'.
+
+ There are no special requirements to compile this package: The files
+do not have to be loaded before they are compiled, nor do they need to
+be compiled in any particular order.
+
+ You may choose to put the files into your main `lisp/' directory,
+replacing the original `cl.el' file there. Or, you could put them into
+a directory that comes before `lisp/' on your `load-path' so that the
+old `cl.el' is effectively hidden.
+
+ Also, format the `cl.texinfo' file and put the resulting Info files
+in the `info/' directory or another suitable place.
+
+ You may instead wish to leave this package's components all in their
+own directory, and then add this directory to your `load-path' and
+(Emacs 19 only) `Info-directory-list'. Add the directory to the front
+of the list so the old "CL" package and its documentation are hidden.
+
+\1f
+File: cl.info, Node: Naming Conventions, Prev: Installation, Up: Overview
+
+Naming Conventions
+==================
+
+Except where noted, all functions defined by this package have the same
+names and calling conventions as their Common Lisp counterparts.
+
+ Following is a complete list of functions whose names were changed
+from Common Lisp, usually to avoid conflicts with Emacs. In each case,
+a `*' has been appended to the Common Lisp name to obtain the Emacs
+name:
+
+ defun* defsubst* defmacro* function*
+ member* assoc* rassoc* get*
+ remove* delete* mapcar* sort*
+ floor* ceiling* truncate* round*
+ mod* rem* random*
+
+ Internal function and variable names in the package are prefixed by
+`cl-'. Here is a complete list of functions *not* prefixed by `cl-'
+which were not taken from Common Lisp:
+
+ member delete remove remq
+ rassoc floatp-safe lexical-let lexical-let*
+ callf callf2 letf letf*
+ defsubst* defalias add-hook eval-when-compile
+
+(Most of these are Emacs 19 features provided to Emacs 18 users, or
+introduced, like `remq', for reasons of symmetry with similar features.)
+
+ The following simple functions and macros are defined in `cl.el';
+they do not cause other components like `cl-extra' to be loaded.
+
+ eql floatp-safe abs endp
+ evenp oddp plusp minusp
+ last butlast nbutlast caar .. cddddr
+ list* ldiff rest first .. tenth
+ member [1] copy-list subst mapcar* [2]
+ adjoin [3] acons pairlis when
+ unless pop [4] push [4] pushnew [3,4]
+ incf [4] decf [4] proclaim declaim
+ add-hook
+
+[1] This is the Emacs 19-compatible function, not `member*'.
+
+[2] Only for one sequence argument or two list arguments.
+
+[3] Only if `:test' is `eq', `equal', or unspecified, and `:key' is not
+used.
+
+[4] Only when PLACE is a plain variable name.
+
+\1f
+File: cl.info, Node: Program Structure, Next: Predicates, Prev: Overview, Up: Top
+
+Program Structure
+*****************
+
+This section describes features of the "CL" package which have to do
+with programs as a whole: advanced argument lists for functions, and
+the `eval-when' construct.
+
+* Menu:
+
+* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
+* Time of Evaluation:: The `eval-when' construct.
+* Function Aliases:: The `defalias' function.
+
+\1f
+File: cl.info, Node: Argument Lists, Next: Time of Evaluation, Prev: Program Structure, Up: Program Structure
+
+Argument Lists
+==============
+
+Emacs Lisp's notation for argument lists of functions is a subset of
+the Common Lisp notation. As well as the familiar `&optional' and
+`&rest' markers, Common Lisp allows you to specify default values for
+optional arguments, and it provides the additional markers `&key' and
+`&aux'.
+
+ Since argument parsing is built-in to Emacs, there is no way for
+this package to implement Common Lisp argument lists seamlessly.
+Instead, this package defines alternates for several Lisp forms which
+you must use if you need Common Lisp argument lists.
+
+ - Special Form: defun* NAME ARGLIST BODY...
+ This form is identical to the regular `defun' form, except that
+ ARGLIST is allowed to be a full Common Lisp argument list. Also,
+ the function body is enclosed in an implicit block called NAME;
+ *note Blocks and Exits::..
+
+ - Special Form: defsubst* NAME ARGLIST BODY...
+ This is just like `defun*', except that the function that is
+ defined is automatically proclaimed `inline', i.e., calls to it
+ may be expanded into in-line code by the byte compiler. This is
+ analogous to the `defsubst' form in Emacs 19; `defsubst*' uses a
+ different method (compiler macros) which works in all version of
+ Emacs, and also generates somewhat more efficient inline
+ expansions. In particular, `defsubst*' arranges for the
+ processing of keyword arguments, default values, etc., to be done
+ at compile-time whenever possible.
+
+ - Special Form: defmacro* NAME ARGLIST BODY...
+ This is identical to the regular `defmacro' form, except that
+ ARGLIST is allowed to be a full Common Lisp argument list. The
+ `&environment' keyword is supported as described in Steele. The
+ `&whole' keyword is supported only within destructured lists (see
+ below); top-level `&whole' cannot be implemented with the current
+ Emacs Lisp interpreter. The macro expander body is enclosed in an
+ implicit block called NAME.
+
+ - Special Form: function* SYMBOL-OR-LAMBDA
+ This is identical to the regular `function' form, except that if
+ the argument is a `lambda' form then that form may use a full
+ Common Lisp argument list.
+
+ Also, all forms (such as `defsetf' and `flet') defined in this
+package that include ARGLISTs in their syntax allow full Common Lisp
+argument lists.
+
+ Note that it is *not* necessary to use `defun*' in order to have
+access to most "CL" features in your function. These features are
+always present; `defun*''s only difference from `defun' is its more
+flexible argument lists and its implicit block.
+
+ The full form of a Common Lisp argument list is
+
+ (VAR...
+ &optional (VAR INITFORM SVAR)...
+ &rest VAR
+ &key ((KEYWORD VAR) INITFORM SVAR)...
+ &aux (VAR INITFORM)...)
+
+ Each of the five argument list sections is optional. The SVAR,
+INITFORM, and KEYWORD parts are optional; if they are omitted, then
+`(VAR)' may be written simply `VAR'.
+
+ The first section consists of zero or more "required" arguments.
+These arguments must always be specified in a call to the function;
+there is no difference between Emacs Lisp and Common Lisp as far as
+required arguments are concerned.
+
+ The second section consists of "optional" arguments. These
+arguments may be specified in the function call; if they are not,
+INITFORM specifies the default value used for the argument. (No
+INITFORM means to use `nil' as the default.) The INITFORM is evaluated
+with the bindings for the preceding arguments already established; `(a
+&optional (b (1+ a)))' matches one or two arguments, with the second
+argument defaulting to one plus the first argument. If the SVAR is
+specified, it is an auxiliary variable which is bound to `t' if the
+optional argument was specified, or to `nil' if the argument was
+omitted. If you don't use an SVAR, then there will be no way for your
+function to tell whether it was called with no argument, or with the
+default value passed explicitly as an argument.
+
+ The third section consists of a single "rest" argument. If more
+arguments were passed to the function than are accounted for by the
+required and optional arguments, those extra arguments are collected
+into a list and bound to the "rest" argument variable. Common Lisp's
+`&rest' is equivalent to that of Emacs Lisp. Common Lisp accepts
+`&body' as a synonym for `&rest' in macro contexts; this package
+accepts it all the time.
+
+ The fourth section consists of "keyword" arguments. These are
+optional arguments which are specified by name rather than positionally
+in the argument list. For example,
+
+ (defun* foo (a &optional b &key c d (e 17)))
+
+defines a function which may be called with one, two, or more
+arguments. The first two arguments are bound to `a' and `b' in the
+usual way. The remaining arguments must be pairs of the form `:c',
+`:d', or `:e' followed by the value to be bound to the corresponding
+argument variable. (Symbols whose names begin with a colon are called
+"keywords", and they are self-quoting in the same way as `nil' and `t'.)
+
+ For example, the call `(foo 1 2 :d 3 :c 4)' sets the five arguments
+to 1, 2, 4, 3, and 17, respectively. If the same keyword appears more
+than once in the function call, the first occurrence takes precedence
+over the later ones. Note that it is not possible to specify keyword
+arguments without specifying the optional argument `b' as well, since
+`(foo 1 :c 2)' would bind `b' to the keyword `:c', then signal an error
+because `2' is not a valid keyword.
+
+ If a KEYWORD symbol is explicitly specified in the argument list as
+shown in the above diagram, then that keyword will be used instead of
+just the variable name prefixed with a colon. You can specify a
+KEYWORD symbol which does not begin with a colon at all, but such
+symbols will not be self-quoting; you will have to quote them
+explicitly with an apostrophe in the function call.
+
+ Ordinarily it is an error to pass an unrecognized keyword to a
+function, e.g., `(foo 1 2 :c 3 :goober 4)'. You can ask Lisp to ignore
+unrecognized keywords, either by adding the marker `&allow-other-keys'
+after the keyword section of the argument list, or by specifying an
+`:allow-other-keys' argument in the call whose value is non-`nil'. If
+the function uses both `&rest' and `&key' at the same time, the "rest"
+argument is bound to the keyword list as it appears in the call. For
+example:
+
+ (defun* find-thing (thing &rest rest &key need &allow-other-keys)
+ (or (apply 'member* thing thing-list :allow-other-keys t rest)
+ (if need (error "Thing not found"))))
+
+This function takes a `:need' keyword argument, but also accepts other
+keyword arguments which are passed on to the `member*' function.
+`allow-other-keys' is used to keep both `find-thing' and `member*' from
+complaining about each others' keywords in the arguments.
+
+ As a (significant) performance optimization, this package implements
+the scan for keyword arguments by calling `memq' to search for keywords
+in a "rest" argument. Technically speaking, this is incorrect, since
+`memq' looks at the odd-numbered values as well as the even-numbered
+keywords. The net effect is that if you happen to pass a keyword symbol
+as the *value* of another keyword argument, where that keyword symbol
+happens to equal the name of a valid keyword argument of the same
+function, then the keyword parser will become confused. This minor bug
+can only affect you if you use keyword symbols as general-purpose data
+in your program; this practice is strongly discouraged in Emacs Lisp.
+
+ The fifth section of the argument list consists of "auxiliary
+variables". These are not really arguments at all, but simply
+variables which are bound to `nil' or to the specified INITFORMS during
+execution of the function. There is no difference between the
+following two functions, except for a matter of stylistic taste:
+
+ (defun* foo (a b &aux (c (+ a b)) d)
+ BODY)
+
+ (defun* foo (a b)
+ (let ((c (+ a b)) d)
+ BODY))
+
+ Argument lists support "destructuring". In Common Lisp,
+destructuring is only allowed with `defmacro'; this package allows it
+with `defun*' and other argument lists as well. In destructuring, any
+argument variable (VAR in the above diagram) can be replaced by a list
+of variables, or more generally, a recursive argument list. The
+corresponding argument value must be a list whose elements match this
+recursive argument list. For example:
+
+ (defmacro* dolist ((var listform &optional resultform)
+ &rest body)
+ ...)
+
+ This says that the first argument of `dolist' must be a list of two
+or three items; if there are other arguments as well as this list, they
+are stored in `body'. All features allowed in regular argument lists
+are allowed in these recursive argument lists. In addition, the clause
+`&whole VAR' is allowed at the front of a recursive argument list. It
+binds VAR to the whole list being matched; thus `(&whole all a b)'
+matches a list of two things, with `a' bound to the first thing, `b'
+bound to the second thing, and `all' bound to the list itself. (Common
+Lisp allows `&whole' in top-level `defmacro' argument lists as well,
+but Emacs Lisp does not support this usage.)
+
+ One last feature of destructuring is that the argument list may be
+dotted, so that the argument list `(a b . c)' is functionally
+equivalent to `(a b &rest c)'.
+
+ If the optimization quality `safety' is set to 0 (*note
+Declarations::.), error checking for wrong number of arguments and
+invalid keyword arguments is disabled. By default, argument lists are
+rigorously checked.
+
+\1f
+File: cl.info, Node: Time of Evaluation, Next: Function Aliases, Prev: Argument Lists, Up: Program Structure
+
+Time of Evaluation
+==================
+
+Normally, the byte-compiler does not actually execute the forms in a
+file it compiles. For example, if a file contains `(setq foo t)', the
+act of compiling it will not actually set `foo' to `t'. This is true
+even if the `setq' was a top-level form (i.e., not enclosed in a
+`defun' or other form). Sometimes, though, you would like to have
+certain top-level forms evaluated at compile-time. For example, the
+compiler effectively evaluates `defmacro' forms at compile-time so that
+later parts of the file can refer to the macros that are defined.
+
+ - Special Form: eval-when (SITUATIONS...) FORMS...
+ This form controls when the body FORMS are evaluated. The
+ SITUATIONS list may contain any set of the symbols `compile',
+ `load', and `eval' (or their long-winded ANSI equivalents,
+ `:compile-toplevel', `:load-toplevel', and `:execute').
+
+ The `eval-when' form is handled differently depending on whether
+ or not it is being compiled as a top-level form. Specifically, it
+ gets special treatment if it is being compiled by a command such
+ as `byte-compile-file' which compiles files or buffers of code,
+ and it appears either literally at the top level of the file or
+ inside a top-level `progn'.
+
+ For compiled top-level `eval-when's, the body FORMS are executed
+ at compile-time if `compile' is in the SITUATIONS list, and the
+ FORMS are written out to the file (to be executed at load-time) if
+ `load' is in the SITUATIONS list.
+
+ For non-compiled-top-level forms, only the `eval' situation is
+ relevant. (This includes forms executed by the interpreter, forms
+ compiled with `byte-compile' rather than `byte-compile-file', and
+ non-top-level forms.) The `eval-when' acts like a `progn' if
+ `eval' is specified, and like `nil' (ignoring the body FORMS) if
+ not.
+
+ The rules become more subtle when `eval-when's are nested; consult
+ Steele (second edition) for the gruesome details (and some
+ gruesome examples).
+
+ Some simple examples:
+
+ ;; Top-level forms in foo.el:
+ (eval-when (compile) (setq foo1 'bar))
+ (eval-when (load) (setq foo2 'bar))
+ (eval-when (compile load) (setq foo3 'bar))
+ (eval-when (eval) (setq foo4 'bar))
+ (eval-when (eval compile) (setq foo5 'bar))
+ (eval-when (eval load) (setq foo6 'bar))
+ (eval-when (eval compile load) (setq foo7 'bar))
+
+ When `foo.el' is compiled, these variables will be set during the
+ compilation itself:
+
+ foo1 foo3 foo5 foo7 ; `compile'
+
+ When `foo.elc' is loaded, these variables will be set:
+
+ foo2 foo3 foo6 foo7 ; `load'
+
+ And if `foo.el' is loaded uncompiled, these variables will be set:
+
+ foo4 foo5 foo6 foo7 ; `eval'
+
+ If these seven `eval-when's had been, say, inside a `defun', then
+ the first three would have been equivalent to `nil' and the last
+ four would have been equivalent to the corresponding `setq's.
+
+ Note that `(eval-when (load eval) ...)' is equivalent to `(progn
+ ...)' in all contexts. The compiler treats certain top-level
+ forms, like `defmacro' (sort-of) and `require', as if they were
+ wrapped in `(eval-when (compile load eval) ...)'.
+
+ Emacs 19 includes two special forms related to `eval-when'. One of
+these, `eval-when-compile', is not quite equivalent to any `eval-when'
+construct and is described below. This package defines a version of
+`eval-when-compile' for the benefit of Emacs 18 users.
+
+ The other form, `(eval-and-compile ...)', is exactly equivalent to
+`(eval-when (compile load eval) ...)' and so is not itself defined by
+this package.
+
+ - Special Form: eval-when-compile FORMS...
+ The FORMS are evaluated at compile-time; at execution time, this
+ form acts like a quoted constant of the resulting value. Used at
+ top-level, `eval-when-compile' is just like `eval-when (compile
+ eval)'. In other contexts, `eval-when-compile' allows code to be
+ evaluated once at compile-time for efficiency or other reasons.
+
+ This form is similar to the `#.' syntax of true Common Lisp.
+
+ - Special Form: load-time-value FORM
+ The FORM is evaluated at load-time; at execution time, this form
+ acts like a quoted constant of the resulting value.
+
+ Early Common Lisp had a `#,' syntax that was similar to this, but
+ ANSI Common Lisp replaced it with `load-time-value' and gave it
+ more well-defined semantics.
+
+ In a compiled file, `load-time-value' arranges for FORM to be
+ evaluated when the `.elc' file is loaded and then used as if it
+ were a quoted constant. In code compiled by `byte-compile' rather
+ than `byte-compile-file', the effect is identical to
+ `eval-when-compile'. In uncompiled code, both `eval-when-compile'
+ and `load-time-value' act exactly like `progn'.
+
+ (defun report ()
+ (insert "This function was executed on: "
+ (current-time-string)
+ ", compiled on: "
+ (eval-when-compile (current-time-string))
+ ;; or '#.(current-time-string) in real Common Lisp
+ ", and loaded on: "
+ (load-time-value (current-time-string))))
+
+ Byte-compiled, the above defun will result in the following code
+ (or its compiled equivalent, of course) in the `.elc' file:
+
+ (setq --temp-- (current-time-string))
+ (defun report ()
+ (insert "This function was executed on: "
+ (current-time-string)
+ ", compiled on: "
+ '"Wed Jun 23 18:33:43 1993"
+ ", and loaded on: "
+ --temp--))
+
+\1f
+File: cl.info, Node: Function Aliases, Prev: Time of Evaluation, Up: Program Structure
+
+Function Aliases
+================
+
+This section describes a feature from GNU Emacs 19 which this package
+makes available in other versions of Emacs.
+
+ - Function: defalias SYMBOL FUNCTION
+ This function sets SYMBOL's function cell to FUNCTION. It is
+ equivalent to `fset', except that in GNU Emacs 19 it also records
+ the setting in `load-history' so that it can be undone by a later
+ `unload-feature'.
+
+ In other versions of Emacs, `defalias' is a synonym for `fset'.
+
+\1f
+File: cl.info, Node: Predicates, Next: Control Structure, Prev: Program Structure, Up: Top
+
+Predicates
+**********
+
+This section describes functions for testing whether various facts are
+true or false.
+
+* Menu:
+
+* Type Predicates:: `typep', `deftype', and `coerce'
+* Equality Predicates:: `eql' and `equalp'
+
+\1f
+File: cl.info, Node: Type Predicates, Next: Equality Predicates, Prev: Predicates, Up: Predicates
+
+Type Predicates
+===============
+
+The "CL" package defines a version of the Common Lisp `typep' predicate.
+
+ - Function: typep OBJECT TYPE
+ Check if OBJECT is of type TYPE, where TYPE is a (quoted) type
+ name of the sort used by Common Lisp. For example, `(typep foo
+ 'integer)' is equivalent to `(integerp foo)'.
+
+ The TYPE argument to the above function is either a symbol or a list
+beginning with a symbol.
+
+ * If the type name is a symbol, Emacs appends `-p' to the symbol
+ name to form the name of a predicate function for testing the
+ type. (Built-in predicates whose names end in `p' rather than
+ `-p' are used when appropriate.)
+
+ * The type symbol `t' stands for the union of all types. `(typep
+ OBJECT t)' is always true. Likewise, the type symbol `nil' stands
+ for nothing at all, and `(typep OBJECT nil)' is always false.
+
+ * The type symbol `null' represents the symbol `nil'. Thus `(typep
+ OBJECT 'null)' is equivalent to `(null OBJECT)'.
+
+ * The type symbol `real' is a synonym for `number', and `fixnum' is
+ a synonym for `integer'.
+
+ * The type symbols `character' and `string-char' match characters.
+ In Emacs-19 and XEmacs-19, characters are the same thing as
+ integers in the range 0-255. In XEmacs-20, where characters are a
+ first-class data type, this checks for actual characters, and
+ `(typep 8BIT-INTEGER 'character)' will return `nil'.
+
+ * The type symbol `float' uses the `floatp-safe' predicate defined
+ by this package rather than `floatp', so it will work correctly
+ even in Emacs versions without floating-point support.
+
+ * The type list `(integer LOW HIGH)' represents all integers between
+ LOW and HIGH, inclusive. Either bound may be a list of a single
+ integer to specify an exclusive limit, or a `*' to specify no
+ limit. The type `(integer * *)' is thus equivalent to `integer'.
+
+ * Likewise, lists beginning with `float', `real', or `number'
+ represent numbers of that type falling in a particular range.
+
+ * Lists beginning with `and', `or', and `not' form combinations of
+ types. For example, `(or integer (float 0 *))' represents all
+ objects that are integers or non-negative floats.
+
+ * Lists beginning with `member' or `member*' represent objects `eql'
+ to any of the following values. For example, `(member 1 2 3 4)'
+ is equivalent to `(integer 1 4)', and `(member nil)' is equivalent
+ to `null'.
+
+ * Lists of the form `(satisfies PREDICATE)' represent all objects
+ for which PREDICATE returns true when called with that object as
+ an argument.
+
+ The following function and macro (not technically predicates) are
+related to `typep'.
+
+ - Function: coerce OBJECT TYPE
+ This function attempts to convert OBJECT to the specified TYPE.
+ If OBJECT is already of that type as determined by `typep', it is
+ simply returned. Otherwise, certain types of conversions will be
+ made: If TYPE is any sequence type (`string', `list', etc.) then
+ OBJECT will be converted to that type if possible. If TYPE is
+ `character', then strings of length one and symbols with
+ one-character names can be coerced. If TYPE is `float', then
+ integers can be coerced in versions of Emacs that support floats.
+ In all other circumstances, `coerce' signals an error.
+
+ - Special Form: deftype NAME ARGLIST FORMS...
+ This macro defines a new type called NAME. It is similar to
+ `defmacro' in many ways; when NAME is encountered as a type name,
+ the body FORMS are evaluated and should return a type specifier
+ that is equivalent to the type. The ARGLIST is a Common Lisp
+ argument list of the sort accepted by `defmacro*'. The type
+ specifier `(NAME ARGS...)' is expanded by calling the expander
+ with those arguments; the type symbol `NAME' is expanded by
+ calling the expander with no arguments. The ARGLIST is processed
+ the same as for `defmacro*' except that optional arguments without
+ explicit defaults use `*' instead of `nil' as the "default"
+ default. Some examples:
+
+ (deftype null () '(satisfies null)) ; predefined
+ (deftype list () '(or null cons)) ; predefined
+ (deftype unsigned-byte (&optional bits)
+ (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
+ (unsigned-byte 8) == (integer 0 255)
+ (unsigned-byte) == (integer 0 *)
+ unsigned-byte == (integer 0 *)
+
+ The last example shows how the Common Lisp `unsigned-byte' type
+ specifier could be implemented if desired; this package does not
+ implement `unsigned-byte' by default.
+
+ The `typecase' and `check-type' macros also use type names. *Note
+Conditionals::. *Note Assertions::. The `map', `concatenate', and
+`merge' functions take type-name arguments to specify the type of
+sequence to return. *Note Sequences::.
+
+\1f
+File: cl.info, Node: Equality Predicates, Prev: Type Predicates, Up: Predicates
+
+Equality Predicates
+===================
+
+This package defines two Common Lisp predicates, `eql' and `equalp'.
+
+ - Function: eql A B
+ This function is almost the same as `eq', except that if A and B
+ are numbers of the same type, it compares them for numeric
+ equality (as if by `equal' instead of `eq'). This makes a
+ difference only for versions of Emacs that are compiled with
+ floating-point support, such as Emacs 19. Emacs floats are
+ allocated objects just like cons cells, which means that `(eq 3.0
+ 3.0)' will not necessarily be true--if the two `3.0's were
+ allocated separately, the pointers will be different even though
+ the numbers are the same. But `(eql 3.0 3.0)' will always be true.
+
+ The types of the arguments must match, so `(eql 3 3.0)' is still
+ false.
+
+ Note that Emacs integers are "direct" rather than allocated, which
+ basically means `(eq 3 3)' will always be true. Thus `eq' and
+ `eql' behave differently only if floating-point numbers are
+ involved, and are indistinguishable on Emacs versions that don't
+ support floats.
+
+ There is a slight inconsistency with Common Lisp in the treatment
+ of positive and negative zeros. Some machines, notably those with
+ IEEE standard arithmetic, represent `+0' and `-0' as distinct
+ values. Normally this doesn't matter because the standard
+ specifies that `(= 0.0 -0.0)' should always be true, and this is
+ indeed what Emacs Lisp and Common Lisp do. But the Common Lisp
+ standard states that `(eql 0.0 -0.0)' and `(equal 0.0 -0.0)' should
+ be false on IEEE-like machines; Emacs Lisp does not do this, and in
+ fact the only known way to distinguish between the two zeros in
+ Emacs Lisp is to `format' them and check for a minus sign.
+
+ - Function: equalp A B
+ This function is a more flexible version of `equal'. In
+ particular, it compares strings and characters case-insensitively,
+ and it compares numbers without regard to type (so that `(equalp 3
+ 3.0)' is true). Vectors and conses are compared recursively. All
+ other objects are compared as if by `equal'.
+
+ This function differs from Common Lisp `equalp' in several
+ respects. In keeping with the idea that strings are less
+ vector-like in Emacs Lisp, this package's `equalp' also will not
+ compare strings against vectors of integers.
+
+ Also note that the Common Lisp functions `member' and `assoc' use
+`eql' to compare elements, whereas Emacs Lisp follows the MacLisp
+tradition and uses `equal' for these two functions. In Emacs, use
+`member*' and `assoc*' to get functions which use `eql' for comparisons.
+
+\1f
+File: cl.info, Node: Control Structure, Next: Macros, Prev: Predicates, Up: Top
+
+Control Structure
+*****************
+
+The features described in the following sections implement various
+advanced control structures, including the powerful `setf' facility and
+a number of looping and conditional constructs.
+
+* Menu:
+
+* Assignment:: The `psetq' form
+* Generalized Variables:: `setf', `incf', `push', etc.
+* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
+* Conditionals:: `when', `unless', `case', `typecase'
+* Blocks and Exits:: `block', `return', `return-from'
+* Iteration:: `do', `dotimes', `dolist', `do-symbols'
+* Loop Facility:: The Common Lisp `loop' macro
+* Multiple Values:: `values', `multiple-value-bind', etc.
+
+\1f
+File: cl.info, Node: Assignment, Next: Generalized Variables, Prev: Control Structure, Up: Control Structure
+
+Assignment
+==========
+
+The `psetq' form is just like `setq', except that multiple assignments
+are done in parallel rather than sequentially.
+
+ - Special Form: psetq [SYMBOL FORM]...
+ This special form (actually a macro) is used to assign to several
+ variables simultaneously. Given only one SYMBOL and FORM, it has
+ the same effect as `setq'. Given several SYMBOL and FORM pairs,
+ it evaluates all the FORMs in advance and then stores the
+ corresponding variables afterwards.
+
+ (setq x 2 y 3)
+ (setq x (+ x y) y (* x y))
+ x
+ => 5
+ y ; `y' was computed after `x' was set.
+ => 15
+ (setq x 2 y 3)
+ (psetq x (+ x y) y (* x y))
+ x
+ => 5
+ y ; `y' was computed before `x' was set.
+ => 6
+
+ The simplest use of `psetq' is `(psetq x y y x)', which exchanges
+ the values of two variables. (The `rotatef' form provides an even
+ more convenient way to swap two variables; *note Modify Macros::..)
+
+ `psetq' always returns `nil'.
+
+\1f
+File: cl.info, Node: Generalized Variables, Next: Variable Bindings, Prev: Assignment, Up: Control Structure
+
+Generalized Variables
+=====================
+
+A "generalized variable" or "place form" is one of the many places in
+Lisp memory where values can be stored. The simplest place form is a
+regular Lisp variable. But the cars and cdrs of lists, elements of
+arrays, properties of symbols, and many other locations are also places
+where Lisp values are stored.
+
+ The `setf' form is like `setq', except that it accepts arbitrary
+place forms on the left side rather than just symbols. For example,
+`(setf (car a) b)' sets the car of `a' to `b', doing the same operation
+as `(setcar a b)' but without having to remember two separate functions
+for setting and accessing every type of place.
+
+ Generalized variables are analogous to "lvalues" in the C language,
+where `x = a[i]' gets an element from an array and `a[i] = x' stores an
+element using the same notation. Just as certain forms like `a[i]' can
+be lvalues in C, there is a set of forms that can be generalized
+variables in Lisp.
+
+* Menu:
+
+* Basic Setf:: `setf' and place forms
+* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
+* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
+
+\1f
+File: cl.info, Node: Basic Setf, Next: Modify Macros, Prev: Generalized Variables, Up: Generalized Variables
+
+Basic Setf
+----------
+
+The `setf' macro is the most basic way to operate on generalized
+variables.
+
+ - Special Form: setf [PLACE FORM]...
+ This macro evaluates FORM and stores it in PLACE, which must be a
+ valid generalized variable form. If there are several PLACE and
+ FORM pairs, the assignments are done sequentially just as with
+ `setq'. `setf' returns the value of the last FORM.
+
+ The following Lisp forms will work as generalized variables, and
+ so may legally appear in the PLACE argument of `setf':
+
+ * A symbol naming a variable. In other words, `(setf x y)' is
+ exactly equivalent to `(setq x y)', and `setq' itself is
+ strictly speaking redundant now that `setf' exists. Many
+ programmers continue to prefer `setq' for setting simple
+ variables, though, purely for stylistic or historical reasons.
+ The macro `(setf x y)' actually expands to `(setq x y)', so
+ there is no performance penalty for using it in compiled code.
+
+ * A call to any of the following Lisp functions:
+
+ car cdr caar .. cddddr
+ nth rest first .. tenth
+ aref elt nthcdr
+ symbol-function symbol-value symbol-plist
+ get get* getf
+ gethash subseq
+
+ Note that for `nthcdr' and `getf', the list argument of the
+ function must itself be a valid PLACE form. For example,
+ `(setf (nthcdr 0 foo) 7)' will set `foo' itself to 7. Note
+ that `push' and `pop' on an `nthcdr' place can be used to
+ insert or delete at any position in a list. The use of
+ `nthcdr' as a PLACE form is an extension to standard Common
+ Lisp.
+
+ * The following Emacs-specific functions are also `setf'-able.
+ (Some of these are defined only in Emacs 19 or only in
+ XEmacs.)
+
+ buffer-file-name marker-position
+ buffer-modified-p match-data
+ buffer-name mouse-position
+ buffer-string overlay-end
+ buffer-substring overlay-get
+ current-buffer overlay-start
+ current-case-table point
+ current-column point-marker
+ current-global-map point-max
+ current-input-mode point-min
+ current-local-map process-buffer
+ current-window-configuration process-filter
+ default-file-modes process-sentinel
+ default-value read-mouse-position
+ documentation-property screen-height
+ extent-data screen-menubar
+ extent-end-position screen-width
+ extent-start-position selected-window
+ face-background selected-screen
+ face-background-pixmap selected-frame
+ face-font standard-case-table
+ face-foreground syntax-table
+ face-underline-p window-buffer
+ file-modes window-dedicated-p
+ frame-height window-display-table
+ frame-parameters window-height
+ frame-visible-p window-hscroll
+ frame-width window-point
+ get-register window-start
+ getenv window-width
+ global-key-binding x-get-cut-buffer
+ keymap-parent x-get-cutbuffer
+ local-key-binding x-get-secondary-selection
+ mark x-get-selection
+ mark-marker
+
+ Most of these have directly corresponding "set" functions,
+ like `use-local-map' for `current-local-map', or `goto-char'
+ for `point'. A few, like `point-min', expand to longer
+ sequences of code when they are `setf''d (`(narrow-to-region
+ x (point-max))' in this case).
+
+ * A call of the form `(substring SUBPLACE N [M])', where
+ SUBPLACE is itself a legal generalized variable whose current
+ value is a string, and where the value stored is also a
+ string. The new string is spliced into the specified part of
+ the destination string. For example:
+
+ (setq a (list "hello" "world"))
+ => ("hello" "world")
+ (cadr a)
+ => "world"
+ (substring (cadr a) 2 4)
+ => "rl"
+ (setf (substring (cadr a) 2 4) "o")
+ => "o"
+ (cadr a)
+ => "wood"
+ a
+ => ("hello" "wood")
+
+ The generalized variable `buffer-substring', listed above,
+ also works in this way by replacing a portion of the current
+ buffer.
+
+ * A call of the form `(apply 'FUNC ...)' or `(apply (function
+ FUNC) ...)', where FUNC is a `setf'-able function whose store
+ function is "suitable" in the sense described in Steele's
+ book; since none of the standard Emacs place functions are
+ suitable in this sense, this feature is only interesting when
+ used with places you define yourself with
+ `define-setf-method' or the long form of `defsetf'.
+
+ * A macro call, in which case the macro is expanded and `setf'
+ is applied to the resulting form.
+
+ * Any form for which a `defsetf' or `define-setf-method' has
+ been made.
+
+ Using any forms other than these in the PLACE argument to `setf'
+ will signal an error.
+
+ The `setf' macro takes care to evaluate all subforms in the proper
+ left-to-right order; for example,
+
+ (setf (aref vec (incf i)) i)
+
+ looks like it will evaluate `(incf i)' exactly once, before the
+ following access to `i'; the `setf' expander will insert temporary
+ variables as necessary to ensure that it does in fact work this
+ way no matter what setf-method is defined for `aref'. (In this
+ case, `aset' would be used and no such steps would be necessary
+ since `aset' takes its arguments in a convenient order.)
+
+ However, if the PLACE form is a macro which explicitly evaluates
+ its arguments in an unusual order, this unusual order will be
+ preserved. Adapting an example from Steele, given
+
+ (defmacro wrong-order (x y) (list 'aref y x))
+
+ the form `(setf (wrong-order A B) 17)' will evaluate B first, then
+ A, just as in an actual call to `wrong-order'.
+
--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+File: cl.info, Node: Modify Macros, Next: Customizing Setf, Prev: Basic Setf, Up: Generalized Variables
+
+Modify Macros
+-------------
+
+This package defines a number of other macros besides `setf' that
+operate on generalized variables. Many are interesting and useful even
+when the PLACE is just a variable name.
+
+ - Special Form: psetf [PLACE FORM]...
+ This macro is to `setf' what `psetq' is to `setq': When several
+ PLACEs and FORMs are involved, the assignments take place in
+ parallel rather than sequentially. Specifically, all subforms are
+ evaluated from left to right, then all the assignments are done
+ (in an undefined order).
+
+ - Special Form: incf PLACE &optional X
+ This macro increments the number stored in PLACE by one, or by X
+ if specified. The incremented value is returned. For example,
+ `(incf i)' is equivalent to `(setq i (1+ i))', and `(incf (car x)
+ 2)' is equivalent to `(setcar x (+ (car x) 2))'.
+
+ Once again, care is taken to preserve the "apparent" order of
+ evaluation. For example,
+
+ (incf (aref vec (incf i)))
+
+ appears to increment `i' once, then increment the element of `vec'
+ addressed by `i'; this is indeed exactly what it does, which means
+ the above form is *not* equivalent to the "obvious" expansion,
+
+ (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
+
+ but rather to something more like
+
+ (let ((temp (incf i)))
+ (setf (aref vec temp) (1+ (aref vec temp))))
+
+ Again, all of this is taken care of automatically by `incf' and
+ the other generalized-variable macros.
+
+ As a more Emacs-specific example of `incf', the expression `(incf
+ (point) N)' is essentially equivalent to `(forward-char N)'.
+
+ - Special Form: decf PLACE &optional X
+ This macro decrements the number stored in PLACE by one, or by X
+ if specified.
+
+ - Special Form: pop PLACE
+ This macro removes and returns the first element of the list stored
+ in PLACE. It is analogous to `(prog1 (car PLACE) (setf PLACE (cdr
+ PLACE)))', except that it takes care to evaluate all subforms only
+ once.
+
+ - Special Form: push X PLACE
+ This macro inserts X at the front of the list stored in PLACE. It
+ is analogous to `(setf PLACE (cons X PLACE))', except for
+ evaluation of the subforms.
+
+ - Special Form: pushnew X PLACE &key :test :test-not :key
+ This macro inserts X at the front of the list stored in PLACE, but
+ only if X was not `eql' to any existing element of the list. The
+ optional keyword arguments are interpreted in the same way as for
+ `adjoin'. *Note Lists as Sets::.
+
+ - Special Form: shiftf PLACE... NEWVALUE
+ This macro shifts the PLACEs left by one, shifting in the value of
+ NEWVALUE (which may be any Lisp expression, not just a generalized
+ variable), and returning the value shifted out of the first PLACE.
+ Thus, `(shiftf A B C D)' is equivalent to
+
+ (prog1
+ A
+ (psetf A B
+ B C
+ C D))
+
+ except that the subforms of A, B, and C are actually evaluated
+ only once each and in the apparent order.
+
+ - Special Form: rotatef PLACE...
+ This macro rotates the PLACEs left by one in circular fashion.
+ Thus, `(rotatef A B C D)' is equivalent to
+
+ (psetf A B
+ B C
+ C D
+ D A)
+
+ except for the evaluation of subforms. `rotatef' always returns
+ `nil'. Note that `(rotatef A B)' conveniently exchanges A and B.
+
+ The following macros were invented for this package; they have no
+analogues in Common Lisp.
+
+ - Special Form: letf (BINDINGS...) FORMS...
+ This macro is analogous to `let', but for generalized variables
+ rather than just symbols. Each BINDING should be of the form
+ `(PLACE VALUE)'; the original contents of the PLACEs are saved,
+ the VALUEs are stored in them, and then the body FORMs are
+ executed. Afterwards, the PLACES are set back to their original
+ saved contents. This cleanup happens even if the FORMs exit
+ irregularly due to a `throw' or an error.
+
+ For example,
+
+ (letf (((point) (point-min))
+ (a 17))
+ ...)
+
+ moves "point" in the current buffer to the beginning of the buffer,
+ and also binds `a' to 17 (as if by a normal `let', since `a' is
+ just a regular variable). After the body exits, `a' is set back
+ to its original value and point is moved back to its original
+ position.
+
+ Note that `letf' on `(point)' is not quite like a
+ `save-excursion', as the latter effectively saves a marker which
+ tracks insertions and deletions in the buffer. Actually, a `letf'
+ of `(point-marker)' is much closer to this behavior. (`point' and
+ `point-marker' are equivalent as `setf' places; each will accept
+ either an integer or a marker as the stored value.)
+
+ Since generalized variables look like lists, `let''s shorthand of
+ using `foo' for `(foo nil)' as a BINDING would be ambiguous in
+ `letf' and is not allowed.
+
+ However, a BINDING specifier may be a one-element list `(PLACE)',
+ which is similar to `(PLACE PLACE)'. In other words, the PLACE is
+ not disturbed on entry to the body, and the only effect of the
+ `letf' is to restore the original value of PLACE afterwards. (The
+ redundant access-and-store suggested by the `(PLACE PLACE)'
+ example does not actually occur.)
+
+ In most cases, the PLACE must have a well-defined value on entry
+ to the `letf' form. The only exceptions are plain variables and
+ calls to `symbol-value' and `symbol-function'. If the symbol is
+ not bound on entry, it is simply made unbound by `makunbound' or
+ `fmakunbound' on exit.
+
+ - Special Form: letf* (BINDINGS...) FORMS...
+ This macro is to `letf' what `let*' is to `let': It does the
+ bindings in sequential rather than parallel order.
+
+ - Special Form: callf FUNCTION PLACE ARGS...
+ This is the "generic" modify macro. It calls FUNCTION, which
+ should be an unquoted function name, macro name, or lambda. It
+ passes PLACE and ARGS as arguments, and assigns the result back to
+ PLACE. For example, `(incf PLACE N)' is the same as `(callf +
+ PLACE N)'. Some more examples:
+
+ (callf abs my-number)
+ (callf concat (buffer-name) "<" (int-to-string n) ">")
+ (callf union happy-people (list joe bob) :test 'same-person)
+
+ *Note Customizing Setf::, for `define-modify-macro', a way to
+ create even more concise notations for modify macros. Note again
+ that `callf' is an extension to standard Common Lisp.
+
+ - Special Form: callf2 FUNCTION ARG1 PLACE ARGS...
+ This macro is like `callf', except that PLACE is the *second*
+ argument of FUNCTION rather than the first. For example, `(push X
+ PLACE)' is equivalent to `(callf2 cons X PLACE)'.
+
+ The `callf' and `callf2' macros serve as building blocks for other
+macros like `incf', `pushnew', and `define-modify-macro'. The `letf'
+and `letf*' macros are used in the processing of symbol macros; *note
+Macro Bindings::..
+
+\1f
+File: cl.info, Node: Customizing Setf, Prev: Modify Macros, Up: Generalized Variables
+
+Customizing Setf
+----------------
+
+Common Lisp defines three macros, `define-modify-macro', `defsetf', and
+`define-setf-method', that allow the user to extend generalized
+variables in various ways.
+
+ - Special Form: define-modify-macro NAME ARGLIST FUNCTION [DOC-STRING]
+ This macro defines a "read-modify-write" macro similar to `incf'
+ and `decf'. The macro NAME is defined to take a PLACE argument
+ followed by additional arguments described by ARGLIST. The call
+
+ (NAME PLACE ARGS...)
+
+ will be expanded to
+
+ (callf FUNC PLACE ARGS...)
+
+ which in turn is roughly equivalent to
+
+ (setf PLACE (FUNC PLACE ARGS...))
+
+ For example:
+
+ (define-modify-macro incf (&optional (n 1)) +)
+ (define-modify-macro concatf (&rest args) concat)
+
+ Note that `&key' is not allowed in ARGLIST, but `&rest' is
+ sufficient to pass keywords on to the function.
+
+ Most of the modify macros defined by Common Lisp do not exactly
+ follow the pattern of `define-modify-macro'. For example, `push'
+ takes its arguments in the wrong order, and `pop' is completely
+ irregular. You can define these macros "by hand" using
+ `get-setf-method', or consult the source file `cl-macs.el' to see
+ how to use the internal `setf' building blocks.
+
+ - Special Form: defsetf ACCESS-FN UPDATE-FN
+ This is the simpler of two `defsetf' forms. Where ACCESS-FN is
+ the name of a function which accesses a place, this declares
+ UPDATE-FN to be the corresponding store function. From now on,
+
+ (setf (ACCESS-FN ARG1 ARG2 ARG3) VALUE)
+
+ will be expanded to
+
+ (UPDATE-FN ARG1 ARG2 ARG3 VALUE)
+
+ The UPDATE-FN is required to be either a true function, or a macro
+ which evaluates its arguments in a function-like way. Also, the
+ UPDATE-FN is expected to return VALUE as its result. Otherwise,
+ the above expansion would not obey the rules for the way `setf' is
+ supposed to behave.
+
+ As a special (non-Common-Lisp) extension, a third argument of `t'
+ to `defsetf' says that the `update-fn''s return value is not
+ suitable, so that the above `setf' should be expanded to something
+ more like
+
+ (let ((temp VALUE))
+ (UPDATE-FN ARG1 ARG2 ARG3 temp)
+ temp)
+
+ Some examples of the use of `defsetf', drawn from the standard
+ suite of setf methods, are:
+
+ (defsetf car setcar)
+ (defsetf symbol-value set)
+ (defsetf buffer-name rename-buffer t)
+
+ - Special Form: defsetf ACCESS-FN ARGLIST (STORE-VAR) FORMS...
+ This is the second, more complex, form of `defsetf'. It is rather
+ like `defmacro' except for the additional STORE-VAR argument. The
+ FORMS should return a Lisp form which stores the value of
+ STORE-VAR into the generalized variable formed by a call to
+ ACCESS-FN with arguments described by ARGLIST. The FORMS may
+ begin with a string which documents the `setf' method (analogous
+ to the doc string that appears at the front of a function).
+
+ For example, the simple form of `defsetf' is shorthand for
+
+ (defsetf ACCESS-FN (&rest args) (store)
+ (append '(UPDATE-FN) args (list store)))
+
+ The Lisp form that is returned can access the arguments from
+ ARGLIST and STORE-VAR in an unrestricted fashion; macros like
+ `setf' and `incf' which invoke this setf-method will insert
+ temporary variables as needed to make sure the apparent order of
+ evaluation is preserved.
+
+ Another example drawn from the standard package:
+
+ (defsetf nth (n x) (store)
+ (list 'setcar (list 'nthcdr n x) store))
+
+ - Special Form: define-setf-method ACCESS-FN ARGLIST FORMS...
+ This is the most general way to create new place forms. When a
+ `setf' to ACCESS-FN with arguments described by ARGLIST is
+ expanded, the FORMS are evaluated and must return a list of five
+ items:
+
+ 1. A list of "temporary variables".
+
+ 2. A list of "value forms" corresponding to the temporary
+ variables above. The temporary variables will be bound to
+ these value forms as the first step of any operation on the
+ generalized variable.
+
+ 3. A list of exactly one "store variable" (generally obtained
+ from a call to `gensym').
+
+ 4. A Lisp form which stores the contents of the store variable
+ into the generalized variable, assuming the temporaries have
+ been bound as described above.
+
+ 5. A Lisp form which accesses the contents of the generalized
+ variable, assuming the temporaries have been bound.
+
+ This is exactly like the Common Lisp macro of the same name,
+ except that the method returns a list of five values rather than
+ the five values themselves, since Emacs Lisp does not support
+ Common Lisp's notion of multiple return values.
+
+ Once again, the FORMS may begin with a documentation string.
+
+ A setf-method should be maximally conservative with regard to
+ temporary variables. In the setf-methods generated by `defsetf',
+ the second return value is simply the list of arguments in the
+ place form, and the first return value is a list of a
+ corresponding number of temporary variables generated by `gensym'.
+ Macros like `setf' and `incf' which use this setf-method will
+ optimize away most temporaries that turn out to be unnecessary, so
+ there is little reason for the setf-method itself to optimize.
+
+ - Function: get-setf-method PLACE &optional ENV
+ This function returns the setf-method for PLACE, by invoking the
+ definition previously recorded by `defsetf' or
+ `define-setf-method'. The result is a list of five values as
+ described above. You can use this function to build your own
+ `incf'-like modify macros. (Actually, it is better to use the
+ internal functions `cl-setf-do-modify' and `cl-setf-do-store',
+ which are a bit easier to use and which also do a number of
+ optimizations; consult the source code for the `incf' function for
+ a simple example.)
+
+ The argument ENV specifies the "environment" to be passed on to
+ `macroexpand' if `get-setf-method' should need to expand a macro
+ in PLACE. It should come from an `&environment' argument to the
+ macro or setf-method that called `get-setf-method'.
+
+ See also the source code for the setf-methods for `apply' and
+ `substring', each of which works by calling `get-setf-method' on a
+ simpler case, then massaging the result in various ways.
+
+ Modern Common Lisp defines a second, independent way to specify the
+`setf' behavior of a function, namely "`setf' functions" whose names
+are lists `(setf NAME)' rather than symbols. For example, `(defun
+(setf foo) ...)' defines the function that is used when `setf' is
+applied to `foo'. This package does not currently support `setf'
+functions. In particular, it is a compile-time error to use `setf' on
+a form which has not already been `defsetf''d or otherwise declared; in
+newer Common Lisps, this would not be an error since the function
+`(setf FUNC)' might be defined later.
+
+\1f
+File: cl.info, Node: Variable Bindings, Next: Conditionals, Prev: Generalized Variables, Up: Control Structure
+
+Variable Bindings
+=================
+
+These Lisp forms make bindings to variables and function names,
+analogous to Lisp's built-in `let' form.
+
+ *Note Modify Macros::, for the `letf' and `letf*' forms which are
+also related to variable bindings.
+
+* Menu:
+
+* Dynamic Bindings:: The `progv' form
+* Lexical Bindings:: `lexical-let' and lexical closures
+* Function Bindings:: `flet' and `labels'
+* Macro Bindings:: `macrolet' and `symbol-macrolet'
+
+\1f
+File: cl.info, Node: Dynamic Bindings, Next: Lexical Bindings, Prev: Variable Bindings, Up: Variable Bindings
+
+Dynamic Bindings
+----------------
+
+The standard `let' form binds variables whose names are known at
+compile-time. The `progv' form provides an easy way to bind variables
+whose names are computed at run-time.
+
+ - Special Form: progv SYMBOLS VALUES FORMS...
+ This form establishes `let'-style variable bindings on a set of
+ variables computed at run-time. The expressions SYMBOLS and
+ VALUES are evaluated, and must return lists of symbols and values,
+ respectively. The symbols are bound to the corresponding values
+ for the duration of the body FORMs. If VALUES is shorter than
+ SYMBOLS, the last few symbols are made unbound (as if by
+ `makunbound') inside the body. If SYMBOLS is shorter than VALUES,
+ the excess values are ignored.
+
+\1f
+File: cl.info, Node: Lexical Bindings, Next: Function Bindings, Prev: Dynamic Bindings, Up: Variable Bindings
+
+Lexical Bindings
+----------------
+
+The "CL" package defines the following macro which more closely follows
+the Common Lisp `let' form:
+
+ - Special Form: lexical-let (BINDINGS...) FORMS...
+ This form is exactly like `let' except that the bindings it
+ establishes are purely lexical. Lexical bindings are similar to
+ local variables in a language like C: Only the code physically
+ within the body of the `lexical-let' (after macro expansion) may
+ refer to the bound variables.
+
+ (setq a 5)
+ (defun foo (b) (+ a b))
+ (let ((a 2)) (foo a))
+ => 4
+ (lexical-let ((a 2)) (foo a))
+ => 7
+
+ In this example, a regular `let' binding of `a' actually makes a
+ temporary change to the global variable `a', so `foo' is able to
+ see the binding of `a' to 2. But `lexical-let' actually creates a
+ distinct local variable `a' for use within its body, without any
+ effect on the global variable of the same name.
+
+ The most important use of lexical bindings is to create "closures".
+ A closure is a function object that refers to an outside lexical
+ variable. For example:
+
+ (defun make-adder (n)
+ (lexical-let ((n n))
+ (function (lambda (m) (+ n m)))))
+ (setq add17 (make-adder 17))
+ (funcall add17 4)
+ => 21
+
+ The call `(make-adder 17)' returns a function object which adds 17
+ to its argument. If `let' had been used instead of `lexical-let',
+ the function object would have referred to the global `n', which
+ would have been bound to 17 only during the call to `make-adder'
+ itself.
+
+ (defun make-counter ()
+ (lexical-let ((n 0))
+ (function* (lambda (&optional (m 1)) (incf n m)))))
+ (setq count-1 (make-counter))
+ (funcall count-1 3)
+ => 3
+ (funcall count-1 14)
+ => 17
+ (setq count-2 (make-counter))
+ (funcall count-2 5)
+ => 5
+ (funcall count-1 2)
+ => 19
+ (funcall count-2)
+ => 6
+
+ Here we see that each call to `make-counter' creates a distinct
+ local variable `n', which serves as a private counter for the
+ function object that is returned.
+
+ Closed-over lexical variables persist until the last reference to
+ them goes away, just like all other Lisp objects. For example,
+ `count-2' refers to a function object which refers to an instance
+ of the variable `n'; this is the only reference to that variable,
+ so after `(setq count-2 nil)' the garbage collector would be able
+ to delete this instance of `n'. Of course, if a `lexical-let'
+ does not actually create any closures, then the lexical variables
+ are free as soon as the `lexical-let' returns.
+
+ Many closures are used only during the extent of the bindings they
+ refer to; these are known as "downward funargs" in Lisp parlance.
+ When a closure is used in this way, regular Emacs Lisp dynamic
+ bindings suffice and will be more efficient than `lexical-let'
+ closures:
+
+ (defun add-to-list (x list)
+ (mapcar (function (lambda (y) (+ x y))) list))
+ (add-to-list 7 '(1 2 5))
+ => (8 9 12)
+
+ Since this lambda is only used while `x' is still bound, it is not
+ necessary to make a true closure out of it.
+
+ You can use `defun' or `flet' inside a `lexical-let' to create a
+ named closure. If several closures are created in the body of a
+ single `lexical-let', they all close over the same instance of the
+ lexical variable.
+
+ The `lexical-let' form is an extension to Common Lisp. In true
+ Common Lisp, all bindings are lexical unless declared otherwise.
+
+ - Special Form: lexical-let* (BINDINGS...) FORMS...
+ This form is just like `lexical-let', except that the bindings are
+ made sequentially in the manner of `let*'.
+
+\1f
+File: cl.info, Node: Function Bindings, Next: Macro Bindings, Prev: Lexical Bindings, Up: Variable Bindings
+
+Function Bindings
+-----------------
+
+These forms make `let'-like bindings to functions instead of variables.
+
+ - Special Form: flet (BINDINGS...) FORMS...
+ This form establishes `let'-style bindings on the function cells
+ of symbols rather than on the value cells. Each BINDING must be a
+ list of the form `(NAME ARGLIST FORMS...)', which defines a
+ function exactly as if it were a `defun*' form. The function NAME
+ is defined accordingly for the duration of the body of the `flet';
+ then the old function definition, or lack thereof, is restored.
+
+ While `flet' in Common Lisp establishes a lexical binding of NAME,
+ Emacs Lisp `flet' makes a dynamic binding. The result is that
+ `flet' affects indirect calls to a function as well as calls
+ directly inside the `flet' form itself.
+
+ You can use `flet' to disable or modify the behavior of a function
+ in a temporary fashion. This will even work on Emacs primitives,
+ although note that some calls to primitive functions internal to
+ Emacs are made without going through the symbol's function cell,
+ and so will not be affected by `flet'. For example,
+
+ (flet ((message (&rest args) (push args saved-msgs)))
+ (do-something))
+
+ This code attempts to replace the built-in function `message' with
+ a function that simply saves the messages in a list rather than
+ displaying them. The original definition of `message' will be
+ restored after `do-something' exits. This code will work fine on
+ messages generated by other Lisp code, but messages generated
+ directly inside Emacs will not be caught since they make direct
+ C-language calls to the message routines rather than going through
+ the Lisp `message' function.
+
+ Functions defined by `flet' may use the full Common Lisp argument
+ notation supported by `defun*'; also, the function body is
+ enclosed in an implicit block as if by `defun*'. *Note Program
+ Structure::.
+
+ - Special Form: labels (BINDINGS...) FORMS...
+ The `labels' form is a synonym for `flet'. (In Common Lisp,
+ `labels' and `flet' differ in ways that depend on their lexical
+ scoping; these distinctions vanish in dynamically scoped Emacs
+ Lisp.)
+
+\1f
+File: cl.info, Node: Macro Bindings, Prev: Function Bindings, Up: Variable Bindings
+
+Macro Bindings
+--------------
+
+These forms create local macros and "symbol macros."
+
+ - Special Form: macrolet (BINDINGS...) FORMS...
+ This form is analogous to `flet', but for macros instead of
+ functions. Each BINDING is a list of the same form as the
+ arguments to `defmacro*' (i.e., a macro name, argument list, and
+ macro-expander forms). The macro is defined accordingly for use
+ within the body of the `macrolet'.
+
+ Because of the nature of macros, `macrolet' is lexically scoped
+ even in Emacs Lisp: The `macrolet' binding will affect only calls
+ that appear physically within the body FORMS, possibly after
+ expansion of other macros in the body.
+
+ - Special Form: symbol-macrolet (BINDINGS...) FORMS...
+ This form creates "symbol macros", which are macros that look like
+ variable references rather than function calls. Each BINDING is a
+ list `(VAR EXPANSION)'; any reference to VAR within the body FORMS
+ is replaced by EXPANSION.
+
+ (setq bar '(5 . 9))
+ (symbol-macrolet ((foo (car bar)))
+ (incf foo))
+ bar
+ => (6 . 9)
+
+ A `setq' of a symbol macro is treated the same as a `setf'. I.e.,
+ `(setq foo 4)' in the above would be equivalent to `(setf foo 4)',
+ which in turn expands to `(setf (car bar) 4)'.
+
+ Likewise, a `let' or `let*' binding a symbol macro is treated like
+ a `letf' or `letf*'. This differs from true Common Lisp, where
+ the rules of lexical scoping cause a `let' binding to shadow a
+ `symbol-macrolet' binding. In this package, only `lexical-let'
+ and `lexical-let*' will shadow a symbol macro.
+
+ There is no analogue of `defmacro' for symbol macros; all symbol
+ macros are local. A typical use of `symbol-macrolet' is in the
+ expansion of another macro:
+
+ (defmacro* my-dolist ((x list) &rest body)
+ (let ((var (gensym)))
+ (list 'loop 'for var 'on list 'do
+ (list* 'symbol-macrolet (list (list x (list 'car var)))
+ body))))
+
+ (setq mylist '(1 2 3 4))
+ (my-dolist (x mylist) (incf x))
+ mylist
+ => (2 3 4 5)
+
+ In this example, the `my-dolist' macro is similar to `dolist'
+ (*note Iteration::.) except that the variable `x' becomes a true
+ reference onto the elements of the list. The `my-dolist' call
+ shown here expands to
+
+ (loop for G1234 on mylist do
+ (symbol-macrolet ((x (car G1234)))
+ (incf x)))
+
+ which in turn expands to
+
+ (loop for G1234 on mylist do (incf (car G1234)))
+
+ *Note Loop Facility::, for a description of the `loop' macro.
+ This package defines a nonstandard `in-ref' loop clause that works
+ much like `my-dolist'.
+
+\1f
+File: cl.info, Node: Conditionals, Next: Blocks and Exits, Prev: Variable Bindings, Up: Control Structure
+
+Conditionals
+============
+
+These conditional forms augment Emacs Lisp's simple `if', `and', `or',
+and `cond' forms.
+
+ - Special Form: when TEST FORMS...
+ This is a variant of `if' where there are no "else" forms, and
+ possibly several "then" forms. In particular,
+
+ (when TEST A B C)
+
+ is entirely equivalent to
+
+ (if TEST (progn A B C) nil)
+
+ - Special Form: unless TEST FORMS...
+ This is a variant of `if' where there are no "then" forms, and
+ possibly several "else" forms:
+
+ (unless TEST A B C)
+
+ is entirely equivalent to
+
+ (when (not TEST) A B C)
+
+ - Special Form: case KEYFORM CLAUSE...
+ This macro evaluates KEYFORM, then compares it with the key values
+ listed in the various CLAUSEs. Whichever clause matches the key
+ is executed; comparison is done by `eql'. If no clause matches,
+ the `case' form returns `nil'. The clauses are of the form
+
+ (KEYLIST BODY-FORMS...)
+
+ where KEYLIST is a list of key values. If there is exactly one
+ value, and it is not a cons cell or the symbol `nil' or `t', then
+ it can be used by itself as a KEYLIST without being enclosed in a
+ list. All key values in the `case' form must be distinct. The
+ final clauses may use `t' in place of a KEYLIST to indicate a
+ default clause that should be taken if none of the other clauses
+ match. (The symbol `otherwise' is also recognized in place of
+ `t'. To make a clause that matches the actual symbol `t', `nil',
+ or `otherwise', enclose the symbol in a list.)
+
+ For example, this expression reads a keystroke, then does one of
+ four things depending on whether it is an `a', a `b', a <RET> or
+ <LFD>, or anything else.
+
+ (case (read-char)
+ (?a (do-a-thing))
+ (?b (do-b-thing))
+ ((?\r ?\n) (do-ret-thing))
+ (t (do-other-thing)))
+
+ - Special Form: ecase KEYFORM CLAUSE...
+ This macro is just like `case', except that if the key does not
+ match any of the clauses, an error is signalled rather than simply
+ returning `nil'.
+
+ - Special Form: typecase KEYFORM CLAUSE...
+ This macro is a version of `case' that checks for types rather
+ than values. Each CLAUSE is of the form `(TYPE BODY...)'. *Note
+ Type Predicates::, for a description of type specifiers. For
+ example,
+
+ (typecase x
+ (integer (munch-integer x))
+ (float (munch-float x))
+ (string (munch-integer (string-to-int x)))
+ (t (munch-anything x)))
+
+ The type specifier `t' matches any type of object; the word
+ `otherwise' is also allowed. To make one clause match any of
+ several types, use an `(or ...)' type specifier.
+
+ - Special Form: etypecase KEYFORM CLAUSE...
+ This macro is just like `typecase', except that if the key does
+ not match any of the clauses, an error is signalled rather than
+ simply returning `nil'.
+
+\1f
+File: cl.info, Node: Blocks and Exits, Next: Iteration, Prev: Conditionals, Up: Control Structure
+
+Blocks and Exits
+================
+
+Common Lisp "blocks" provide a non-local exit mechanism very similar to
+`catch' and `throw', but lexically rather than dynamically scoped.
+This package actually implements `block' in terms of `catch'; however,
+the lexical scoping allows the optimizing byte-compiler to omit the
+costly `catch' step if the body of the block does not actually
+`return-from' the block.
+
+ - Special Form: block NAME FORMS...
+ The FORMS are evaluated as if by a `progn'. However, if any of
+ the FORMS execute `(return-from NAME)', they will jump out and
+ return directly from the `block' form. The `block' returns the
+ result of the last FORM unless a `return-from' occurs.
+
+ The `block'/`return-from' mechanism is quite similar to the
+ `catch'/`throw' mechanism. The main differences are that block
+ NAMEs are unevaluated symbols, rather than forms (such as quoted
+ symbols) which evaluate to a tag at run-time; and also that blocks
+ are lexically scoped whereas `catch'/`throw' are dynamically
+ scoped. This means that functions called from the body of a
+ `catch' can also `throw' to the `catch', but the `return-from'
+ referring to a block name must appear physically within the FORMS
+ that make up the body of the block. They may not appear within
+ other called functions, although they may appear within macro
+ expansions or `lambda's in the body. Block names and `catch'
+ names form independent name-spaces.
+
+ In true Common Lisp, `defun' and `defmacro' surround the function
+ or expander bodies with implicit blocks with the same name as the
+ function or macro. This does not occur in Emacs Lisp, but this
+ package provides `defun*' and `defmacro*' forms which do create
+ the implicit block.
+
+ The Common Lisp looping constructs defined by this package, such
+ as `loop' and `dolist', also create implicit blocks just as in
+ Common Lisp.
+
+ Because they are implemented in terms of Emacs Lisp `catch' and
+ `throw', blocks have the same overhead as actual `catch'
+ constructs (roughly two function calls). However, Zawinski and
+ Furuseth's optimizing byte compiler (standard in Emacs 19) will
+ optimize away the `catch' if the block does not in fact contain
+ any `return' or `return-from' calls that jump to it. This means
+ that `do' loops and `defun*' functions which don't use `return'
+ don't pay the overhead to support it.
+
+ - Special Form: return-from NAME [RESULT]
+ This macro returns from the block named NAME, which must be an
+ (unevaluated) symbol. If a RESULT form is specified, it is
+ evaluated to produce the result returned from the `block'.
+ Otherwise, `nil' is returned.
+
+ - Special Form: return [RESULT]
+ This macro is exactly like `(return-from nil RESULT)'. Common
+ Lisp loops like `do' and `dolist' implicitly enclose themselves in
+ `nil' blocks.
+
+\1f
+File: cl.info, Node: Iteration, Next: Loop Facility, Prev: Blocks and Exits, Up: Control Structure
+
+Iteration
+=========
+
+The macros described here provide more sophisticated, high-level
+looping constructs to complement Emacs Lisp's basic `while' loop.
+
+ - Special Form: loop FORMS...
+ The "CL" package supports both the simple, old-style meaning of
+ `loop' and the extremely powerful and flexible feature known as
+ the "Loop Facility" or "Loop Macro". This more advanced facility
+ is discussed in the following section; *note Loop Facility::..
+ The simple form of `loop' is described here.
+
+ If `loop' is followed by zero or more Lisp expressions, then
+ `(loop EXPRS...)' simply creates an infinite loop executing the
+ expressions over and over. The loop is enclosed in an implicit
+ `nil' block. Thus,
+
+ (loop (foo) (if (no-more) (return 72)) (bar))
+
+ is exactly equivalent to
+
+ (block nil (while t (foo) (if (no-more) (return 72)) (bar)))
+
+ If any of the expressions are plain symbols, the loop is instead
+ interpreted as a Loop Macro specification as described later.
+ (This is not a restriction in practice, since a plain symbol in
+ the above notation would simply access and throw away the value of
+ a variable.)
+
+ - Special Form: do (SPEC...) (END-TEST [RESULT...]) FORMS...
+ This macro creates a general iterative loop. Each SPEC is of the
+ form
+
+ (VAR [INIT [STEP]])
+
+ The loop works as follows: First, each VAR is bound to the
+ associated INIT value as if by a `let' form. Then, in each
+ iteration of the loop, the END-TEST is evaluated; if true, the
+ loop is finished. Otherwise, the body FORMS are evaluated, then
+ each VAR is set to the associated STEP expression (as if by a
+ `psetq' form) and the next iteration begins. Once the END-TEST
+ becomes true, the RESULT forms are evaluated (with the VARs still
+ bound to their values) to produce the result returned by `do'.
+
+ The entire `do' loop is enclosed in an implicit `nil' block, so
+ that you can use `(return)' to break out of the loop at any time.
+
+ If there are no RESULT forms, the loop returns `nil'. If a given
+ VAR has no STEP form, it is bound to its INIT value but not
+ otherwise modified during the `do' loop (unless the code
+ explicitly modifies it); this case is just a shorthand for putting
+ a `(let ((VAR INIT)) ...)' around the loop. If INIT is also
+ omitted it defaults to `nil', and in this case a plain `VAR' can
+ be used in place of `(VAR)', again following the analogy with
+ `let'.
+
+ This example (from Steele) illustrates a loop which applies the
+ function `f' to successive pairs of values from the lists `foo'
+ and `bar'; it is equivalent to the call `(mapcar* 'f foo bar)'.
+ Note that this loop has no body FORMS at all, performing all its
+ work as side effects of the rest of the loop.
+
+ (do ((x foo (cdr x))
+ (y bar (cdr y))
+ (z nil (cons (f (car x) (car y)) z)))
+ ((or (null x) (null y))
+ (nreverse z)))
+
+ - Special Form: do* (SPEC...) (END-TEST [RESULT...]) FORMS...
+ This is to `do' what `let*' is to `let'. In particular, the
+ initial values are bound as if by `let*' rather than `let', and
+ the steps are assigned as if by `setq' rather than `psetq'.
+
+ Here is another way to write the above loop:
+
+ (do* ((xp foo (cdr xp))
+ (yp bar (cdr yp))
+ (x (car xp) (car xp))
+ (y (car yp) (car yp))
+ z)
+ ((or (null xp) (null yp))
+ (nreverse z))
+ (push (f x y) z))
+
+ - Special Form: dolist (VAR LIST [RESULT]) FORMS...
+ This is a more specialized loop which iterates across the elements
+ of a list. LIST should evaluate to a list; the body FORMS are
+ executed with VAR bound to each element of the list in turn.
+ Finally, the RESULT form (or `nil') is evaluated with VAR bound to
+ `nil' to produce the result returned by the loop. The loop is
+ surrounded by an implicit `nil' block.
+
+ - Special Form: dotimes (VAR COUNT [RESULT]) FORMS...
+ This is a more specialized loop which iterates a specified number
+ of times. The body is executed with VAR bound to the integers
+ from zero (inclusive) to COUNT (exclusive), in turn. Then the
+ `result' form is evaluated with VAR bound to the total number of
+ iterations that were done (i.e., `(max 0 COUNT)') to get the
+ return value for the loop form. The loop is surrounded by an
+ implicit `nil' block.
+
+ - Special Form: do-symbols (VAR [OBARRAY [RESULT]]) FORMS...
+ This loop iterates over all interned symbols. If OBARRAY is
+ specified and is not `nil', it loops over all symbols in that
+ obarray. For each symbol, the body FORMS are evaluated with VAR
+ bound to that symbol. The symbols are visited in an unspecified
+ order. Afterward the RESULT form, if any, is evaluated (with VAR
+ bound to `nil') to get the return value. The loop is surrounded
+ by an implicit `nil' block.
+
+ - Special Form: do-all-symbols (VAR [RESULT]) FORMS...
+ This is identical to `do-symbols' except that the OBARRAY argument
+ is omitted; it always iterates over the default obarray.
+
+ *Note Mapping over Sequences::, for some more functions for
+iterating over vectors or lists.
+
+\1f
+File: cl.info, Node: Loop Facility, Next: Multiple Values, Prev: Iteration, Up: Control Structure
+
+Loop Facility
+=============
+
+A common complaint with Lisp's traditional looping constructs is that
+they are either too simple and limited, such as Common Lisp's `dotimes'
+or Emacs Lisp's `while', or too unreadable and obscure, like Common
+Lisp's `do' loop.
+
+ To remedy this, recent versions of Common Lisp have added a new
+construct called the "Loop Facility" or "`loop' macro," with an
+easy-to-use but very powerful and expressive syntax.
+
+* Menu:
+
+* Loop Basics:: `loop' macro, basic clause structure
+* Loop Examples:: Working examples of `loop' macro
+* For Clauses:: Clauses introduced by `for' or `as'
+* Iteration Clauses:: `repeat', `while', `thereis', etc.
+* Accumulation Clauses:: `collect', `sum', `maximize', etc.
+* Other Clauses:: `with', `if', `initially', `finally'
+
+\1f
+File: cl.info, Node: Loop Basics, Next: Loop Examples, Prev: Loop Facility, Up: Loop Facility
+
+Loop Basics
+-----------
+
+The `loop' macro essentially creates a mini-language within Lisp that
+is specially tailored for describing loops. While this language is a
+little strange-looking by the standards of regular Lisp, it turns out
+to be very easy to learn and well-suited to its purpose.
+
+ Since `loop' is a macro, all parsing of the loop language takes
+place at byte-compile time; compiled `loop's are just as efficient as
+the equivalent `while' loops written longhand.
+
+ - Special Form: loop CLAUSES...
+ A loop construct consists of a series of CLAUSEs, each introduced
+ by a symbol like `for' or `do'. Clauses are simply strung
+ together in the argument list of `loop', with minimal extra
+ parentheses. The various types of clauses specify
+ initializations, such as the binding of temporary variables,
+ actions to be taken in the loop, stepping actions, and final
+ cleanup.
+
+ Common Lisp specifies a certain general order of clauses in a loop:
+
+ (loop NAME-CLAUSE
+ VAR-CLAUSES...
+ ACTION-CLAUSES...)
+
+ The NAME-CLAUSE optionally gives a name to the implicit block that
+ surrounds the loop. By default, the implicit block is named
+ `nil'. The VAR-CLAUSES specify what variables should be bound
+ during the loop, and how they should be modified or iterated
+ throughout the course of the loop. The ACTION-CLAUSES are things
+ to be done during the loop, such as computing, collecting, and
+ returning values.
+
+ The Emacs version of the `loop' macro is less restrictive about
+ the order of clauses, but things will behave most predictably if
+ you put the variable-binding clauses `with', `for', and `repeat'
+ before the action clauses. As in Common Lisp, `initially' and
+ `finally' clauses can go anywhere.
+
+ Loops generally return `nil' by default, but you can cause them to
+ return a value by using an accumulation clause like `collect', an
+ end-test clause like `always', or an explicit `return' clause to
+ jump out of the implicit block. (Because the loop body is
+ enclosed in an implicit block, you can also use regular Lisp
+ `return' or `return-from' to break out of the loop.)
+
+ The following sections give some examples of the Loop Macro in
+action, and describe the particular loop clauses in great detail.
+Consult the second edition of Steele's "Common Lisp, the Language", for
+additional discussion and examples of the `loop' macro.
+
+\1f
+File: cl.info, Node: Loop Examples, Next: For Clauses, Prev: Loop Basics, Up: Loop Facility
+
+Loop Examples
+-------------
+
+Before listing the full set of clauses that are allowed, let's look at
+a few example loops just to get a feel for the `loop' language.
+
+ (loop for buf in (buffer-list)
+ collect (buffer-file-name buf))
+
+This loop iterates over all Emacs buffers, using the list returned by
+`buffer-list'. For each buffer `buf', it calls `buffer-file-name' and
+collects the results into a list, which is then returned from the
+`loop' construct. The result is a list of the file names of all the
+buffers in Emacs' memory. The words `for', `in', and `collect' are
+reserved words in the `loop' language.
+
+ (loop repeat 20 do (insert "Yowsa\n"))
+
+This loop inserts the phrase "Yowsa" twenty times in the current buffer.
+
+ (loop until (eobp) do (munch-line) (forward-line 1))
+
+This loop calls `munch-line' on every line until the end of the buffer.
+If point is already at the end of the buffer, the loop exits
+immediately.
+
+ (loop do (munch-line) until (eobp) do (forward-line 1))
+
+This loop is similar to the above one, except that `munch-line' is
+always called at least once.
+
+ (loop for x from 1 to 100
+ for y = (* x x)
+ until (>= y 729)
+ finally return (list x (= y 729)))
+
+This more complicated loop searches for a number `x' whose square is
+729. For safety's sake it only examines `x' values up to 100; dropping
+the phrase `to 100' would cause the loop to count upwards with no
+limit. The second `for' clause defines `y' to be the square of `x'
+within the loop; the expression after the `=' sign is reevaluated each
+time through the loop. The `until' clause gives a condition for
+terminating the loop, and the `finally' clause says what to do when the
+loop finishes. (This particular example was written less concisely
+than it could have been, just for the sake of illustration.)
+
+ Note that even though this loop contains three clauses (two `for's
+and an `until') that would have been enough to define loops all by
+themselves, it still creates a single loop rather than some sort of
+triple-nested loop. You must explicitly nest your `loop' constructs if
+you want nested loops.
+
--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+File: cl.info, Node: For Clauses, Next: Iteration Clauses, Prev: Loop Examples, Up: Loop Facility
+
+For Clauses
+-----------
+
+Most loops are governed by one or more `for' clauses. A `for' clause
+simultaneously describes variables to be bound, how those variables are
+to be stepped during the loop, and usually an end condition based on
+those variables.
+
+ The word `as' is a synonym for the word `for'. This word is
+followed by a variable name, then a word like `from' or `across' that
+describes the kind of iteration desired. In Common Lisp, the phrase
+`being the' sometimes precedes the type of iteration; in this package
+both `being' and `the' are optional. The word `each' is a synonym for
+`the', and the word that follows it may be singular or plural: `for x
+being the elements of y' or `for x being each element of y'. Which
+form you use is purely a matter of style.
+
+ The variable is bound around the loop as if by `let':
+
+ (setq i 'happy)
+ (loop for i from 1 to 10 do (do-something-with i))
+ i
+ => happy
+
+`for VAR from EXPR1 to EXPR2 by EXPR3'
+ This type of `for' clause creates a counting loop. Each of the
+ three sub-terms is optional, though there must be at least one
+ term so that the clause is marked as a counting clause.
+
+ The three expressions are the starting value, the ending value, and
+ the step value, respectively, of the variable. The loop counts
+ upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2
+ inclusively. If you omit the `from' term, the loop counts from
+ zero; if you omit the `to' term, the loop counts forever without
+ stopping (unless stopped by some other loop clause, of course); if
+ you omit the `by' term, the loop counts in steps of one.
+
+ You can replace the word `from' with `upfrom' or `downfrom' to
+ indicate the direction of the loop. Likewise, you can replace
+ `to' with `upto' or `downto'. For example, `for x from 5 downto
+ 1' executes five times with `x' taking on the integers from 5 down
+ to 1 in turn. Also, you can replace `to' with `below' or `above',
+ which are like `upto' and `downto' respectively except that they
+ are exclusive rather than inclusive limits:
+
+ (loop for x to 10 collect x)
+ => (0 1 2 3 4 5 6 7 8 9 10)
+ (loop for x below 10 collect x)
+ => (0 1 2 3 4 5 6 7 8 9)
+
+ The `by' value is always positive, even for downward-counting
+ loops. Some sort of `from' value is required for downward loops;
+ `for x downto 5' is not a legal loop clause all by itself.
+
+`for VAR in LIST by FUNCTION'
+ This clause iterates VAR over all the elements of LIST, in turn.
+ If you specify the `by' term, then FUNCTION is used to traverse
+ the list instead of `cdr'; it must be a function taking one
+ argument. For example:
+
+ (loop for x in '(1 2 3 4 5 6) collect (* x x))
+ => (1 4 9 16 25 36)
+ (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
+ => (1 9 25)
+
+`for VAR on LIST by FUNCTION'
+ This clause iterates VAR over all the cons cells of LIST.
+
+ (loop for x on '(1 2 3 4) collect x)
+ => ((1 2 3 4) (2 3 4) (3 4) (4))
+
+ With `by', there is no real reason that the `on' expression must
+ be a list. For example:
+
+ (loop for x on first-animal by 'next-animal collect x)
+
+ where `(next-animal x)' takes an "animal" X and returns the next
+ in the (assumed) sequence of animals, or `nil' if X was the last
+ animal in the sequence.
+
+`for VAR in-ref LIST by FUNCTION'
+ This is like a regular `in' clause, but VAR becomes a `setf'-able
+ "reference" onto the elements of the list rather than just a
+ temporary variable. For example,
+
+ (loop for x in-ref my-list do (incf x))
+
+ increments every element of `my-list' in place. This clause is an
+ extension to standard Common Lisp.
+
+`for VAR across ARRAY'
+ This clause iterates VAR over all the elements of ARRAY, which may
+ be a vector or a string.
+
+ (loop for x across "aeiou"
+ do (use-vowel (char-to-string x)))
+
+`for VAR across-ref ARRAY'
+ This clause iterates over an array, with VAR a `setf'-able
+ reference onto the elements; see `in-ref' above.
+
+`for VAR being the elements of SEQUENCE'
+ This clause iterates over the elements of SEQUENCE, which may be a
+ list, vector, or string. Since the type must be determined at
+ run-time, this is somewhat less efficient than `in' or `across'.
+ The clause may be followed by the additional term `using (index
+ VAR2)' to cause VAR2 to be bound to the successive indices
+ (starting at 0) of the elements.
+
+ This clause type is taken from older versions of the `loop' macro,
+ and is not present in modern Common Lisp. The `using (sequence
+ ...)' term of the older macros is not supported.
+
+`for VAR being the elements of-ref SEQUENCE'
+ This clause iterates over a sequence, with VAR a `setf'-able
+ reference onto the elements; see `in-ref' above.
+
+`for VAR being the symbols [of OBARRAY]'
+ This clause iterates over symbols, either over all interned symbols
+ or over all symbols in OBARRAY. The loop is executed with VAR
+ bound to each symbol in turn. The symbols are visited in an
+ unspecified order.
+
+ As an example,
+
+ (loop for sym being the symbols
+ when (fboundp sym)
+ when (string-match "^map" (symbol-name sym))
+ collect sym)
+
+ returns a list of all the functions whose names begin with `map'.
+
+ The Common Lisp words `external-symbols' and `present-symbols' are
+ also recognized but are equivalent to `symbols' in Emacs Lisp.
+
+ Due to a minor implementation restriction, it will not work to have
+ more than one `for' clause iterating over symbols, hash tables,
+ keymaps, overlays, or intervals in a given `loop'. Fortunately,
+ it would rarely if ever be useful to do so. It *is* legal to mix
+ one of these types of clauses with other clauses like `for ... to'
+ or `while'.
+
+`for VAR being the hash-keys of HASH-TABLE'
+ This clause iterates over the entries in HASH-TABLE. For each
+ hash table entry, VAR is bound to the entry's key. If you write
+ `the hash-values' instead, VAR is bound to the values of the
+ entries. The clause may be followed by the additional term `using
+ (hash-values VAR2)' (where `hash-values' is the opposite word of
+ the word following `the') to cause VAR and VAR2 to be bound to the
+ two parts of each hash table entry.
+
+`for VAR being the key-codes of KEYMAP'
+ This clause iterates over the entries in KEYMAP. In GNU Emacs 18
+ and 19, keymaps are either alists or vectors, and key-codes are
+ integers or symbols. In XEmacs, keymaps are a special new data
+ type, and key-codes are symbols or lists of symbols. The
+ iteration does not enter nested keymaps or inherited (parent)
+ keymaps. You can use `the key-bindings' to access the commands
+ bound to the keys rather than the key codes, and you can add a
+ `using' clause to access both the codes and the bindings together.
+
+`for VAR being the key-seqs of KEYMAP'
+ This clause iterates over all key sequences defined by KEYMAP and
+ its nested keymaps, where VAR takes on values which are strings in
+ Emacs 18 or vectors in Emacs 19. The strings or vectors are
+ reused for each iteration, so you must copy them if you wish to
+ keep them permanently. You can add a `using (key-bindings ...)'
+ clause to get the command bindings as well.
+
+`for VAR being the overlays [of BUFFER] ...'
+ This clause iterates over the Emacs 19 "overlays" or XEmacs
+ "extents" of a buffer (the clause `extents' is synonymous with
+ `overlays'). Under Emacs 18, this clause iterates zero times. If
+ the `of' term is omitted, the current buffer is used. This clause
+ also accepts optional `from POS' and `to POS' terms, limiting the
+ clause to overlays which overlap the specified region.
+
+`for VAR being the intervals [of BUFFER] ...'
+ This clause iterates over all intervals of a buffer with constant
+ text properties. The variable VAR will be bound to conses of
+ start and end positions, where one start position is always equal
+ to the previous end position. The clause allows `of', `from',
+ `to', and `property' terms, where the latter term restricts the
+ search to just the specified property. The `of' term may specify
+ either a buffer or a string. This clause is useful only in GNU
+ Emacs 19; in other versions, all buffers and strings consist of a
+ single interval.
+
+`for VAR being the frames'
+ This clause iterates over all frames, i.e., X window system windows
+ open on Emacs files. This clause works only under Emacs 19. The
+ clause `screens' is a synonym for `frames'. The frames are
+ visited in `next-frame' order starting from `selected-frame'.
+
+`for VAR being the windows [of FRAME]'
+ This clause iterates over the windows (in the Emacs sense) of the
+ current frame, or of the specified FRAME. (In Emacs 18 there is
+ only ever one frame, and the `of' term is not allowed there.)
+
+`for VAR being the buffers'
+ This clause iterates over all buffers in Emacs. It is equivalent
+ to `for VAR in (buffer-list)'.
+
+`for VAR = EXPR1 then EXPR2'
+ This clause does a general iteration. The first time through the
+ loop, VAR will be bound to EXPR1. On the second and successive
+ iterations it will be set by evaluating EXPR2 (which may refer to
+ the old value of VAR). For example, these two loops are
+ effectively the same:
+
+ (loop for x on my-list by 'cddr do ...)
+ (loop for x = my-list then (cddr x) while x do ...)
+
+ Note that this type of `for' clause does not imply any sort of
+ terminating condition; the above example combines it with a
+ `while' clause to tell when to end the loop.
+
+ If you omit the `then' term, EXPR1 is used both for the initial
+ setting and for successive settings:
+
+ (loop for x = (random) when (> x 0) return x)
+
+ This loop keeps taking random numbers from the `(random)' function
+ until it gets a positive one, which it then returns.
+
+ If you include several `for' clauses in a row, they are treated
+sequentially (as if by `let*' and `setq'). You can instead use the
+word `and' to link the clauses, in which case they are processed in
+parallel (as if by `let' and `psetq').
+
+ (loop for x below 5 for y = nil then x collect (list x y))
+ => ((0 nil) (1 1) (2 2) (3 3) (4 4))
+ (loop for x below 5 and y = nil then x collect (list x y))
+ => ((0 nil) (1 0) (2 1) (3 2) (4 3))
+
+In the first loop, `y' is set based on the value of `x' that was just
+set by the previous clause; in the second loop, `x' and `y' are set
+simultaneously so `y' is set based on the value of `x' left over from
+the previous time through the loop.
+
+ Another feature of the `loop' macro is "destructuring", similar in
+concept to the destructuring provided by `defmacro'. The VAR part of
+any `for' clause can be given as a list of variables instead of a
+single variable. The values produced during loop execution must be
+lists; the values in the lists are stored in the corresponding
+variables.
+
+ (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
+ => (5 9 13)
+
+ In loop destructuring, if there are more values than variables the
+trailing values are ignored, and if there are more variables than
+values the trailing variables get the value `nil'. If `nil' is used as
+a variable name, the corresponding values are ignored. Destructuring
+may be nested, and dotted lists of variables like `(x . y)' are allowed.
+
+\1f
+File: cl.info, Node: Iteration Clauses, Next: Accumulation Clauses, Prev: For Clauses, Up: Loop Facility
+
+Iteration Clauses
+-----------------
+
+Aside from `for' clauses, there are several other loop clauses that
+control the way the loop operates. They might be used by themselves,
+or in conjunction with one or more `for' clauses.
+
+`repeat INTEGER'
+ This clause simply counts up to the specified number using an
+ internal temporary variable. The loops
+
+ (loop repeat n do ...)
+ (loop for temp to n do ...)
+
+ are identical except that the second one forces you to choose a
+ name for a variable you aren't actually going to use.
+
+`while CONDITION'
+ This clause stops the loop when the specified condition (any Lisp
+ expression) becomes `nil'. For example, the following two loops
+ are equivalent, except for the implicit `nil' block that surrounds
+ the second one:
+
+ (while COND FORMS...)
+ (loop while COND do FORMS...)
+
+`until CONDITION'
+ This clause stops the loop when the specified condition is true,
+ i.e., non-`nil'.
+
+`always CONDITION'
+ This clause stops the loop when the specified condition is `nil'.
+ Unlike `while', it stops the loop using `return nil' so that the
+ `finally' clauses are not executed. If all the conditions were
+ non-`nil', the loop returns `t':
+
+ (if (loop for size in size-list always (> size 10))
+ (some-big-sizes)
+ (no-big-sizes))
+
+`never CONDITION'
+ This clause is like `always', except that the loop returns `t' if
+ any conditions were false, or `nil' otherwise.
+
+`thereis CONDITION'
+ This clause stops the loop when the specified form is non-`nil';
+ in this case, it returns that non-`nil' value. If all the values
+ were `nil', the loop returns `nil'.
+
+\1f
+File: cl.info, Node: Accumulation Clauses, Next: Other Clauses, Prev: Iteration Clauses, Up: Loop Facility
+
+Accumulation Clauses
+--------------------
+
+These clauses cause the loop to accumulate information about the
+specified Lisp FORM. The accumulated result is returned from the loop
+unless overridden, say, by a `return' clause.
+
+`collect FORM'
+ This clause collects the values of FORM into a list. Several
+ examples of `collect' appear elsewhere in this manual.
+
+ The word `collecting' is a synonym for `collect', and likewise for
+ the other accumulation clauses.
+
+`append FORM'
+ This clause collects lists of values into a result list using
+ `append'.
+
+`nconc FORM'
+ This clause collects lists of values into a result list by
+ destructively modifying the lists rather than copying them.
+
+`concat FORM'
+ This clause concatenates the values of the specified FORM into a
+ string. (It and the following clause are extensions to standard
+ Common Lisp.)
+
+`vconcat FORM'
+ This clause concatenates the values of the specified FORM into a
+ vector.
+
+`count FORM'
+ This clause counts the number of times the specified FORM
+ evaluates to a non-`nil' value.
+
+`sum FORM'
+ This clause accumulates the sum of the values of the specified
+ FORM, which must evaluate to a number.
+
+`maximize FORM'
+ This clause accumulates the maximum value of the specified FORM,
+ which must evaluate to a number. The return value is undefined if
+ `maximize' is executed zero times.
+
+`minimize FORM'
+ This clause accumulates the minimum value of the specified FORM.
+
+ Accumulation clauses can be followed by `into VAR' to cause the data
+to be collected into variable VAR (which is automatically `let'-bound
+during the loop) rather than an unnamed temporary variable. Also,
+`into' accumulations do not automatically imply a return value. The
+loop must use some explicit mechanism, such as `finally return', to
+return the accumulated result.
+
+ It is legal for several accumulation clauses of the same type to
+accumulate into the same place. From Steele:
+
+ (loop for name in '(fred sue alice joe june)
+ for kids in '((bob ken) () () (kris sunshine) ())
+ collect name
+ append kids)
+ => (fred bob ken sue alice joe kris sunshine june)
+
+\1f
+File: cl.info, Node: Other Clauses, Prev: Accumulation Clauses, Up: Loop Facility
+
+Other Clauses
+-------------
+
+This section describes the remaining loop clauses.
+
+`with VAR = VALUE'
+ This clause binds a variable to a value around the loop, but
+ otherwise leaves the variable alone during the loop. The following
+ loops are basically equivalent:
+
+ (loop with x = 17 do ...)
+ (let ((x 17)) (loop do ...))
+ (loop for x = 17 then x do ...)
+
+ Naturally, the variable VAR might be used for some purpose in the
+ rest of the loop. For example:
+
+ (loop for x in my-list with res = nil do (push x res)
+ finally return res)
+
+ This loop inserts the elements of `my-list' at the front of a new
+ list being accumulated in `res', then returns the list `res' at
+ the end of the loop. The effect is similar to that of a `collect'
+ clause, but the list gets reversed by virtue of the fact that
+ elements are being pushed onto the front of `res' rather than the
+ end.
+
+ If you omit the `=' term, the variable is initialized to `nil'.
+ (Thus the `= nil' in the above example is unnecessary.)
+
+ Bindings made by `with' are sequential by default, as if by
+ `let*'. Just like `for' clauses, `with' clauses can be linked
+ with `and' to cause the bindings to be made by `let' instead.
+
+`if CONDITION CLAUSE'
+ This clause executes the following loop clause only if the
+ specified condition is true. The following CLAUSE should be an
+ accumulation, `do', `return', `if', or `unless' clause. Several
+ clauses may be linked by separating them with `and'. These
+ clauses may be followed by `else' and a clause or clauses to
+ execute if the condition was false. The whole construct may
+ optionally be followed by the word `end' (which may be used to
+ disambiguate an `else' or `and' in a nested `if').
+
+ The actual non-`nil' value of the condition form is available by
+ the name `it' in the "then" part. For example:
+
+ (setq funny-numbers '(6 13 -1))
+ => (6 13 -1)
+ (loop for x below 10
+ if (oddp x)
+ collect x into odds
+ and if (memq x funny-numbers) return (cdr it) end
+ else
+ collect x into evens
+ finally return (vector odds evens))
+ => [(1 3 5 7 9) (0 2 4 6 8)]
+ (setq funny-numbers '(6 7 13 -1))
+ => (6 7 13 -1)
+ (loop <same thing again>)
+ => (13 -1)
+
+ Note the use of `and' to put two clauses into the "then" part, one
+ of which is itself an `if' clause. Note also that `end', while
+ normally optional, was necessary here to make it clear that the
+ `else' refers to the outermost `if' clause. In the first case,
+ the loop returns a vector of lists of the odd and even values of
+ X. In the second case, the odd number 7 is one of the
+ `funny-numbers' so the loop returns early; the actual returned
+ value is based on the result of the `memq' call.
+
+`when CONDITION CLAUSE'
+ This clause is just a synonym for `if'.
+
+`unless CONDITION CLAUSE'
+ The `unless' clause is just like `if' except that the sense of the
+ condition is reversed.
+
+`named NAME'
+ This clause gives a name other than `nil' to the implicit block
+ surrounding the loop. The NAME is the symbol to be used as the
+ block name.
+
+`initially [do] FORMS...'
+ This keyword introduces one or more Lisp forms which will be
+ executed before the loop itself begins (but after any variables
+ requested by `for' or `with' have been bound to their initial
+ values). `initially' clauses can appear anywhere; if there are
+ several, they are executed in the order they appear in the loop.
+ The keyword `do' is optional.
+
+`finally [do] FORMS...'
+ This introduces Lisp forms which will be executed after the loop
+ finishes (say, on request of a `for' or `while'). `initially' and
+ `finally' clauses may appear anywhere in the loop construct, but
+ they are executed (in the specified order) at the beginning or
+ end, respectively, of the loop.
+
+`finally return FORM'
+ This says that FORM should be executed after the loop is done to
+ obtain a return value. (Without this, or some other clause like
+ `collect' or `return', the loop will simply return `nil'.)
+ Variables bound by `for', `with', or `into' will still contain
+ their final values when FORM is executed.
+
+`do FORMS...'
+ The word `do' may be followed by any number of Lisp expressions
+ which are executed as an implicit `progn' in the body of the loop.
+ Many of the examples in this section illustrate the use of `do'.
+
+`return FORM'
+ This clause causes the loop to return immediately. The following
+ Lisp form is evaluated to give the return value of the `loop'
+ form. The `finally' clauses, if any, are not executed. Of
+ course, `return' is generally used inside an `if' or `unless', as
+ its use in a top-level loop clause would mean the loop would never
+ get to "loop" more than once.
+
+ The clause `return FORM' is equivalent to `do (return FORM)' (or
+ `return-from' if the loop was named). The `return' clause is
+ implemented a bit more efficiently, though.
+
+ While there is no high-level way to add user extensions to `loop'
+(comparable to `defsetf' for `setf', say), this package does offer two
+properties called `cl-loop-handler' and `cl-loop-for-handler' which are
+functions to be called when a given symbol is encountered as a
+top-level loop clause or `for' clause, respectively. Consult the
+source code in file `cl-macs.el' for details.
+
+ This package's `loop' macro is compatible with that of Common Lisp,
+except that a few features are not implemented: `loop-finish' and
+data-type specifiers. Naturally, the `for' clauses which iterate over
+keymaps, overlays, intervals, frames, windows, and buffers are
+Emacs-specific extensions.
+
+\1f
+File: cl.info, Node: Multiple Values, Prev: Loop Facility, Up: Control Structure
+
+Multiple Values
+===============
+
+Common Lisp functions can return zero or more results. Emacs Lisp
+functions, by contrast, always return exactly one result. This package
+makes no attempt to emulate Common Lisp multiple return values; Emacs
+versions of Common Lisp functions that return more than one value
+either return just the first value (as in `compiler-macroexpand') or
+return a list of values (as in `get-setf-method'). This package *does*
+define placeholders for the Common Lisp functions that work with
+multiple values, but in Emacs Lisp these functions simply operate on
+lists instead. The `values' form, for example, is a synonym for `list'
+in Emacs.
+
+ - Special Form: multiple-value-bind (VAR...) VALUES-FORM FORMS...
+ This form evaluates VALUES-FORM, which must return a list of
+ values. It then binds the VARs to these respective values, as if
+ by `let', and then executes the body FORMS. If there are more
+ VARs than values, the extra VARs are bound to `nil'. If there are
+ fewer VARs than values, the excess values are ignored.
+
+ - Special Form: multiple-value-setq (VAR...) FORM
+ This form evaluates FORM, which must return a list of values. It
+ then sets the VARs to these respective values, as if by `setq'.
+ Extra VARs or values are treated the same as in
+ `multiple-value-bind'.
+
+ The older Quiroz package attempted a more faithful (but still
+imperfect) emulation of Common Lisp multiple values. The old method
+"usually" simulated true multiple values quite well, but under certain
+circumstances would leave spurious return values in memory where a
+later, unrelated `multiple-value-bind' form would see them.
+
+ Since a perfect emulation is not feasible in Emacs Lisp, this
+package opts to keep it as simple and predictable as possible.
+
+\1f
+File: cl.info, Node: Macros, Next: Declarations, Prev: Control Structure, Up: Top
+
+Macros
+******
+
+This package implements the various Common Lisp features of `defmacro',
+such as destructuring, `&environment', and `&body'. Top-level `&whole'
+is not implemented for `defmacro' due to technical difficulties. *Note
+Argument Lists::.
+
+ Destructuring is made available to the user by way of the following
+macro:
+
+ - Special Form: destructuring-bind ARGLIST EXPR FORMS...
+ This macro expands to code which executes FORMS, with the
+ variables in ARGLIST bound to the list of values returned by EXPR.
+ The ARGLIST can include all the features allowed for `defmacro'
+ argument lists, including destructuring. (The `&environment'
+ keyword is not allowed.) The macro expansion will signal an error
+ if EXPR returns a list of the wrong number of arguments or with
+ incorrect keyword arguments.
+
+ This package also includes the Common Lisp `define-compiler-macro'
+facility, which allows you to define compile-time expansions and
+optimizations for your functions.
+
+ - Special Form: define-compiler-macro NAME ARGLIST FORMS...
+ This form is similar to `defmacro', except that it only expands
+ calls to NAME at compile-time; calls processed by the Lisp
+ interpreter are not expanded, nor are they expanded by the
+ `macroexpand' function.
+
+ The argument list may begin with a `&whole' keyword and a
+ variable. This variable is bound to the macro-call form itself,
+ i.e., to a list of the form `(NAME ARGS...)'. If the macro
+ expander returns this form unchanged, then the compiler treats it
+ as a normal function call. This allows compiler macros to work as
+ optimizers for special cases of a function, leaving complicated
+ cases alone.
+
+ For example, here is a simplified version of a definition that
+ appears as a standard part of this package:
+
+ (define-compiler-macro member* (&whole form a list &rest keys)
+ (if (and (null keys)
+ (eq (car-safe a) 'quote)
+ (not (floatp-safe (cadr a))))
+ (list 'memq a list)
+ form))
+
+ This definition causes `(member* A LIST)' to change to a call to
+ the faster `memq' in the common case where A is a
+ non-floating-point constant; if A is anything else, or if there
+ are any keyword arguments in the call, then the original `member*'
+ call is left intact. (The actual compiler macro for `member*'
+ optimizes a number of other cases, including common `:test'
+ predicates.)
+
+ - Function: compiler-macroexpand FORM
+ This function is analogous to `macroexpand', except that it
+ expands compiler macros rather than regular macros. It returns
+ FORM unchanged if it is not a call to a function for which a
+ compiler macro has been defined, or if that compiler macro decided
+ to punt by returning its `&whole' argument. Like `macroexpand',
+ it expands repeatedly until it reaches a form for which no further
+ expansion is possible.
+
+ *Note Macro Bindings::, for descriptions of the `macrolet' and
+`symbol-macrolet' forms for making "local" macro definitions.
+
+\1f
+File: cl.info, Node: Declarations, Next: Symbols, Prev: Macros, Up: Top
+
+Declarations
+************
+
+Common Lisp includes a complex and powerful "declaration" mechanism
+that allows you to give the compiler special hints about the types of
+data that will be stored in particular variables, and about the ways
+those variables and functions will be used. This package defines
+versions of all the Common Lisp declaration forms: `declare',
+`locally', `proclaim', `declaim', and `the'.
+
+ Most of the Common Lisp declarations are not currently useful in
+Emacs Lisp, as the byte-code system provides little opportunity to
+benefit from type information, and `special' declarations are redundant
+in a fully dynamically-scoped Lisp. A few declarations are meaningful
+when the optimizing Emacs 19 byte compiler is being used, however.
+Under the earlier non-optimizing compiler, these declarations will
+effectively be ignored.
+
+ - Function: proclaim DECL-SPEC
+ This function records a "global" declaration specified by
+ DECL-SPEC. Since `proclaim' is a function, DECL-SPEC is evaluated
+ and thus should normally be quoted.
+
+ - Special Form: declaim DECL-SPECS...
+ This macro is like `proclaim', except that it takes any number of
+ DECL-SPEC arguments, and the arguments are unevaluated and
+ unquoted. The `declaim' macro also puts an `(eval-when (compile
+ load eval) ...)' around the declarations so that they will be
+ registered at compile-time as well as at run-time. (This is vital,
+ since normally the declarations are meant to influence the way the
+ compiler treats the rest of the file that contains the `declaim'
+ form.)
+
+ - Special Form: declare DECL-SPECS...
+ This macro is used to make declarations within functions and other
+ code. Common Lisp allows declarations in various locations,
+ generally at the beginning of any of the many "implicit `progn's"
+ throughout Lisp syntax, such as function bodies, `let' bodies,
+ etc. Currently the only declaration understood by `declare' is
+ `special'.
+
+ - Special Form: locally DECLARATIONS... FORMS...
+ In this package, `locally' is no different from `progn'.
+
+ - Special Form: the TYPE FORM
+ Type information provided by `the' is ignored in this package; in
+ other words, `(the TYPE FORM)' is equivalent to FORM. Future
+ versions of the optimizing byte-compiler may make use of this
+ information.
+
+ For example, `mapcar' can map over both lists and arrays. It is
+ hard for the compiler to expand `mapcar' into an in-line loop
+ unless it knows whether the sequence will be a list or an array
+ ahead of time. With `(mapcar 'car (the vector foo))', a future
+ compiler would have enough information to expand the loop in-line.
+ For now, Emacs Lisp will treat the above code as exactly equivalent
+ to `(mapcar 'car foo)'.
+
+ Each DECL-SPEC in a `proclaim', `declaim', or `declare' should be a
+list beginning with a symbol that says what kind of declaration it is.
+This package currently understands `special', `inline', `notinline',
+`optimize', and `warn' declarations. (The `warn' declaration is an
+extension of standard Common Lisp.) Other Common Lisp declarations,
+such as `type' and `ftype', are silently ignored.
+
+`special'
+ Since all variables in Emacs Lisp are "special" (in the Common
+ Lisp sense), `special' declarations are only advisory. They
+ simply tell the optimizing byte compiler that the specified
+ variables are intentionally being referred to without being bound
+ in the body of the function. The compiler normally emits warnings
+ for such references, since they could be typographical errors for
+ references to local variables.
+
+ The declaration `(declare (special VAR1 VAR2))' is equivalent to
+ `(defvar VAR1) (defvar VAR2)' in the optimizing compiler, or to
+ nothing at all in older compilers (which do not warn for non-local
+ references).
+
+ In top-level contexts, it is generally better to write `(defvar
+ VAR)' than `(declaim (special VAR))', since `defvar' makes your
+ intentions clearer. But the older byte compilers can not handle
+ `defvar's appearing inside of functions, while `(declare (special
+ VAR))' takes care to work correctly with all compilers.
+
+`inline'
+ The `inline' DECL-SPEC lists one or more functions whose bodies
+ should be expanded "in-line" into calling functions whenever the
+ compiler is able to arrange for it. For example, the Common Lisp
+ function `cadr' is declared `inline' by this package so that the
+ form `(cadr X)' will expand directly into `(car (cdr X))' when it
+ is called in user functions, for a savings of one (relatively
+ expensive) function call.
+
+ The following declarations are all equivalent. Note that the
+ `defsubst' form is a convenient way to define a function and
+ declare it inline all at once, but it is available only in Emacs
+ 19.
+
+ (declaim (inline foo bar))
+ (eval-when (compile load eval) (proclaim '(inline foo bar)))
+ (proclaim-inline foo bar) ; XEmacs only
+ (defsubst foo (...) ...) ; instead of defun; Emacs 19 only
+
+ *Please note:* This declaration remains in effect after the
+ containing source file is done. It is correct to use it to
+ request that a function you have defined should be inlined, but it
+ is impolite to use it to request inlining of an external function.
+
+ In Common Lisp, it is possible to use `(declare (inline ...))'
+ before a particular call to a function to cause just that call to
+ be inlined; the current byte compilers provide no way to implement
+ this, so `(declare (inline ...))' is currently ignored by this
+ package.
+
+`notinline'
+ The `notinline' declaration lists functions which should not be
+ inlined after all; it cancels a previous `inline' declaration.
+
+`optimize'
+ This declaration controls how much optimization is performed by
+ the compiler. Naturally, it is ignored by the earlier
+ non-optimizing compilers.
+
+ The word `optimize' is followed by any number of lists like
+ `(speed 3)' or `(safety 2)'. Common Lisp defines several
+ optimization "qualities"; this package ignores all but `speed' and
+ `safety'. The value of a quality should be an integer from 0 to
+ 3, with 0 meaning "unimportant" and 3 meaning "very important."
+ The default level for both qualities is 1.
+
+ In this package, with the Emacs 19 optimizing compiler, the
+ `speed' quality is tied to the `byte-compile-optimize' flag, which
+ is set to `nil' for `(speed 0)' and to `t' for higher settings;
+ and the `safety' quality is tied to the
+ `byte-compile-delete-errors' flag, which is set to `t' for
+ `(safety 3)' and to `nil' for all lower settings. (The latter
+ flag controls whether the compiler is allowed to optimize out code
+ whose only side-effect could be to signal an error, e.g.,
+ rewriting `(progn foo bar)' to `bar' when it is not known whether
+ `foo' will be bound at run-time.)
+
+ Note that even compiling with `(safety 0)', the Emacs byte-code
+ system provides sufficient checking to prevent real harm from
+ being done. For example, barring serious bugs in Emacs itself,
+ Emacs will not crash with a segmentation fault just because of an
+ error in a fully-optimized Lisp program.
+
+ The `optimize' declaration is normally used in a top-level
+ `proclaim' or `declaim' in a file; Common Lisp allows it to be
+ used with `declare' to set the level of optimization locally for a
+ given form, but this will not work correctly with the current
+ version of the optimizing compiler. (The `declare' will set the
+ new optimization level, but that level will not automatically be
+ unset after the enclosing form is done.)
+
+`warn'
+ This declaration controls what sorts of warnings are generated by
+ the byte compiler. Again, only the optimizing compiler generates
+ warnings. The word `warn' is followed by any number of "warning
+ qualities," similar in form to optimization qualities. The
+ currently supported warning types are `redefine', `callargs',
+ `unresolved', and `free-vars'; in the current system, a value of 0
+ will disable these warnings and any higher value will enable them.
+ See the documentation for the optimizing byte compiler for details.
+
+\1f
+File: cl.info, Node: Symbols, Next: Numbers, Prev: Declarations, Up: Top
+
+Symbols
+*******
+
+This package defines several symbol-related features that were missing
+from Emacs Lisp.
+
+* Menu:
+
+* Property Lists:: `get*', `remprop', `getf', `remf'
+* Creating Symbols:: `gensym', `gentemp'
+
+\1f
+File: cl.info, Node: Property Lists, Next: Creating Symbols, Prev: Symbols, Up: Symbols
+
+Property Lists
+==============
+
+These functions augment the standard Emacs Lisp functions `get' and
+`put' for operating on properties attached to symbols. There are also
+functions for working with property lists as first-class data
+structures not attached to particular symbols.
+
+ - Function: get* SYMBOL PROPERTY &optional DEFAULT
+ This function is like `get', except that if the property is not
+ found, the DEFAULT argument provides the return value. (The Emacs
+ Lisp `get' function always uses `nil' as the default; this
+ package's `get*' is equivalent to Common Lisp's `get'.)
+
+ The `get*' function is `setf'-able; when used in this fashion, the
+ DEFAULT argument is allowed but ignored.
+
+ - Function: remprop SYMBOL PROPERTY
+ This function removes the entry for PROPERTY from the property
+ list of SYMBOL. It returns a true value if the property was
+ indeed found and removed, or `nil' if there was no such property.
+ (This function was probably omitted from Emacs originally because,
+ since `get' did not allow a DEFAULT, it was very difficult to
+ distinguish between a missing property and a property whose value
+ was `nil'; thus, setting a property to `nil' was close enough to
+ `remprop' for most purposes.)
+
+ - Function: getf PLACE PROPERTY &optional DEFAULT
+ This function scans the list PLACE as if it were a property list,
+ i.e., a list of alternating property names and values. If an
+ even-numbered element of PLACE is found which is `eq' to PROPERTY,
+ the following odd-numbered element is returned. Otherwise,
+ DEFAULT is returned (or `nil' if no default is given).
+
+ In particular,
+
+ (get sym prop) == (getf (symbol-plist sym) prop)
+
+ It is legal to use `getf' as a `setf' place, in which case its
+ PLACE argument must itself be a legal `setf' place. The DEFAULT
+ argument, if any, is ignored in this context. The effect is to
+ change (via `setcar') the value cell in the list that corresponds
+ to PROPERTY, or to cons a new property-value pair onto the list if
+ the property is not yet present.
+
+ (put sym prop val) == (setf (getf (symbol-plist sym) prop) val)
+
+ The `get' and `get*' functions are also `setf'-able. The fact
+ that `default' is ignored can sometimes be useful:
+
+ (incf (get* 'foo 'usage-count 0))
+
+ Here, symbol `foo''s `usage-count' property is incremented if it
+ exists, or set to 1 (an incremented 0) otherwise.
+
+ When not used as a `setf' form, `getf' is just a regular function
+ and its PLACE argument can actually be any Lisp expression.
+
+ - Special Form: remf PLACE PROPERTY
+ This macro removes the property-value pair for PROPERTY from the
+ property list stored at PLACE, which is any `setf'-able place
+ expression. It returns true if the property was found. Note that
+ if PROPERTY happens to be first on the list, this will effectively
+ do a `(setf PLACE (cddr PLACE))', whereas if it occurs later, this
+ simply uses `setcdr' to splice out the property and value cells.
+
+\1f
+File: cl.info, Node: Creating Symbols, Prev: Property Lists, Up: Symbols
+
+Creating Symbols
+================
+
+These functions create unique symbols, typically for use as temporary
+variables.
+
+ - Function: gensym &optional X
+ This function creates a new, uninterned symbol (using
+ `make-symbol') with a unique name. (The name of an uninterned
+ symbol is relevant only if the symbol is printed.) By default,
+ the name is generated from an increasing sequence of numbers,
+ `G1000', `G1001', `G1002', etc. If the optional argument X is a
+ string, that string is used as a prefix instead of `G'.
+ Uninterned symbols are used in macro expansions for temporary
+ variables, to ensure that their names will not conflict with
+ "real" variables in the user's code.
+
+ - Variable: *gensym-counter*
+ This variable holds the counter used to generate `gensym' names.
+ It is incremented after each use by `gensym'. In Common Lisp this
+ is initialized with 0, but this package initializes it with a
+ random (time-dependent) value to avoid trouble when two files that
+ each used `gensym' in their compilation are loaded together.
+
+ *XEmacs note:* As of XEmacs 21.0, an uninterned symbol remains
+ uninterned even after being dumped to bytecode. Older versions of
+ Emacs didn't distinguish the printed representation of interned
+ and uninterned symbols, so their names had to be treated more
+ carefully.
+
+ - Function: gentemp &optional X
+ This function is like `gensym', except that it produces a new
+ *interned* symbol. If the symbol that is generated already
+ exists, the function keeps incrementing the counter and trying
+ again until a new symbol is generated.
+
+ The Quiroz `cl.el' package also defined a `defkeyword' form for
+creating self-quoting keyword symbols. This package automatically
+creates all keywords that are called for by `&key' argument specifiers,
+and discourages the use of keywords as data unrelated to keyword
+arguments, so the `defkeyword' form has been discontinued.
+
+\1f
+File: cl.info, Node: Numbers, Next: Sequences, Prev: Symbols, Up: Top
+
+Numbers
+*******
+
+This section defines a few simple Common Lisp operations on numbers
+which were left out of Emacs Lisp.
+
+* Menu:
+
+* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
+* Numerical Functions:: `abs', `expt', `floor*', etc.
+* Random Numbers:: `random*', `make-random-state'
+* Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
+
+\1f
+File: cl.info, Node: Predicates on Numbers, Next: Numerical Functions, Prev: Numbers, Up: Numbers
+
+Predicates on Numbers
+=====================
+
+These functions return `t' if the specified condition is true of the
+numerical argument, or `nil' otherwise.
+
+ - Function: plusp NUMBER
+ This predicate tests whether NUMBER is positive. It is an error
+ if the argument is not a number.
+
+ - Function: minusp NUMBER
+ This predicate tests whether NUMBER is negative. It is an error
+ if the argument is not a number.
+
+ - Function: oddp INTEGER
+ This predicate tests whether INTEGER is odd. It is an error if
+ the argument is not an integer.
+
+ - Function: evenp INTEGER
+ This predicate tests whether INTEGER is even. It is an error if
+ the argument is not an integer.
+
+ - Function: floatp-safe OBJECT
+ This predicate tests whether OBJECT is a floating-point number.
+ On systems that support floating-point, this is equivalent to
+ `floatp'. On other systems, this always returns `nil'.
+
+\1f
+File: cl.info, Node: Numerical Functions, Next: Random Numbers, Prev: Predicates on Numbers, Up: Numbers
+
+Numerical Functions
+===================
+
+These functions perform various arithmetic operations on numbers.
+
+ - Function: abs NUMBER
+ This function returns the absolute value of NUMBER. (Newer
+ versions of Emacs provide this as a built-in function; this package
+ defines `abs' only for Emacs 18 versions which don't provide it as
+ a primitive.)
+
+ - Function: expt BASE POWER
+ This function returns BASE raised to the power of NUMBER. (Newer
+ versions of Emacs provide this as a built-in function; this
+ package defines `expt' only for Emacs 18 versions which don't
+ provide it as a primitive.)
+
+ - Function: gcd &rest INTEGERS
+ This function returns the Greatest Common Divisor of the arguments.
+ For one argument, it returns the absolute value of that argument.
+ For zero arguments, it returns zero.
+
+ - Function: lcm &rest INTEGERS
+ This function returns the Least Common Multiple of the arguments.
+ For one argument, it returns the absolute value of that argument.
+ For zero arguments, it returns one.
+
+ - Function: isqrt INTEGER
+ This function computes the "integer square root" of its integer
+ argument, i.e., the greatest integer less than or equal to the true
+ square root of the argument.
+
+ - Function: floor* NUMBER &optional DIVISOR
+ This function implements the Common Lisp `floor' function. It is
+ called `floor*' to avoid name conflicts with the simpler `floor'
+ function built-in to Emacs 19.
+
+ With one argument, `floor*' returns a list of two numbers: The
+ argument rounded down (toward minus infinity) to an integer, and
+ the "remainder" which would have to be added back to the first
+ return value to yield the argument again. If the argument is an
+ integer X, the result is always the list `(X 0)'. If the argument
+ is an Emacs 19 floating-point number, the first result is a Lisp
+ integer and the second is a Lisp float between 0 (inclusive) and 1
+ (exclusive).
+
+ With two arguments, `floor*' divides NUMBER by DIVISOR, and
+ returns the floor of the quotient and the corresponding remainder
+ as a list of two numbers. If `(floor* X Y)' returns `(Q R)', then
+ `Q*Y + R = X', with R between 0 (inclusive) and R (exclusive).
+ Also, note that `(floor* X)' is exactly equivalent to `(floor* X
+ 1)'.
+
+ This function is entirely compatible with Common Lisp's `floor'
+ function, except that it returns the two results in a list since
+ Emacs Lisp does not support multiple-valued functions.
+
+ - Function: ceiling* NUMBER &optional DIVISOR
+ This function implements the Common Lisp `ceiling' function, which
+ is analogous to `floor' except that it rounds the argument or
+ quotient of the arguments up toward plus infinity. The remainder
+ will be between 0 and minus R.
+
+ - Function: truncate* NUMBER &optional DIVISOR
+ This function implements the Common Lisp `truncate' function,
+ which is analogous to `floor' except that it rounds the argument
+ or quotient of the arguments toward zero. Thus it is equivalent
+ to `floor*' if the argument or quotient is positive, or to
+ `ceiling*' otherwise. The remainder has the same sign as NUMBER.
+
+ - Function: round* NUMBER &optional DIVISOR
+ This function implements the Common Lisp `round' function, which
+ is analogous to `floor' except that it rounds the argument or
+ quotient of the arguments to the nearest integer. In the case of
+ a tie (the argument or quotient is exactly halfway between two
+ integers), it rounds to the even integer.
+
+ - Function: mod* NUMBER DIVISOR
+ This function returns the same value as the second return value of
+ `floor'.
+
+ - Function: rem* NUMBER DIVISOR
+ This function returns the same value as the second return value of
+ `truncate'.
+
+ These definitions are compatible with those in the Quiroz `cl.el'
+package, except that this package appends `*' to certain function names
+to avoid conflicts with existing Emacs 19 functions, and that the
+mechanism for returning multiple values is different.
+
+\1f
+File: cl.info, Node: Random Numbers, Next: Implementation Parameters, Prev: Numerical Functions, Up: Numbers
+
+Random Numbers
+==============
+
+This package also provides an implementation of the Common Lisp random
+number generator. It uses its own additive-congruential algorithm,
+which is much more likely to give statistically clean random numbers
+than the simple generators supplied by many operating systems.
+
+ - Function: random* NUMBER &optional STATE
+ This function returns a random nonnegative number less than
+ NUMBER, and of the same type (either integer or floating-point).
+ The STATE argument should be a `random-state' object which holds
+ the state of the random number generator. The function modifies
+ this state object as a side effect. If STATE is omitted, it
+ defaults to the variable `*random-state*', which contains a
+ pre-initialized `random-state' object.
+
+ - Variable: *random-state*
+ This variable contains the system "default" `random-state' object,
+ used for calls to `random*' that do not specify an alternative
+ state object. Since any number of programs in the Emacs process
+ may be accessing `*random-state*' in interleaved fashion, the
+ sequence generated from this variable will be irreproducible for
+ all intents and purposes.
+
+ - Function: make-random-state &optional STATE
+ This function creates or copies a `random-state' object. If STATE
+ is omitted or `nil', it returns a new copy of `*random-state*'.
+ This is a copy in the sense that future sequences of calls to
+ `(random* N)' and `(random* N S)' (where S is the new random-state
+ object) will return identical sequences of random numbers.
+
+ If STATE is a `random-state' object, this function returns a copy
+ of that object. If STATE is `t', this function returns a new
+ `random-state' object seeded from the date and time. As an
+ extension to Common Lisp, STATE may also be an integer in which
+ case the new object is seeded from that integer; each different
+ integer seed will result in a completely different sequence of
+ random numbers.
+
+ It is legal to print a `random-state' object to a buffer or file
+ and later read it back with `read'. If a program wishes to use a
+ sequence of pseudo-random numbers which can be reproduced later
+ for debugging, it can call `(make-random-state t)' to get a new
+ sequence, then print this sequence to a file. When the program is
+ later rerun, it can read the original run's random-state from the
+ file.
+
+ - Function: random-state-p OBJECT
+ This predicate returns `t' if OBJECT is a `random-state' object,
+ or `nil' otherwise.
+
--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+File: cl.info, Node: Implementation Parameters, Prev: Random Numbers, Up: Numbers
+
+Implementation Parameters
+=========================
+
+This package defines several useful constants having to with numbers.
+
+ - Variable: most-positive-fixnum
+ This constant equals the largest value a Lisp integer can hold.
+ It is typically `2^23-1' or `2^25-1'.
+
+ - Variable: most-negative-fixnum
+ This constant equals the smallest (most negative) value a Lisp
+ integer can hold.
+
+ The following parameters have to do with floating-point numbers.
+This package determines their values by exercising the computer's
+floating-point arithmetic in various ways. Because this operation
+might be slow, the code for initializing them is kept in a separate
+function that must be called before the parameters can be used.
+
+ - Function: cl-float-limits
+ This function makes sure that the Common Lisp floating-point
+ parameters like `most-positive-float' have been initialized.
+ Until it is called, these parameters will be `nil'. If this
+ version of Emacs does not support floats (e.g., most versions of
+ Emacs 18), the parameters will remain `nil'. If the parameters
+ have already been initialized, the function returns immediately.
+
+ The algorithm makes assumptions that will be valid for most modern
+ machines, but will fail if the machine's arithmetic is extremely
+ unusual, e.g., decimal.
+
+ Since true Common Lisp supports up to four different floating-point
+precisions, it has families of constants like
+`most-positive-single-float', `most-positive-double-float',
+`most-positive-long-float', and so on. Emacs has only one
+floating-point precision, so this package omits the precision word from
+the constants' names.
+
+ - Variable: most-positive-float
+ This constant equals the largest value a Lisp float can hold. For
+ those systems whose arithmetic supports infinities, this is the
+ largest *finite* value. For IEEE machines, the value is
+ approximately `1.79e+308'.
+
+ - Variable: most-negative-float
+ This constant equals the most-negative value a Lisp float can hold.
+ (It is assumed to be equal to `(- most-positive-float)'.)
+
+ - Variable: least-positive-float
+ This constant equals the smallest Lisp float value greater than
+ zero. For IEEE machines, it is about `4.94e-324' if denormals are
+ supported or `2.22e-308' if not.
+
+ - Variable: least-positive-normalized-float
+ This constant equals the smallest *normalized* Lisp float greater
+ than zero, i.e., the smallest value for which IEEE denormalization
+ will not result in a loss of precision. For IEEE machines, this
+ value is about `2.22e-308'. For machines that do not support the
+ concept of denormalization and gradual underflow, this constant
+ will always equal `least-positive-float'.
+
+ - Variable: least-negative-float
+ This constant is the negative counterpart of
+ `least-positive-float'.
+
+ - Variable: least-negative-normalized-float
+ This constant is the negative counterpart of
+ `least-positive-normalized-float'.
+
+ - Variable: float-epsilon
+ This constant is the smallest positive Lisp float that can be added
+ to 1.0 to produce a distinct value. Adding a smaller number to 1.0
+ will yield 1.0 again due to roundoff. For IEEE machines, epsilon
+ is about `2.22e-16'.
+
+ - Variable: float-negative-epsilon
+ This is the smallest positive value that can be subtracted from
+ 1.0 to produce a distinct value. For IEEE machines, it is about
+ `1.11e-16'.
+
+\1f
+File: cl.info, Node: Sequences, Next: Lists, Prev: Numbers, Up: Top
+
+Sequences
+*********
+
+Common Lisp defines a number of functions that operate on "sequences",
+which are either lists, strings, or vectors. Emacs Lisp includes a few
+of these, notably `elt' and `length'; this package defines most of the
+rest.
+
+* Menu:
+
+* Sequence Basics:: Arguments shared by all sequence functions
+* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc.
+* Sequence Functions:: `subseq', `remove*', `substitute', etc.
+* Searching Sequences:: `find', `position', `count', `search', etc.
+* Sorting Sequences:: `sort*', `stable-sort', `merge'
+
+\1f
+File: cl.info, Node: Sequence Basics, Next: Mapping over Sequences, Prev: Sequences, Up: Sequences
+
+Sequence Basics
+===============
+
+Many of the sequence functions take keyword arguments; *note Argument
+Lists::.. All keyword arguments are optional and, if specified, may
+appear in any order.
+
+ The `:key' argument should be passed either `nil', or a function of
+one argument. This key function is used as a filter through which the
+elements of the sequence are seen; for example, `(find x y :key 'car)'
+is similar to `(assoc* x y)': It searches for an element of the list
+whose `car' equals `x', rather than for an element which equals `x'
+itself. If `:key' is omitted or `nil', the filter is effectively the
+identity function.
+
+ The `:test' and `:test-not' arguments should be either `nil', or
+functions of two arguments. The test function is used to compare two
+sequence elements, or to compare a search value with sequence elements.
+(The two values are passed to the test function in the same order as
+the original sequence function arguments from which they are derived,
+or, if they both come from the same sequence, in the same order as they
+appear in that sequence.) The `:test' argument specifies a function
+which must return true (non-`nil') to indicate a match; instead, you
+may use `:test-not' to give a function which returns *false* to
+indicate a match. The default test function is `:test 'eql'.
+
+ Many functions which take ITEM and `:test' or `:test-not' arguments
+also come in `-if' and `-if-not' varieties, where a PREDICATE function
+is passed instead of ITEM, and sequence elements match if the predicate
+returns true on them (or false in the case of `-if-not'). For example:
+
+ (remove* 0 seq :test '=) == (remove-if 'zerop seq)
+
+to remove all zeros from sequence `seq'.
+
+ Some operations can work on a subsequence of the argument sequence;
+these function take `:start' and `:end' arguments which default to zero
+and the length of the sequence, respectively. Only elements between
+START (inclusive) and END (exclusive) are affected by the operation.
+The END argument may be passed `nil' to signify the length of the
+sequence; otherwise, both START and END must be integers, with `0 <=
+START <= END <= (length SEQ)'. If the function takes two sequence
+arguments, the limits are defined by keywords `:start1' and `:end1' for
+the first, and `:start2' and `:end2' for the second.
+
+ A few functions accept a `:from-end' argument, which, if non-`nil',
+causes the operation to go from right-to-left through the sequence
+instead of left-to-right, and a `:count' argument, which specifies an
+integer maximum number of elements to be removed or otherwise processed.
+
+ The sequence functions make no guarantees about the order in which
+the `:test', `:test-not', and `:key' functions are called on various
+elements. Therefore, it is a bad idea to depend on side effects of
+these functions. For example, `:from-end' may cause the sequence to be
+scanned actually in reverse, or it may be scanned forwards but
+computing a result "as if" it were scanned backwards. (Some functions,
+like `mapcar*' and `every', *do* specify exactly the order in which the
+function is called so side effects are perfectly acceptable in those
+cases.)
+
+ Strings in GNU Emacs 19 may contain "text properties" as well as
+character data. Except as noted, it is undefined whether or not text
+properties are preserved by sequence functions. For example, `(remove*
+?A STR)' may or may not preserve the properties of the characters
+copied from STR into the result.
+
+\1f
+File: cl.info, Node: Mapping over Sequences, Next: Sequence Functions, Prev: Sequence Basics, Up: Sequences
+
+Mapping over Sequences
+======================
+
+These functions "map" the function you specify over the elements of
+lists or arrays. They are all variations on the theme of the built-in
+function `mapcar'.
+
+ - Function: mapcar* FUNCTION SEQ &rest MORE-SEQS
+ This function calls FUNCTION on successive parallel sets of
+ elements from its argument sequences. Given a single SEQ argument
+ it is equivalent to `mapcar'; given N sequences, it calls the
+ function with the first elements of each of the sequences as the N
+ arguments to yield the first element of the result list, then with
+ the second elements, and so on. The mapping stops as soon as the
+ shortest sequence runs out. The argument sequences may be any
+ mixture of lists, strings, and vectors; the return sequence is
+ always a list.
+
+ Common Lisp's `mapcar' accepts multiple arguments but works only
+ on lists; Emacs Lisp's `mapcar' accepts a single sequence
+ argument. This package's `mapcar*' works as a compatible superset
+ of both.
+
+ - Function: map RESULT-TYPE FUNCTION SEQ &rest MORE-SEQS
+ This function maps FUNCTION over the argument sequences, just like
+ `mapcar*', but it returns a sequence of type RESULT-TYPE rather
+ than a list. RESULT-TYPE must be one of the following symbols:
+ `vector', `string', `list' (in which case the effect is the same
+ as for `mapcar*'), or `nil' (in which case the results are thrown
+ away and `map' returns `nil').
+
+ - Function: maplist FUNCTION LIST &rest MORE-LISTS
+ This function calls FUNCTION on each of its argument lists, then
+ on the `cdr's of those lists, and so on, until the shortest list
+ runs out. The results are returned in the form of a list. Thus,
+ `maplist' is like `mapcar*' except that it passes in the list
+ pointers themselves rather than the `car's of the advancing
+ pointers.
+
+ - Function: mapc FUNCTION SEQ &rest MORE-SEQS
+ This function is like `mapcar*', except that the values returned
+ by FUNCTION are ignored and thrown away rather than being
+ collected into a list. The return value of `mapc' is SEQ, the
+ first sequence.
+
+ - Function: mapl FUNCTION LIST &rest MORE-LISTS
+ This function is like `maplist', except that it throws away the
+ values returned by FUNCTION.
+
+ - Function: mapcan FUNCTION SEQ &rest MORE-SEQS
+ This function is like `mapcar*', except that it concatenates the
+ return values (which must be lists) using `nconc', rather than
+ simply collecting them into a list.
+
+ - Function: mapcon FUNCTION LIST &rest MORE-LISTS
+ This function is like `maplist', except that it concatenates the
+ return values using `nconc'.
+
+ - Function: some PREDICATE SEQ &rest MORE-SEQS
+ This function calls PREDICATE on each element of SEQ in turn; if
+ PREDICATE returns a non-`nil' value, `some' returns that value,
+ otherwise it returns `nil'. Given several sequence arguments, it
+ steps through the sequences in parallel until the shortest one
+ runs out, just as in `mapcar*'. You can rely on the left-to-right
+ order in which the elements are visited, and on the fact that
+ mapping stops immediately as soon as PREDICATE returns non-`nil'.
+
+ - Function: every PREDICATE SEQ &rest MORE-SEQS
+ This function calls PREDICATE on each element of the sequence(s)
+ in turn; it returns `nil' as soon as PREDICATE returns `nil' for
+ any element, or `t' if the predicate was true for all elements.
+
+ - Function: notany PREDICATE SEQ &rest MORE-SEQS
+ This function calls PREDICATE on each element of the sequence(s)
+ in turn; it returns `nil' as soon as PREDICATE returns a non-`nil'
+ value for any element, or `t' if the predicate was `nil' for all
+ elements.
+
+ - Function: notevery PREDICATE SEQ &rest MORE-SEQS
+ This function calls PREDICATE on each element of the sequence(s)
+ in turn; it returns a non-`nil' value as soon as PREDICATE returns
+ `nil' for any element, or `t' if the predicate was true for all
+ elements.
+
+ - Function: reduce FUNCTION SEQ &key :from-end :start :end
+ :initial-value :key
+ This function combines the elements of SEQ using an associative
+ binary operation. Suppose FUNCTION is `*' and SEQ is the list `(2
+ 3 4 5)'. The first two elements of the list are combined with `(*
+ 2 3) = 6'; this is combined with the next element, `(* 6 4) = 24',
+ and that is combined with the final element: `(* 24 5) = 120'.
+ Note that the `*' function happens to be self-reducing, so that
+ `(* 2 3 4 5)' has the same effect as an explicit call to `reduce'.
+
+ If `:from-end' is true, the reduction is right-associative instead
+ of left-associative:
+
+ (reduce '- '(1 2 3 4))
+ == (- (- (- 1 2) 3) 4) => -8
+ (reduce '- '(1 2 3 4) :from-end t)
+ == (- 1 (- 2 (- 3 4))) => -2
+
+ If `:key' is specified, it is a function of one argument which is
+ called on each of the sequence elements in turn.
+
+ If `:initial-value' is specified, it is effectively added to the
+ front (or rear in the case of `:from-end') of the sequence. The
+ `:key' function is *not* applied to the initial value.
+
+ If the sequence, including the initial value, has exactly one
+ element then that element is returned without ever calling
+ FUNCTION. If the sequence is empty (and there is no initial
+ value), then FUNCTION is called with no arguments to obtain the
+ return value.
+
+ All of these mapping operations can be expressed conveniently in
+terms of the `loop' macro. In compiled code, `loop' will be faster
+since it generates the loop as in-line code with no function calls.
+
+\1f
+File: cl.info, Node: Sequence Functions, Next: Searching Sequences, Prev: Mapping over Sequences, Up: Sequences
+
+Sequence Functions
+==================
+
+This section describes a number of Common Lisp functions for operating
+on sequences.
+
+ - Function: subseq SEQUENCE START &optional END
+ This function returns a given subsequence of the argument
+ SEQUENCE, which may be a list, string, or vector. The indices
+ START and END must be in range, and START must be no greater than
+ END. If END is omitted, it defaults to the length of the
+ sequence. The return value is always a copy; it does not share
+ structure with SEQUENCE.
+
+ As an extension to Common Lisp, START and/or END may be negative,
+ in which case they represent a distance back from the end of the
+ sequence. This is for compatibility with Emacs' `substring'
+ function. Note that `subseq' is the *only* sequence function that
+ allows negative START and END.
+
+ You can use `setf' on a `subseq' form to replace a specified range
+ of elements with elements from another sequence. The replacement
+ is done as if by `replace', described below.
+
+ - Function: concatenate RESULT-TYPE &rest SEQS
+ This function concatenates the argument sequences together to form
+ a result sequence of type RESULT-TYPE, one of the symbols
+ `vector', `string', or `list'. The arguments are always copied,
+ even in cases such as `(concatenate 'list '(1 2 3))' where the
+ result is identical to an argument.
+
+ - Function: fill SEQ ITEM &key :start :end
+ This function fills the elements of the sequence (or the specified
+ part of the sequence) with the value ITEM.
+
+ - Function: replace SEQ1 SEQ2 &key :start1 :end1 :start2 :end2
+ This function copies part of SEQ2 into part of SEQ1. The sequence
+ SEQ1 is not stretched or resized; the amount of data copied is
+ simply the shorter of the source and destination (sub)sequences.
+ The function returns SEQ1.
+
+ If SEQ1 and SEQ2 are `eq', then the replacement will work
+ correctly even if the regions indicated by the start and end
+ arguments overlap. However, if SEQ1 and SEQ2 are lists which
+ share storage but are not `eq', and the start and end arguments
+ specify overlapping regions, the effect is undefined.
+
+ - Function: remove* ITEM SEQ &key :test :test-not :key :count :start
+ :end :from-end
+ This returns a copy of SEQ with all elements matching ITEM
+ removed. The result may share storage with or be `eq' to SEQ in
+ some circumstances, but the original SEQ will not be modified.
+ The `:test', `:test-not', and `:key' arguments define the matching
+ test that is used; by default, elements `eql' to ITEM are removed.
+ The `:count' argument specifies the maximum number of matching
+ elements that can be removed (only the leftmost COUNT matches are
+ removed). The `:start' and `:end' arguments specify a region in
+ SEQ in which elements will be removed; elements outside that
+ region are not matched or removed. The `:from-end' argument, if
+ true, says that elements should be deleted from the end of the
+ sequence rather than the beginning (this matters only if COUNT was
+ also specified).
+
+ - Function: delete* ITEM SEQ &key :test :test-not :key :count :start
+ :end :from-end
+ This deletes all elements of SEQ which match ITEM. It is a
+ destructive operation. Since Emacs Lisp does not support
+ stretchable strings or vectors, this is the same as `remove*' for
+ those sequence types. On lists, `remove*' will copy the list if
+ necessary to preserve the original list, whereas `delete*' will
+ splice out parts of the argument list. Compare `append' and
+ `nconc', which are analogous non-destructive and destructive list
+ operations in Emacs Lisp.
+
+ The predicate-oriented functions `remove-if', `remove-if-not',
+`delete-if', and `delete-if-not' are defined similarly.
+
+ - Function: delete ITEM LIST
+ This MacLisp-compatible function deletes from LIST all elements
+ which are `equal' to ITEM. The `delete' function is built-in to
+ Emacs 19; this package defines it equivalently in Emacs 18.
+
+ - Function: remove ITEM LIST
+ This function removes from LIST all elements which are `equal' to
+ ITEM. This package defines it for symmetry with `delete', even
+ though `remove' is not built-in to Emacs 19.
+
+ - Function: remq ITEM LIST
+ This function removes from LIST all elements which are `eq' to
+ ITEM. This package defines it for symmetry with `delq', even
+ though `remq' is not built-in to Emacs 19.
+
+ - Function: remove-duplicates SEQ &key :test :test-not :key :start
+ :end :from-end
+ This function returns a copy of SEQ with duplicate elements
+ removed. Specifically, if two elements from the sequence match
+ according to the `:test', `:test-not', and `:key' arguments, only
+ the rightmost one is retained. If `:from-end' is true, the
+ leftmost one is retained instead. If `:start' or `:end' is
+ specified, only elements within that subsequence are examined or
+ removed.
+
+ - Function: delete-duplicates SEQ &key :test :test-not :key :start
+ :end :from-end
+ This function deletes duplicate elements from SEQ. It is a
+ destructive version of `remove-duplicates'.
+
+ - Function: substitute NEW OLD SEQ &key :test :test-not :key :count
+ :start :end :from-end
+ This function returns a copy of SEQ, with all elements matching
+ OLD replaced with NEW. The `:count', `:start', `:end', and
+ `:from-end' arguments may be used to limit the number of
+ substitutions made.
+
+ - Function: nsubstitute NEW OLD SEQ &key :test :test-not :key :count
+ :start :end :from-end
+ This is a destructive version of `substitute'; it performs the
+ substitution using `setcar' or `aset' rather than by returning a
+ changed copy of the sequence.
+
+ The `substitute-if', `substitute-if-not', `nsubstitute-if', and
+`nsubstitute-if-not' functions are defined similarly. For these, a
+PREDICATE is given in place of the OLD argument.
+
+\1f
+File: cl.info, Node: Searching Sequences, Next: Sorting Sequences, Prev: Sequence Functions, Up: Sequences
+
+Searching Sequences
+===================
+
+These functions search for elements or subsequences in a sequence.
+(See also `member*' and `assoc*'; *note Lists::..)
+
+ - Function: find ITEM SEQ &key :test :test-not :key :start :end
+ :from-end
+ This function searches SEQ for an element matching ITEM. If it
+ finds a match, it returns the matching element. Otherwise, it
+ returns `nil'. It returns the leftmost match, unless `:from-end'
+ is true, in which case it returns the rightmost match. The
+ `:start' and `:end' arguments may be used to limit the range of
+ elements that are searched.
+
+ - Function: position ITEM SEQ &key :test :test-not :key :start :end
+ :from-end
+ This function is like `find', except that it returns the integer
+ position in the sequence of the matching item rather than the item
+ itself. The position is relative to the start of the sequence as
+ a whole, even if `:start' is non-zero. The function returns `nil'
+ if no matching element was found.
+
+ - Function: count ITEM SEQ &key :test :test-not :key :start :end
+ This function returns the number of elements of SEQ which match
+ ITEM. The result is always a nonnegative integer.
+
+ The `find-if', `find-if-not', `position-if', `position-if-not',
+`count-if', and `count-if-not' functions are defined similarly.
+
+ - Function: mismatch SEQ1 SEQ2 &key :test :test-not :key :start1 :end1
+ :start2 :end2 :from-end
+ This function compares the specified parts of SEQ1 and SEQ2. If
+ they are the same length and the corresponding elements match
+ (according to `:test', `:test-not', and `:key'), the function
+ returns `nil'. If there is a mismatch, the function returns the
+ index (relative to SEQ1) of the first mismatching element. This
+ will be the leftmost pair of elements which do not match, or the
+ position at which the shorter of the two otherwise-matching
+ sequences runs out.
+
+ If `:from-end' is true, then the elements are compared from right
+ to left starting at `(1- END1)' and `(1- END2)'. If the sequences
+ differ, then one plus the index of the rightmost difference
+ (relative to SEQ1) is returned.
+
+ An interesting example is `(mismatch str1 str2 :key 'upcase)',
+ which compares two strings case-insensitively.
+
+ - Function: search SEQ1 SEQ2 &key :test :test-not :key :from-end
+ :start1 :end1 :start2 :end2
+ This function searches SEQ2 for a subsequence that matches SEQ1
+ (or part of it specified by `:start1' and `:end1'.) Only matches
+ which fall entirely within the region defined by `:start2' and
+ `:end2' will be considered. The return value is the index of the
+ leftmost element of the leftmost match, relative to the start of
+ SEQ2, or `nil' if no matches were found. If `:from-end' is true,
+ the function finds the *rightmost* matching subsequence.
+
+\1f
+File: cl.info, Node: Sorting Sequences, Prev: Searching Sequences, Up: Sequences
+
+Sorting Sequences
+=================
+
+ - Function: sort* SEQ PREDICATE &key :key
+ This function sorts SEQ into increasing order as determined by
+ using PREDICATE to compare pairs of elements. PREDICATE should
+ return true (non-`nil') if and only if its first argument is less
+ than (not equal to) its second argument. For example, `<' and
+ `string-lessp' are suitable predicate functions for sorting
+ numbers and strings, respectively; `>' would sort numbers into
+ decreasing rather than increasing order.
+
+ This function differs from Emacs' built-in `sort' in that it can
+ operate on any type of sequence, not just lists. Also, it accepts
+ a `:key' argument which is used to preprocess data fed to the
+ PREDICATE function. For example,
+
+ (setq data (sort data 'string-lessp :key 'downcase))
+
+ sorts DATA, a sequence of strings, into increasing alphabetical
+ order without regard to case. A `:key' function of `car' would be
+ useful for sorting association lists.
+
+ The `sort*' function is destructive; it sorts lists by actually
+ rearranging the `cdr' pointers in suitable fashion.
+
+ - Function: stable-sort SEQ PREDICATE &key :key
+ This function sorts SEQ "stably", meaning two elements which are
+ equal in terms of PREDICATE are guaranteed not to be rearranged
+ out of their original order by the sort.
+
+ In practice, `sort*' and `stable-sort' are equivalent in Emacs
+ Lisp because the underlying `sort' function is stable by default.
+ However, this package reserves the right to use non-stable methods
+ for `sort*' in the future.
+
+ - Function: merge TYPE SEQ1 SEQ2 PREDICATE &key :key
+ This function merges two sequences SEQ1 and SEQ2 by interleaving
+ their elements. The result sequence, of type TYPE (in the sense
+ of `concatenate'), has length equal to the sum of the lengths of
+ the two input sequences. The sequences may be modified
+ destructively. Order of elements within SEQ1 and SEQ2 is
+ preserved in the interleaving; elements of the two sequences are
+ compared by PREDICATE (in the sense of `sort') and the lesser
+ element goes first in the result. When elements are equal, those
+ from SEQ1 precede those from SEQ2 in the result. Thus, if SEQ1
+ and SEQ2 are both sorted according to PREDICATE, then the result
+ will be a merged sequence which is (stably) sorted according to
+ PREDICATE.
+
+\1f
+File: cl.info, Node: Lists, Next: Hash Tables, Prev: Sequences, Up: Top
+
+Lists
+*****
+
+The functions described here operate on lists.
+
+* Menu:
+
+* List Functions:: `caddr', `first', `last', `list*', etc.
+* Substitution of Expressions:: `subst', `sublis', etc.
+* Lists as Sets:: `member*', `adjoin', `union', etc.
+* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
+
+\1f
+File: cl.info, Node: List Functions, Next: Substitution of Expressions, Prev: Lists, Up: Lists
+
+List Functions
+==============
+
+This section describes a number of simple operations on lists, i.e.,
+chains of cons cells.
+
+ - Function: caddr X
+ This function is equivalent to `(car (cdr (cdr X)))'. Likewise,
+ this package defines all 28 `cXXXr' functions where XXX is up to
+ four `a's and/or `d's. All of these functions are `setf'-able,
+ and calls to them are expanded inline by the byte-compiler for
+ maximum efficiency.
+
+ - Function: first X
+ This function is a synonym for `(car X)'. Likewise, the functions
+ `second', `third', ..., through `tenth' return the given element
+ of the list X.
+
+ - Function: rest X
+ This function is a synonym for `(cdr X)'.
+
+ - Function: endp X
+ Common Lisp defines this function to act like `null', but
+ signalling an error if `x' is neither a `nil' nor a cons cell.
+ This package simply defines `endp' as a synonym for `null'.
+
+ - Function: list-length X
+ This function returns the length of list X, exactly like `(length
+ X)', except that if X is a circular list (where the cdr-chain
+ forms a loop rather than terminating with `nil'), this function
+ returns `nil'. (The regular `length' function would get stuck if
+ given a circular list.)
+
+ - Function: last X &optional N
+ This function returns the last cons, or the Nth-to-last cons, of
+ the list X. If N is omitted it defaults to 1. The "last cons"
+ means the first cons cell of the list whose `cdr' is not another
+ cons cell. (For normal lists, the `cdr' of the last cons will be
+ `nil'.) This function returns `nil' if X is `nil' or shorter than
+ N. Note that the last *element* of the list is `(car (last X))'.
+
+ - Function: butlast X &optional N
+ This function returns the list X with the last element, or the
+ last N elements, removed. If N is greater than zero it makes a
+ copy of the list so as not to damage the original list. In
+ general, `(append (butlast X N) (last X N))' will return a list
+ equal to X.
+
+ - Function: nbutlast X &optional N
+ This is a version of `butlast' that works by destructively
+ modifying the `cdr' of the appropriate element, rather than making
+ a copy of the list.
+
+ - Function: list* ARG &rest OTHERS
+ This function constructs a list of its arguments. The final
+ argument becomes the `cdr' of the last cell constructed. Thus,
+ `(list* A B C)' is equivalent to `(cons A (cons B C))', and
+ `(list* A B nil)' is equivalent to `(list A B)'.
+
+ (Note that this function really is called `list*' in Common Lisp;
+ it is not a name invented for this package like `member*' or
+ `defun*'.)
+
+ - Function: ldiff LIST SUBLIST
+ If SUBLIST is a sublist of LIST, i.e., is `eq' to one of the cons
+ cells of LIST, then this function returns a copy of the part of
+ LIST up to but not including SUBLIST. For example, `(ldiff x
+ (cddr x))' returns the first two elements of the list `x'. The
+ result is a copy; the original LIST is not modified. If SUBLIST
+ is not a sublist of LIST, a copy of the entire LIST is returned.
+
+ - Function: copy-list LIST
+ This function returns a copy of the list LIST. It copies dotted
+ lists like `(1 2 . 3)' correctly.
+
+ - Function: copy-tree X &optional VECP
+ This function returns a copy of the tree of cons cells X. Unlike
+ `copy-sequence' (and its alias `copy-list'), which copies only
+ along the `cdr' direction, this function copies (recursively)
+ along both the `car' and the `cdr' directions. If X is not a cons
+ cell, the function simply returns X unchanged. If the optional
+ VECP argument is true, this function copies vectors (recursively)
+ as well as cons cells.
+
+ - Function: tree-equal X Y &key :test :test-not :key
+ This function compares two trees of cons cells. If X and Y are
+ both cons cells, their `car's and `cdr's are compared recursively.
+ If neither X nor Y is a cons cell, they are compared by `eql', or
+ according to the specified test. The `:key' function, if
+ specified, is applied to the elements of both trees. *Note
+ Sequences::.
+
+\1f
+File: cl.info, Node: Substitution of Expressions, Next: Lists as Sets, Prev: List Functions, Up: Lists
+
+Substitution of Expressions
+===========================
+
+These functions substitute elements throughout a tree of cons cells.
+(*Note Sequence Functions::, for the `substitute' function, which works
+on just the top-level elements of a list.)
+
+ - Function: subst NEW OLD TREE &key :test :test-not :key
+ This function substitutes occurrences of OLD with NEW in TREE, a
+ tree of cons cells. It returns a substituted tree, which will be
+ a copy except that it may share storage with the argument TREE in
+ parts where no substitutions occurred. The original TREE is not
+ modified. This function recurses on, and compares against OLD,
+ both `car's and `cdr's of the component cons cells. If OLD is
+ itself a cons cell, then matching cells in the tree are
+ substituted as usual without recursively substituting in that
+ cell. Comparisons with OLD are done according to the specified
+ test (`eql' by default). The `:key' function is applied to the
+ elements of the tree but not to OLD.
+
+ - Function: nsubst NEW OLD TREE &key :test :test-not :key
+ This function is like `subst', except that it works by destructive
+ modification (by `setcar' or `setcdr') rather than copying.
+
+ The `subst-if', `subst-if-not', `nsubst-if', and `nsubst-if-not'
+functions are defined similarly.
+
+ - Function: sublis ALIST TREE &key :test :test-not :key
+ This function is like `subst', except that it takes an association
+ list ALIST of OLD-NEW pairs. Each element of the tree (after
+ applying the `:key' function, if any), is compared with the `car's
+ of ALIST; if it matches, it is replaced by the corresponding `cdr'.
+
+ - Function: nsublis ALIST TREE &key :test :test-not :key
+ This is a destructive version of `sublis'.
+
+\1f
+File: cl.info, Node: Lists as Sets, Next: Association Lists, Prev: Substitution of Expressions, Up: Lists
+
+Lists as Sets
+=============
+
+These functions perform operations on lists which represent sets of
+elements.
+
+ - Function: member ITEM LIST
+ This MacLisp-compatible function searches LIST for an element
+ which is `equal' to ITEM. The `member' function is built-in to
+ Emacs 19; this package defines it equivalently in Emacs 18. See
+ the following function for a Common-Lisp compatible version.
+
+ - Function: member* ITEM LIST &key :test :test-not :key
+ This function searches LIST for an element matching ITEM. If a
+ match is found, it returns the cons cell whose `car' was the
+ matching element. Otherwise, it returns `nil'. Elements are
+ compared by `eql' by default; you can use the `:test',
+ `:test-not', and `:key' arguments to modify this behavior. *Note
+ Sequences::.
+
+ Note that this function's name is suffixed by `*' to avoid the
+ incompatible `member' function defined in Emacs 19. (That
+ function uses `equal' for comparisons; it is equivalent to
+ `(member* ITEM LIST :test 'equal)'.)
+
+ The `member-if' and `member-if-not' functions analogously search for
+elements which satisfy a given predicate.
+
+ - Function: tailp SUBLIST LIST
+ This function returns `t' if SUBLIST is a sublist of LIST, i.e.,
+ if SUBLIST is `eql' to LIST or to any of its `cdr's.
+
+ - Function: adjoin ITEM LIST &key :test :test-not :key
+ This function conses ITEM onto the front of LIST, like `(cons ITEM
+ LIST)', but only if ITEM is not already present on the list (as
+ determined by `member*'). If a `:key' argument is specified, it
+ is applied to ITEM as well as to the elements of LIST during the
+ search, on the reasoning that ITEM is "about" to become part of
+ the list.
+
+ - Function: union LIST1 LIST2 &key :test :test-not :key
+ This function combines two lists which represent sets of items,
+ returning a list that represents the union of those two sets. The
+ result list will contain all items which appear in LIST1 or LIST2,
+ and no others. If an item appears in both LIST1 and LIST2 it will
+ be copied only once. If an item is duplicated in LIST1 or LIST2,
+ it is undefined whether or not that duplication will survive in the
+ result list. The order of elements in the result list is also
+ undefined.
+
+ - Function: nunion LIST1 LIST2 &key :test :test-not :key
+ This is a destructive version of `union'; rather than copying, it
+ tries to reuse the storage of the argument lists if possible.
+
+ - Function: intersection LIST1 LIST2 &key :test :test-not :key
+ This function computes the intersection of the sets represented by
+ LIST1 and LIST2. It returns the list of items which appear in
+ both LIST1 and LIST2.
+
+ - Function: nintersection LIST1 LIST2 &key :test :test-not :key
+ This is a destructive version of `intersection'. It tries to
+ reuse storage of LIST1 rather than copying. It does *not* reuse
+ the storage of LIST2.
+
+ - Function: set-difference LIST1 LIST2 &key :test :test-not :key
+ This function computes the "set difference" of LIST1 and LIST2,
+ i.e., the set of elements that appear in LIST1 but *not* in LIST2.
+
+ - Function: nset-difference LIST1 LIST2 &key :test :test-not :key
+ This is a destructive `set-difference', which will try to reuse
+ LIST1 if possible.
+
+ - Function: set-exclusive-or LIST1 LIST2 &key :test :test-not :key
+ This function computes the "set exclusive or" of LIST1 and LIST2,
+ i.e., the set of elements that appear in exactly one of LIST1 and
+ LIST2.
+
+ - Function: nset-exclusive-or LIST1 LIST2 &key :test :test-not :key
+ This is a destructive `set-exclusive-or', which will try to reuse
+ LIST1 and LIST2 if possible.
+
+ - Function: subsetp LIST1 LIST2 &key :test :test-not :key
+ This function checks whether LIST1 represents a subset of LIST2,
+ i.e., whether every element of LIST1 also appears in LIST2.
+
+\1f
+File: cl.info, Node: Association Lists, Prev: Lists as Sets, Up: Lists
+
+Association Lists
+=================
+
+An "association list" is a list representing a mapping from one set of
+values to another; any list whose elements are cons cells is an
+association list.
+
+ - Function: assoc* ITEM A-LIST &key :test :test-not :key
+ This function searches the association list A-LIST for an element
+ whose `car' matches (in the sense of `:test', `:test-not', and
+ `:key', or by comparison with `eql') a given ITEM. It returns the
+ matching element, if any, otherwise `nil'. It ignores elements of
+ A-LIST which are not cons cells. (This corresponds to the
+ behavior of `assq' and `assoc' in Emacs Lisp; Common Lisp's
+ `assoc' ignores `nil's but considers any other non-cons elements
+ of A-LIST to be an error.)
+
+ - Function: rassoc* ITEM A-LIST &key :test :test-not :key
+ This function searches for an element whose `cdr' matches ITEM.
+ If A-LIST represents a mapping, this applies the inverse of the
+ mapping to ITEM.
+
+ - Function: rassoc ITEM A-LIST
+ This function searches like `rassoc*' with a `:test' argument of
+ `equal'. It is analogous to Emacs Lisp's standard `assoc'
+ function, which derives from the MacLisp rather than the Common
+ Lisp tradition.
+
+ The `assoc-if', `assoc-if-not', `rassoc-if', and `rassoc-if-not'
+functions are defined similarly.
+
+ Two simple functions for constructing association lists are:
+
+ - Function: acons KEY VALUE ALIST
+ This is equivalent to `(cons (cons KEY VALUE) ALIST)'.
+
+ - Function: pairlis KEYS VALUES &optional ALIST
+ This is equivalent to `(nconc (mapcar* 'cons KEYS VALUES) ALIST)'.
+
+\1f
+File: cl.info, Node: Hash Tables, Next: Structures, Prev: Lists, Up: Top
+
+Hash Tables
+***********
+
+Hash tables are now implemented directly in the C code and documented in
+*Note Hash Tables: (lispref)Hash Tables.
+
--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+File: cl.info, Node: Structures, Next: Assertions, Prev: Hash Tables, Up: Top
+
+Structures
+**********
+
+The Common Lisp "structure" mechanism provides a general way to define
+data types similar to C's `struct' types. A structure is a Lisp object
+containing some number of "slots", each of which can hold any Lisp data
+object. Functions are provided for accessing and setting the slots,
+creating or copying structure objects, and recognizing objects of a
+particular structure type.
+
+ In true Common Lisp, each structure type is a new type distinct from
+all existing Lisp types. Since the underlying Emacs Lisp system
+provides no way to create new distinct types, this package implements
+structures as vectors (or lists upon request) with a special "tag"
+symbol to identify them.
+
+ - Special Form: defstruct NAME SLOTS...
+ The `defstruct' form defines a new structure type called NAME,
+ with the specified SLOTS. (The SLOTS may begin with a string
+ which documents the structure type.) In the simplest case, NAME
+ and each of the SLOTS are symbols. For example,
+
+ (defstruct person name age sex)
+
+ defines a struct type called `person' which contains three slots.
+ Given a `person' object P, you can access those slots by calling
+ `(person-name P)', `(person-age P)', and `(person-sex P)'. You
+ can also change these slots by using `setf' on any of these place
+ forms:
+
+ (incf (person-age birthday-boy))
+
+ You can create a new `person' by calling `make-person', which
+ takes keyword arguments `:name', `:age', and `:sex' to specify the
+ initial values of these slots in the new object. (Omitting any of
+ these arguments leaves the corresponding slot "undefined,"
+ according to the Common Lisp standard; in Emacs Lisp, such
+ uninitialized slots are filled with `nil'.)
+
+ Given a `person', `(copy-person P)' makes a new object of the same
+ type whose slots are `eq' to those of P.
+
+ Given any Lisp object X, `(person-p X)' returns true if X looks
+ like a `person', false otherwise. (Again, in Common Lisp this
+ predicate would be exact; in Emacs Lisp the best it can do is
+ verify that X is a vector of the correct length which starts with
+ the correct tag symbol.)
+
+ Accessors like `person-name' normally check their arguments
+ (effectively using `person-p') and signal an error if the argument
+ is the wrong type. This check is affected by `(optimize (safety
+ ...))' declarations. Safety level 1, the default, uses a somewhat
+ optimized check that will detect all incorrect arguments, but may
+ use an uninformative error message (e.g., "expected a vector"
+ instead of "expected a `person'"). Safety level 0 omits all
+ checks except as provided by the underlying `aref' call; safety
+ levels 2 and 3 do rigorous checking that will always print a
+ descriptive error message for incorrect inputs. *Note
+ Declarations::.
+
+ (setq dave (make-person :name "Dave" :sex 'male))
+ => [cl-struct-person "Dave" nil male]
+ (setq other (copy-person dave))
+ => [cl-struct-person "Dave" nil male]
+ (eq dave other)
+ => nil
+ (eq (person-name dave) (person-name other))
+ => t
+ (person-p dave)
+ => t
+ (person-p [1 2 3 4])
+ => nil
+ (person-p "Bogus")
+ => nil
+ (person-p '[cl-struct-person counterfeit person object])
+ => t
+
+ In general, NAME is either a name symbol or a list of a name
+ symbol followed by any number of "struct options"; each SLOT is
+ either a slot symbol or a list of the form `(SLOT-NAME
+ DEFAULT-VALUE SLOT-OPTIONS...)'. The DEFAULT-VALUE is a Lisp form
+ which is evaluated any time an instance of the structure type is
+ created without specifying that slot's value.
+
+ Common Lisp defines several slot options, but the only one
+ implemented in this package is `:read-only'. A non-`nil' value
+ for this option means the slot should not be `setf'-able; the
+ slot's value is determined when the object is created and does not
+ change afterward.
+
+ (defstruct person
+ (name nil :read-only t)
+ age
+ (sex 'unknown))
+
+ Any slot options other than `:read-only' are ignored.
+
+ For obscure historical reasons, structure options take a different
+ form than slot options. A structure option is either a keyword
+ symbol, or a list beginning with a keyword symbol possibly followed
+ by arguments. (By contrast, slot options are key-value pairs not
+ enclosed in lists.)
+
+ (defstruct (person (:constructor create-person)
+ (:type list)
+ :named)
+ name age sex)
+
+ The following structure options are recognized.
+
+ `:conc-name'
+ The argument is a symbol whose print name is used as the
+ prefix for the names of slot accessor functions. The default
+ is the name of the struct type followed by a hyphen. The
+ option `(:conc-name p-)' would change this prefix to `p-'.
+ Specifying `nil' as an argument means no prefix, so that the
+ slot names themselves are used to name the accessor functions.
+
+ `:constructor'
+ In the simple case, this option takes one argument which is an
+ alternate name to use for the constructor function. The
+ default is `make-NAME', e.g., `make-person'. The above
+ example changes this to `create-person'. Specifying `nil' as
+ an argument means that no standard constructor should be
+ generated at all.
+
+ In the full form of this option, the constructor name is
+ followed by an arbitrary argument list. *Note Program
+ Structure::, for a description of the format of Common Lisp
+ argument lists. All options, such as `&rest' and `&key', are
+ supported. The argument names should match the slot names;
+ each slot is initialized from the corresponding argument.
+ Slots whose names do not appear in the argument list are
+ initialized based on the DEFAULT-VALUE in their slot
+ descriptor. Also, `&optional' and `&key' arguments which
+ don't specify defaults take their defaults from the slot
+ descriptor. It is legal to include arguments which don't
+ correspond to slot names; these are useful if they are
+ referred to in the defaults for optional, keyword, or `&aux'
+ arguments which *do* correspond to slots.
+
+ You can specify any number of full-format `:constructor'
+ options on a structure. The default constructor is still
+ generated as well unless you disable it with a simple-format
+ `:constructor' option.
+
+ (defstruct
+ (person
+ (:constructor nil) ; no default constructor
+ (:constructor new-person (name sex &optional (age 0)))
+ (:constructor new-hound (&key (name "Rover")
+ (dog-years 0)
+ &aux (age (* 7 dog-years))
+ (sex 'canine))))
+ name age sex)
+
+ The first constructor here takes its arguments positionally
+ rather than by keyword. (In official Common Lisp
+ terminology, constructors that work By Order of Arguments
+ instead of by keyword are called "BOA constructors." No, I'm
+ not making this up.) For example, `(new-person "Jane"
+ 'female)' generates a person whose slots are `"Jane"', 0, and
+ `female', respectively.
+
+ The second constructor takes two keyword arguments, `:name',
+ which initializes the `name' slot and defaults to `"Rover"',
+ and `:dog-years', which does not itself correspond to a slot
+ but which is used to initialize the `age' slot. The `sex'
+ slot is forced to the symbol `canine' with no syntax for
+ overriding it.
+
+ `:copier'
+ The argument is an alternate name for the copier function for
+ this type. The default is `copy-NAME'. `nil' means not to
+ generate a copier function. (In this implementation, all
+ copier functions are simply synonyms for `copy-sequence'.)
+
+ `:predicate'
+ The argument is an alternate name for the predicate which
+ recognizes objects of this type. The default is `NAME-p'.
+ `nil' means not to generate a predicate function. (If the
+ `:type' option is used without the `:named' option, no
+ predicate is ever generated.)
+
+ In true Common Lisp, `typep' is always able to recognize a
+ structure object even if `:predicate' was used. In this
+ package, `typep' simply looks for a function called
+ `TYPENAME-p', so it will work for structure types only if
+ they used the default predicate name.
+
+ `:include'
+ This option implements a very limited form of C++-style
+ inheritance. The argument is the name of another structure
+ type previously created with `defstruct'. The effect is to
+ cause the new structure type to inherit all of the included
+ structure's slots (plus, of course, any new slots described
+ by this struct's slot descriptors). The new structure is
+ considered a "specialization" of the included one. In fact,
+ the predicate and slot accessors for the included type will
+ also accept objects of the new type.
+
+ If there are extra arguments to the `:include' option after
+ the included-structure name, these options are treated as
+ replacement slot descriptors for slots in the included
+ structure, possibly with modified default values. Borrowing
+ an example from Steele:
+
+ (defstruct person name (age 0) sex)
+ => person
+ (defstruct (astronaut (:include person (age 45)))
+ helmet-size
+ (favorite-beverage 'tang))
+ => astronaut
+
+ (setq joe (make-person :name "Joe"))
+ => [cl-struct-person "Joe" 0 nil]
+ (setq buzz (make-astronaut :name "Buzz"))
+ => [cl-struct-astronaut "Buzz" 45 nil nil tang]
+
+ (list (person-p joe) (person-p buzz))
+ => (t t)
+ (list (astronaut-p joe) (astronaut-p buzz))
+ => (nil t)
+
+ (person-name buzz)
+ => "Buzz"
+ (astronaut-name joe)
+ => error: "astronaut-name accessing a non-astronaut"
+
+ Thus, if `astronaut' is a specialization of `person', then
+ every `astronaut' is also a `person' (but not the other way
+ around). Every `astronaut' includes all the slots of a
+ `person', plus extra slots that are specific to astronauts.
+ Operations that work on people (like `person-name') work on
+ astronauts just like other people.
+
+ `:print-function'
+ In full Common Lisp, this option allows you to specify a
+ function which is called to print an instance of the
+ structure type. The Emacs Lisp system offers no hooks into
+ the Lisp printer which would allow for such a feature, so
+ this package simply ignores `:print-function'.
+
+ `:type'
+ The argument should be one of the symbols `vector' or `list'.
+ This tells which underlying Lisp data type should be used to
+ implement the new structure type. Vectors are used by
+ default, but `(:type list)' will cause structure objects to
+ be stored as lists instead.
+
+ The vector representation for structure objects has the
+ advantage that all structure slots can be accessed quickly,
+ although creating vectors is a bit slower in Emacs Lisp.
+ Lists are easier to create, but take a relatively long time
+ accessing the later slots.
+
+ `:named'
+ This option, which takes no arguments, causes a
+ characteristic "tag" symbol to be stored at the front of the
+ structure object. Using `:type' without also using `:named'
+ will result in a structure type stored as plain vectors or
+ lists with no identifying features.
+
+ The default, if you don't specify `:type' explicitly, is to
+ use named vectors. Therefore, `:named' is only useful in
+ conjunction with `:type'.
+
+ (defstruct (person1) name age sex)
+ (defstruct (person2 (:type list) :named) name age sex)
+ (defstruct (person3 (:type list)) name age sex)
+
+ (setq p1 (make-person1))
+ => [cl-struct-person1 nil nil nil]
+ (setq p2 (make-person2))
+ => (person2 nil nil nil)
+ (setq p3 (make-person3))
+ => (nil nil nil)
+
+ (person1-p p1)
+ => t
+ (person2-p p2)
+ => t
+ (person3-p p3)
+ => error: function person3-p undefined
+
+ Since unnamed structures don't have tags, `defstruct' is not
+ able to make a useful predicate for recognizing them. Also,
+ accessors like `person3-name' will be generated but they will
+ not be able to do any type checking. The `person3-name'
+ function, for example, will simply be a synonym for `car' in
+ this case. By contrast, `person2-name' is able to verify
+ that its argument is indeed a `person2' object before
+ proceeding.
+
+ `:initial-offset'
+ The argument must be a nonnegative integer. It specifies a
+ number of slots to be left "empty" at the front of the
+ structure. If the structure is named, the tag appears at the
+ specified position in the list or vector; otherwise, the first
+ slot appears at that position. Earlier positions are filled
+ with `nil' by the constructors and ignored otherwise. If the
+ type `:include's another type, then `:initial-offset'
+ specifies a number of slots to be skipped between the last
+ slot of the included type and the first new slot.
+
+ Except as noted, the `defstruct' facility of this package is
+entirely compatible with that of Common Lisp.
+
+\1f
+File: cl.info, Node: Assertions, Next: Efficiency Concerns, Prev: Structures, Up: Top
+
+Assertions and Errors
+*********************
+
+This section describes two macros that test "assertions", i.e.,
+conditions which must be true if the program is operating correctly.
+Assertions never add to the behavior of a Lisp program; they simply
+make "sanity checks" to make sure everything is as it should be.
+
+ If the optimization property `speed' has been set to 3, and `safety'
+is less than 3, then the byte-compiler will optimize away the following
+assertions. Because assertions might be optimized away, it is a bad
+idea for them to include side-effects.
+
+ - Special Form: assert TEST-FORM [SHOW-ARGS STRING ARGS...]
+ This form verifies that TEST-FORM is true (i.e., evaluates to a
+ non-`nil' value). If so, it returns `nil'. If the test is not
+ satisfied, `assert' signals an error.
+
+ A default error message will be supplied which includes TEST-FORM.
+ You can specify a different error message by including a STRING
+ argument plus optional extra arguments. Those arguments are simply
+ passed to `error' to signal the error.
+
+ If the optional second argument SHOW-ARGS is `t' instead of `nil',
+ then the error message (with or without STRING) will also include
+ all non-constant arguments of the top-level FORM. For example:
+
+ (assert (> x 10) t "x is too small: %d")
+
+ This usage of SHOW-ARGS is an extension to Common Lisp. In true
+ Common Lisp, the second argument gives a list of PLACES which can
+ be `setf''d by the user before continuing from the error. Since
+ Emacs Lisp does not support continuable errors, it makes no sense
+ to specify PLACES.
+
+ - Special Form: check-type FORM TYPE [STRING]
+ This form verifies that FORM evaluates to a value of type TYPE.
+ If so, it returns `nil'. If not, `check-type' signals a
+ `wrong-type-argument' error. The default error message lists the
+ erroneous value along with TYPE and FORM themselves. If STRING is
+ specified, it is included in the error message in place of TYPE.
+ For example:
+
+ (check-type x (integer 1 *) "a positive integer")
+
+ *Note Type Predicates::, for a description of the type specifiers
+ that may be used for TYPE.
+
+ Note that in Common Lisp, the first argument to `check-type' must
+ be a PLACE suitable for use by `setf', because `check-type'
+ signals a continuable error that allows the user to modify PLACE.
+
+ The following error-related macro is also defined:
+
+ - Special Form: ignore-errors FORMS...
+ This executes FORMS exactly like a `progn', except that errors are
+ ignored during the FORMS. More precisely, if an error is
+ signalled then `ignore-errors' immediately aborts execution of the
+ FORMS and returns `nil'. If the FORMS complete successfully,
+ `ignore-errors' returns the result of the last FORM.
+
+\1f
+File: cl.info, Node: Efficiency Concerns, Next: Common Lisp Compatibility, Prev: Assertions, Up: Top
+
+Efficiency Concerns
+*******************
+
+Macros
+======
+
+Many of the advanced features of this package, such as `defun*',
+`loop', and `setf', are implemented as Lisp macros. In byte-compiled
+code, these complex notations will be expanded into equivalent Lisp
+code which is simple and efficient. For example, the forms
+
+ (incf i n)
+ (push x (car p))
+
+are expanded at compile-time to the Lisp forms
+
+ (setq i (+ i n))
+ (setcar p (cons x (car p)))
+
+which are the most efficient ways of doing these respective operations
+in Lisp. Thus, there is no performance penalty for using the more
+readable `incf' and `push' forms in your compiled code.
+
+ *Interpreted* code, on the other hand, must expand these macros
+every time they are executed. For this reason it is strongly
+recommended that code making heavy use of macros be compiled. (The
+features labelled "Special Form" instead of "Function" in this manual
+are macros.) A loop using `incf' a hundred times will execute
+considerably faster if compiled, and will also garbage-collect less
+because the macro expansion will not have to be generated, used, and
+thrown away a hundred times.
+
+ You can find out how a macro expands by using the `cl-prettyexpand'
+function.
+
+ - Function: cl-prettyexpand FORM &optional FULL
+ This function takes a single Lisp form as an argument and inserts
+ a nicely formatted copy of it in the current buffer (which must be
+ in Lisp mode so that indentation works properly). It also expands
+ all Lisp macros which appear in the form. The easiest way to use
+ this function is to go to the `*scratch*' buffer and type, say,
+
+ (cl-prettyexpand '(loop for x below 10 collect x))
+
+ and type `C-x C-e' immediately after the closing parenthesis; the
+ expansion
+
+ (block nil
+ (let* ((x 0)
+ (G1004 nil))
+ (while (< x 10)
+ (setq G1004 (cons x G1004))
+ (setq x (+ x 1)))
+ (nreverse G1004)))
+
+ will be inserted into the buffer. (The `block' macro is expanded
+ differently in the interpreter and compiler, so `cl-prettyexpand'
+ just leaves it alone. The temporary variable `G1004' was created
+ by `gensym'.)
+
+ If the optional argument FULL is true, then *all* macros are
+ expanded, including `block', `eval-when', and compiler macros.
+ Expansion is done as if FORM were a top-level form in a file being
+ compiled. For example,
+
+ (cl-prettyexpand '(pushnew 'x list))
+ -| (setq list (adjoin 'x list))
+ (cl-prettyexpand '(pushnew 'x list) t)
+ -| (setq list (if (memq 'x list) list (cons 'x list)))
+ (cl-prettyexpand '(caddr (member* 'a list)) t)
+ -| (car (cdr (cdr (memq 'a list))))
+
+ Note that `adjoin', `caddr', and `member*' all have built-in
+ compiler macros to optimize them in common cases.
+
+
+Error Checking
+==============
+
+Common Lisp compliance has in general not been sacrificed for the sake
+of efficiency. A few exceptions have been made for cases where
+substantial gains were possible at the expense of marginal
+incompatibility. One example is the use of `memq' (which is treated
+very efficiently by the byte-compiler) to scan for keyword arguments;
+this can become confused in rare cases when keyword symbols are used as
+both keywords and data values at once. This is extremely unlikely to
+occur in practical code, and the use of `memq' allows functions with
+keyword arguments to be nearly as fast as functions that use
+`&optional' arguments.
+
+ The Common Lisp standard (as embodied in Steele's book) uses the
+phrase "it is an error if" to indicate a situation which is not
+supposed to arise in complying programs; implementations are strongly
+encouraged but not required to signal an error in these situations.
+This package sometimes omits such error checking in the interest of
+compactness and efficiency. For example, `do' variable specifiers are
+supposed to be lists of one, two, or three forms; extra forms are
+ignored by this package rather than signalling a syntax error. The
+`endp' function is simply a synonym for `null' in this package.
+Functions taking keyword arguments will accept an odd number of
+arguments, treating the trailing keyword as if it were followed by the
+value `nil'.
+
+ Argument lists (as processed by `defun*' and friends) *are* checked
+rigorously except for the minor point just mentioned; in particular,
+keyword arguments are checked for validity, and `&allow-other-keys' and
+`:allow-other-keys' are fully implemented. Keyword validity checking
+is slightly time consuming (though not too bad in byte-compiled code);
+you can use `&allow-other-keys' to omit this check. Functions defined
+in this package such as `find' and `member*' do check their keyword
+arguments for validity.
+
+
+Optimizing Compiler
+===================
+
+The byte-compiler that comes with Emacs 18 normally fails to expand
+macros that appear in top-level positions in the file (i.e., outside of
+`defun's or other enclosing forms). This would have disastrous
+consequences to programs that used such top-level macros as `defun*',
+`eval-when', and `defstruct'. To work around this problem, the "CL"
+package patches the Emacs 18 compiler to expand top-level macros. This
+patch will apply to your own macros, too, if they are used in a
+top-level context. The patch will not harm versions of the Emacs 18
+compiler which have already had a similar patch applied, nor will it
+affect the optimizing Emacs 19 byte-compiler written by Jamie Zawinski
+and Hallvard Furuseth. The patch is applied to the byte compiler's
+code in Emacs' memory, *not* to the `bytecomp.elc' file stored on disk.
+
+ The Emacs 19 compiler (for Emacs 18) is available from various Emacs
+Lisp archive sites such as `archive.cis.ohio-state.edu'. Its use is
+highly recommended; many of the Common Lisp macros emit code which can
+be improved by optimization. In particular, `block's (whether explicit
+or implicit in constructs like `defun*' and `loop') carry a fair
+run-time penalty; the optimizing compiler removes `block's which are
+not actually referenced by `return' or `return-from' inside the block.
+
+\1f
+File: cl.info, Node: Common Lisp Compatibility, Next: Old CL Compatibility, Prev: Efficiency Concerns, Up: Top
+
+Common Lisp Compatibility
+*************************
+
+Following is a list of all known incompatibilities between this package
+and Common Lisp as documented in Steele (2nd edition).
+
+ Certain function names, such as `member', `assoc', and `floor', were
+already taken by (incompatible) Emacs Lisp functions; this package
+appends `*' to the names of its Common Lisp versions of these functions.
+
+ The word `defun*' is required instead of `defun' in order to use
+extended Common Lisp argument lists in a function. Likewise,
+`defmacro*' and `function*' are versions of those forms which
+understand full-featured argument lists. The `&whole' keyword does not
+work in `defmacro' argument lists (except inside recursive argument
+lists).
+
+ In order to allow an efficient implementation, keyword arguments use
+a slightly cheesy parser which may be confused if a keyword symbol is
+passed as the *value* of another keyword argument. (Specifically,
+`(memq :KEYWORD REST-OF-ARGUMENTS)' is used to scan for `:KEYWORD'
+among the supplied keyword arguments.)
+
+ The `eql' and `equal' predicates do not distinguish between IEEE
+floating-point plus and minus zero. The `equalp' predicate has several
+differences with Common Lisp; *note Predicates::..
+
+ The `setf' mechanism is entirely compatible, except that
+setf-methods return a list of five values rather than five values
+directly. Also, the new "`setf' function" concept (typified by `(defun
+(setf foo) ...)') is not implemented.
+
+ The `do-all-symbols' form is the same as `do-symbols' with no
+OBARRAY argument. In Common Lisp, this form would iterate over all
+symbols in all packages. Since Emacs obarrays are not a first-class
+package mechanism, there is no way for `do-all-symbols' to locate any
+but the default obarray.
+
+ The `loop' macro is complete except that `loop-finish' and type
+specifiers are unimplemented.
+
+ The multiple-value return facility treats lists as multiple values,
+since Emacs Lisp cannot support multiple return values directly. The
+macros will be compatible with Common Lisp if `values' or `values-list'
+is always used to return to a `multiple-value-bind' or other
+multiple-value receiver; if `values' is used without
+`multiple-value-...' or vice-versa the effect will be different from
+Common Lisp.
+
+ Many Common Lisp declarations are ignored, and others match the
+Common Lisp standard in concept but not in detail. For example, local
+`special' declarations, which are purely advisory in Emacs Lisp, do not
+rigorously obey the scoping rules set down in Steele's book.
+
+ The variable `*gensym-counter*' starts out with a pseudo-random
+value rather than with zero. This is to cope with the fact that
+generated symbols become interned when they are written to and loaded
+back from a file.
+
+ The `defstruct' facility is compatible, except that structures are
+of type `:type vector :named' by default rather than some special,
+distinct type. Also, the `:type' slot option is ignored.
+
+ The second argument of `check-type' is treated differently.
+
+\1f
+File: cl.info, Node: Old CL Compatibility, Next: Porting Common Lisp, Prev: Common Lisp Compatibility, Up: Top
+
+Old CL Compatibility
+********************
+
+Following is a list of all known incompatibilities between this package
+and the older Quiroz `cl.el' package.
+
+ This package's emulation of multiple return values in functions is
+incompatible with that of the older package. That package attempted to
+come as close as possible to true Common Lisp multiple return values;
+unfortunately, it could not be 100% reliable and so was prone to
+occasional surprises if used freely. This package uses a simpler
+method, namely replacing multiple values with lists of values, which is
+more predictable though more noticeably different from Common Lisp.
+
+ The `defkeyword' form and `keywordp' function are not implemented in
+this package.
+
+ The `member', `floor', `ceiling', `truncate', `round', `mod', and
+`rem' functions are suffixed by `*' in this package to avoid collision
+with existing functions in Emacs 18 or Emacs 19. The older package
+simply redefined these functions, overwriting the built-in meanings and
+causing serious portability problems with Emacs 19. (Some more recent
+versions of the Quiroz package changed the names to `cl-member', etc.;
+this package defines the latter names as aliases for `member*', etc.)
+
+ Certain functions in the old package which were buggy or inconsistent
+with the Common Lisp standard are incompatible with the conforming
+versions in this package. For example, `eql' and `member' were
+synonyms for `eq' and `memq' in that package, `setf' failed to preserve
+correct order of evaluation of its arguments, etc.
+
+ Finally, unlike the older package, this package is careful to prefix
+all of its internal names with `cl-'. Except for a few functions which
+are explicitly defined as additional features (such as `floatp-safe'
+and `letf'), this package does not export any non-`cl-' symbols which
+are not also part of Common Lisp.
+
+
+The `cl-compat' package
+=======================
+
+The "CL" package includes emulations of some features of the old
+`cl.el', in the form of a compatibility package `cl-compat'. To use
+it, put `(require 'cl-compat)' in your program.
+
+ The old package defined a number of internal routines without `cl-'
+prefixes or other annotations. Call to these routines may have crept
+into existing Lisp code. `cl-compat' provides emulations of the
+following internal routines: `pair-with-newsyms', `zip-lists',
+`unzip-lists', `reassemble-arglists', `duplicate-symbols-p',
+`safe-idiv'.
+
+ Some `setf' forms translated into calls to internal functions that
+user code might call directly. The functions `setnth', `setnthcdr',
+and `setelt' fall in this category; they are defined by `cl-compat',
+but the best fix is to change to use `setf' properly.
+
+ The `cl-compat' file defines the keyword functions `keywordp',
+`keyword-of', and `defkeyword', which are not defined by the new "CL"
+package because the use of keywords as data is discouraged.
+
+ The `build-klist' mechanism for parsing keyword arguments is
+emulated by `cl-compat'; the `with-keyword-args' macro is not, however,
+and in any case it's best to change to use the more natural keyword
+argument processing offered by `defun*'.
+
+ Multiple return values are treated differently by the two Common
+Lisp packages. The old package's method was more compatible with true
+Common Lisp, though it used heuristics that caused it to report
+spurious multiple return values in certain cases. The `cl-compat'
+package defines a set of multiple-value macros that are compatible with
+the old CL package; again, they are heuristic in nature, but they are
+guaranteed to work in any case where the old package's macros worked.
+To avoid name collision with the "official" multiple-value facilities,
+the ones in `cl-compat' have capitalized names: `Values',
+`Values-list', `Multiple-value-bind', etc.
+
+ The functions `cl-floor', `cl-ceiling', `cl-truncate', and
+`cl-round' are defined by `cl-compat' to use the old-style
+multiple-value mechanism, just as they did in the old package. The
+newer `floor*' and friends return their two results in a list rather
+than as multiple values. Note that older versions of the old package
+used the unadorned names `floor', `ceiling', etc.; `cl-compat' cannot
+use these names because they conflict with Emacs 19 built-ins.
+
+\1f
+File: cl.info, Node: Porting Common Lisp, Next: Function Index, Prev: Old CL Compatibility, Up: Top
+
+Porting Common Lisp
+*******************
+
+This package is meant to be used as an extension to Emacs Lisp, not as
+an Emacs implementation of true Common Lisp. Some of the remaining
+differences between Emacs Lisp and Common Lisp make it difficult to
+port large Common Lisp applications to Emacs. For one, some of the
+features in this package are not fully compliant with ANSI or Steele;
+*note Common Lisp Compatibility::.. But there are also quite a few
+features that this package does not provide at all. Here are some
+major omissions that you will want watch out for when bringing Common
+Lisp code into Emacs.
+
+ * Case-insensitivity. Symbols in Common Lisp are case-insensitive
+ by default. Some programs refer to a function or variable as
+ `foo' in one place and `Foo' or `FOO' in another. Emacs Lisp will
+ treat these as three distinct symbols.
+
+ Some Common Lisp code is written in all upper-case. While Emacs
+ is happy to let the program's own functions and variables use this
+ convention, calls to Lisp builtins like `if' and `defun' will have
+ to be changed to lower-case.
+
+ * Lexical scoping. In Common Lisp, function arguments and `let'
+ bindings apply only to references physically within their bodies
+ (or within macro expansions in their bodies). Emacs Lisp, by
+ contrast, uses "dynamic scoping" wherein a binding to a variable
+ is visible even inside functions called from the body.
+
+ Variables in Common Lisp can be made dynamically scoped by
+ declaring them `special' or using `defvar'. In Emacs Lisp it is
+ as if all variables were declared `special'.
+
+ Often you can use code that was written for lexical scoping even
+ in a dynamically scoped Lisp, but not always. Here is an example
+ of a Common Lisp code fragment that would fail in Emacs Lisp:
+
+ (defun map-odd-elements (func list)
+ (loop for x in list
+ for flag = t then (not flag)
+ collect (if flag x (funcall func x))))
+
+ (defun add-odd-elements (list x)
+ (map-odd-elements (function (lambda (a) (+ a x))) list))
+
+ In Common Lisp, the two functions' usages of `x' are completely
+ independent. In Emacs Lisp, the binding to `x' made by
+ `add-odd-elements' will have been hidden by the binding in
+ `map-odd-elements' by the time the `(+ a x)' function is called.
+
+ (This package avoids such problems in its own mapping functions by
+ using names like `cl-x' instead of `x' internally; as long as you
+ don't use the `cl-' prefix for your own variables no collision can
+ occur.)
+
+ *Note Lexical Bindings::, for a description of the `lexical-let'
+ form which establishes a Common Lisp-style lexical binding, and
+ some examples of how it differs from Emacs' regular `let'.
+
+ * Common Lisp allows the shorthand `#'x' to stand for `(function
+ x)', just as `'x' stands for `(quote x)'. In Common Lisp, one
+ traditionally uses `#'' notation when referring to the name of a
+ function. In Emacs Lisp, it works just as well to use a regular
+ quote:
+
+ (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp
+ (loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp
+
+ When `#'' introduces a `lambda' form, it is best to write out
+ `(function ...)' longhand in Emacs Lisp. You can use a regular
+ quote, but then the byte-compiler won't know that the `lambda'
+ expression is code that can be compiled.
+
+ (mapcar #'(lambda (x) (* x 2)) list) ; Common Lisp
+ (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp
+
+ XEmacs supports `#'' notation starting with version 19.8.
+
+ * Reader macros. Common Lisp includes a second type of macro that
+ works at the level of individual characters. For example, Common
+ Lisp implements the quote notation by a reader macro called `'',
+ whereas Emacs Lisp's parser just treats quote as a special case.
+ Some Lisp packages use reader macros to create special syntaxes
+ for themselves, which the Emacs parser is incapable of reading.
+
+ * Other syntactic features. Common Lisp provides a number of
+ notations beginning with `#' that the Emacs Lisp parser won't
+ understand. For example, `#| ... |#' is an alternate comment
+ notation, and `#+lucid (foo)' tells the parser to ignore the
+ `(foo)' except in Lucid Common Lisp.
+
+ The number prefixes `#b', `#o', and `#x', however, are supported
+ by the Emacs Lisp parser to represent numbers in binary, octal,
+ and hexadecimal notation (or radix), just like in Common Lisp.
+
+ * Packages. In Common Lisp, symbols are divided into "packages".
+ Symbols that are Lisp built-ins are typically stored in one
+ package; symbols that are vendor extensions are put in another,
+ and each application program would have a package for its own
+ symbols. Certain symbols are "exported" by a package and others
+ are internal; certain packages "use" or import the exported symbols
+ of other packages. To access symbols that would not normally be
+ visible due to this importing and exporting, Common Lisp provides
+ a syntax like `package:symbol' or `package::symbol'.
+
+ Emacs Lisp has a single namespace for all interned symbols, and
+ then uses a naming convention of putting a prefix like `cl-' in
+ front of the name. Some Emacs packages adopt the Common Lisp-like
+ convention of using `cl:' or `cl::' as the prefix. However, the
+ Emacs parser does not understand colons and just treats them as
+ part of the symbol name. Thus, while `mapcar' and `lisp:mapcar'
+ may refer to the same symbol in Common Lisp, they are totally
+ distinct in Emacs Lisp. Common Lisp programs which refer to a
+ symbol by the full name sometimes and the short name other times
+ will not port cleanly to Emacs.
+
+ Emacs Lisp does have a concept of "obarrays," which are
+ package-like collections of symbols, but this feature is not
+ strong enough to be used as a true package mechanism.
+
+ * Keywords. The notation `:test-not' in Common Lisp really is a
+ shorthand for `keyword:test-not'; keywords are just symbols in a
+ built-in `keyword' package with the special property that all its
+ symbols are automatically self-evaluating. Common Lisp programs
+ often use keywords liberally to avoid having to use quotes.
+
+ In Emacs Lisp a keyword is just a symbol whose name begins with a
+ colon; since the Emacs parser does not treat them specially, they
+ have to be explicitly made self-evaluating by a statement like
+ `(setq :test-not ':test-not)'. This package arranges to execute
+ such a statement whenever `defun*' or some other form sees a
+ keyword being used as an argument. Common Lisp code that assumes
+ that a symbol `:mumble' will be self-evaluating even though it was
+ never introduced by a `defun*' will have to be fixed.
+
+ * The `format' function is quite different between Common Lisp and
+ Emacs Lisp. It takes an additional "destination" argument before
+ the format string. A destination of `nil' means to format to a
+ string as in Emacs Lisp; a destination of `t' means to write to
+ the terminal (similar to `message' in Emacs). Also, format
+ control strings are utterly different; `~' is used instead of `%'
+ to introduce format codes, and the set of available codes is much
+ richer. There are no notations like `\n' for string literals;
+ instead, `format' is used with the "newline" format code, `~%'.
+ More advanced formatting codes provide such features as paragraph
+ filling, case conversion, and even loops and conditionals.
+
+ While it would have been possible to implement most of Common Lisp
+ `format' in this package (under the name `format*', of course), it
+ was not deemed worthwhile. It would have required a huge amount
+ of code to implement even a decent subset of `format*', yet the
+ functionality it would provide over Emacs Lisp's `format' would
+ rarely be useful.
+
+ * Vector constants use square brackets in Emacs Lisp, but `#(a b c)'
+ notation in Common Lisp. To further complicate matters, Emacs 19
+ introduces its own `#(' notation for something entirely
+ different--strings with properties.
+
+ * Characters are distinct from integers in Common Lisp. The
+ notation for character constants is also different: `#\A' instead
+ of `?A'. Also, `string=' and `string-equal' are synonyms in Emacs
+ Lisp whereas the latter is case-insensitive in Common Lisp.
+
+ * Data types. Some Common Lisp data types do not exist in Emacs
+ Lisp. Rational numbers and complex numbers are not present, nor
+ are large integers (all integers are "fixnums"). All arrays are
+ one-dimensional. There are no readtables or pathnames; streams
+ are a set of existing data types rather than a new data type of
+ their own. Hash tables, random-states, structures, and packages
+ (obarrays) are built from Lisp vectors or lists rather than being
+ distinct types.
+
+ * The Common Lisp Object System (CLOS) is not implemented, nor is
+ the Common Lisp Condition System.
+
+ * Common Lisp features that are completely redundant with Emacs Lisp
+ features of a different name generally have not been implemented.
+ For example, Common Lisp writes `defconstant' where Emacs Lisp
+ uses `defconst'. Similarly, `make-list' takes its arguments in
+ different ways in the two Lisps but does exactly the same thing,
+ so this package has not bothered to implement a Common Lisp-style
+ `make-list'.
+
+ * A few more notable Common Lisp features not included in this
+ package: `compiler-let', `tagbody', `prog', `ldb/dpb',
+ `parse-integer', `cerror'.
+
+ * Recursion. While recursion works in Emacs Lisp just like it does
+ in Common Lisp, various details of the Emacs Lisp system and
+ compiler make recursion much less efficient than it is in most
+ Lisps. Some schools of thought prefer to use recursion in Lisp
+ over other techniques; they would sum a list of numbers using
+ something like
+
+ (defun sum-list (list)
+ (if list
+ (+ (car list) (sum-list (cdr list)))
+ 0))
+
+ where a more iteratively-minded programmer might write one of
+ these forms:
+
+ (let ((total 0)) (dolist (x my-list) (incf total x)) total)
+ (loop for x in my-list sum x)
+
+ While this would be mainly a stylistic choice in most Common Lisps,
+ in Emacs Lisp you should be aware that the iterative forms are
+ much faster than recursion. Also, Lisp programmers will want to
+ note that the current Emacs Lisp compiler does not optimize tail
+ recursion.
+
--- /dev/null
+This is Info file ../info/cl.info, produced by Makeinfo version 1.68
+from the input file cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+ This file documents the GNU Emacs Common Lisp emulation package.
+
+ Copyright (C) 1993 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+\1f
+File: cl.info, Node: Function Index, Next: Variable Index, Prev: Porting Common Lisp, Up: Top
+
+Function Index
+**************
+
+* Menu:
+
+* abs: Numerical Functions.
+* acons: Association Lists.
+* adjoin: Lists as Sets.
+* assert: Assertions.
+* assoc*: Association Lists.
+* assoc-if: Association Lists.
+* assoc-if-not: Association Lists.
+* block: Blocks and Exits.
+* butlast: List Functions.
+* caddr: List Functions.
+* callf: Modify Macros.
+* callf2: Modify Macros.
+* case: Conditionals.
+* ceiling*: Numerical Functions.
+* check-type: Assertions.
+* cl-float-limits: Implementation Parameters.
+* cl-prettyexpand: Efficiency Concerns.
+* coerce: Type Predicates.
+* compiler-macroexpand: Macros.
+* concatenate: Sequence Functions.
+* copy-list: List Functions.
+* copy-tree: List Functions.
+* count: Searching Sequences.
+* count-if: Searching Sequences.
+* count-if-not: Searching Sequences.
+* decf: Modify Macros.
+* declaim: Declarations.
+* declare: Declarations.
+* defalias: Function Aliases.
+* define-compiler-macro: Macros.
+* define-modify-macro: Customizing Setf.
+* define-setf-method: Customizing Setf.
+* defmacro*: Argument Lists.
+* defsetf: Customizing Setf.
+* defstruct: Structures.
+* defsubst*: Argument Lists.
+* deftype: Type Predicates.
+* defun*: Argument Lists.
+* delete: Sequence Functions.
+* delete*: Sequence Functions.
+* delete-duplicates: Sequence Functions.
+* delete-if: Sequence Functions.
+* delete-if-not: Sequence Functions.
+* destructuring-bind: Macros.
+* do: Iteration.
+* do*: Iteration.
+* do-all-symbols: Iteration.
+* do-symbols: Iteration.
+* dolist: Iteration.
+* dotimes: Iteration.
+* ecase: Conditionals.
+* endp: List Functions.
+* eql: Equality Predicates.
+* equalp: Equality Predicates.
+* etypecase: Conditionals.
+* eval-when: Time of Evaluation.
+* eval-when-compile: Time of Evaluation.
+* evenp: Predicates on Numbers.
+* every: Mapping over Sequences.
+* expt: Numerical Functions.
+* fill: Sequence Functions.
+* find: Searching Sequences.
+* find-if: Searching Sequences.
+* find-if-not: Searching Sequences.
+* first: List Functions.
+* flet: Function Bindings.
+* floatp-safe: Predicates on Numbers.
+* floor*: Numerical Functions.
+* function*: Argument Lists.
+* gcd: Numerical Functions.
+* gensym: Creating Symbols.
+* gentemp: Creating Symbols.
+* get*: Property Lists.
+* get-setf-method: Customizing Setf.
+* getf: Property Lists.
+* ignore-errors: Assertions.
+* incf: Modify Macros.
+* intersection: Lists as Sets.
+* isqrt: Numerical Functions.
+* labels: Function Bindings.
+* last: List Functions.
+* lcm: Numerical Functions.
+* ldiff: List Functions.
+* letf: Modify Macros.
+* letf*: Modify Macros.
+* lexical-let: Lexical Bindings.
+* lexical-let*: Lexical Bindings.
+* list*: List Functions.
+* list-length: List Functions.
+* load-time-value: Time of Evaluation.
+* locally: Declarations.
+* loop <1>: Iteration.
+* loop: Loop Basics.
+* macrolet: Macro Bindings.
+* make-random-state: Random Numbers.
+* map: Mapping over Sequences.
+* mapc: Mapping over Sequences.
+* mapcan: Mapping over Sequences.
+* mapcar*: Mapping over Sequences.
+* mapcon: Mapping over Sequences.
+* mapl: Mapping over Sequences.
+* maplist: Mapping over Sequences.
+* member: Lists as Sets.
+* member*: Lists as Sets.
+* member-if: Lists as Sets.
+* member-if-not: Lists as Sets.
+* merge: Sorting Sequences.
+* minusp: Predicates on Numbers.
+* mismatch: Searching Sequences.
+* mod*: Numerical Functions.
+* multiple-value-bind: Multiple Values.
+* multiple-value-setq: Multiple Values.
+* nbutlast: List Functions.
+* nintersection: Lists as Sets.
+* notany: Mapping over Sequences.
+* notevery: Mapping over Sequences.
+* nset-difference: Lists as Sets.
+* nset-exclusive-or: Lists as Sets.
+* nsublis: Substitution of Expressions.
+* nsubst: Substitution of Expressions.
+* nsubst-if: Substitution of Expressions.
+* nsubst-if-not: Substitution of Expressions.
+* nsubstitute: Sequence Functions.
+* nsubstitute-if: Sequence Functions.
+* nsubstitute-if-not: Sequence Functions.
+* nunion: Lists as Sets.
+* oddp: Predicates on Numbers.
+* pairlis: Association Lists.
+* plusp: Predicates on Numbers.
+* pop: Modify Macros.
+* position: Searching Sequences.
+* position-if: Searching Sequences.
+* position-if-not: Searching Sequences.
+* proclaim: Declarations.
+* progv: Dynamic Bindings.
+* psetf: Modify Macros.
+* psetq: Assignment.
+* push: Modify Macros.
+* pushnew: Modify Macros.
+* random*: Random Numbers.
+* random-state-p: Random Numbers.
+* rassoc: Association Lists.
+* rassoc*: Association Lists.
+* rassoc-if: Association Lists.
+* rassoc-if-not: Association Lists.
+* reduce: Mapping over Sequences.
+* rem*: Numerical Functions.
+* remf: Property Lists.
+* remove: Sequence Functions.
+* remove*: Sequence Functions.
+* remove-duplicates: Sequence Functions.
+* remove-if: Sequence Functions.
+* remove-if-not: Sequence Functions.
+* remprop: Property Lists.
+* remq: Sequence Functions.
+* replace: Sequence Functions.
+* rest: List Functions.
+* return: Blocks and Exits.
+* return-from: Blocks and Exits.
+* rotatef: Modify Macros.
+* round*: Numerical Functions.
+* search: Searching Sequences.
+* set-difference: Lists as Sets.
+* set-exclusive-or: Lists as Sets.
+* setf: Basic Setf.
+* shiftf: Modify Macros.
+* some: Mapping over Sequences.
+* sort*: Sorting Sequences.
+* stable-sort: Sorting Sequences.
+* sublis: Substitution of Expressions.
+* subseq: Sequence Functions.
+* subsetp: Lists as Sets.
+* subst: Substitution of Expressions.
+* subst-if: Substitution of Expressions.
+* subst-if-not: Substitution of Expressions.
+* substitute: Sequence Functions.
+* substitute-if: Sequence Functions.
+* substitute-if-not: Sequence Functions.
+* symbol-macrolet: Macro Bindings.
+* tailp: Lists as Sets.
+* the: Declarations.
+* tree-equal: List Functions.
+* truncate*: Numerical Functions.
+* typecase: Conditionals.
+* typep: Type Predicates.
+* union: Lists as Sets.
+* unless: Conditionals.
+* when: Conditionals.
+
+\1f
+File: cl.info, Node: Variable Index, Prev: Function Index, Up: Top
+
+Variable Index
+**************
+
+* Menu:
+
+* *gensym-counter*: Creating Symbols.
+* *random-state*: Random Numbers.
+* float-epsilon: Implementation Parameters.
+* float-negative-epsilon: Implementation Parameters.
+* least-negative-float: Implementation Parameters.
+* least-negative-normalized-float: Implementation Parameters.
+* least-positive-float: Implementation Parameters.
+* least-positive-normalized-float: Implementation Parameters.
+* most-negative-fixnum: Implementation Parameters.
+* most-negative-float: Implementation Parameters.
+* most-positive-fixnum: Implementation Parameters.
+* most-positive-float: Implementation Parameters.
+
+
--- /dev/null
+This is Info file ../info/custom.info, produced by Makeinfo version
+1.68 from the input file custom.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Customizations: (custom). Customization Library.
+END-INFO-DIR-ENTRY
+
+\1f
+File: custom.info, Node: Top, Next: Declaring Groups, Prev: (dir), Up: (dir)
+
+The Customization Library
+*************************
+
+ This manual describes how to declare customization groups, variables,
+and faces. It doesn't contain any examples, but please look at the file
+`cus-edit.el' which contains many declarations you can learn from.
+
+* Menu:
+
+* Declaring Groups::
+* Declaring Variables::
+* Declaring Faces::
+* Usage for Package Authors::
+* Utilities::
+* The Init File::
+* Wishlist::
+
+ All the customization declarations can be changes by keyword
+arguments. Groups, variables, and faces all share these common
+keywords:
+
+`:group'
+ VALUE should be a customization group. Add SYMBOL to that group.
+
+`:link'
+ VALUE should be a widget type. Add VALUE to the external links
+ for this customization option. Useful widget types include
+ `custom-manual', `info-link', and `url-link'.
+
+`:load'
+ Add VALUE to the files that should be loaded before displaying
+ this customization option. The value should be either a string,
+ which should be a string which will be loaded with `load-library'
+ unless present in `load-history', or a symbol which will be loaded
+ with `require'.
+
+`:tag'
+ VALUE should be a short string used for identifying the option in
+ customization menus and buffers. By default the tag will be
+ automatically created from the options name.
+
+\1f
+File: custom.info, Node: Declaring Groups, Next: Declaring Variables, Prev: Top, Up: Top
+
+Declaring Groups
+================
+
+ Use `defgroup' to declare new customization groups.
+
+ - Function: defgroup SYMBOL MEMBERS DOC [KEYWORD VALUE]...
+ Declare SYMBOL as a customization group containing MEMBERS.
+ SYMBOL does not need to be quoted.
+
+ DOC is the group documentation.
+
+ MEMBERS should be an alist of the form ((NAME WIDGET)...) where
+ NAME is a symbol and WIDGET is a widget for editing that symbol.
+ Useful widgets are `custom-variable' for editing variables,
+ `custom-face' for editing faces, and `custom-group' for editing
+ groups.
+
+ Internally, custom uses the symbol property `custom-group' to keep
+ track of the group members, and `group-documentation' for the
+ documentation string.
+
+ The following additional KEYWORD's are defined:
+
+ `:prefix'
+ VALUE should be a string. If the string is a prefix for the
+ name of a member of the group, that prefix will be ignored
+ when creating a tag for that member.
+
+\1f
+File: custom.info, Node: Declaring Variables, Next: Declaring Faces, Prev: Declaring Groups, Up: Top
+
+Declaring Variables
+===================
+
+ Use `defcustom' to declare user editable variables.
+
+ - Function: defcustom SYMBOL VALUE DOC [KEYWORD VALUE]...
+ Declare SYMBOL as a customizable variable that defaults to VALUE.
+ Neither SYMBOL nor VALUE needs to be quoted. If SYMBOL is not
+ already bound, initialize it to VALUE.
+
+ DOC is the variable documentation.
+
+ The following additional KEYWORD's are defined:
+
+ `:type'
+ VALUE should be a widget type.
+
+ `:options'
+ VALUE should be a list of possible members of the specified
+ type. For hooks, this is a list of function names.
+
+ `:initialize'
+ VALUE should be a function used to initialize the variable.
+ It takes two arguments, the symbol and value given in the
+ `defcustom' call. Some predefined functions are:
+
+ `custom-initialize-set'
+ Use the `:set' method to initialize the variable. Do not
+ initialize it if already bound. This is the default
+ `:initialize' method.
+
+ `custom-initialize-default'
+ Always use `set-default' to initialize the variable,
+ even if a `:set' method has been specified.
+
+ `custom-initialize-reset'
+ If the variable is already bound, reset it by calling
+ the `:set' method with the value returned by the `:get'
+ method.
+
+ `custom-initialize-changed'
+ Like `custom-initialize-reset', but use `set-default' to
+ initialize the variable if it is not bound and has not
+ been set already.
+
+ `:set'
+ VALUE should be a function to set the value of the symbol. It
+ takes two arguments, the symbol to set and the value to give
+ it. The default is `set-default'.
+
+ `:get'
+ VALUE should be a function to extract the value of symbol.
+ The function takes one argument, a symbol, and should return
+ the current value for that symbol. The default is
+ `default-value'.
+
+ `:require'
+ VALUE should be a feature symbol. Each feature will be
+ required when the `defcustom' is evaluated, or when Emacs is
+ started if the user has saved this option.
+
+ *Note Sexp Types: (widget)Sexp Types, for information about
+ widgets to use together with the `:type' keyword.
+
+ Internally, custom uses the symbol property `custom-type' to keep
+track of the variables type, `standard-value' for the program specified
+default value, `saved-value' for a value saved by the user, and
+`variable-documentation' for the documentation string.
+
+ Use `custom-add-option' to specify that a specific function is
+useful as an member of a hook.
+
+ - Function: custom-add-option SYMBOL OPTION
+ To the variable SYMBOL add OPTION.
+
+ If SYMBOL is a hook variable, OPTION should be a hook member. For
+ other types variables, the effect is undefined."
+
+\1f
+File: custom.info, Node: Declaring Faces, Next: Usage for Package Authors, Prev: Declaring Variables, Up: Top
+
+Declaring Faces
+===============
+
+ Faces are declared with `defface'.
+
+ - Function: defface FACE SPEC DOC [KEYWORD VALUE]...
+ Declare FACE as a customizable face that defaults to SPEC. FACE
+ does not need to be quoted.
+
+ If FACE has been set with `custom-set-face', set the face
+ attributes as specified by that function, otherwise set the face
+ attributes according to SPEC.
+
+ DOC is the face documentation.
+
+ SPEC should be an alist of the form `((DISPLAY ATTS)...)'.
+
+ ATTS is a list of face attributes and their values. The possible
+ attributes are defined in the variable `custom-face-attributes'.
+
+ The ATTS of the first entry in SPEC where the DISPLAY matches the
+ frame should take effect in that frame. DISPLAY can either be the
+ symbol `t', which will match all frames, or an alist of the form
+ `((REQ ITEM...)...)'
+
+ For the DISPLAY to match a FRAME, the REQ property of the frame
+ must match one of the ITEM. The following REQ are defined:
+
+ `type'
+ (the value of (window-system))
+ Should be one of `x' or `tty'.
+
+ `class'
+ (the frame's color support)
+ Should be one of `color', `grayscale', or `mono'.
+
+ `background'
+ (what color is used for the background text)
+ Should be one of `light' or `dark'.
+
+ Internally, custom uses the symbol property `face-defface-spec' for
+ the program specified default face properties, `saved-face' for
+ properties saved by the user, and `face-documentation' for the
+ documentation string.
+
+
+\1f
+File: custom.info, Node: Usage for Package Authors, Next: Utilities, Prev: Declaring Faces, Up: Top
+
+Usage for Package Authors
+=========================
+
+ The recommended usage for the author of a typical emacs lisp package
+is to create one group identifying the package, and make all user
+options and faces members of that group. If the package has more than
+around 20 such options, they should be divided into a number of
+subgroups, with each subgroup being member of the top level group.
+
+ The top level group for the package should itself be member of one or
+more of the standard customization groups. There exists a group for
+each *finder* keyword. Press `C-h p' to see a list of finder keywords,
+and add you group to each of them, using the `:group' keyword.
+
+\1f
+File: custom.info, Node: Utilities, Next: The Init File, Prev: Usage for Package Authors, Up: Top
+
+Utilities
+=========
+
+ These utilities can come in handy when adding customization support.
+
+ - Widget: custom-manual
+ Widget type for specifying the info manual entry for a
+ customization option. It takes one argument, an info address.
+
+ - Function: custom-add-to-group GROUP MEMBER WIDGET
+ To existing GROUP add a new MEMBER of type WIDGET, If there
+ already is an entry for that member, overwrite it.
+
+ - Function: custom-add-link SYMBOL WIDGET
+ To the custom option SYMBOL add the link WIDGET.
+
+ - Function: custom-add-load SYMBOL LOAD
+ To the custom option SYMBOL add the dependency LOAD. LOAD should
+ be either a library file name, or a feature name.
+
+ - Function: customize-menu-create SYMBOL &optional NAME
+ Create menu for customization group SYMBOL. If optional NAME is
+ given, use that as the name of the menu. Otherwise the menu will
+ be named `Customize'. The menu is in a format applicable to
+ `easy-menu-define'.
+
+\1f
+File: custom.info, Node: The Init File, Next: Wishlist, Prev: Utilities, Up: Top
+
+The Init File
+=============
+
+ When you save the customizations, call to `custom-set-variables',
+`custom-set-faces' are inserted into the file specified by
+`custom-file'. By default `custom-file' is your `.emacs' file. If you
+use another file, you must explicitly load it yourself. The two
+functions will initialize variables and faces as you have specified.
+
+\1f
+File: custom.info, Node: Wishlist, Prev: The Init File, Up: Top
+
+Wishlist
+========
+
+ * Better support for keyboard operations in the customize buffer.
+
+ * Integrate with `w3' so you can get customization buffers with much
+ better formatting. I'm thinking about adding a
+ <custom>name</custom> tag. The latest w3 have some support for
+ this, so come up with a convincing example.
+
+ * Add an `examples' section, with explained examples of custom type
+ definitions.
+
+ * Support selectable color themes. I.e., change many faces by
+ setting one variable.
+
+ * Support undo using lmi's `gnus-undo.el'.
+
+ * Make it possible to append to `choice', `radio', and `set' options.
+
+ * Ask whether set or modified variables should be saved in
+ `kill-buffer-hook'.
+
+ Ditto for `kill-emacs-query-functions'.
+
+ * Command to check if there are any customization options that does
+ not belong to an existing group.
+
+ * Optionally disable the point-cursor and instead highlight the
+ selected item in XEmacs. This is like the *Completions* buffer in
+ XEmacs. Suggested by Jens Lautenbacher
+ `<jens@lemming0.lem.uni-karlsruhe.de>'.
+
+ * Explain why it is necessary that all choices have different default
+ values.
+
+ * Add some direct support for meta variables, i.e. make it possible
+ to specify that this variable should be reset when that variable is
+ changed.
+
+ * Add tutorial.
+
+ * Describe the `:type' syntax in this manual.
+
+ * Find a place is this manual for the following text:
+
+ *Radio vs. Buttons*
+
+ Use a radio if you can't find a good way to describe the item in
+ the choice menu text. I.e. it is better to use a radio if you
+ expect the user would otherwise manually select each item from the
+ choice menu in turn to see what it expands too.
+
+ Avoid radios if some of the items expands to complex structures.
+
+ I mostly use radios when most of the items are of type
+ `function-item' or `variable-item'.
+
+ * Update customize buffers when `custom-set-variable' or
+ `custom-save-customized' is called.
+
+ * Better handling of saved but uninitialized items.
+
+ * Detect when faces have been changed outside customize.
+
+ * Enable mouse help in Emacs by default.
+
+ * Add an easy way to display the standard settings when an item is
+ modified.
+
+ * See if it is feasible to scan files for customization information
+ instead of loading them,
+
+ * Add hint message when user push a non-pushable tag.
+
+ Suggest that the user unhide if hidden, and edit the value directly
+ otherwise.
+
+ * Use checkboxes and radio buttons in the state menus.
+
+ * Add option to hide `[hide]' for short options. Default, on.
+
+ * Add option to hide `[state]' for options with their standard
+ settings.
+
+ * There should be a way to specify site defaults for user options.
+
+ * There should be more buffer styles. The default `nested style,
+ the old `outline' style, a `numeric' style with numbers instead of
+ stars, an `empty' style with just the group name, and `compact'
+ with only one line per item.
+
+ * Newline and tab should be displayed as `^J' and `^I' in the
+ `regexp' and `file' widgets. I think this can be done in XEmacs
+ by adding a display table to the face.
+
+ * Use glyphs to draw the `customize-browse' tree.
+
+ Add echo and balloon help. You should be able to read the
+ documentation simply by moving the mouse pointer above the name.
+
+ Add parent links.
+
+ Add colors.
+
+
+\1f
+Tag Table:
+Node: Top\7f230
+Node: Declaring Groups\7f1651
+Node: Declaring Variables\7f2752
+Node: Declaring Faces\7f5843
+Node: Usage for Package Authors\7f7541
+Node: Utilities\7f8320
+Node: The Init File\7f9404
+Node: Wishlist\7f9856
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/emodules.info, produced by Makeinfo version
+1.68 from the input file emodules.texi.
+
+ This file documents the module loading technology of XEmacs.
+
+ Copyright (C) 1998 J. Kean Johnston.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: emodules.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
+
+ This Info file contains v1.0 of the XEmacs dynamic loadable module
+support documentation.
+
+* Menu:
+
+* Introduction:: Introducing Emacs Modules
+* Annatomy of a Module:: Basic module layout and technology
+* Using ellcc:: How to use the module compiler
+* Defining Functions:: Creating new Lisp primitives
+* Defining Variables:: Creating new Lisp variables
+* Index:: Concept Index
+
+ -- The Detailed Node Listing --
+
+Annatomy of a Module
+
+* Required Header File:: Always include <emodules.h>
+* Required Functions:: Functions you must always provide
+* Required Variables:: Variables whose values you must provide
+* Loading other Modules:: How to load dependant modules
+
+Using `ellcc'
+
+* Compile Mode:: Compiling modules using ellcc
+* Initialization Mode:: Generating documentation and variables
+* Link Mode:: Creating the final loadable module
+* Other ellcc options:: Other useful options
+* Environment Variables:: How to control ellcc
+
+Defining Functions
+
+* Using DEFUN:: Using the DEFUN macro to define functions
+* Declaring Functions:: Declaring functions to the Lisp reader
+
+\1f
+File: emodules.info, Node: Introduction, Next: Annatomy of a Module, Prev: Top, Up: Top
+
+Introduction
+************
+
+ XEmacs is a powerful, extensible editor. The traditional way of
+extending the functionality of XEmacs is to use its built-in Lisp
+language (called Emacs Lisp, or Elisp for short). However, while Elisp
+is a full programming language and capable of extending XEmacs in more
+ways than you can imagine, it does have its short-comings.
+
+ Firstly, Elisp is an interpreted language, and this has serious speed
+implications. Like all other interpreted languages (like Java), Elisp
+is often suitable only for certain types of application or extension.
+So although Elisp is a general purpose language, and very ligh level,
+there are times when it is desirable to descend to a lower level
+compiled language for speed purposes.
+
+ Secondly, Elisp (or Lisp in general) is not a very common language
+any more, except for certain circles in the computer industry. C is a
+far more commonly known language, and because it is compiled, more
+suited to a wider range of applications, especially those that require
+low level access to a system or need to be as quick as possible.
+
+ This manual describes a new way of extending XEmacs, by using dynamic
+loadable modules (also knows as dynamicaly loadable libraries (DLLs),
+dynamic shared objects (DSOs) or just simply shared objectcs), which can
+be written in C or C++ and loaded into XEmacs at any time. I sometimes
+refer to this technology as "CEmacs", which is short for "C Extensible
+Emacs".
+
+ XEmacs modules are configured into and installed with XEmacs by
+default on all systems that support loading of shared objects. From a
+users perspective, the internals of XEmacs modules are irrelevant. All
+a user will ever need to know about shared objects is the name of the
+shared object when they want to load a given module. From a developers
+perspective though, a lot more is provided.
+
+ * Of primary interest is the `ellcc' program. This program is
+ created during compile time, and is intended to abstract compiler
+ specific characteristics from the developer. This program is
+ called to compile and link all objects that will make up the final
+ shared object, and accepts all common C compiler flags. `ellcc'
+ also sets up the correct environment for compiling modules by
+ enabling any special compiler modes (such as PIC mode), setting
+ the correct include paths for the location of XEmacs internal
+ header files etc. The program will also invoke the linker
+ correctly to created the final shared object which is loaded into
+ XEmacs.
+
+ * CEmacs also makes all of the relevant XEmacs internal header
+ files availible for module authors to use. This is often required
+ to get data structure definitions and external variable
+ declarations. The header files installed include the module
+ specific header file `emodules.h'. Due to the nature of dynamic
+ modules, most of the internals of XEmacs are exposed. *Note Top:
+ (internals)Top, for a more complete discussion on how to extend
+ and understand XEmacs. All of the rules for C modules are
+ discussed there.
+
+ * Part of the XEmacs distribution is a set of sample modules.
+ These are not installed when XEmacs is, but remain in the XEmacs
+ source tree. These modules live in the directory `modules', which
+ is a sub-directory of the main XEmacs source code directory.
+ Please look at the samples carefully, and maybe even use them as a
+ basis for making your own modules. Most of the concepts required
+ for writing extension modules are covered in the samples.
+
+ * Last, but not least is this manual. This can be viewed from
+ within XEmacs, and it can be printed out as well. It is the
+ intention of this document that it will describe everything you
+ need to know about extending XEmacs in C. If you do not find this
+ to be the case, please contact the author(s).
+
+ The rest of this document will discuss the actual mechanics of
+XEmacs modules and work through several of the samples. Please be sure
+that you have read the XEmacs Internals Manual and understand
+everything in it. The concepts there apply to all modules. This
+document may have some overlap, but it is the internals manual which
+should be considered the final authority. It will also help a great
+deal to look at the actual XEmacs source code to see how things are
+done.
+
+\1f
+File: emodules.info, Node: Annatomy of a Module, Next: Using ellcc, Prev: Introduction, Up: Top
+
+Annatomy of a Module
+********************
+
+ Each dynamically loadable XEmacs extension (hereafter refered to as a
+module) has a certain compulsory format, and must contain several
+pieces of information and several mandatory functions. This chapter
+describes the basic layout of a module, and provides a very simple
+sample. The source for this sample can be found in the file
+`modules/simple/sample.c' in the main XEmacs source code tree.
+
+* Menu:
+
+* Required Header File:: Always include <emodules.h>
+* Required Functions:: Functions you must always provide
+* Required Variables:: Variables whose values you must provide
+* Loading other Modules:: How to load dependant modules
+
+\1f
+File: emodules.info, Node: Required Header File, Next: Required Functions, Prev: Annatomy of a Module, Up: Annatomy of a Module
+
+Required Header File
+====================
+
+ Every module must include the file `<emodules.h>'. This will
+include several other XEmacs internal header files, and will set up
+certain vital macros. One of the most important files included by
+`emodules.h' is the generated `config.h' file, which contains all of
+the required system abstraction macros and definitions. Most modules
+will probably require some pre-processor conditionals based on
+constants defined in `config.h'. Please read that file to familiarize
+yourself with the macros defined there.
+
+ Depending on exactly what your module will be doing, you will
+probably need to include one or more of the XEmacs internal header
+files. When you `#include <emodules.h>', you will get a few of the
+most important XEmacs header files included automatically for you. The
+files included are:
+
+`lisp.h'
+ This file contains most of the macros required for declaring Lisp
+ object types, macros for accessing Lisp objects, and global
+ variable declarations.
+
+`sysdep.h'
+ All system dependant declarations and abstraction macros live
+ here. You should never call low level system functions directly.
+ Rather, you should use the abstraction macros provided in this
+ header file.
+
+`window.h'
+ This header file defines the window structures and Lisp types, and
+ provides functions and macros for manipulating multiple XEmacs
+ windows.
+
+`buffer.h'
+ All macros and function declarations for manipulating internal and
+ user visible buffers appear in this file.
+
+`insdel.h'
+ This header provides the information required for performing text
+ insertion and deletion.
+
+`frame.h'
+ Provides the required structure, macro and function definitions for
+ manipulating XEmacs frames.
+
+\1f
+File: emodules.info, Node: Required Functions, Next: Required Variables, Prev: Required Header File, Up: Annatomy of a Module
+
+Required Functions
+==================
+
+ Every module requires several initialization functions. It is the
+responsibility of these functions to load in any dependant modules, and
+to declare all variables and functions which are to be made visibile to
+the XEmacs Lisp reader. Each of these functions performs a very
+specific task, and they are executed in the correct order by XEmacs.
+All of these functions are `void' functions which take no arguments.
+Here, briefly, are the required module functions. Note that the actual
+function names do not end with the string `_module', but rather they
+end with the abbreviated module name by which the module is known.
+More on the module name and its importance later. Just bear in mind
+that the text `_module' in the functions below is simply a
+place-holder, not an actual function name.
+
+`syms_of_module'
+ This required function is responsible for introducing to the Lisp
+ reader all functions that you have defined in your module using
+ `DEFUN()'. Note that *only* functions are declared here, using
+ the `DEFSUBR()' macro. No variables are declared.
+
+`vars_of_module'
+ This required function contains calls to macros such as
+ `DEFVAR_LISP()', `DEFVAR_BOOL()' etc, and its purpose is to
+ declare and initialize all and any variables that your module
+ defines. They syntax for declaring variables is identical to the
+ syntax used for all internal XEmacs source code.
+
+`modules_of_module'
+ This optional function should be used to load in any modules which
+ your module depends on. The XEmacs module loading code makes sure
+ that the same module is not loaded twice, so several modules can
+ safely call the module load function for the same module. Only
+ one copy of each module (at a given version) will ever be loaded.
+
+`docs_of_module'
+ This is a required function, but not one which you need ever write.
+ This function is created automatically by `ellcc' when the module
+ initialization code is produced. It is required to document all
+ functions and variables declared in your module.
+
+\1f
+File: emodules.info, Node: Required Variables, Next: Loading other Modules, Prev: Required Functions, Up: Annatomy of a Module
+
+Required Variables
+==================
+
+ Not only does a module need to declare the initialization functions
+mentioned above, it is also required to provide certain variables which
+the module loading code searches for in order to determine the viability
+of a module. You are *not* required to provide these variables in your
+source files. They are automatically set up in the module
+initialization file by the `ellcc' compiler. These variables are
+discussed here simply for the sake of completeness.
+
+`emodules_compiler'
+ This is a variable of type `long', and is used to indicate the
+ version of the XEmacs loading technology that was used to produce
+ the module being loaded. This version number is completely
+ unrelated to the XEmacs version number, as a given module may
+ quite well work regardless of the version of XEmacs that was
+ installed at the time the module was created.
+
+ The XEmacs modules version is used to differentiate between major
+ changes in the module loading technology, not versions of XEmacs.
+
+`emodules_name'
+ This is a short (typically 10 characters or less) name for the
+ module, and it is used as a suffix for all of the required
+ functions. This is also the name by which the module is
+ recognised when loading dependant modules. The name does not
+ necessarily have to be the same as the physical file name,
+ although keeping the two names in sync is a pretty good idea. The
+ name must not be empty, and it must be a valid part of a C
+ function name. The value of this variable is appended to the
+ function names `syms_of_', `vars_of_', `modules_of_' and
+ `docs_of_' to form the actual function names that the module
+ loading code looks for when loading a module.
+
+ This variable is set by the `--mod-name' argument to `ellcc'.
+
+`emodules_version'
+ This string variable is used to load specific versions of a module.
+ Rarely will two or more versions of a module be left lying around,
+ but just in case this does happen, this variable can be used to
+ control exactly which module should be loaded. See the Lisp
+ function `load-module' for more details. This variable is set by
+ the `--mod-version' argument to `ellcc'.
+
+`emodules_title'
+ This is a string which describes the module, and can contain
+ spaces or other special characters. It is used solely for
+ descriptive purposes, and does not affect the loading of the
+ module. The value is set by the `--mod-title' argument to `ellcc'.
+
+\1f
+File: emodules.info, Node: Loading other Modules, Prev: Required Variables, Up: Annatomy of a Module
+
+Loading other Modules
+=====================
+
+ During the loading of a module, it is the responsibility of the
+function `modules_of_module' to load in any modules which the current
+module depends on. If the module is stand-alone, and does not depend
+on other modules, then this function can be left empty or even
+undeclared. However, if it does have dependnacies, it must call
+`emodules_load':
+
+ int emodules_load (CONST char *module,
+ CONST char *modname,
+ CONST char *modver)
+
+ The first argument MODULE is the name of the actual shared object or
+DLL. You can omit the `.so', `.ell' or `.dll' extension of you wish.
+If you do not specify an absolute path name, then the same rules as
+apply to loading Lisp modules are applied when searching for the
+module. If the module cannot be found in any of the standard places,
+and an absolute path name was not specified, `emodules_load' will
+signal an error and loading of the module will stop.
+
+ The second argument (MODNAME) is the module name to load, and must
+match the contents of the variable EMODULE_NAME in the module to be
+loaded. A mis-match will cause the module load to fail. If this
+parameter is `NULL' or empty, then no checks are performed against the
+target module's EMODULE_NAME variable.
+
+ The last argument, MODVER, is the desired version of the module to
+load, and is compared to the target module's EMODULE_VERSION value. If
+this parameter is not `NULL' or empty, and the match fails, then the
+load of the module will fail.
+
+ `emodules_load' can be called recursively. If, at any point during
+the loading of modules a failure is encountered, then all modules that
+were loaded since the top level call to `emodules_load' will be
+unloaded. This means that if any child modules fail to load, then
+their parents will also fail to load. This does not include previous
+successful calls to `emodules_load' at the top level.
+
+\1f
+File: emodules.info, Node: Using ellcc, Next: Defining Functions, Prev: Annatomy of a Module, Up: Top
+
+Using `ellcc'
+*************
+
+ Before discussing the anatomy of a module in greater detail, you
+should be aware of the steps required in order to correctly compile and
+link a module for use within XEmacs. There is little difference between
+compiling normal C code and compiling a module. In fact, all that
+changes is the command used to compile the module, and a few extra
+arguments to the compiler.
+
+ XEmacs now ships with a new user utility, called `ellcc'. This is
+the "Emacs Loadable Library C Compiler". This is a wrapper program
+that will invoke the real C compiler with the correct arguments to
+compile and link your module. With the exception of a few command line
+options, this program can be considered a replacement for your C
+compiler. It accepts all of the same flags and arguments that your C
+compiler does, so in many cases you can simply set the `make' variable
+`CC' to `ellcc' and your code will be compiled as an Emacs module
+rather than a static C object.
+
+ `ellcc' has three distinct modes of operation. It can be run in
+compile, link or initialization mode. These modes are discussed in more
+detail below. If you want `ellcc' to show the commands it is
+executing, you can specify the option `--mode=verbose' to `ellcc'.
+Specifying this option twice will enable certain extra debugging
+messages to be displayed on the standard output.
+
+* Menu:
+
+* Compile Mode:: Compiling modules using ellcc
+* Initialization Mode:: Generating documentation and variables
+* Link Mode:: Creating the final loadable module
+* Other ellcc options:: Other useful options
+* Environment Variables:: How to control ellcc
+
+\1f
+File: emodules.info, Node: Compile Mode, Next: Initialization Mode, Prev: Using ellcc, Up: Using ellcc
+
+Compile Mode
+============
+
+ By default, `ellcc' is in "compile" mode. This means that it
+assumes that all of the command line arguments are C compiler arguments,
+and that you want to compile the specified source file or files. You
+can force compile mode by specifying the `--mode=compile' argument to
+`ellcc'.
+
+ In this mode, `ellcc' is simply a front-end to the same C compiler
+that was used to create the XEmacs binary itself. All `ellcc' does in
+this mode is insert a few extra command line arguments before the
+arguments you specify to `ellcc' itself. `ellcc' will then invoke the
+C compiler to compile your module, and will return the same exit codes
+and messages that your C compiler does.
+
+ By far the easiest way to compile modules is to construct a
+`Makefile' as you would for a normal program, and simply insert, at
+some appropriate place something similar to:
+
+ CC=ellcc --mode=compile
+
+ .c.o:
+ $(CC) $(CFLAGS) -c $<
+
+ After this, all you need to do is provide simple `make' rules for
+compiling your module source files. Since modules are most useful when
+they are small and self-contained, most modules will have a single
+source file, aside from the module specific initialization file (see
+below for details).
+
+\1f
+File: emodules.info, Node: Initialization Mode, Next: Link Mode, Prev: Compile Mode, Up: Using ellcc
+
+Initialization Mode
+===================
+
+ XEmacs uses a rather bizarre way of documenting variables and
+functions. Rather than have the documentation for compiled functions
+and variables passed as static strings in the source code, the
+documentation is included as a C comment. A special program, called
+`make-docfile', is used to scan the source code files and extract the
+documentation from these comments, producing the XEmacs `DOC' file,
+which the internal help engine scans when the documentation for a
+function or variable is requested.
+
+ Due to the internal construction of Lisp objects, subrs and other
+such things, adding documentation for a compiled function or variable
+in a compiled module, at any time after XEmacs has been "dumped" is
+somewhat problematic. Fortunately, as a module writer you are insulated
+from the difficulties thanks to your friend `ellcc' and some internal
+trickery in the module loading code. This is all done using the
+"initialization" mode of `ellcc'.
+
+ The result of running `ellcc' in initialization mode is a C source
+file which you compile with (you guessed it) `ellcc' in compile mode.
+Initialization mode is where you set the module name, version, title
+and gather together all of the documentaion strings for the functions
+and vairables in your module. There are several options that you are
+required to pass `ellcc' in initialization mode, the first of which is
+the mode switch itself, `--mode=init'.
+
+ Next, you need to specify the name of the C source code file that
+`ellcc' will produce, and you specify this using the
+`--mod-output=FILENAME' argument. FILENAME is the name of the C source
+code file that will contain the module variables and `docs_of_module'
+function.
+
+ As discussed previously, each module requires a short "handle" or
+module name. This is specified with the `--mod-name=NAME' option,
+where NAME is the abbreviated module name. This NAME must consist only
+of characters that are valid in C function and variable names.
+
+ The module version is specified using `--mod-version=VERSION'
+argument, with VERSION being any arbitrary version string. This
+version can be passed as an optional second argument to the Lisp
+function `load-module', and as the third argument to the internal
+module loading command `emodules_load'. This version string is used to
+distinguish between different versions of the same module, and to
+ensure that the module is loaded at a specific version.
+
+ Last, but not least, is the module title. Specified using the
+`--mod-title=TITLE' option, the specified TITLE is used when the list
+of loaded modules is displayed. The module title serves no purpose
+other than to inform the user of the function of the module. This
+string should be brief, as it has to be formatted to fit the screen.
+
+ Following all of these parameters, you need to provide the list of
+all source code modules that make up your module. These are the files
+which are scanned by `make-docfile', and provide the information
+required to populate the `docs_of_module' function. Below is a sample
+`Makefile' fragment which indicates how all of this is used.
+
+ CC=ellcc --mode=compile
+ LD=ellcc --mode=link
+ MODINIT=ellcc --mode=init
+ CFLAGS=-O2 -DSOME_STUFF
+
+ .c.o:
+ $(CC) $(CFLAGS) -c $<
+
+ MODNAME=sample
+ MODVER=1.0.0
+ MODTITLE="Small sample module"
+
+ SRCS=modfile1.c modfile2.c modfile3.c
+ OBJS=$(SRCS:.c=.o)
+
+ all: sample.ell
+ clean:
+ rm -f $(OBJS) sample_init.o sample.ell
+
+ install: all
+ mkdir `ellcc --mod-location`/mymods > /dev/null
+ cp sample.ell `ellcc --mod-location`/mymods/sample.ell
+
+ sample.ell: $(OBJS) sample_init.o
+ $(LD) --mod-output=$ $(OBJS) sample_init.o
+
+ sample_init.o: sample_init.c
+ sample_init.c: $(SRCS)
+ $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \
+ --mod-title=$(MODTITLE) --mod-output=$ $(SRCS)
+
+ The above `Makefile' is, in fact, complete, and would compile the
+sample module, and optionally install it. The `--mod-location'
+argument to `ellcc' will produce, on the standard output, the base
+location of the XEmacs module directory. Each sub-directory of that
+directory is automatically searched for for modules when they are loaded
+with `load-module'. An alternative location would be
+`/usr/local/lib/xemacs/site-modules'. That path can change depending
+on the options the person who compiled XEmacs chose, so you can always
+determine the correct site location using the `--mod-site-location'
+option. This directory is treated the same way as the main module
+directory. Each sub-directory within it is searched for a given module
+when the user attempts to load it. The valid extensions that the
+loader attempts to use are `.so', `.ell' and `.dll'. You can use any
+of these extensions, although `.ell' is the prefered extension.
+
+\1f
+File: emodules.info, Node: Link Mode, Next: Other ellcc options, Prev: Initialization Mode, Up: Using ellcc
+
+Link Mode
+=========
+
+ Once all of your source code files have been compiled (including the
+generated init file) you need to link them all together to created the
+loadable module. To do this, you invoke `ellcc' in link mode, by
+pasing the `--mode-link' command. You need to specify the final output
+file using the `--mod-output=NAME' command, but other than that all
+other arguments are passed on directly to the system compiler or
+linker, along with any other required arguments to create the loadable
+module.
+
+ The module has complete access to all symbols that were present in
+the dumped XEmacs, so you do not need to link against libraries that
+were linked in with the main executable. If your library uses some
+other extra libraries, you will need to link with those. There is
+nothing particularly complicated about link mode. All you need to do
+is make sure you invoke it correctly in the `Makefile'. See the sample
+`Makefile' above for an example of a well constructed `Makefile' that
+invoked the linker correctly.
+
+\1f
+File: emodules.info, Node: Other ellcc options, Next: Environment Variables, Prev: Link Mode, Up: Using ellcc
+
+Other `ellcc' options
+=====================
+
+ Aside from the three main `ellcc' modes described above, `ellcc' can
+accept several other options. These are typically used in a `Makefile'
+to determine installation paths. `ellcc' also allows you to over-ride
+several of its built-in compiler and linker options using environment
+variables. Here is the complete list of options that `ellcc' accepts.
+
+`--mode=compile'
+ Enables compilation mode. Use this to compile source modules.
+
+`--mode=link'
+ Enabled link edit mode. Use this to create the final module.
+
+`--mode=init'
+ Used to create the documentation function and to initialize other
+ required variables. Produces a C source file that must be
+ compiled with `ellcc' in compile mode before linking the final
+ module.
+
+`--mode=verbose'
+ Enables verbose mode. This will show you the commands that are
+ being executed, as well as the version number of `ellcc'. If you
+ specify this option twice, then some extra debugging information
+ is displayed.
+
+`--mod-name=NAME'
+ Sets the short internaml module NAME to the string specified,
+ which must consist only of valid C identifiers. Required during
+ initialization mode.
+
+`--mod-version=VERSION'
+ Sets the internal module VERSION to the specified string.
+ Required during initialization mode.
+
+`--mod-title=TITLE'
+ Sets the module descriptive TITLE to the string specified. This
+ string can contain any printable characters, but should not be too
+ long. It is required during initialization mode.
+
+`--mod-output=FILENAME'
+ Used to control the output file name. This is used during
+ initialization mode to set the name of the C source file that will
+ be created to FILENAME. During link mode, it sets the name of the
+ final loadable module to FILENAME.
+
+`--mod-location'
+ This will print the name of the standard module installation path
+ on the standard output and immediately exit `ellcc'. Use this
+ option to determine the directory prefix of where you should
+ install your modules.
+
+`--mod-site-location'
+ This will print the name of the site specific module location and
+ exit.
+
+`--mod-archdir'
+ Prints the name of the root of the architecture-dependant
+ directory that XEmacs searches for architecture-dependant files.
+
+`--mod-config'
+ Prints the name of the configuration for which XEmacs and `ellcc'
+ were compiled.
+
+\1f
+File: emodules.info, Node: Environment Variables, Prev: Other ellcc options, Up: Using ellcc
+
+Environment Variables
+=====================
+
+ During its normal operation, `ellcc' uses the compiler and linker
+flags that were determined at the time XEmacs was configured. In
+certain rare circumstances you may wish to over-ride the flags passed to
+the compiler or linker, and you can do so using environment variables.
+The table below lists all of the environment variables that `ellcc'
+recognises.
+
+`ELLCC'
+ This is used to over-ride the name of the C compiler that is
+ invoked by `ellcc'.
+
+`ELLLD'
+ Sets the name of the link editor to use to created the final
+ module.
+
+`ELLCFLAGS'
+ Sets the compiler flags passed on when compiling source modules.
+ This only sets the basic C compiler flags. There are certain
+ hard-coded flags that will always be passed.
+
+`ELLLDFLAGS'
+ Sets the flags passed on to the linker. This does *not* include
+ the flags for enabling PIC mode. This just sets basic linker
+ flags.
+
+`ELLDLLFLAGS'
+ Sets the flags passed to the linker that are required to created
+ shared and loadable objects.
+
+`ELLPICFLAGS'
+ Sets the C compiler option required to produce an object file that
+ is suitable for including in a shared library. This option should
+ turn on PIC mode, or the moral equivalent thereof on the target
+ system.
+
+`ELLMAKEDOC'
+ Sets the name of the `make-docfile' program to use. Usually
+ `ellcc' will use the version that was compiled and installed with
+ XEmacs, but this option allows you to specify an alternative path.
+ Used during the compile phase of XEmacs itself.
+
+\1f
+File: emodules.info, Node: Defining Functions, Next: Defining Variables, Prev: Using ellcc, Up: Top
+
+Defining Functions
+******************
+
+ One of the main reasons you would ever write a module is to provide
+one or more "functions" for the user or the editor to use. The term
+"function" is a bit overloaded here, as it refers to both a C function
+and the way it appears to Lisp, which is a "subroutine", or simply a
+"subr". A Lisp subr is also known as a Lisp primitive, but that term
+applies less to dynamic modules. *Note Writing Lisp Primitives:
+(internals)Writing Lisp Primitives, for details on how to declare
+functions. You should familiarize yourself with the instructions
+there. The format of the function declaration is identical in modules.
+
+ Normal Lisp primitives document the functions they defining by
+including the documentation as a C comment. During the build process,
+a program called `make-docfile' is run, which will extract all of these
+comments, build up a single large documentation file, and will store
+pointers to the start of each documentation entry in the dumped XEmacs.
+This, of course, will not work for dynamic modules, as they are loaded
+long after XEmacs has been dumped. For this reason, we require a
+special means for adding documentation for new subrs. This is what the
+macro `CDOCSUBR' is used for, and this is used extensively during
+`ellcc' initialization mode.
+
+ When using `DEFUN' in normal XEmacs C code, the sixth "parameter" is
+a C comment which documents the function. For a dynamic module, we of
+course need to convert the C comment to a usable string, and we need to
+set the documentation pointer of the subr to this string. As a module
+programmer, you don't actually need to do any work for this to happen.
+It is all taken care of in the `docs_of_module' function created by
+`ellcc'.
+
+* Menu:
+
+* Using DEFUN:: Using the DEFUN macro to define functions
+* Declaring Functions:: Declaring functions to the Lisp reader
+
+\1f
+File: emodules.info, Node: Using DEFUN, Next: Declaring Functions, Prev: Defining Functions, Up: Defining Functions
+
+Using `DEFUN'
+=============
+
+ Although the full syntax of a function declaration is discussed in
+the XEmacs internals manual in greater depth, what follows is a brief
+description of how to define and implement a new Lisp primitive in a
+module. This is done using the `DEFUN' macro. Here is a small example:
+
+ DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
+ Sample Emacs primitive function.
+
+ The specified FILE is frobricated before it is fnozzled.
+ */
+ (file))
+ {
+ char *filename;
+
+ if (NILP(file))
+ return Qnil;
+
+ filename = (char *)XSTRING_DATA(file);
+ frob(filename);
+ return Qt;
+ }
+
+ The first argument is the name of the function as it will appear to
+the Lisp reader. This must be provided as a string. The second
+argument is the name of the actual C function that will be created.
+This is typically the Lisp function name with a preceding capital `F',
+with hyphens converted to underscores. This must be a valid C function
+name. Next come the minimum and maximum number of arguments,
+respectively. This is used to ensure that the correct number of
+arguments are passed to the function. Next is the `interactive'
+definition. If this function is meant to be run by a user
+interactively, then you need to specify the argument types and prompts
+in this string. Please consult the XEmacs Lisp manual for more
+details. Next comes a C comment that is the documentation for this
+function. This comment *must* exist. Last comes the list of function
+argument names, if any.
+
+\1f
+File: emodules.info, Node: Declaring Functions, Prev: Using DEFUN, Up: Defining Functions
+
+Declaring Functions
+===================
+
+ Simply writing the code for a function is not enough to make it
+availible to the Lisp reader. You have to, during module
+initialization, let the Lisp reader know about the new function. This
+is done by calling `DEFSUBR' with the name of the function. This is
+the sole purpose of the initialization function `syms_of_module'.
+*Note Required Functions::, for more details.
+
+ Each call to `DEFSUBR' takes as its only argument the name of the
+function, which is the same as the second argument to the call to
+`DEFUN'. Using the example function above, you would insert the
+following code in the `syms_of_module' function:
+
+ DEFSUBR(Fmy_function);
+
+ This call will instruct XEmacs to make the function visible to the
+Lisp reader and will prepare for the insertion of the documentation into
+the right place. Once this is done, the user can call the Lisp
+function `my-function', if it was defined as an interactive function
+(which in this case it was).
+
+ Thats all there is to defining and announcing new functions. The
+rules for what goes inside the functions, and how to write good
+modules, is beyond the scope of this document. Please consult the
+XEmacs internals manual for more details.
+
+\1f
+File: emodules.info, Node: Defining Variables, Next: Index, Prev: Defining Functions, Up: Top
+
+Defining Variables
+******************
+
+ Rarely will you write a module that only contains functions. It is
+common to also provide variables which can be used to control the
+behaviour of the function, or store the results of the function being
+executed. The actual C variable types are the same for modules and
+internal XEmacs primitives, and the declaration of the variables is
+identical.
+
+ *Note Adding Global Lisp Variables: (internals)Adding Global Lisp
+Variables, for more information on variables and naming conventions.
+
+ Once your variables are defined, you need to initialize them and make
+the Lisp reader aware of them. This is done in the `vars_of_module'
+initialization function using special XEmacs macros such as
+`DEFVAR_LISP', `DEFVAR_BOOL', `DEFVAR_INT' etc. The best way to see
+how to use these macros is to look at existing source code, or read the
+internals manual.
+
+ One *very* important difference between XEmacs variables and module
+variables is how you use pure space. Simply put, you *never* use pure
+space in XEmacs modules. The pure space storage is of a limited size,
+and is initialized propperly during the dumping of XEmacs. Because
+variables are being added dynamically to an already running XEmacs when
+you load a module, you cannot use pure space. Be warned: *do not use
+pure space in modules. Repeat, do not use pure space in modules.*
+Once again, to remove all doubts: *DO NOT USE PURE SPACE IN MODULES!!!*
+
+ Below is a small example which declares and initializes two
+variables. You will note that this code takes into account the fact
+that this module may very well be compiled into XEmacs itself. This is
+a prudent thing to do.
+
+ Lisp_Object Vsample_string;
+ int sample_boolean;
+
+ void
+ vars_of_module()
+ {
+ DEFVAR_LISP ("sample-string", &Vsample_string /*
+ This is a sample string, declared in a module.
+
+ Nothing magical about it.
+ */);
+
+ DEFVAR_BOOL("sample-boolean", &sample_boolean /*
+ *Sample user-settable boolean.
+ */);
+
+ sample_boolean = 0;
+ Vsample_string = build_string("My string");
+ }
+
+\1f
+File: emodules.info, Node: Index, Prev: Defining Variables, Up: Top
+
+Index
+*****
+
+* Menu:
+
+* annatomy: Annatomy of a Module.
+* compiler: Introduction.
+* compiling: Compile Mode.
+* config.h: Required Header File.
+* defining functions: Defining Functions.
+* defining objects: Defining Variables.
+* defining variables: Defining Variables.
+* DEFSUBR: Declaring Functions.
+* DEFUN: Using DEFUN.
+* DEFVAR_BOOL: Defining Variables.
+* DEFVAR_INT: Defining Variables.
+* DEFVAR_LISP: Defining Variables.
+* dependancies: Loading other Modules.
+* DLL: Introduction.
+* docs_of_module: Required Functions.
+* documentation <1>: Initialization Mode.
+* documentation: Introduction.
+* DSO: Introduction.
+* ellcc <1>: Introduction.
+* ellcc: Using ellcc.
+* ELLCC: Environment Variables.
+* ELLCFLAGS: Environment Variables.
+* ELLDLLFLAGS: Environment Variables.
+* ELLLD: Environment Variables.
+* ELLLDFLAGS: Environment Variables.
+* ELLMAKEDOC: Environment Variables.
+* ELLPICFLAGS: Environment Variables.
+* Emacs Modules: Introduction.
+* emodules.h: Required Header File.
+* emodules_load: Loading other Modules.
+* environment variables: Environment Variables.
+* format, module: Annatomy of a Module.
+* functions, declaring: Declaring Functions.
+* functions, defining: Using DEFUN.
+* functions, Lisp: Using DEFUN.
+* functions, required: Required Functions.
+* header files: Introduction.
+* help: Introduction.
+* include files: Required Header File.
+* initialization <1>: Required Variables.
+* initialization <2>: Initialization Mode.
+* initialization: Required Functions.
+* linker: Introduction.
+* linking: Link Mode.
+* module compiler: Using ellcc.
+* module format: Annatomy of a Module.
+* module skeleton: Annatomy of a Module.
+* modules_of_module <1>: Required Functions.
+* modules_of_module: Loading other Modules.
+* objects, defining: Defining Variables.
+* objects, Lisp: Defining Variables.
+* paths: Other ellcc options.
+* required functions: Required Functions.
+* required header: Required Header File.
+* required variables: Required Variables.
+* samples: Introduction.
+* shared object: Introduction.
+* skeleton, module: Annatomy of a Module.
+* subrs: Using DEFUN.
+* syms_of_module: Required Functions.
+* variables, defining: Defining Variables.
+* variables, Lisp: Defining Variables.
+* variables, required: Required Variables.
+* vars_of_module: Required Functions.
+
+
+\1f
+Tag Table:
+Node: Top\7f1562
+Node: Introduction\7f2908
+Node: Annatomy of a Module\7f7417
+Node: Required Header File\7f8233
+Node: Required Functions\7f10154
+Node: Required Variables\7f12403
+Node: Loading other Modules\7f15090
+Node: Using ellcc\7f17148
+Node: Compile Mode\7f18943
+Node: Initialization Mode\7f20311
+Node: Link Mode\7f25343
+Node: Other ellcc options\7f26490
+Node: Environment Variables\7f29070
+Node: Defining Functions\7f30761
+Node: Using DEFUN\7f32772
+Node: Declaring Functions\7f34483
+Node: Defining Variables\7f35826
+Node: Index\7f38071
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/external-widget.info, produced by Makeinfo
+version 1.68 from the input file external-widget.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* External Widget: (external-widget) External Client Widget.
+END-INFO-DIR-ENTRY
+
+\1f
+File: external-widget.info, Node: Top, Next: Using an External Client Widget, Up: (dir)
+
+ An "external client widget" is a widget that is part of another
+program but functions as an Emacs frame. This is intended to be a more
+powerful replacement for standard text widgets.
+
+* Menu:
+
+* Using an External Client Widget::
+* External Client Widget Resource Settings::
+* Motif-Specific Info About the External Client Widget::
+
+\1f
+File: external-widget.info, Node: Using an External Client Widget, Next: External Client Widget Resource Settings, Prev: Top, Up: Top
+
+Using an External Client Widget
+*******************************
+
+ There are three different implementations of the external client
+widget. One is designed for use in Motif applications and is linked
+with the option `-lextcli_Xm'. Another is designed for non-Motif
+applications that still use the X toolkit; it is linked with the option
+`-lextcli_Xt'. The third is designed for applications that do not use
+the X toolkit; it is linked with the option `-lextcli_Xlib'. In order
+to use an external client widget in a client program that uses the X
+toolkit (i.e. either of the first two options described above), simply
+create an instance of widget type ExternalClient and link your program
+with the appropriate library. The corresponding header file is called
+`ExternalClient.h'.
+
+ Documentation still needs to be provided for using the raw Xlib
+version of the external client widget.
+
+ The external client widget will not do anything until an instance of
+Emacs is told about this particular widget. To do that, call the
+function `make-frame', specifying a value for the frame parameter
+`window-id'. This value should be a string containing the decimal
+representation of the widget's X window ID number (this can be obtained
+by the Xt function `XtWindow()'). In order for the client program to
+communicate this information to Emacs, a method such as sending a
+ToolTalk message needs to be used.
+
+ Once `make-frame' has been called, Emacs will create a frame that
+occupies the client widget's window. This frame can be used just like
+any other frame in Emacs.
+
+\1f
+File: external-widget.info, Node: External Client Widget Resource Settings, Next: Motif-Specific Info About the External Client Widget, Prev: Using an External Client Widget, Up: Top
+
+External Client Widget Resource Settings
+****************************************
+
+ The external client widget is a subclass of the Motif widget
+XmPrimitive and thus inherits all its resources. In addition, the
+following new resources are defined:
+
+`deadShell (class DeadShell)'
+ A boolean resource indicating whether the last request to the
+ ExternalShell widget that contains the frame corresponding to this
+ widget timed out. If true, no further requests will be made (all
+ requests will automatically fail) until a response to the last
+ request is received. This resource should normally not be set by
+ the user.
+
+`shellTimeout (class ShellTimeout)'
+ A value specifying how long (in milliseconds) the client should
+ wait for a response when making a request to the corresponding
+ ExternalShell widget. If this timeout is exceeded, the client
+ will assume that the shell is dead and will fail the request and
+ all subsequent requests until a response to the request is
+ received. Default value is 5000, or 5 seconds.
+
+ The shell that contains the frame corresponding to an external client
+widget is of type ExternalShell, as opposed to standard frames, whose
+shell is of type TopLevelShell. The ExternalShell widget is a direct
+subclass of Shell and thus inherits its resources. In addition, the
+following new resources are defined:
+
+`window (class Window)'
+ The X window ID of the widget to use for this Emacs frame. This is
+ normally set by the call to `x-create-frame' and should not be
+ modified by the user.
+
+`deadClient (class DeadClient)'
+ A boolean resource indicating whether the last request to the
+ corresponding ExternalClient widget timed out. If true, no further
+ requests will be made (all requests will automatically fail) until
+ a response to the last request is received. This resource should
+ normally not be set by the user.
+
+`ClientTimeout (class ClientTimeout)'
+ A value specifying how long (in milliseconds) the shell should wait
+ for a response when making a request to the corresponding
+ ExternalClient widget. If this timeout is exceeded, the shell
+ will assume that the client is dead and will fail the request and
+ all subsequent requests until a response to the request is
+ received. Default value is 5000, or 5 seconds.
+
+ Note that the requests that are made between the client and the shell
+are primarily for handling query-geometry and geometry-manager requests
+made by parent or child widgets.
+
+\1f
+File: external-widget.info, Node: Motif-Specific Info About the External Client Widget, Prev: External Client Widget Resource Settings, Up: Top
+
+Motif-Specific Info About the External Client Widget
+****************************************************
+
+ By default, the external client widget has navigation type
+`XmTAB_GROUP'.
+
+ The widget traversal keystrokes are modified slightly from the
+standard XmPrimitive keystrokes. In particular, `<TAB>' alone does not
+traverse to the next widget (`Ctrl-<TAB>' must be used instead), but
+functions like a normal <TAB> in Emacs. This follows the semantics of
+the Motif text widget. The traversal keystrokes `Ctrl-<TAB>' and
+`Shift-<TAB>' are silently filtered by the external client widget and
+are not seen by Emacs.
+
+
+\1f
+Tag Table:
+Node: Top\7f258
+Node: Using an External Client Widget\7f688
+Node: External Client Widget Resource Settings\7f2403
+Node: Motif-Specific Info About the External Client Widget\7f5146
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/info.info, produced by Makeinfo version 1.68
+from the input file info.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Info: (info). Documentation browsing system.
+END-INFO-DIR-ENTRY
+
+ This file describes how to use Info, the on-line, menu-driven GNU
+documentation system.
+
+ Copyright (C) 1989, 92, 96, 97 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: info.info, Node: Top, Next: Getting Started, Up: (dir)
+
+Info: An Introduction
+*********************
+
+ Info is a program for reading documentation, which you are using now.
+
+ To learn how to use Info, type the command `h'. It brings you to a
+programmed instruction sequence.
+
+ To learn advanced Info commands, type `n' twice. This brings you to
+`Info for Experts', skipping over the `Getting Started' chapter.
+
+* Menu:
+
+* Getting Started:: Getting started using an Info reader.
+* Advanced Info:: Advanced commands within Info.
+* Create an Info File:: How to make your own Info file.
+* The Standalone Info Program: (info-stnd.info).
+
+\1f
+File: info.info, Node: Getting Started, Next: Advanced Info, Prev: Top, Up: Top
+
+Getting Started
+***************
+
+ This first part of the Info manual describes how to get around inside
+of Info. The second part of the manual describes various advanced Info
+commands, and how to write an Info as distinct from a Texinfo file.
+The third part is about how to generate Info files from Texinfo files.
+
+* Menu:
+
+* Help-Small-Screen:: Starting Info on a Small Screen
+* Help:: How to use Info
+* Help-P:: Returning to the Previous node
+* Help-^L:: The Space, Rubout, B and ^L commands.
+* Help-M:: Menus
+* Help-Adv:: Some advanced Info commands
+* Help-Q:: Quitting Info
+
+\1f
+File: info.info, Node: Help-Small-Screen, Next: Help, Up: Getting Started
+
+Starting Info on a Small Screen
+===============================
+
+ Since your terminal has an unusually small number of lines on its
+screen, it is necessary to give you special advice at the beginning.
+
+ If you see the text `--All----' at near the bottom right corner of
+the screen, it means the entire text you are looking at fits on the
+screen. If you see `--Top----' instead, it means that there is more
+text below that does not fit. To move forward through the text and see
+another screen full, press the Space bar, <SPC>. To move back up,
+press the key labeled `Backspace' or <Delete>.
+
+ Here are 40 lines of junk, so you can try Spaces and Deletes and see
+what they do. At the end are instructions of what you should do next.
+
+ This is line 17
+This is line 18
+This is line 19
+This is line 20
+This is line 21
+This is line 22
+This is line 23
+This is line 24
+This is line 25
+This is line 26
+This is line 27
+This is line 28
+This is line 29
+This is line 30
+This is line 31
+This is line 32
+This is line 33
+This is line 34
+This is line 35
+This is line 36
+This is line 37
+This is line 38
+This is line 39
+This is line 40
+This is line 41
+This is line 42
+This is line 43
+This is line 44
+This is line 45
+This is line 46
+This is line 47
+This is line 48
+This is line 49
+This is line 50
+This is line 51
+This is line 52
+This is line 53
+This is line 54
+This is line 55
+This is line 56
+If you have managed to get here, go back to the beginning with Delete,
+and come back here again, then you understand Space and Delete. So now
+type an `n' --just one character; don't type the quotes and don't type
+the Return key afterward-- to get to the normal start of the course.
+
+\1f
+File: info.info, Node: Help, Next: Help-P, Prev: Help-Small-Screen, Up: Getting Started
+
+How to use Info
+===============
+
+ You are talking to the program Info, for reading documentation.
+
+ Right now you are looking at one "Node" of Information. A node
+contains text describing a specific topic at a specific level of
+detail. This node's topic is "how to use Info".
+
+ The top line of a node is its "header". This node's header (look at
+it now) says that it is the node named `Help' in the file `info'. It
+says that the `Next' node after this one is the node called `Help-P'.
+An advanced Info command lets you go to any node whose name you know.
+
+ Besides a `Next', a node can have a `Previous' or an `Up'. This
+node has a `Previous' but no `Up', as you can see.
+
+ Now it is time to move on to the `Next' node, named `Help-P'.
+
+ >> Type `n' to move there. Type just one character; do not type
+the quotes and do not type a <RET> afterward.
+
+ `>>' in the margin means it is really time to try a command.
+
+\1f
+File: info.info, Node: Help-P, Next: Help-^L, Prev: Help, Up: Getting Started
+
+Returning to the Previous node
+==============================
+
+ This node is called `Help-P'. The `Previous' node, as you see, is
+`Help', which is the one you just came from using the `n' command.
+Another `n' command now would take you to the next node, `Help-^L'.
+
+ >> But do not do that yet. First, try the `p' command, which takes
+ you to the `Previous' node. When you get there, you can do an `n'
+again to return here.
+
+ This all probably seems insultingly simple so far, but *do not* be
+led into skimming. Things will get more complicated soon. Also, do
+not try a new command until you are told it is time to. Otherwise, you
+may make Info skip past an important warning that was coming up.
+
+ >> Now do an `n' to get to the node `Help-^L' and learn more.
+
+\1f
+File: info.info, Node: Help-^L, Next: Help-M, Prev: Help-P, Up: Getting Started
+
+The Space, Delete, B and ^L commands.
+=====================================
+
+ This node's header tells you that you are now at node `Help-^L', and
+that `p' would get you back to `Help-P'. The node's title is
+underlined; it says what the node is about (most nodes have titles).
+
+ This is a big node and it does not all fit on your display screen.
+You can tell that there is more that is not visible because you can see
+the string `--Top-----' rather than `--All----' near the bottom right
+corner of the screen.
+
+ The Space, Delete and `B' commands exist to allow you to "move
+around" in a node that does not all fit on the screen at once. Space
+moves forward, to show what was below the bottom of the screen. Delete
+moves backward, to show what was above the top of the screen (there is
+not anything above the top until you have typed some spaces).
+
+ >> Now try typing a Space (afterward, type a Delete to return here).
+
+ When you type the space, the two lines that were at the bottom of
+the screen appear at the top, followed by more lines. Delete takes the
+two lines from the top and moves them to the bottom, *usually*, but if
+there are not a full screen's worth of lines above them they may not
+make it all the way to the bottom.
+
+ If you type Space when there is no more to see, it rings the bell
+and otherwise does nothing. The same goes for Delete when the header
+of the node is visible.
+
+ If your screen is ever garbaged, you can tell Info to print it out
+again by typing `C-l' (`Control-L', that is--hold down "Control" and
+type an <L> or `l').
+
+ >> Type `C-l' now.
+
+ To move back to the beginning of the node you are on, you can type a
+lot of Deletes. You can also type simply `b' for beginning. >> Try
+that now. (We have put in enough verbiage to push this past the first
+screenful, but screens are so big nowadays that perhaps it isn't
+enough. You may need to shrink your Emacs or Info window.) Then come
+back, with Spaces.
+
+ If your screen is very tall, all of this node might fit at once. In
+that case, "b" won't do anything. Sorry; what can we do?
+
+ You have just learned a considerable number of commands. If you
+want to use one but have trouble remembering which, you should type a
+<?> which prints out a brief list of commands. When you are finished
+looking at the list, make it go away by pressing <SPC> repeatedly.
+
+ >> Type a <?> now. Press <SPC> to see consecutive screenfuls of >>
+the list until finished.
+
+ From now on, you will encounter large nodes without warning, and
+will be expected to know how to use Space and Delete to move around in
+them without being told. Since not all terminals have the same size
+screen, it would be impossible to warn you anyway.
+
+ >> Now type `n' to see the description of the `m' command.
+
+\1f
+File: info.info, Node: Help-M, Next: Help-Adv, Prev: Help-^L, Up: Getting Started
+
+Menus
+=====
+
+ Menus and the `m' command
+
+ With only the `n' and `p' commands for moving between nodes, nodes
+are restricted to a linear sequence. Menus allow a branching
+structure. A menu is a list of other nodes you can move to. It is
+actually just part of the text of the node formatted specially so that
+Info can interpret it. The beginning of a menu is always identified by
+a line which starts with `* Menu:'. A node contains a menu if and only
+if it has a line in it which starts that way. The only menu you can
+use at any moment is the one in the node you are in. To use a menu in
+any other node, you must move to that node first.
+
+ After the start of the menu, each line that starts with a `*'
+identifies one subtopic. The line usually contains a brief name for
+the subtopic (followed by a `:'), the name of the node that talks about
+that subtopic, and optionally some further description of the subtopic.
+Lines in the menu that do not start with a `*' have no special
+meaning--they are only for the human reader's benefit and do not define
+additional subtopics. Here is an example:
+
+ * Foo: FOO's Node This tells about FOO
+
+ The subtopic name is Foo, and the node describing it is `FOO's Node'.
+The rest of the line is just for the reader's Information. [[ But this
+line is not a real menu item, simply because there is no line above it
+which starts with `* Menu:'.]]
+
+ When you use a menu to go to another node (in a way that will be
+described soon), what you specify is the subtopic name, the first thing
+in the menu line. Info uses it to find the menu line, extracts the
+node name from it, and goes to that node. The reason that there is
+both a subtopic name and a node name is that the node name must be
+meaningful to the computer and may therefore have to be ugly looking.
+The subtopic name can be chosen just to be convenient for the user to
+specify. Often the node name is convenient for the user to specify and
+so both it and the subtopic name are the same. There is an
+abbreviation for this:
+
+ * Foo:: This tells about FOO
+
+This means that the subtopic name and node name are the same; they are
+both `Foo'.
+
+ >> Now use Spaces to find the menu in this node, then come back to
+the front with a `b' and some Spaces. As you see, a menu is
+actually visible in its node. If you cannot find a menu in a node
+by looking at it, then the node does not have a menu and the `m'
+command is not available.
+
+ The command to go to one of the subnodes is `m'--but *do not do it
+yet!* Before you use `m', you must understand the difference between
+commands and arguments. So far, you have learned several commands that
+do not need arguments. When you type one, Info processes it and is
+instantly ready for another command. The `m' command is different: it
+is incomplete without the "name of the subtopic". Once you have typed
+`m', Info tries to read the subtopic name.
+
+ Now look for the line containing many dashes near the bottom of the
+screen. There is one more line beneath that one, but usually it is
+blank. If it is empty, Info is ready for a command, such as `n' or `b'
+or Space or `m'. If that line contains text ending in a colon, it
+means Info is trying to read the "argument" to a command. At such
+times, commands do not work, because Info tries to use them as the
+argument. You must either type the argument and finish the command you
+started, or type `Control-g' to cancel the command. When you have done
+one of those things, the line becomes blank again.
+
+ The command to go to a subnode via a menu is `m'. After you type
+the `m', the line at the bottom of the screen says `Menu item: '. You
+must then type the name of the subtopic you want, and end it with a
+<RET>.
+
+ You can abbreviate the subtopic name. If the abbreviation is not
+unique, the first matching subtopic is chosen. Some menus put the
+shortest possible abbreviation for each subtopic name in capital
+letters, so you can see how much you need to type. It does not matter
+whether you use upper case or lower case when you type the subtopic.
+You should not put any spaces at the end, or inside of the item name,
+except for one space where a space appears in the item in the menu.
+
+ You can also use the "completion" feature to help enter the subtopic
+name. If you type the Tab key after entering part of a name, it will
+magically fill in more of the name--as much as follows uniquely from
+what you have entered.
+
+ If you move the cursor to one of the menu subtopic lines, then you do
+not need to type the argument: you just type a Return, and it stands for
+the subtopic of the line you are on.
+
+ Here is a menu to give you a chance to practice.
+
+ * Menu: The menu starts here.
+
+ This menu gives you three ways of going to one place, Help-FOO.
+
+ * Foo: Help-FOO. A node you can visit for fun.
+* Bar: Help-FOO. Strange! two ways to get to the same place.
+* Help-FOO:: And yet another!
+>> Now type just an `m' and see what happens:
+
+ Now you are "inside" an `m' command. Commands cannot be used now;
+the next thing you will type must be the name of a subtopic.
+
+ You can change your mind about doing the `m' by typing Control-g.
+
+ >> Try that now; notice the bottom line clear.
+
+ >> Then type another `m'.
+
+ >> Now type `BAR' item name. Do not type Return yet.
+
+ While you are typing the item name, you can use the Delete key to
+cancel one character at a time if you make a mistake.
+
+ >> Type one to cancel the `R'. You could type another `R' to
+replace it. You do not have to, since `BA' is a valid abbreviation.
+
+ >> Now you are ready to go. Type a <RET>.
+
+ After visiting Help-FOO, you should return here.
+
+ >> Type `n' to see more commands.
+
+ Here is another way to get to Help-FOO, a menu. You can ignore this
+if you want, or else try it (but then please come back to here).
+
+* Menu:
+
+* Help-FOO::
+
+\1f
+File: info.info, Node: Help-FOO, Up: Help-M
+
+The `u' command
+---------------
+
+ Congratulations! This is the node `Help-FOO'. Unlike the other
+nodes you have seen, this one has an `Up': `Help-M', the node you just
+came from via the `m' command. This is the usual convention--the nodes
+you reach from a menu have `Up' nodes that lead back to the menu.
+Menus move Down in the tree, and `Up' moves Up. `Previous', on the
+other hand, is usually used to "stay on the same level but go backwards"
+
+ You can go back to the node `Help-M' by typing the command `u' for
+"Up". That puts you at the *front* of the node--to get back to where
+you were reading you have to type some <SPC>s.
+
+ >> Now type `u' to move back up to `Help-M'.
+
+\1f
+File: info.info, Node: Help-Adv, Next: Help-Q, Prev: Help-M, Up: Getting Started
+
+Some advanced Info commands
+===========================
+
+ The course is almost over, so please stick with it to the end.
+
+ If you have been moving around to different nodes and wish to
+retrace your steps, the `l' command (`l' for "last") will do that, one
+node-step at a time. As you move from node to node, Info records the
+nodes where you have been in a special history list. The `l' command
+revisits nodes in the history list; each successive `l' command moves
+one step back through the history.
+
+ If you have been following directions, ad `l' command now will get
+you back to `Help-M'. Another `l' command would undo the `u' and get
+you back to `Help-FOO'. Another `l' would undo the `m' and get you
+back to `Help-M'.
+
+ >> Try typing three `l''s, pausing in between to see what each
+`l' does.
+
+ Then follow directions again and you will end up back here.
+
+ Note the difference between `l' and `p': `l' moves to where *you*
+last were, whereas `p' always moves to the node which the header says
+is the `Previous' node (from this node, to `Help-M').
+
+ The `d' command gets you instantly to the Directory node. This
+node, which is the first one you saw when you entered Info, has a menu
+which leads (directly, or indirectly through other menus), to all the
+nodes that exist.
+
+ >> Try doing a `d', then do an `l' to return here (yes, *do*
+return).
+
+ Sometimes, in Info documentation, you will see a cross reference.
+Cross references look like this: *Note Cross: Help-Cross. That is a
+real, live cross reference which is named `Cross' and points at the
+node named `Help-Cross'.
+
+ If you wish to follow a cross reference, you must use the `f'
+command. The `f' must be followed by the cross reference name (in this
+case, `Cross'). While you enter the name, you can use the Delete key
+to edit your input. If you change your mind about following any
+reference, you can use `Control-g' to cancel the command.
+
+ Completion is available in the `f' command; you can complete among
+all the cross reference names in the current node by typing a Tab.
+
+ >> Type `f', followed by `Cross', and a <RET>.
+
+ To get a list of all the cross references in the current node, you
+can type `?' after an `f'. The `f' continues to await a cross
+reference name even after printing the list, so if you don't actually
+want to follow a reference, you should type a `Control-g' to cancel the
+`f'.
+
+ >> Type "f?" to get a list of the cross references in this node.
+Then type a `Control-g' and see how the `f' gives up.
+
+ >> Now type `n' to see the last node of the course.
+
+\1f
+File: info.info, Node: Help-Cross, Up: Help-Adv
+
+The node reached by the cross reference in Info
+-----------------------------------------------
+
+ This is the node reached by the cross reference named `Cross'.
+
+ While this node is specifically intended to be reached by a cross
+reference, most cross references lead to nodes that "belong" someplace
+else far away in the structure of Info. So you cannot expect the
+footnote to have a `Next', `Previous' or `Up' pointing back to where
+you came from. In general, the `l' (el) command is the only way to get
+back there.
+
+ >> Type `l' to return to the node where the cross reference was.
+
+\1f
+File: info.info, Node: Help-Q, Prev: Help-Adv, Up: Getting Started
+
+Quitting Info
+=============
+
+ To get out of Info, back to what you were doing before, type `q' for
+"Quit".
+
+ This is the end of the course on using Info. There are some other
+commands that are meant for experienced users; they are useful, and you
+can find them by looking in the directory node for documentation on
+Info. Finding them will be a good exercise in using Info in the usual
+manner.
+
+ >> Type `d' to go to the Info directory node; then type `mInfo'
+and Return, to get to the node about Info and see what other help is
+available.
+
+\1f
+File: info.info, Node: Advanced Info, Next: Create an Info File, Prev: Getting Started, Up: Top
+
+Info for Experts
+****************
+
+ This chapter describes various advanced Info commands, and how to
+write an Info as distinct from a Texinfo file. (However, in most
+cases, writing a Texinfo file is better, since you can use it *both* to
+generate an Info file and to make a printed manual. *Note Overview of
+Texinfo: (texinfo)Top.)
+
+* Menu:
+
+* Expert:: Advanced Info commands: g, s, e, and 1 - 5.
+* Add:: Describes how to add new nodes to the hierarchy.
+ Also tells what nodes look like.
+* Menus:: How to add to or create menus in Info nodes.
+* Cross-refs:: How to add cross-references to Info nodes.
+* Tags:: How to make tag tables for Info files.
+* Checking:: Checking an Info File
+* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
+
+\1f
+File: info.info, Node: Expert, Next: Add, Up: Advanced Info
+
+Advanced Info Commands
+======================
+
+ `g', `s', `1', - `9', and `e'
+
+ If you know a node's name, you can go there by typing `g', the name,
+and <RET>. Thus, `gTop<RET>' would go to the node called `Top' in this
+file (its directory node). `gExpert<RET>' would come back here.
+
+ Unlike `m', `g' does not allow the use of abbreviations.
+
+ To go to a node in another file, you can include the filename in the
+node name by putting it at the front, in parentheses. Thus,
+`g(dir)Top<RET>' would go to the Info Directory node, which is node
+`Top' in the file `dir'.
+
+ The node name `*' specifies the whole file. So you can look at all
+of the current file by typing `g*<RET>' or all of any other file with
+`g(FILENAME)<RET>'.
+
+ The `s' command allows you to search a whole file for a string. It
+switches to the next node if and when that is necessary. You type `s'
+followed by the string to search for, terminated by <RET>. To search
+for the same string again, just `s' followed by <RET> will do. The
+file's nodes are scanned in the order they are in in the file, which
+has no necessary relationship to the order that they may be in in the
+tree structure of menus and `next' pointers. But normally the two
+orders are not very different. In any case, you can always do a `b' to
+find out what node you have reached, if the header is not visible (this
+can happen, because `s' puts your cursor at the occurrence of the
+string, not at the beginning of the node).
+
+ If you grudge the system each character of type-in it requires, you
+might like to use the commands `1', `2', `3', `4', ... `9'. They are
+short for the `m' command together with an argument. `1' goes through
+the first item in the current node's menu; `2' goes through the second
+item, etc.
+
+ If you display supports multiple fonts, and you are using Emacs' Info
+mode to read Info files, the `*' for the fifth menu item is underlines,
+and so is the `*' for the ninth item; these underlines make it easy to
+see at a glance which number to use for an item.
+
+ On ordinary terminals, you won't have underlining. If you need to
+actually count items, it is better to use `m' instead, and specify the
+name.
+
+ The Info command `e' changes from Info mode to an ordinary Emacs
+editing mode, so that you can edit the text of the current node. Type
+`C-c C-c' to switch back to Info. The `e' command is allowed only if
+the variable `Info-enable-edit' is non-`nil'.
+
+\1f
+File: info.info, Node: Add, Next: Menus, Prev: Expert, Up: Advanced Info
+
+Adding a new node to Info
+=========================
+
+ To add a new topic to the list in the Info directory, you must:
+ 1. Create some nodes, in some file, to document that topic.
+
+ 2. Put that topic in the menu in the directory. *Note Menu: Menus.
+
+ Usually, the way to create the nodes is with Texinfo *note Overview
+of Texinfo: (texinfo)Top.); this has the advantage that you can also
+make a printed manual from them. However, if you want to edit an Info
+file, here is how.
+
+ The new node can live in an existing documentation file, or in a new
+one. It must have a <^_> character before it (invisible to the user;
+this node has one but you cannot see it), and it ends with either a
+<^_>, a <^L>, or the end of file. Note: If you put in a <^L> to end a
+new node, be sure that there is a <^_> after it to start the next one,
+since <^L> cannot *start* a node. Also, a nicer way to make a node
+boundary be a page boundary as well is to put a <^L> *right after* the
+<^_>.
+
+ The <^_> starting a node must be followed by a newline or a <^L>
+newline, after which comes the node's header line. The header line
+must give the node's name (by which Info finds it), and state the names
+of the `Next', `Previous', and `Up' nodes (if there are any). As you
+can see, this node's `Up' node is the node `Top', which points at all
+the documentation for Info. The `Next' node is `Menus'.
+
+ The keywords "Node", "Previous", "Up", and "Next", may appear in any
+order, anywhere in the header line, but the recommended order is the
+one in this sentence. Each keyword must be followed by a colon, spaces
+and tabs, and then the appropriate name. The name may be terminated
+with a tab, a comma, or a newline. A space does not end it; node names
+may contain spaces. The case of letters in the names is insignificant.
+
+ A node name has two forms. A node in the current file is named by
+what appears after the `Node: ' in that node's first line. For
+example, this node's name is `Add'. A node in another file is named by
+`(FILENAME)NODE-WITHIN-FILE', as in `(info)Add' for this node. If the
+file name starts with "./", then it is relative to the current
+directory; otherwise, it is relative starting from the standard Info
+file directory of your site. The name `(FILENAME)Top' can be
+abbreviated to just `(FILENAME)'. By convention, the name `Top' is
+used for the "highest" node in any single file--the node whose `Up'
+points out of the file. The Directory node is `(dir)'. The `Top' node
+of a document file listed in the Directory should have an `Up: (dir)'
+in it.
+
+ The node name `*' is special: it refers to the entire file. Thus,
+`g*' shows you the whole current file. The use of the node `*' is to
+make it possible to make old-fashioned, unstructured files into nodes
+of the tree.
+
+ The `Node:' name, in which a node states its own name, must not
+contain a filename, since Info when searching for a node does not
+expect one to be there. The `Next', `Previous' and `Up' names may
+contain them. In this node, since the `Up' node is in the same file,
+it was not necessary to use one.
+
+ Note that the nodes in this file have a file name in the header
+line. The file names are ignored by Info, but they serve as comments
+to help identify the node for the user.
+
+\1f
+File: info.info, Node: Menus, Next: Cross-refs, Prev: Add, Up: Advanced Info
+
+How to Create Menus
+===================
+
+ Any node in the Info hierarchy may have a "menu"--a list of subnodes.
+The `m' command searches the current node's menu for the topic which it
+reads from the terminal.
+
+ A menu begins with a line starting with `* Menu:'. The rest of the
+line is a comment. After the starting line, every line that begins
+with a `* ' lists a single topic. The name of the topic-the argument
+that the user must give to the `m' command to select this topic--comes
+right after the star and space, and is followed by a colon, spaces and
+tabs, and the name of the node which discusses that topic. The node
+name, like node names following `Next', `Previous' and `Up', may be
+terminated with a tab, comma, or newline; it may also be terminated
+with a period.
+
+ If the node name and topic name are the same, then rather than
+giving the name twice, the abbreviation `* NAME::' may be used (and
+should be used, whenever possible, as it reduces the visual clutter in
+the menu).
+
+ It is considerate to choose the topic names so that they differ from
+each other very near the beginning--this allows the user to type short
+abbreviations. In a long menu, it is a good idea to capitalize the
+beginning of each item name which is the minimum acceptable
+abbreviation for it (a long menu is more than 5 or so entries).
+
+ The nodes listed in a node's menu are called its "subnodes", and it
+is their "superior". They should each have an `Up:' pointing at the
+superior. It is often useful to arrange all or most of the subnodes in
+a sequence of `Next' and `Previous' pointers so that someone who wants
+to see them all need not keep revisiting the Menu.
+
+ The Info Directory is simply the menu of the node `(dir)Top'--that
+is, node `Top' in file `.../info/dir'. You can put new entries in that
+menu just like any other menu. The Info Directory is *not* the same as
+the file directory called `info'. It happens that many of Info's files
+live on that file directory, but they do not have to; and files on that
+directory are not automatically listed in the Info Directory node.
+
+ Also, although the Info node graph is claimed to be a "hierarchy",
+in fact it can be *any* directed graph. Shared structures and pointer
+cycles are perfectly possible, and can be used if they are appropriate
+to the meaning to be expressed. There is no need for all the nodes in
+a file to form a connected structure. In fact, this file has two
+connected components. You are in one of them, which is under the node
+`Top'; the other contains the node `Help' which the `h' command goes
+to. In fact, since there is no garbage collector, nothing terrible
+happens if a substructure is not pointed to, but such a substructure is
+rather useless since nobody can ever find out that it exists.
+
+\1f
+File: info.info, Node: Cross-refs, Next: Tags, Prev: Menus, Up: Advanced Info
+
+Creating Cross References
+=========================
+
+ A cross reference can be placed anywhere in the text, unlike a menu
+item which must go at the front of a line. A cross reference looks
+like a menu item except that it has `*note' instead of `*'. It
+*cannot* be terminated by a `)', because `)''s are so often part of
+node names. If you wish to enclose a cross reference in parentheses,
+terminate it with a period first. Here are two examples of cross
+references pointers:
+
+ *Note details: commands. (See *note 3: Full Proof.)
+
+ They are just examples. The places they "lead to" do not really
+exist!
+
+\1f
+File: info.info, Node: Tags, Next: Checking, Prev: Cross-refs, Up: Advanced Info
+
+Tag Tables for Info Files
+=========================
+
+ You can speed up the access to nodes of a large Info file by giving
+it a tag table. Unlike the tag table for a program, the tag table for
+an Info file lives inside the file itself and is used automatically
+whenever Info reads in the file.
+
+ To make a tag table, go to a node in the file using Emacs Info mode
+and type `M-x Info-tagify'. Then you must use `C-x C-s' to save the
+file.
+
+ Once the Info file has a tag table, you must make certain it is up
+to date. If, as a result of deletion of text, any node moves back more
+than a thousand characters in the file from the position recorded in
+the tag table, Info will no longer be able to find that node. To
+update the tag table, use the `Info-tagify' command again.
+
+ An Info file tag table appears at the end of the file and looks like
+this:
+
+ ^_\f
+ Tag Table:
+ File: info, Node: Cross-refs^?21419
+ File: info, Node: Tags^?22145
+ ^_
+ End Tag Table
+
+Note that it contains one line per node, and this line contains the
+beginning of the node's header (ending just after the node name), a
+Delete character, and the character position in the file of the
+beginning of the node.
+
+\1f
+File: info.info, Node: Checking, Next: Emacs Info Variables, Prev: Tags, Up: Advanced Info
+
+Checking an Info File
+=====================
+
+ When creating an Info file, it is easy to forget the name of a node
+when you are making a pointer to it from another node. If you put in
+the wrong name for a node, this is not detected until someone tries to
+go through the pointer using Info. Verification of the Info file is an
+automatic process which checks all pointers to nodes and reports any
+pointers which are invalid. Every `Next', `Previous', and `Up' is
+checked, as is every menu item and every cross reference. In addition,
+any `Next' which does not have a `Previous' pointing back is reported.
+Only pointers within the file are checked, because checking pointers to
+other files would be terribly slow. But those are usually few.
+
+ To check an Info file, do `M-x Info-validate' while looking at any
+node of the file with Emacs Info mode.
+
+\1f
+File: info.info, Node: Emacs Info Variables, Prev: Checking, Up: Advanced Info
+
+Emacs Info-mode Variables
+=========================
+
+ The following variables may modify the behaviour of Info-mode in
+Emacs; you may wish to set one or several of these variables
+interactively, or in your `~/.emacs' init file. *Note Examining and
+Setting Variables: (emacs)Examining.
+
+`Info-enable-edit'
+ Set to `nil', disables the `e' (`Info-edit') command. A non-`nil'
+ value enables it. *Note Edit: Add.
+
+`Info-enable-active-nodes'
+ When set to a non-`nil' value, allows Info to execute Lisp code
+ associated with nodes. The Lisp code is executed when the node is
+ selected.
+
+`Info-directory-list'
+ The list of directories to search for Info files. Each element is
+ a string (directory name) or `nil' (try default directory).
+
+`Info-directory'
+ The standard directory for Info documentation files. Only used
+ when the function `Info-directory' is called.
+
+\1f
+File: info.info, Node: Create an Info File, Prev: Advanced Info, Up: Top
+
+Creating an Info File from a Makeinfo file
+******************************************
+
+ `makeinfo' is a utility that converts a Texinfo file into an Info
+file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
+functions that do the same.
+
+ *Note Creating an Info File: (texinfo)Create an Info File, to learn
+how to create an Info file from a Texinfo file.
+
+ *Note Overview of Texinfo: (texinfo)Top, to learn how to write a
+Texinfo file.
+
+
+\1f
+Tag Table:
+Node: Top\7f1085
+Node: Getting Started\7f1770
+Node: Help-Small-Screen\7f2518
+Node: Help\7f4267
+Node: Help-P\7f5297
+Node: Help-^L\7f6159
+Node: Help-M\7f9037
+Node: Help-FOO\7f15047
+Node: Help-Adv\7f15785
+Node: Help-Cross\7f18460
+Node: Help-Q\7f19106
+Node: Advanced Info\7f19733
+Node: Expert\7f20709
+Node: Add\7f23222
+Node: Menus\7f26581
+Node: Cross-refs\7f29455
+Node: Tags\7f30157
+Node: Checking\7f31459
+Node: Emacs Info Variables\7f32412
+Node: Create an Info File\7f33401
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+Indirect:
+internals.info-1: 1789
+internals.info-2: 45943
+internals.info-3: 93017
+internals.info-4: 141389
+internals.info-5: 183420
+internals.info-6: 232841
+internals.info-7: 281571
+internals.info-8: 330967
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f1789
+Node: A History of Emacs\7f6369
+Node: Through Version 18\7f7894
+Node: Lucid Emacs\7f11315
+Node: GNU Emacs 19\7f14333
+Node: GNU Emacs 20\7f16516
+Node: XEmacs\7f16943
+Node: XEmacs From the Outside\7f20122
+Node: The Lisp Language\7f21890
+Node: XEmacs From the Perspective of Building\7f31435
+Node: XEmacs From the Inside\7f37560
+Node: The XEmacs Object System (Abstractly Speaking)\7f45943
+Node: How Lisp Objects Are Represented in C\7f60031
+Node: Rules When Writing New C Code\7f68593
+Node: General Coding Rules\7f69397
+Node: Writing Lisp Primitives\7f74557
+Node: Adding Global Lisp Variables\7f85727
+Node: Coding for Mule\7f89365
+Node: Character-Related Data Types\7f90344
+Node: Working With Character and Byte Positions\7f93017
+Node: Conversion to and from External Data\7f96767
+Node: General Guidelines for Writing Mule-Aware Code\7f101648
+Node: An Example of Mule-Aware Code\7f103679
+Node: Techniques for XEmacs Developers\7f105666
+Node: A Summary of the Various XEmacs Modules\7f109437
+Node: Low-Level Modules\7f110257
+Node: Basic Lisp Modules\7f117779
+Node: Modules for Standard Editing Operations\7f126103
+Node: Editor-Level Control Flow Modules\7f131991
+Node: Modules for the Basic Displayable Lisp Objects\7f135438
+Node: Modules for other Display-Related Lisp Objects\7f137960
+Node: Modules for the Redisplay Mechanism\7f139038
+Node: Modules for Interfacing with the File System\7f141389
+Node: Modules for Other Aspects of the Lisp Interpreter and Object System\7f145087
+Node: Modules for Interfacing with the Operating System\7f150541
+Node: Modules for Interfacing with X Windows\7f158202
+Node: Modules for Internationalization\7f161638
+Node: Allocation of Objects in XEmacs Lisp\7f164275
+Node: Introduction to Allocation\7f164829
+Node: Garbage Collection\7f170292
+Node: GCPROing\7f173245
+Node: Garbage Collection - Step by Step\7f180056
+Node: Invocation\7f180448
+Node: garbage_collect_1\7f183420
+Node: mark_object\7f192900
+Node: gc_sweep\7f194712
+Node: sweep_lcrecords_1\7f199775
+Node: compact_string_chars\7f200770
+Node: sweep_strings\7f202950
+Node: sweep_bit_vectors_1\7f203915
+Node: Integers and Characters\7f204591
+Node: Allocation from Frob Blocks\7f205343
+Node: lrecords\7f206947
+Node: Low-level allocation\7f219409
+Node: Pure Space\7f223577
+Node: Cons\7f223752
+Node: Vector\7f224468
+Node: Bit Vector\7f225045
+Node: Symbol\7f225538
+Node: Marker\7f226107
+Node: String\7f226662
+Node: Compiled Function\7f230277
+Node: Events and the Event Loop\7f230446
+Node: Introduction to Events\7f230925
+Node: Main Loop\7f232841
+Node: Specifics of the Event Gathering Mechanism\7f236417
+Node: Specifics About the Emacs Event\7f248870
+Node: The Event Stream Callback Routines\7f249125
+Node: Other Event Loop Functions\7f249370
+Node: Converting Events\7f250510
+Node: Dispatching Events; The Command Builder\7f251119
+Node: Evaluation; Stack Frames; Bindings\7f251354
+Node: Evaluation\7f251696
+Node: Dynamic Binding; The specbinding Stack; Unwind-Protects\7f258236
+Node: Simple Special Forms\7f260620
+Node: Catch and Throw\7f261402
+Node: Symbols and Variables\7f263977
+Node: Introduction to Symbols\7f264241
+Node: Obarrays\7f265279
+Node: Symbol Values\7f268812
+Node: Buffers and Textual Representation\7f271100
+Node: Introduction to Buffers\7f271758
+Node: The Text in a Buffer\7f274421
+Node: Buffer Lists\7f281571
+Node: Markers and Extents\7f283522
+Node: Bufbytes and Emchars\7f285787
+Node: The Buffer Object\7f286002
+Node: MULE Character Sets and Encodings\7f289482
+Node: Character Sets\7f290544
+Node: Encodings\7f293987
+Node: Japanese EUC (Extended Unix Code)\7f295054
+Node: JIS7\7f295868
+Node: Internal Mule Encodings\7f297218
+Node: Internal String Encoding\7f299048
+Node: Internal Character Encoding\7f301161
+Node: CCL\7f302885
+Node: The Lisp Reader and Compiler\7f309637
+Node: Lstreams\7f309850
+Node: Creating an Lstream\7f310881
+Node: Lstream Types\7f312091
+Node: Lstream Functions\7f312343
+Node: Lstream Methods\7f315865
+Node: Consoles; Devices; Frames; Windows\7f318994
+Node: Introduction to Consoles; Devices; Frames; Windows\7f319309
+Node: Point\7f321801
+Node: Window Hierarchy\7f323080
+Node: The Window Object\7f327530
+Node: The Redisplay Mechanism\7f330967
+Node: Critical Redisplay Sections\7f331759
+Node: Line Start Cache\7f332714
+Node: Redisplay Piece by Piece\7f335951
+Node: Extents\7f337987
+Node: Introduction to Extents\7f338525
+Node: Extent Ordering\7f339651
+Node: Format of the Extent Info\7f340892
+Node: Zero-Length Extents\7f342780
+Node: Mathematics of Extent Ordering\7f344178
+Node: Extent Fragments\7f348935
+Node: Faces\7f350022
+Node: Glyphs\7f350138
+Node: Specifiers\7f353156
+Node: Menus\7f353285
+Node: Subprocesses\7f355543
+Node: Interface to X Windows\7f357519
+Node: Index\7f357690
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: Top, Next: A History of Emacs, Prev: (dir), Up: (dir)
+
+ This Info file contains v1.0 of the XEmacs Internals Manual.
+
+* Menu:
+
+* A History of Emacs:: Times, dates, important events.
+* XEmacs From the Outside:: A broad conceptual overview.
+* The Lisp Language:: An overview.
+* XEmacs From the Perspective of Building::
+* XEmacs From the Inside::
+* The XEmacs Object System (Abstractly Speaking)::
+* How Lisp Objects Are Represented in C::
+* Rules When Writing New C Code::
+* A Summary of the Various XEmacs Modules::
+* Allocation of Objects in XEmacs Lisp::
+* Events and the Event Loop::
+* Evaluation; Stack Frames; Bindings::
+* Symbols and Variables::
+* Buffers and Textual Representation::
+* MULE Character Sets and Encodings::
+* The Lisp Reader and Compiler::
+* Lstreams::
+* Consoles; Devices; Frames; Windows::
+* The Redisplay Mechanism::
+* Extents::
+* Faces::
+* Glyphs::
+* Specifiers::
+* Menus::
+* Subprocesses::
+* Interface to X Windows::
+* Index:: Index including concepts, functions, variables,
+ and other terms.
+
+ -- The Detailed Node Listing --
+
+Here are other nodes that are inferiors of those already listed,
+mentioned here so you can get to them in one step:
+
+A History of Emacs
+
+* Through Version 18:: Unification prevails.
+* Lucid Emacs:: One version 19 Emacs.
+* GNU Emacs 19:: The other version 19 Emacs.
+* XEmacs:: The continuation of Lucid Emacs.
+
+Rules When Writing New C Code
+
+* General Coding Rules::
+* Writing Lisp Primitives::
+* Adding Global Lisp Variables::
+* Techniques for XEmacs Developers::
+
+A Summary of the Various XEmacs Modules
+
+* Low-Level Modules::
+* Basic Lisp Modules::
+* Modules for Standard Editing Operations::
+* Editor-Level Control Flow Modules::
+* Modules for the Basic Displayable Lisp Objects::
+* Modules for other Display-Related Lisp Objects::
+* Modules for the Redisplay Mechanism::
+* Modules for Interfacing with the File System::
+* Modules for Other Aspects of the Lisp Interpreter and Object System::
+* Modules for Interfacing with the Operating System::
+* Modules for Interfacing with X Windows::
+* Modules for Internationalization::
+
+Allocation of Objects in XEmacs Lisp
+
+* Introduction to Allocation::
+* Garbage Collection::
+* GCPROing::
+* Garbage Collection - Step by Step::
+* Integers and Characters::
+* Allocation from Frob Blocks::
+* lrecords::
+* Low-level allocation::
+* Pure Space::
+* Cons::
+* Vector::
+* Bit Vector::
+* Symbol::
+* Marker::
+* String::
+* Compiled Function::
+
+Events and the Event Loop
+
+* Introduction to Events::
+* Main Loop::
+* Specifics of the Event Gathering Mechanism::
+* Specifics About the Emacs Event::
+* The Event Stream Callback Routines::
+* Other Event Loop Functions::
+* Converting Events::
+* Dispatching Events; The Command Builder::
+
+Evaluation; Stack Frames; Bindings
+
+* Evaluation::
+* Dynamic Binding; The specbinding Stack; Unwind-Protects::
+* Simple Special Forms::
+* Catch and Throw::
+
+Symbols and Variables
+
+* Introduction to Symbols::
+* Obarrays::
+* Symbol Values::
+
+Buffers and Textual Representation
+
+* Introduction to Buffers:: A buffer holds a block of text such as a file.
+* The Text in a Buffer:: Representation of the text in a buffer.
+* Buffer Lists:: Keeping track of all buffers.
+* Markers and Extents:: Tagging locations within a buffer.
+* Bufbytes and Emchars:: Representation of individual characters.
+* The Buffer Object:: The Lisp object corresponding to a buffer.
+
+MULE Character Sets and Encodings
+
+* Character Sets::
+* Encodings::
+* Internal Mule Encodings::
+
+Encodings
+
+* Japanese EUC (Extended Unix Code)::
+* JIS7::
+
+Internal Mule Encodings
+
+* Internal String Encoding::
+* Internal Character Encoding::
+
+The Lisp Reader and Compiler
+
+Lstreams
+
+Consoles; Devices; Frames; Windows
+
+* Introduction to Consoles; Devices; Frames; Windows::
+* Point::
+* Window Hierarchy::
+
+The Redisplay Mechanism
+
+* Critical Redisplay Sections::
+* Line Start Cache::
+
+Extents
+
+* Introduction to Extents:: Extents are ranges over text, with properties.
+* Extent Ordering:: How extents are ordered internally.
+* Format of the Extent Info:: The extent information in a buffer or string.
+* Zero-Length Extents:: A weird special case.
+* Mathematics of Extent Ordering:: A rigorous foundation.
+* Extent Fragments:: Cached information useful for redisplay.
+
+Faces
+
+Glyphs
+
+Specifiers
+
+Menus
+
+Subprocesses
+
+Interface to X Windows
+
+\1f
+File: internals.info, Node: A History of Emacs, Next: XEmacs From the Outside, Prev: Top, Up: Top
+
+A History of Emacs
+******************
+
+ XEmacs is a powerful, customizable text editor and development
+environment. It began as Lucid Emacs, which was in turn derived from
+GNU Emacs, a program written by Richard Stallman of the Free Software
+Foundation. GNU Emacs dates back to the 1970's, and was modelled after
+a package called "Emacs", written in 1976, that was a set of macros on
+top of TECO, an old, old text editor written at MIT on the DEC PDP 10
+under one of the earliest time-sharing operating systems, ITS
+(Incompatible Timesharing System). (ITS dates back well before Unix.)
+ITS, TECO, and Emacs were products of a group of people at MIT who
+called themselves "hackers", who shared an idealistic belief system
+about the free exchange of information and were fanatical in their
+devotion to and time spent with computers. (The hacker subculture dates
+back to the late 1950's at MIT and is described in detail in Steven
+Levy's book `Hackers'. This book also includes a lot of information
+about Stallman himself and the development of Lisp, a programming
+language developed at MIT that underlies Emacs.)
+
+* Menu:
+
+* Through Version 18:: Unification prevails.
+* Lucid Emacs:: One version 19 Emacs.
+* GNU Emacs 19:: The other version 19 Emacs.
+* GNU Emacs 20:: The other version 20 Emacs.
+* XEmacs:: The continuation of Lucid Emacs.
+
+\1f
+File: internals.info, Node: Through Version 18, Next: Lucid Emacs, Up: A History of Emacs
+
+Through Version 18
+==================
+
+ Although the history of the early versions of GNU Emacs is unclear,
+the history is well-known from the middle of 1985. A time line is:
+
+ * GNU Emacs version 15 (15.34) was released sometime in 1984 or 1985
+ and shared some code with a version of Emacs written by James
+ Gosling (the same James Gosling who later created the Java
+ language).
+
+ * GNU Emacs version 16 (first released version was 16.56) was
+ released on July 15, 1985. All Gosling code was removed due to
+ potential copyright problems with the code.
+
+ * version 16.57: released on September 16, 1985.
+
+ * versions 16.58, 16.59: released on September 17, 1985.
+
+ * version 16.60: released on September 19, 1985. These later
+ version 16's incorporated patches from the net, esp. for getting
+ Emacs to work under System V.
+
+ * version 17.36 (first official v17 release) released on December 20,
+ 1985. Included a TeX-able user manual. First official unpatched
+ version that worked on vanilla System V machines.
+
+ * version 17.43 (second official v17 release) released on January 25,
+ 1986.
+
+ * version 17.45 released on January 30, 1986.
+
+ * version 17.46 released on February 4, 1986.
+
+ * version 17.48 released on February 10, 1986.
+
+ * version 17.49 released on February 12, 1986.
+
+ * version 17.55 released on March 18, 1986.
+
+ * version 17.57 released on March 27, 1986.
+
+ * version 17.58 released on April 4, 1986.
+
+ * version 17.61 released on April 12, 1986.
+
+ * version 17.63 released on May 7, 1986.
+
+ * version 17.64 released on May 12, 1986.
+
+ * version 18.24 (a beta version) released on October 2, 1986.
+
+ * version 18.30 (a beta version) released on November 15, 1986.
+
+ * version 18.31 (a beta version) released on November 23, 1986.
+
+ * version 18.32 (a beta version) released on December 7, 1986.
+
+ * version 18.33 (a beta version) released on December 12, 1986.
+
+ * version 18.35 (a beta version) released on January 5, 1987.
+
+ * version 18.36 (a beta version) released on January 21, 1987.
+
+ * January 27, 1987: The Great Usenet Renaming. net.emacs is now
+ comp.emacs.
+
+ * version 18.37 (a beta version) released on February 12, 1987.
+
+ * version 18.38 (a beta version) released on March 3, 1987.
+
+ * version 18.39 (a beta version) released on March 14, 1987.
+
+ * version 18.40 (a beta version) released on March 18, 1987.
+
+ * version 18.41 (the first "official" release) released on March 22,
+ 1987.
+
+ * version 18.45 released on June 2, 1987.
+
+ * version 18.46 released on June 9, 1987.
+
+ * version 18.47 released on June 18, 1987.
+
+ * version 18.48 released on September 3, 1987.
+
+ * version 18.49 released on September 18, 1987.
+
+ * version 18.50 released on February 13, 1988.
+
+ * version 18.51 released on May 7, 1988.
+
+ * version 18.52 released on September 1, 1988.
+
+ * version 18.53 released on February 24, 1989.
+
+ * version 18.54 released on April 26, 1989.
+
+ * version 18.55 released on August 23, 1989. This is the earliest
+ version that is still available by FTP.
+
+ * version 18.56 released on January 17, 1991.
+
+ * version 18.57 released late January, 1991.
+
+ * version 18.58 released ?????.
+
+ * version 18.59 released October 31, 1992.
+
+\1f
+File: internals.info, Node: Lucid Emacs, Next: GNU Emacs 19, Prev: Through Version 18, Up: A History of Emacs
+
+Lucid Emacs
+===========
+
+ Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of
+C++ and Lisp development environments. It began when Lucid decided they
+wanted to use Emacs as the editor and cornerstone of their C++
+development environment (called "Energize"). They needed many features
+that were not available in the existing version of GNU Emacs (version
+18.5something), in particular good and integrated support for GUI
+elements such as mouse support, multiple fonts, multiple window-system
+windows, etc. A branch of GNU Emacs called Epoch, written at the
+University of Illinois, existed that supplied many of these features;
+however, Lucid needed more than what existed in Epoch. At the time, the
+Free Software Foundation was working on version 19 of Emacs (this was
+sometime around 1991), which was planned to have similar features, and
+so Lucid decided to work with the Free Software Foundation. Their plan
+was to add features that they needed, and coordinate with the FSF so
+that the features would get included back into Emacs version 19.
+
+ Delays in the release of version 19 occurred, however (resulting in
+it finally being released more than a year after what was initially
+planned), and Lucid encountered unexpected technical resistance in
+getting their changes merged back into version 19, so they decided to
+release their own version of Emacs, which became Lucid Emacs 19.0.
+
+ The initial authors of Lucid Emacs were Matthieu Devin, Harlan
+Sexton, and Eric Benson, and the work was later taken over by Jamie
+Zawinski, who became "Mr. Lucid Emacs" for many releases.
+
+ A time line for Lucid Emacs/XEmacs is
+
+ * version 19.0 shipped with Energize 1.0, April 1992.
+
+ * version 19.1 released June 4, 1992.
+
+ * version 19.2 released June 19, 1992.
+
+ * version 19.3 released September 9, 1992.
+
+ * version 19.4 released January 21, 1993.
+
+ * version 19.5 was a repackaging of 19.4 with a few bug fixes and
+ shipped with Energize 2.0. Never released to the net.
+
+ * version 19.6 released April 9, 1993.
+
+ * version 19.7 was a repackaging of 19.6 with a few bug fixes and
+ shipped with Energize 2.1. Never released to the net.
+
+ * version 19.8 released September 6, 1993.
+
+ * version 19.9 released January 12, 1994.
+
+ * version 19.10 released May 27, 1994.
+
+ * version 19.11 (first XEmacs) released September 13, 1994.
+
+ * version 19.12 released June 23, 1995.
+
+ * version 19.13 released September 1, 1995.
+
+ * version 19.14 released June 23, 1996.
+
+ * version 20.0 released February 9, 1997.
+
+ * version 19.15 released March 28, 1997.
+
+ * version 20.1 (not released to the net) April 15, 1997.
+
+ * version 20.2 released May 16, 1997.
+
+ * version 19.16 released October 31, 1997.
+
+ * version 20.3 (the first stable version of XEmacs 20.x) released
+ November 30, 1997. version 20.4 released February 28, 1998.
+
+\1f
+File: internals.info, Node: GNU Emacs 19, Next: GNU Emacs 20, Prev: Lucid Emacs, Up: A History of Emacs
+
+GNU Emacs 19
+============
+
+ About a year after the initial release of Lucid Emacs, the FSF
+released a beta of their version of Emacs 19 (referred to here as "GNU
+Emacs"). By this time, the current version of Lucid Emacs was 19.6.
+(Strangely, the first released beta from the FSF was GNU Emacs 19.7.) A
+time line for GNU Emacs version 19 is
+
+ * version 19.8 (beta) released May 27, 1993.
+
+ * version 19.9 (beta) released May 27, 1993.
+
+ * version 19.10 (beta) released May 30, 1993.
+
+ * version 19.11 (beta) released June 1, 1993.
+
+ * version 19.12 (beta) released June 2, 1993.
+
+ * version 19.13 (beta) released June 8, 1993.
+
+ * version 19.14 (beta) released June 17, 1993.
+
+ * version 19.15 (beta) released June 19, 1993.
+
+ * version 19.16 (beta) released July 6, 1993.
+
+ * version 19.17 (beta) released late July, 1993.
+
+ * version 19.18 (beta) released August 9, 1993.
+
+ * version 19.19 (beta) released August 15, 1993.
+
+ * version 19.20 (beta) released November 17, 1993.
+
+ * version 19.21 (beta) released November 17, 1993.
+
+ * version 19.22 (beta) released November 28, 1993.
+
+ * version 19.23 (beta) released May 17, 1994.
+
+ * version 19.24 (beta) released May 16, 1994.
+
+ * version 19.25 (beta) released June 3, 1994.
+
+ * version 19.26 (beta) released September 11, 1994.
+
+ * version 19.27 (beta) released September 14, 1994.
+
+ * version 19.28 (first "official" release) released November 1, 1994.
+
+ * version 19.29 released June 21, 1995.
+
+ * version 19.30 released November 24, 1995.
+
+ * version 19.31 released May 25, 1996.
+
+ * version 19.32 released July 31, 1996.
+
+ * version 19.33 released August 11, 1996.
+
+ * version 19.34 released August 21, 1996.
+
+ * version 19.34b released September 6, 1996.
+
+ In some ways, GNU Emacs 19 was better than Lucid Emacs; in some ways,
+worse. Lucid soon began incorporating features from GNU Emacs 19 into
+Lucid Emacs; the work was mostly done by Richard Mlynarik, who had been
+working on and using GNU Emacs for a long time (back as far as version
+16 or 17).
+
+\1f
+File: internals.info, Node: GNU Emacs 20, Next: XEmacs, Prev: GNU Emacs 19, Up: A History of Emacs
+
+GNU Emacs 20
+============
+
+ On February 2, 1997 work began on GNU Emacs to integrate Mule. The
+first release was made in September of that year.
+
+ A timeline for Emacs 20 is
+
+ * version 20.1 released September 17, 1997.
+
+ * version 20.2 released September 20, 1997.
+
+ * version 20.3 released August 19, 1998.
+
+\1f
+File: internals.info, Node: XEmacs, Prev: GNU Emacs 20, Up: A History of Emacs
+
+XEmacs
+======
+
+ Around the time that Lucid was developing Energize, Sun Microsystems
+was developing their own development environment (called "SPARCWorks")
+and also decided to use Emacs. They joined forces with the Epoch team
+at the University of Illinois and later with Lucid. The maintainer of
+the last-released version of Epoch was Marc Andreessen, but he dropped
+out and the Epoch project, headed by Simon Kaplan, lured Chuck Thompson
+away from a system administration job to become the primary Lucid Emacs
+author for Epoch and Sun. Chuck's area of specialty became the
+redisplay engine (he replaced the old Lucid Emacs redisplay engine with
+a ported version from Epoch and then later rewrote it from scratch).
+Sun also hired Ben Wing (the author of Win-Emacs, a port of Lucid Emacs
+to Microsoft Windows 3.1) in 1993, for what was initially a one-month
+contract to fix some event problems but later became a many-year
+involvement, punctuated by a six-month contract with Amdahl Corporation.
+
+ In 1994, Sun and Lucid agreed to rename Lucid Emacs to XEmacs (a name
+not favorable to either company); the first release called XEmacs was
+version 19.11. In June 1994, Lucid folded and Jamie quit to work for
+the newly formed Mosaic Communications Corp., later Netscape
+Communications Corp. (co-founded by the same Marc Andreessen, who had
+quit his Epoch job to work on a graphical browser for the World Wide
+Web). Chuck then become the primary maintainer of XEmacs, and put out
+versions 19.11 through 19.14 in conjunction with Ben. For 19.12 and
+19.13, Chuck added the new redisplay and many other display improvements
+and Ben added MULE support (support for Asian and other languages) and
+redesigned most of the internal Lisp subsystems to better support the
+MULE work and the various other features being added to XEmacs. After
+19.14 Chuck retired as primary maintainer and Steve Baur stepped in.
+
+ Soon after 19.13 was released, work began in earnest on the MULE
+internationalization code and the source tree was divided into two
+development paths. The MULE version was initially called 19.20, but was
+soon renamed to 20.0. In 1996 Martin Buchholz of Sun Microsystems took
+over the care and feeding of it and worked on it in parallel with the
+19.14 development that was occurring at the same time. After much work
+by Martin, it was decided to release 20.0 ahead of 19.15 in February
+1997. The source tree remained divided until 20.2 when the version 19
+source was finally retired at version 19.16.
+
+ In 1997, Sun finally dropped all pretense of support for XEmacs and
+Martin Buchholz left the company in November. Since then, and mostly
+for the previous year, because Steve Baur was never paid to work on
+XEmacs, XEmacs has existed solely on the contributions of volunteers
+from the Free Software Community. Starting from 1997, Hrvoje Niksic and
+Kyle Jones have figured prominently in XEmacs development.
+
+ Many attempts have been made to merge XEmacs and GNU Emacs, but they
+have consistently failed.
+
+ A more detailed history is contained in the XEmacs About page.
+
+\1f
+File: internals.info, Node: XEmacs From the Outside, Next: The Lisp Language, Prev: A History of Emacs, Up: Top
+
+XEmacs From the Outside
+***********************
+
+ XEmacs appears to the outside world as an editor, but it is really a
+Lisp environment. At its heart is a Lisp interpreter; it also
+"happens" to contain many specialized object types (e.g. buffers,
+windows, frames, events) that are useful for implementing an editor.
+Some of these objects (in particular windows and frames) have
+displayable representations, and XEmacs provides a function
+`redisplay()' that ensures that the display of all such objects matches
+their internal state. Most of the time, a standard Lisp environment is
+in a "read-eval-print" loop - i.e. "read some Lisp code, execute it,
+and print the results". XEmacs has a similar loop:
+
+ * read an event
+
+ * dispatch the event (i.e. "do it")
+
+ * redisplay
+
+ Reading an event is done using the Lisp function `next-event', which
+waits for something to happen (typically, the user presses a key or
+moves the mouse) and returns an event object describing this.
+Dispatching an event is done using the Lisp function `dispatch-event',
+which looks up the event in a keymap object (a particular kind of
+object that associates an event with a Lisp function) and calls that
+function. The function "does" what the user has requested by changing
+the state of particular frame objects, buffer objects, etc. Finally,
+`redisplay()' is called, which updates the display to reflect those
+changes just made. Thus is an "editor" born.
+
+ Note that you do not have to use XEmacs as an editor; you could just
+as well make it do your taxes, compute pi, play bridge, etc. You'd just
+have to write functions to do those operations in Lisp.
+
+\1f
+File: internals.info, Node: The Lisp Language, Next: XEmacs From the Perspective of Building, Prev: XEmacs From the Outside, Up: Top
+
+The Lisp Language
+*****************
+
+ Lisp is a general-purpose language that is higher-level than C and in
+many ways more powerful than C. Powerful dialects of Lisp such as
+Common Lisp are probably much better languages for writing very large
+applications than is C. (Unfortunately, for many non-technical reasons
+C and its successor C++ have become the dominant languages for
+application development. These languages are both inadequate for
+extremely large applications, which is evidenced by the fact that newer,
+larger programs are becoming ever harder to write and are requiring ever
+more programmers despite great increases in C development environments;
+and by the fact that, although hardware speeds and reliability have been
+growing at an exponential rate, most software is still generally
+considered to be slow and buggy.)
+
+ The new Java language holds promise as a better general-purpose
+development language than C. Java has many features in common with
+Lisp that are not shared by C (this is not a coincidence, since Java
+was designed by James Gosling, a former Lisp hacker). This will be
+discussed more later.
+
+ For those used to C, here is a summary of the basic differences
+between C and Lisp:
+
+ 1. Lisp has an extremely regular syntax. Every function, expression,
+ and control statement is written in the form
+
+ (FUNC ARG1 ARG2 ...)
+
+ This is as opposed to C, which writes functions as
+
+ func(ARG1, ARG2, ...)
+
+ but writes expressions involving operators as (e.g.)
+
+ ARG1 + ARG2
+
+ and writes control statements as (e.g.)
+
+ while (EXPR) { STATEMENT1; STATEMENT2; ... }
+
+ Lisp equivalents of the latter two would be
+
+ (+ ARG1 ARG2 ...)
+
+ and
+
+ (while EXPR STATEMENT1 STATEMENT2 ...)
+
+ 2. Lisp is a safe language. Assuming there are no bugs in the Lisp
+ interpreter/compiler, it is impossible to write a program that
+ "core dumps" or otherwise causes the machine to execute an illegal
+ instruction. This is very different from C, where perhaps the most
+ common outcome of a bug is exactly such a crash. A corollary of
+ this is that the C operation of casting a pointer is impossible
+ (and unnecessary) in Lisp, and that it is impossible to access
+ memory outside the bounds of an array.
+
+ 3. Programs and data are written in the same form. The
+ parenthesis-enclosing form described above for statements is the
+ same form used for the most common data type in Lisp, the list.
+ Thus, it is possible to represent any Lisp program using Lisp data
+ types, and for one program to construct Lisp statements and then
+ dynamically "evaluate" them, or cause them to execute.
+
+ 4. All objects are "dynamically typed". This means that part of every
+ object is an indication of what type it is. A Lisp program can
+ manipulate an object without knowing what type it is, and can
+ query an object to determine its type. This means that,
+ correspondingly, variables and function parameters can hold
+ objects of any type and are not normally declared as being of any
+ particular type. This is opposed to the "static typing" of C,
+ where variables can hold exactly one type of object and must be
+ declared as such, and objects do not contain an indication of
+ their type because it's implicit in the variables they are stored
+ in. It is possible in C to have a variable hold different types
+ of objects (e.g. through the use of `void *' pointers or
+ variable-argument functions), but the type information must then be
+ passed explicitly in some other fashion, leading to additional
+ program complexity.
+
+ 5. Allocated memory is automatically reclaimed when it is no longer
+ in use. This operation is called "garbage collection" and
+ involves looking through all variables to see what memory is being
+ pointed to, and reclaiming any memory that is not pointed to and
+ is thus "inaccessible" and out of use. This is as opposed to C,
+ in which allocated memory must be explicitly reclaimed using
+ `free()'. If you simply drop all pointers to memory without
+ freeing it, it becomes "leaked" memory that still takes up space.
+ Over a long period of time, this can cause your program to grow
+ and grow until it runs out of memory.
+
+ 6. Lisp has built-in facilities for handling errors and exceptions.
+ In C, when an error occurs, usually either the program exits
+ entirely or the routine in which the error occurs returns a value
+ indicating this. If an error occurs in a deeply-nested routine,
+ then every routine currently called must unwind itself normally
+ and return an error value back up to the next routine. This means
+ that every routine must explicitly check for an error in all the
+ routines it calls; if it does not do so, unexpected and often
+ random behavior results. This is an extremely common source of
+ bugs in C programs. An alternative would be to do a non-local
+ exit using `longjmp()', but that is often very dangerous because
+ the routines that were exited past had no opportunity to clean up
+ after themselves and may leave things in an inconsistent state,
+ causing a crash shortly afterwards.
+
+ Lisp provides mechanisms to make such non-local exits safe. When
+ an error occurs, a routine simply signals that an error of a
+ particular class has occurred, and a non-local exit takes place.
+ Any routine can trap errors occurring in routines it calls by
+ registering an error handler for some or all classes of errors.
+ (If no handler is registered, a default handler, generally
+ installed by the top-level event loop, is executed; this prints
+ out the error and continues.) Routines can also specify cleanup
+ code (called an "unwind-protect") that will be called when control
+ exits from a block of code, no matter how that exit occurs - i.e.
+ even if a function deeply nested below it causes a non-local exit
+ back to the top level.
+
+ Note that this facility has appeared in some recent vintages of C,
+ in particular Visual C++ and other PC compilers written for the
+ Microsoft Win32 API.
+
+ 7. In Emacs Lisp, local variables are "dynamically scoped". This
+ means that if you declare a local variable in a particular
+ function, and then call another function, that subfunction can
+ "see" the local variable you declared. This is actually
+ considered a bug in Emacs Lisp and in all other early dialects of
+ Lisp, and was corrected in Common Lisp. (In Common Lisp, you can
+ still declare dynamically scoped variables if you want to - they
+ are sometimes useful - but variables by default are "lexically
+ scoped" as in C.)
+
+ For those familiar with Lisp, Emacs Lisp is modelled after MacLisp,
+an early dialect of Lisp developed at MIT (no relation to the Macintosh
+computer). There is a Common Lisp compatibility package available for
+Emacs that provides many of the features of Common Lisp.
+
+ The Java language is derived in many ways from C, and shares a
+similar syntax, but has the following features in common with Lisp (and
+different from C):
+
+ 1. Java is a safe language, like Lisp.
+
+ 2. Java provides garbage collection, like Lisp.
+
+ 3. Java has built-in facilities for handling errors and exceptions,
+ like Lisp.
+
+ 4. Java has a type system that combines the best advantages of both
+ static and dynamic typing. Objects (except very simple types) are
+ explicitly marked with their type, as in dynamic typing; but there
+ is a hierarchy of types and functions are declared to accept only
+ certain types, thus providing the increased compile-time
+ error-checking of static typing.
+
+ The Java language also has some negative attributes:
+
+ 1. Java uses the edit/compile/run model of software development. This
+ makes it hard to use interactively. For example, to use Java like
+ `bc' it is necessary to write a special purpose, albeit tiny,
+ application. In Emacs Lisp, a calculator comes built-in without
+ any effort - one can always just type an expression in the
+ `*scratch*' buffer.
+
+ 2. Java tries too hard to enforce, not merely enable, portability,
+ making ordinary access to standard OS facilities painful. Java
+ has an "agenda". I think this is why `chdir' is not part of
+ standard Java, which is inexcusable.
+
+ Unfortunately, there is no perfect language. Static typing allows a
+compiler to catch programmer errors and produce more efficient code, but
+makes programming more tedious and less fun. For the forseeable future,
+an Ideal Editing and Programming Environment (and that is what XEmacs
+aspires to) will be programmable in multiple languages: high level ones
+like Lisp for user customization and prototyping, and lower level ones
+for infrastructure and industrial strength applications. If I had my
+way, XEmacs would be friendly towards the Python, Scheme, C++, ML,
+etc... communities. But there are serious technical difficulties to
+achieving that goal.
+
+ The word "application" in the previous paragraph was used
+intentionally. XEmacs implements an API for programs written in Lisp
+that makes it a full-fledged application platform, very much like an OS
+inside the real OS.
+
+\1f
+File: internals.info, Node: XEmacs From the Perspective of Building, Next: XEmacs From the Inside, Prev: The Lisp Language, Up: Top
+
+XEmacs From the Perspective of Building
+***************************************
+
+ The heart of XEmacs is the Lisp environment, which is written in C.
+This is contained in the `src/' subdirectory. Underneath `src/' are
+two subdirectories of header files: `s/' (header files for particular
+operating systems) and `m/' (header files for particular machine
+types). In practice the distinction between the two types of header
+files is blurred. These header files define or undefine certain
+preprocessor constants and macros to indicate particular
+characteristics of the associated machine or operating system. As part
+of the configure process, one `s/' file and one `m/' file is identified
+for the particular environment in which XEmacs is being built.
+
+ XEmacs also contains a great deal of Lisp code. This implements the
+operations that make XEmacs useful as an editor as well as just a Lisp
+environment, and also contains many add-on packages that allow XEmacs to
+browse directories, act as a mail and Usenet news reader, compile Lisp
+code, etc. There is actually more Lisp code than C code associated with
+XEmacs, but much of the Lisp code is peripheral to the actual operation
+of the editor. The Lisp code all lies in subdirectories underneath the
+`lisp/' directory.
+
+ The `lwlib/' directory contains C code that implements a generalized
+interface onto different X widget toolkits and also implements some
+widgets of its own that behave like Motif widgets but are faster, free,
+and in some cases more powerful. The code in this directory compiles
+into a library and is mostly independent from XEmacs.
+
+ The `etc/' directory contains various data files associated with
+XEmacs. Some of them are actually read by XEmacs at startup; others
+merely contain useful information of various sorts.
+
+ The `lib-src/' directory contains C code for various auxiliary
+programs that are used in connection with XEmacs. Some of them are used
+during the build process; others are used to perform certain functions
+that cannot conveniently be placed in the XEmacs executable (e.g. the
+`movemail' program for fetching mail out of `/var/spool/mail', which
+must be setgid to `mail' on many systems; and the `gnuclient' program,
+which allows an external script to communicate with a running XEmacs
+process).
+
+ The `man/' directory contains the sources for the XEmacs
+documentation. It is mostly in a form called Texinfo, which can be
+converted into either a printed document (by passing it through TeX) or
+into on-line documentation called "info files".
+
+ The `info/' directory contains the results of formatting the XEmacs
+documentation as "info files", for on-line use. These files are used
+when you enter the Info system using `C-h i' or through the Help menu.
+
+ The `dynodump/' directory contains auxiliary code used to build
+XEmacs on Solaris platforms.
+
+ The other directories contain various miscellaneous code and
+information that is not normally used or needed.
+
+ The first step of building involves running the `configure' program
+and passing it various parameters to specify any optional features you
+want and compiler arguments and such, as described in the `INSTALL'
+file. This determines what the build environment is, chooses the
+appropriate `s/' and `m/' file, and runs a series of tests to determine
+many details about your environment, such as which library functions
+are available and exactly how they work. The reason for running these
+tests is that it allows XEmacs to be compiled on a much wider variety
+of platforms than those that the XEmacs developers happen to be
+familiar with, including various sorts of hybrid platforms. This is
+especially important now that many operating systems give you a great
+deal of control over exactly what features you want installed, and allow
+for easy upgrading of parts of a system without upgrading the rest. It
+would be impossible to pre-determine and pre-specify the information for
+all possible configurations.
+
+ In fact, the `s/' and `m/' files are basically *evil*, since they
+contain unmaintainable platform-specific hard-coded information.
+XEmacs has been moving in the direction of having all system-specific
+information be determined dynamically by `configure'. Perhaps someday
+we can `rm -rf src/s src/m'.
+
+ When configure is done running, it generates `Makefile's and
+`GNUmakefile's and the file `src/config.h' (which describes the
+features of your system) from template files. You then run `make',
+which compiles the auxiliary code and programs in `lib-src/' and
+`lwlib/' and the main XEmacs executable in `src/'. The result of
+compiling and linking is an executable called `temacs', which is *not*
+the final XEmacs executable. `temacs' by itself is not intended to
+function as an editor or even display any windows on the screen, and if
+you simply run it, it will exit immediately. The `Makefile' runs
+`temacs' with certain options that cause it to initialize itself, read
+in a number of basic Lisp files, and then dump itself out into a new
+executable called `xemacs'. This new executable has been
+pre-initialized and contains pre-digested Lisp code that is necessary
+for the editor to function (this includes most basic editing functions,
+e.g. `kill-line', that can be defined in terms of other Lisp
+primitives; some initialization code that is called when certain
+objects, such as frames, are created; and all of the standard
+keybindings and code for the actions they result in). This executable,
+`xemacs', is the executable that you run to use the XEmacs editor.
+
+ Although `temacs' is not intended to be run as an editor, it can, by
+using the incantation `temacs -batch -l loadup.el run-temacs'. This is
+useful when the dumping procedure described above is broken, or when
+using certain program debugging tools such as Purify. These tools get
+mighty confused by the tricks played by the XEmacs build process, such
+as allocation memory in one process, and freeing it in the next.
+
+\1f
+File: internals.info, Node: XEmacs From the Inside, Next: The XEmacs Object System (Abstractly Speaking), Prev: XEmacs From the Perspective of Building, Up: Top
+
+XEmacs From the Inside
+**********************
+
+ Internally, XEmacs is quite complex, and can be very confusing. To
+simplify things, it can be useful to think of XEmacs as containing an
+event loop that "drives" everything, and a number of other subsystems,
+such as a Lisp engine and a redisplay mechanism. Each of these other
+subsystems exists simultaneously in XEmacs, and each has a certain
+state. The flow of control continually passes in and out of these
+different subsystems in the course of normal operation of the editor.
+
+ It is important to keep in mind that, most of the time, the editor is
+"driven" by the event loop. Except during initialization and batch
+mode, all subsystems are entered directly or indirectly through the
+event loop, and ultimately, control exits out of all subsystems back up
+to the event loop. This cycle of entering a subsystem, exiting back out
+to the event loop, and starting another iteration of the event loop
+occurs once each keystroke, mouse motion, etc.
+
+ If you're trying to understand a particular subsystem (other than the
+event loop), think of it as a "daemon" process or "servant" that is
+responsible for one particular aspect of a larger system, and
+periodically receives commands or environment changes that cause it to
+do something. Ultimately, these commands and environment changes are
+always triggered by the event loop. For example:
+
+ * The window and frame mechanism is responsible for keeping track of
+ what windows and frames exist, what buffers are in them, etc. It
+ is periodically given commands (usually from the user) to make a
+ change to the current window/frame state: i.e. create a new frame,
+ delete a window, etc.
+
+ * The buffer mechanism is responsible for keeping track of what
+ buffers exist and what text is in them. It is periodically given
+ commands (usually from the user) to insert or delete text, create
+ a buffer, etc. When it receives a text-change command, it
+ notifies the redisplay mechanism.
+
+ * The redisplay mechanism is responsible for making sure that
+ windows and frames are displayed correctly. It is periodically
+ told (by the event loop) to actually "do its job", i.e. snoop
+ around and see what the current state of the environment (mostly
+ of the currently-existing windows, frames, and buffers) is, and
+ make sure that that state matches what's actually displayed. It
+ keeps lots and lots of information around (such as what is
+ actually being displayed currently, and what the environment was
+ last time it checked) so that it can minimize the work it has to
+ do. It is also helped along in that whenever a relevant change to
+ the environment occurs, the redisplay mechanism is told about
+ this, so it has a pretty good idea of where it has to look to find
+ possible changes and doesn't have to look everywhere.
+
+ * The Lisp engine is responsible for executing the Lisp code in
+ which most user commands are written. It is entered through a
+ call to `eval' or `funcall', which occurs as a result of
+ dispatching an event from the event loop. The functions it calls
+ issue commands to the buffer mechanism, the window/frame
+ subsystem, etc.
+
+ * The Lisp allocation subsystem is responsible for keeping track of
+ Lisp objects. It is given commands from the Lisp engine to
+ allocate objects, garbage collect, etc.
+
+ etc.
+
+ The important idea here is that there are a number of independent
+subsystems each with its own responsibility and persistent state, just
+like different employees in a company, and each subsystem is
+periodically given commands from other subsystems. Commands can flow
+from any one subsystem to any other, but there is usually some sort of
+hierarchy, with all commands originating from the event subsystem.
+
+ XEmacs is entered in `main()', which is in `emacs.c'. When this is
+called the first time (in a properly-invoked `temacs'), it does the
+following:
+
+ 1. It does some very basic environment initializations, such as
+ determining where it and its directories (e.g. `lisp/' and `etc/')
+ reside and setting up signal handlers.
+
+ 2. It initializes the entire Lisp interpreter.
+
+ 3. It sets the initial values of many built-in variables (including
+ many variables that are visible to Lisp programs), such as the
+ global keymap object and the built-in faces (a face is an object
+ that describes the display characteristics of text). This
+ involves creating Lisp objects and thus is dependent on step (2).
+
+ 4. It performs various other initializations that are relevant to the
+ particular environment it is running in, such as retrieving
+ environment variables, determining the current date and the user
+ who is running the program, examining its standard input, creating
+ any necessary file descriptors, etc.
+
+ 5. At this point, the C initialization is complete. A Lisp program
+ that was specified on the command line (usually `loadup.el') is
+ called (temacs is normally invoked as `temacs -batch -l loadup.el
+ dump'). `loadup.el' loads all of the other Lisp files that are
+ needed for the operation of the editor, calls the `dump-emacs'
+ function to write out `xemacs', and then kills the temacs process.
+
+ When `xemacs' is then run, it only redoes steps (1) and (4) above;
+all variables already contain the values they were set to when the
+executable was dumped, and all memory that was allocated with
+`malloc()' is still around. (XEmacs knows whether it is being run as
+`xemacs' or `temacs' because it sets the global variable `initialized'
+to 1 after step (4) above.) At this point, `xemacs' calls a Lisp
+function to do any further initialization, which includes parsing the
+command-line (the C code can only do limited command-line parsing,
+which includes looking for the `-batch' and `-l' flags and a few other
+flags that it needs to know about before initialization is complete),
+creating the first frame (or "window" in standard window-system
+parlance), running the user's init file (usually the file `.emacs' in
+the user's home directory), etc. The function to do this is usually
+called `normal-top-level'; `loadup.el' tells the C code about this
+function by setting its name as the value of the Lisp variable
+`top-level'.
+
+ When the Lisp initialization code is done, the C code enters the
+event loop, and stays there for the duration of the XEmacs process.
+The code for the event loop is contained in `keyboard.c', and is called
+`Fcommand_loop_1()'. Note that this event loop could very well be
+written in Lisp, and in fact a Lisp version exists; but apparently,
+doing this makes XEmacs run noticeably slower.
+
+ Notice how much of the initialization is done in Lisp, not in C. In
+general, XEmacs tries to move as much code as is possible into Lisp.
+Code that remains in C is code that implements the Lisp interpreter
+itself, or code that needs to be very fast, or code that needs to do
+system calls or other such stuff that needs to be done in C, or code
+that needs to have access to "forbidden" structures. (One conscious
+aspect of the design of Lisp under XEmacs is a clean separation between
+the external interface to a Lisp object's functionality and its internal
+implementation. Part of this design is that Lisp programs are
+forbidden from accessing the contents of the object other than through
+using a standard API. In this respect, XEmacs Lisp is similar to
+modern Lisp dialects but differs from GNU Emacs, which tends to expose
+the implementation and allow Lisp programs to look at it directly. The
+major advantage of hiding the implementation is that it allows the
+implementation to be redesigned without affecting any Lisp programs,
+including those that might want to be "clever" by looking directly at
+the object's contents and possibly manipulating them.)
+
+ Moving code into Lisp makes the code easier to debug and maintain and
+makes it much easier for people who are not XEmacs developers to
+customize XEmacs, because they can make a change with much less chance
+of obscure and unwanted interactions occurring than if they were to
+change the C code.
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: The XEmacs Object System (Abstractly Speaking), Next: How Lisp Objects Are Represented in C, Prev: XEmacs From the Inside, Up: Top
+
+The XEmacs Object System (Abstractly Speaking)
+**********************************************
+
+ At the heart of the Lisp interpreter is its management of objects.
+XEmacs Lisp contains many built-in objects, some of which are simple
+and others of which can be very complex; and some of which are very
+common, and others of which are rarely used or are only used
+internally. (Since the Lisp allocation system, with its automatic
+reclamation of unused storage, is so much more convenient than
+`malloc()' and `free()', the C code makes extensive use of it in its
+internal operations.)
+
+ The basic Lisp objects are
+
+`integer'
+ 28 or 31 bits of precision, or 60 or 63 bits on 64-bit machines;
+ the reason for this is described below when the internal Lisp
+ object representation is described.
+
+`float'
+ Same precision as a double in C.
+
+`cons'
+ A simple container for two Lisp objects, used to implement lists
+ and most other data structures in Lisp.
+
+`char'
+ An object representing a single character of text; chars behave
+ like integers in many ways but are logically considered text
+ rather than numbers and have a different read syntax. (the read
+ syntax for a char contains the char itself or some textual
+ encoding of it - for example, a Japanese Kanji character might be
+ encoded as `^[$(B#&^[(B' using the ISO-2022 encoding standard -
+ rather than the numerical representation of the char; this way, if
+ the mapping between chars and integers changes, which is quite
+ possible for Kanji characters and other extended characters, the
+ same character will still be created. Note that some primitives
+ confuse chars and integers. The worst culprit is `eq', which
+ makes a special exception and considers a char to be `eq' to its
+ integer equivalent, even though in no other case are objects of two
+ different types `eq'. The reason for this monstrosity is
+ compatibility with existing code; the separation of char from
+ integer came fairly recently.)
+
+`symbol'
+ An object that contains Lisp objects and is referred to by name;
+ symbols are used to implement variables and named functions and to
+ provide the equivalent of preprocessor constants in C.
+
+`vector'
+ A one-dimensional array of Lisp objects providing constant-time
+ access to any of the objects; access to an arbitrary object in a
+ vector is faster than for lists, but the operations that can be
+ done on a vector are more limited.
+
+`string'
+ Self-explanatory; behaves much like a vector of chars but has a
+ different read syntax and is stored and manipulated more compactly.
+
+`bit-vector'
+ A vector of bits; similar to a string in spirit.
+
+`compiled-function'
+ An object containing compiled Lisp code, known as "byte code".
+
+`subr'
+ A Lisp primitive, i.e. a Lisp-callable function implemented in C.
+
+ Note that there is no basic "function" type, as in more powerful
+versions of Lisp (where it's called a "closure"). XEmacs Lisp does not
+provide the closure semantics implemented by Common Lisp and Scheme.
+The guts of a function in XEmacs Lisp are represented in one of four
+ways: a symbol specifying another function (when one function is an
+alias for another), a list (whose first element must be the symbol
+`lambda') containing the function's source code, a compiled-function
+object, or a subr object. (In other words, given a symbol specifying
+the name of a function, calling `symbol-function' to retrieve the
+contents of the symbol's function cell will return one of these types
+of objects.)
+
+ XEmacs Lisp also contains numerous specialized objects used to
+implement the editor:
+
+`buffer'
+ Stores text like a string, but is optimized for insertion and
+ deletion and has certain other properties that can be set.
+
+`frame'
+ An object with various properties whose displayable representation
+ is a "window" in window-system parlance.
+
+`window'
+ A section of a frame that displays the contents of a buffer; often
+ called a "pane" in window-system parlance.
+
+`window-configuration'
+ An object that represents a saved configuration of windows in a
+ frame.
+
+`device'
+ An object representing a screen on which frames can be displayed;
+ equivalent to a "display" in the X Window System and a "TTY" in
+ character mode.
+
+`face'
+ An object specifying the appearance of text or graphics; it has
+ properties such as font, foreground color, and background color.
+
+`marker'
+ An object that refers to a particular position in a buffer and
+ moves around as text is inserted and deleted to stay in the same
+ relative position to the text around it.
+
+`extent'
+ Similar to a marker but covers a range of text in a buffer; can
+ also specify properties of the text, such as a face in which the
+ text is to be displayed, whether the text is invisible or
+ unmodifiable, etc.
+
+`event'
+ Generated by calling `next-event' and contains information
+ describing a particular event happening in the system, such as the
+ user pressing a key or a process terminating.
+
+`keymap'
+ An object that maps from events (described using lists, vectors,
+ and symbols rather than with an event object because the mapping
+ is for classes of events, rather than individual events) to
+ functions to execute or other events to recursively look up; the
+ functions are described by name, using a symbol, or using lists to
+ specify the function's code.
+
+`glyph'
+ An object that describes the appearance of an image (e.g. pixmap)
+ on the screen; glyphs can be attached to the beginning or end of
+ extents and in some future version of XEmacs will be able to be
+ inserted directly into a buffer.
+
+`process'
+ An object that describes a connection to an externally-running
+ process.
+
+ There are some other, less-commonly-encountered general objects:
+
+`hash-table'
+ An object that maps from an arbitrary Lisp object to another
+ arbitrary Lisp object, using hashing for fast lookup.
+
+`obarray'
+ A limited form of hash-table that maps from strings to symbols;
+ obarrays are used to look up a symbol given its name and are not
+ actually their own object type but are kludgily represented using
+ vectors with hidden fields (this representation derives from GNU
+ Emacs).
+
+`specifier'
+ A complex object used to specify the value of a display property; a
+ default value is given and different values can be specified for
+ particular frames, buffers, windows, devices, or classes of device.
+
+`char-table'
+ An object that maps from chars or classes of chars to arbitrary
+ Lisp objects; internally char tables use a complex nested-vector
+ representation that is optimized to the way characters are
+ represented as integers.
+
+`range-table'
+ An object that maps from ranges of integers to arbitrary Lisp
+ objects.
+
+ And some strange special-purpose objects:
+
+`charset'
+`coding-system'
+ Objects used when MULE, or multi-lingual/Asian-language, support is
+ enabled.
+
+`color-instance'
+`font-instance'
+`image-instance'
+ An object that encapsulates a window-system resource; instances are
+ mostly used internally but are exposed on the Lisp level for
+ cleanness of the specifier model and because it's occasionally
+ useful for Lisp program to create or query the properties of
+ instances.
+
+`subwindow'
+ An object that encapsulate a "subwindow" resource, i.e. a
+ window-system child window that is drawn into by an external
+ process; this object should be integrated into the glyph system
+ but isn't yet, and may change form when this is done.
+
+`tooltalk-message'
+`tooltalk-pattern'
+ Objects that represent resources used in the ToolTalk interprocess
+ communication protocol.
+
+`toolbar-button'
+ An object used in conjunction with the toolbar.
+
+ And objects that are only used internally:
+
+`opaque'
+ A generic object for encapsulating arbitrary memory; this allows
+ you the generality of `malloc()' and the convenience of the Lisp
+ object system.
+
+`lstream'
+ A buffering I/O stream, used to provide a unified interface to
+ anything that can accept output or provide input, such as a file
+ descriptor, a stdio stream, a chunk of memory, a Lisp buffer, a
+ Lisp string, etc.; it's a Lisp object to make its memory
+ management more convenient.
+
+`char-table-entry'
+ Subsidiary objects in the internal char-table representation.
+
+`extent-auxiliary'
+`menubar-data'
+`toolbar-data'
+ Various special-purpose objects that are basically just used to
+ encapsulate memory for particular subsystems, similar to the more
+ general "opaque" object.
+
+`symbol-value-forward'
+`symbol-value-buffer-local'
+`symbol-value-varalias'
+`symbol-value-lisp-magic'
+ Special internal-only objects that are placed in the value cell of
+ a symbol to indicate that there is something special with this
+ variable - e.g. it has no value, it mirrors another variable, or
+ it mirrors some C variable; there is really only one kind of
+ object, called a "symbol-value-magic", but it is sort-of halfway
+ kludged into semi-different object types.
+
+ Some types of objects are "permanent", meaning that once created,
+they do not disappear until explicitly destroyed, using a function such
+as `delete-buffer', `delete-window', `delete-frame', etc. Others will
+disappear once they are not longer used, through the garbage collection
+mechanism. Buffers, frames, windows, devices, and processes are among
+the objects that are permanent. Note that some objects can go both
+ways: Faces can be created either way; extents are normally permanent,
+but detached extents (extents not referring to any text, as happens to
+some extents when the text they are referring to is deleted) are
+temporary. Note that some permanent objects, such as faces and coding
+systems, cannot be deleted. Note also that windows are unique in that
+they can be *undeleted* after having previously been deleted. (This
+happens as a result of restoring a window configuration.)
+
+ Note that many types of objects have a "read syntax", i.e. a way of
+specifying an object of that type in Lisp code. When you load a Lisp
+file, or type in code to be evaluated, what really happens is that the
+function `read' is called, which reads some text and creates an object
+based on the syntax of that text; then `eval' is called, which possibly
+does something special; then this loop repeats until there's no more
+text to read. (`eval' only actually does something special with
+symbols, which causes the symbol's value to be returned, similar to
+referencing a variable; and with conses [i.e. lists], which cause a
+function invocation. All other values are returned unchanged.)
+
+ The read syntax
+
+ 17297
+
+ converts to an integer whose value is 17297.
+
+ 1.983e-4
+
+ converts to a float whose value is 1.983e-4, or .0001983.
+
+ ?b
+
+ converts to a char that represents the lowercase letter b.
+
+ ?^[$(B#&^[(B
+
+ (where `^[' actually is an `ESC' character) converts to a particular
+Kanji character when using an ISO2022-based coding system for input.
+(To decode this goo: `ESC' begins an escape sequence; `ESC $ (' is a
+class of escape sequences meaning "switch to a 94x94 character set";
+`ESC $ ( B' means "switch to Japanese Kanji"; `#' and `&' collectively
+index into a 94-by-94 array of characters [subtract 33 from the ASCII
+value of each character to get the corresponding index]; `ESC (' is a
+class of escape sequences meaning "switch to a 94 character set"; `ESC
+(B' means "switch to US ASCII". It is a coincidence that the letter
+`B' is used to denote both Japanese Kanji and US ASCII. If the first
+`B' were replaced with an `A', you'd be requesting a Chinese Hanzi
+character from the GB2312 character set.)
+
+ "foobar"
+
+ converts to a string.
+
+ foobar
+
+ converts to a symbol whose name is `"foobar"'. This is done by
+looking up the string equivalent in the global variable `obarray',
+whose contents should be an obarray. If no symbol is found, a new
+symbol with the name `"foobar"' is automatically created and added to
+`obarray'; this process is called "interning" the symbol.
+
+ (foo . bar)
+
+ converts to a cons cell containing the symbols `foo' and `bar'.
+
+ (1 a 2.5)
+
+ converts to a three-element list containing the specified objects
+(note that a list is actually a set of nested conses; see the XEmacs
+Lisp Reference).
+
+ [1 a 2.5]
+
+ converts to a three-element vector containing the specified objects.
+
+ #[... ... ... ...]
+
+ converts to a compiled-function object (the actual contents are not
+shown since they are not relevant here; look at a file that ends with
+`.elc' for examples).
+
+ #*01110110
+
+ converts to a bit-vector.
+
+ #s(hash-table ... ...)
+
+ converts to a hash table (the actual contents are not shown).
+
+ #s(range-table ... ...)
+
+ converts to a range table (the actual contents are not shown).
+
+ #s(char-table ... ...)
+
+ converts to a char table (the actual contents are not shown).
+
+ Note that the `#s()' syntax is the general syntax for structures,
+which are not really implemented in XEmacs Lisp but should be.
+
+ When an object is printed out (using `print' or a related function),
+the read syntax is used, so that the same object can be read in again.
+
+ The other objects do not have read syntaxes, usually because it does
+not really make sense to create them in this fashion (i.e. processes,
+where it doesn't make sense to have a subprocess created as a side
+effect of reading some Lisp code), or because they can't be created at
+all (e.g. subrs). Permanent objects, as a rule, do not have a read
+syntax; nor do most complex objects, which contain too much state to be
+easily initialized through a read syntax.
+
+\1f
+File: internals.info, Node: How Lisp Objects Are Represented in C, Next: Rules When Writing New C Code, Prev: The XEmacs Object System (Abstractly Speaking), Up: Top
+
+How Lisp Objects Are Represented in C
+*************************************
+
+ Lisp objects are represented in C using a 32-bit or 64-bit machine
+word (depending on the processor; i.e. DEC Alphas use 64-bit Lisp
+objects and most other processors use 32-bit Lisp objects). The
+representation stuffs a pointer together with a tag, as follows:
+
+ [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ]
+ [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ]
+
+ <---> ^ <------------------------------------------------------>
+ tag | a pointer to a structure, or an integer
+ |
+ mark bit
+
+ The tag describes the type of the Lisp object. For integers and
+chars, the lower 28 bits contain the value of the integer or char; for
+all others, the lower 28 bits contain a pointer. The mark bit is used
+during garbage-collection, and is always 0 when garbage collection is
+not happening. (The way that garbage collection works, basically, is
+that it loops over all places where Lisp objects could exist - this
+includes all global variables in C that contain Lisp objects [including
+`Vobarray', the C equivalent of `obarray'; through this, all Lisp
+variables will get marked], plus various other places - and recursively
+scans through the Lisp objects, marking each object it finds by setting
+the mark bit. Then it goes through the lists of all objects allocated,
+freeing the ones that are not marked and turning off the mark bit of
+the ones that are marked.)
+
+ Lisp objects use the typedef `Lisp_Object', but the actual C type
+used for the Lisp object can vary. It can be either a simple type
+(`long' on the DEC Alpha, `int' on other machines) or a structure whose
+fields are bit fields that line up properly (actually, a union of
+structures is used). Generally the simple integral type is preferable
+because it ensures that the compiler will actually use a machine word
+to represent the object (some compilers will use more general and less
+efficient code for unions and structs even if they can fit in a machine
+word). The union type, however, has the advantage of stricter type
+checking (if you accidentally pass an integer where a Lisp object is
+desired, you get a compile error), and it makes it easier to decode
+Lisp objects when debugging. The choice of which type to use is
+determined by the preprocessor constant `USE_UNION_TYPE' which is
+defined via the `--use-union-type' option to `configure'.
+
+ Note that there are only eight types that the tag can represent, but
+many more actual types than this. This is handled by having one of the
+tag types specify a meta-type called a "record"; for all such objects,
+the first four bytes of the pointed-to structure indicate what the
+actual type is.
+
+ Note also that having 28 bits for pointers and integers restricts a
+lot of things to 256 megabytes of memory. (Basically, enough pointers
+and indices and whatnot get stuffed into Lisp objects that the total
+amount of memory used by XEmacs can't grow above 256 megabytes. In
+older versions of XEmacs and GNU Emacs, the tag was 5 bits wide,
+allowing for 32 types, which was more than the actual number of types
+that existed at the time, and no "record" type was necessary. However,
+this limited the editor to 64 megabytes total, which some users who
+edited large files might conceivably exceed.)
+
+ Also, note that there is an implicit assumption here that all
+pointers are low enough that the top bits are all zero and can just be
+chopped off. On standard machines that allocate memory from the bottom
+up (and give each process its own address space), this works fine. Some
+machines, however, put the data space somewhere else in memory (e.g.
+beginning at 0x80000000). Those machines cope by defining
+`DATA_SEG_BITS' in the corresponding `m/' or `s/' file to the proper
+mask. Then, pointers retrieved from Lisp objects are automatically
+OR'ed with this value prior to being used.
+
+ A corollary of the previous paragraph is that *(pointers to)
+stack-allocated structures cannot be put into Lisp objects*. The stack
+is generally located near the top of memory; if you put such a pointer
+into a Lisp object, it will get its top bits chopped off, and you will
+lose.
+
+ Actually, there's an alternative representation of a `Lisp_Object',
+invented by Kyle Jones, that is used when the `--use-minimal-tagbits'
+option to `configure' is used. In this case the 2 lower bits are used
+for the tag bits. This representation assumes that pointers to structs
+are always aligned to multiples of 4, so the lower 2 bits are always
+zero.
+
+ [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ]
+ [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ]
+
+ <---------------------------------------------------------> <->
+ a pointer to a structure, or an integer tag
+
+ A tag of 00 is used for all pointer object types, a tag of 10 is used
+for characters, and the other two tags 01 and 11 are joined together to
+form the integer object type. The markbit is moved to part of the
+structure being pointed at (integers and chars do not need to be marked,
+since no memory is allocated). This representation has these
+advantages:
+
+ 1. 31 bits can be used for Lisp Integers.
+
+ 2. *Any* pointer can be represented directly, and no bit masking
+ operations are necessary.
+
+ The disadvantages are:
+
+ 1. An extra level of indirection is needed when accessing the object
+ types that were not record types. So checking whether a Lisp
+ object is a cons cell becomes a slower operation.
+
+ 2. Mark bits can no longer be stored directly in Lisp objects, so
+ another place for them must be found. This means that a cons cell
+ requires more memory than merely room for 2 lisp objects, leading
+ to extra memory use.
+
+ Various macros are used to construct Lisp objects and extract the
+components. Macros of the form `XINT()', `XCHAR()', `XSTRING()',
+`XSYMBOL()', etc. mask out the pointer/integer field and cast it to the
+appropriate type. All of the macros that construct pointers will `OR'
+with `DATA_SEG_BITS' if necessary. `XINT()' needs to be a bit tricky
+so that negative numbers are properly sign-extended: Usually it does
+this by shifting the number four bits to the left and then four bits to
+the right. This assumes that the right-shift operator does an
+arithmetic shift (i.e. it leaves the most-significant bit as-is rather
+than shifting in a zero, so that it mimics a divide-by-two even for
+negative numbers). Not all machines/compilers do this, and on the ones
+that don't, a more complicated definition is selected by defining
+`EXPLICIT_SIGN_EXTEND'.
+
+ Note that when `ERROR_CHECK_TYPECHECK' is defined, the extractor
+macros become more complicated - they check the tag bits and/or the
+type field in the first four bytes of a record type to ensure that the
+object is really of the correct type. This is great for catching places
+where an incorrect type is being dereferenced - this typically results
+in a pointer being dereferenced as the wrong type of structure, with
+unpredictable (and sometimes not easily traceable) results.
+
+ There are similar `XSETTYPE()' macros that construct a Lisp object.
+These macros are of the form `XSETTYPE (LVALUE, RESULT)', i.e. they
+have to be a statement rather than just used in an expression. The
+reason for this is that standard C doesn't let you "construct" a
+structure (but GCC does). Granted, this sometimes isn't too convenient;
+for the case of integers, at least, you can use the function
+`make_int()', which constructs and *returns* an integer Lisp object.
+Note that the `XSETTYPE()' macros are also affected by
+`ERROR_CHECK_TYPECHECK' and make sure that the structure is of the
+right type in the case of record types, where the type is contained in
+the structure.
+
+ The C programmer is responsible for *guaranteeing* that a
+Lisp_Object is is the correct type before using the `XTYPE' macros.
+This is especially important in the case of lists. Use `XCAR' and
+`XCDR' if a Lisp_Object is certainly a cons cell, else use `Fcar()' and
+`Fcdr()'. Trust other C code, but not Lisp code. On the other hand,
+if XEmacs has an internal logic error, it's better to crash
+immediately, so sprinkle "unreachable" `abort()'s liberally about the
+source code.
+
+\1f
+File: internals.info, Node: Rules When Writing New C Code, Next: A Summary of the Various XEmacs Modules, Prev: How Lisp Objects Are Represented in C, Up: Top
+
+Rules When Writing New C Code
+*****************************
+
+ The XEmacs C Code is extremely complex and intricate, and there are
+many rules that are more or less consistently followed throughout the
+code. Many of these rules are not obvious, so they are explained here.
+It is of the utmost importance that you follow them. If you don't,
+you may get something that appears to work, but which will crash in odd
+situations, often in code far away from where the actual breakage is.
+
+* Menu:
+
+* General Coding Rules::
+* Writing Lisp Primitives::
+* Adding Global Lisp Variables::
+* Coding for Mule::
+* Techniques for XEmacs Developers::
+
+\1f
+File: internals.info, Node: General Coding Rules, Next: Writing Lisp Primitives, Up: Rules When Writing New C Code
+
+General Coding Rules
+====================
+
+ The C code is actually written in a dialect of C called "Clean C",
+meaning that it can be compiled, mostly warning-free, with either a C or
+C++ compiler. Coding in Clean C has several advantages over plain C.
+C++ compilers are more nit-picking, and a number of coding errors have
+been found by compiling with C++. The ability to use both C and C++
+tools means that a greater variety of development tools are available to
+the developer.
+
+ Almost every module contains a `syms_of_*()' function and a
+`vars_of_*()' function. The former declares any Lisp primitives you
+have defined and defines any symbols you will be using. The latter
+declares any global Lisp variables you have added and initializes global
+C variables in the module. For each such function, declare it in
+`symsinit.h' and make sure it's called in the appropriate place in
+`emacs.c'. *Important*: There are stringent requirements on exactly
+what can go into these functions. See the comment in `emacs.c'. The
+reason for this is to avoid obscure unwanted interactions during
+initialization. If you don't follow these rules, you'll be sorry! If
+you want to do anything that isn't allowed, create a
+`complex_vars_of_*()' function for it. Doing this is tricky, though:
+You have to make sure your function is called at the right time so that
+all the initialization dependencies work out.
+
+ Every module includes `<config.h>' (angle brackets so that
+`--srcdir' works correctly; `config.h' may or may not be in the same
+directory as the C sources) and `lisp.h'. `config.h' must always be
+included before any other header files (including system header files)
+to ensure that certain tricks played by various `s/' and `m/' files
+work out correctly.
+
+ *All global and static variables that are to be modifiable must be
+declared uninitialized.* This means that you may not use the "declare
+with initializer" form for these variables, such as `int some_variable
+= 0;'. The reason for this has to do with some kludges done during the
+dumping process: If possible, the initialized data segment is re-mapped
+so that it becomes part of the (unmodifiable) code segment in the
+dumped executable. This allows this memory to be shared among multiple
+running XEmacs processes. XEmacs is careful to place as much constant
+data as possible into initialized variables (in particular, into what's
+called the "pure space" - see below) during the `temacs' phase.
+
+ *Please note:* This kludge only works on a few systems nowadays, and
+is rapidly becoming irrelevant because most modern operating systems
+provide "copy-on-write" semantics. All data is initially shared
+between processes, and a private copy is automatically made (on a
+page-by-page basis) when a process first attempts to write to a page of
+memory.
+
+ Formerly, there was a requirement that static variables not be
+declared inside of functions. This had to do with another hack along
+the same vein as what was just described: old USG systems put
+statically-declared variables in the initialized data space, so those
+header files had a `#define static' declaration. (That way, the
+data-segment remapping described above could still work.) This fails
+badly on static variables inside of functions, which suddenly become
+automatic variables; therefore, you weren't supposed to have any of
+them. This awful kludge has been removed in XEmacs because
+
+ 1. almost all of the systems that used this kludge ended up having to
+ disable the data-segment remapping anyway;
+
+ 2. the only systems that didn't were extremely outdated ones;
+
+ 3. this hack completely messed up inline functions.
+
+ The C source code makes heavy use of C preprocessor macros. One
+popular macro style is:
+
+ #define FOO(var, value) do { \
+ Lisp_Object FOO_value = (value); \
+ ... /* compute using FOO_value */ \
+ (var) = bar; \
+ } while (0)
+
+ The `do {...} while (0)' is a standard trick to allow FOO to have
+statement semantics, so that it can safely be used within an `if'
+statement in C, for example. Multiple evaluation is prevented by
+copying a supplied argument into a local variable, so that
+`FOO(var,fun(1))' only calls `fun' once.
+
+ Lisp lists are popular data structures in the C code as well as in
+Elisp. There are two sets of macros that iterate over lists.
+`EXTERNAL_LIST_LOOP_N' should be used when the list has been supplied
+by the user, and cannot be trusted to be acyclic and nil-terminated. A
+`malformed-list' or `circular-list' error will be generated if the list
+being iterated over is not entirely kosher. `LIST_LOOP_N', on the
+other hand, is faster and less safe, and can be used only on trusted
+lists.
+
+ Related macros are `GET_EXTERNAL_LIST_LENGTH' and `GET_LIST_LENGTH',
+which calculate the length of a list, and in the case of
+`GET_EXTERNAL_LIST_LENGTH', validating the properness of the list. The
+macros `EXTERNAL_LIST_LOOP_DELETE_IF' and `LIST_LOOP_DELETE_IF' delete
+elements from a lisp list satisfying some predicate.
+
+\1f
+File: internals.info, Node: Writing Lisp Primitives, Next: Adding Global Lisp Variables, Prev: General Coding Rules, Up: Rules When Writing New C Code
+
+Writing Lisp Primitives
+=======================
+
+ Lisp primitives are Lisp functions implemented in C. The details of
+interfacing the C function so that Lisp can call it are handled by a few
+C macros. The only way to really understand how to write new C code is
+to read the source, but we can explain some things here.
+
+ An example of a special form is the definition of `prog1', from
+`eval.c'. (An ordinary function would have the same general
+appearance.)
+
+ DEFUN ("prog1", Fprog1, 1, UNEVALLED, 0, /*
+ Similar to `progn', but the value of the first form is returned.
+ \(prog1 FIRST BODY...): All the arguments are evaluated sequentially.
+ The value of FIRST is saved during evaluation of the remaining args,
+ whose values are discarded.
+ */
+ (args))
+ {
+ /* This function can GC */
+ REGISTER Lisp_Object val, form, tail;
+ struct gcpro gcpro1;
+
+ val = Feval (XCAR (args));
+
+ GCPRO1 (val);
+
+ LIST_LOOP_3 (form, XCDR (args), tail)
+ Feval (form);
+
+ UNGCPRO;
+ return val;
+ }
+
+ Let's start with a precise explanation of the arguments to the
+`DEFUN' macro. Here is a template for them:
+
+ DEFUN (LNAME, FNAME, MIN_ARGS, MAX_ARGS, INTERACTIVE, /*
+ DOCSTRING
+ */
+ (ARGLIST))
+
+LNAME
+ This string is the name of the Lisp symbol to define as the
+ function name; in the example above, it is `"prog1"'.
+
+FNAME
+ This is the C function name for this function. This is the name
+ that is used in C code for calling the function. The name is, by
+ convention, `F' prepended to the Lisp name, with all dashes (`-')
+ in the Lisp name changed to underscores. Thus, to call this
+ function from C code, call `Fprog1'. Remember that the arguments
+ are of type `Lisp_Object'; various macros and functions for
+ creating values of type `Lisp_Object' are declared in the file
+ `lisp.h'.
+
+ Primitives whose names are special characters (e.g. `+' or `<')
+ are named by spelling out, in some fashion, the special character:
+ e.g. `Fplus()' or `Flss()'. Primitives whose names begin with
+ normal alphanumeric characters but also contain special characters
+ are spelled out in some creative way, e.g. `let*' becomes
+ `FletX()'.
+
+ Each function also has an associated structure that holds the data
+ for the subr object that represents the function in Lisp. This
+ structure conveys the Lisp symbol name to the initialization
+ routine that will create the symbol and store the subr object as
+ its definition. The C variable name of this structure is always
+ `S' prepended to the FNAME. You hardly ever need to be aware of
+ the existence of this structure, since `DEFUN' plus `DEFSUBR'
+ takes care of all the details.
+
+MIN_ARGS
+ This is the minimum number of arguments that the function
+ requires. The function `prog1' allows a minimum of one argument.
+
+MAX_ARGS
+ This is the maximum number of arguments that the function accepts,
+ if there is a fixed maximum. Alternatively, it can be `UNEVALLED',
+ indicating a special form that receives unevaluated arguments, or
+ `MANY', indicating an unlimited number of evaluated arguments (the
+ C equivalent of `&rest'). Both `UNEVALLED' and `MANY' are macros.
+ If MAX_ARGS is a number, it may not be less than MIN_ARGS and it
+ may not be greater than 8. (If you need to add a function with
+ more than 8 arguments, use the `MANY' form. Resist the urge to
+ edit the definition of `DEFUN' in `lisp.h'. If you do it anyways,
+ make sure to also add another clause to the switch statement in
+ `primitive_funcall().')
+
+INTERACTIVE
+ This is an interactive specification, a string such as might be
+ used as the argument of `interactive' in a Lisp function. In the
+ case of `prog1', it is 0 (a null pointer), indicating that `prog1'
+ cannot be called interactively. A value of `""' indicates a
+ function that should receive no arguments when called
+ interactively.
+
+DOCSTRING
+ This is the documentation string. It is written just like a
+ documentation string for a function defined in Lisp; in
+ particular, the first line should be a single sentence. Note how
+ the documentation string is enclosed in a comment, none of the
+ documentation is placed on the same lines as the comment-start and
+ comment-end characters, and the comment-start characters are on
+ the same line as the interactive specification. `make-docfile',
+ which scans the C files for documentation strings, is very
+ particular about what it looks for, and will not properly extract
+ the doc string if it's not in this exact format.
+
+ In order to make both `etags' and `make-docfile' happy, make sure
+ that the `DEFUN' line contains the LNAME and FNAME, and that the
+ comment-start characters for the doc string are on the same line
+ as the interactive specification, and put a newline directly after
+ them (and before the comment-end characters).
+
+ARGLIST
+ This is the comma-separated list of arguments to the C function.
+ For a function with a fixed maximum number of arguments, provide a
+ C argument for each Lisp argument. In this case, unlike regular C
+ functions, the types of the arguments are not declared; they are
+ simply always of type `Lisp_Object'.
+
+ The names of the C arguments will be used as the names of the
+ arguments to the Lisp primitive as displayed in its documentation,
+ modulo the same concerns described above for `F...' names (in
+ particular, underscores in the C arguments become dashes in the
+ Lisp arguments).
+
+ There is one additional kludge: A trailing `_' on the C argument is
+ discarded when forming the Lisp argument. This allows C language
+ reserved words (like `default') or global symbols (like `dirname')
+ to be used as argument names without compiler warnings or errors.
+
+ A Lisp function with MAX_ARGS = `UNEVALLED' is a "special form";
+ its arguments are not evaluated. Instead it receives one argument
+ of type `Lisp_Object', a (Lisp) list of the unevaluated arguments,
+ conventionally named `(args)'.
+
+ When a Lisp function has no upper limit on the number of arguments,
+ specify MAX_ARGS = `MANY'. In this case its implementation in C
+ actually receives exactly two arguments: the number of Lisp
+ arguments (an `int') and the address of a block containing their
+ values (a `Lisp_Object *'). In this case only are the C types
+ specified in the ARGLIST: `(int nargs, Lisp_Object *args)'.
+
+ Within the function `Fprog1' itself, note the use of the macros
+`GCPRO1' and `UNGCPRO'. `GCPRO1' is used to "protect" a variable from
+garbage collection--to inform the garbage collector that it must look
+in that variable and regard the object pointed at by its contents as an
+accessible object. This is necessary whenever you call `Feval' or
+anything that can directly or indirectly call `Feval' (this includes
+the `QUIT' macro!). At such a time, any Lisp object that you intend to
+refer to again must be protected somehow. `UNGCPRO' cancels the
+protection of the variables that are protected in the current function.
+It is necessary to do this explicitly.
+
+ The macro `GCPRO1' protects just one local variable. If you want to
+protect two, use `GCPRO2' instead; repeating `GCPRO1' will not work.
+Macros `GCPRO3' and `GCPRO4' also exist.
+
+ These macros implicitly use local variables such as `gcpro1'; you
+must declare these explicitly, with type `struct gcpro'. Thus, if you
+use `GCPRO2', you must declare `gcpro1' and `gcpro2'.
+
+ Note also that the general rule is "caller-protects"; i.e. you are
+only responsible for protecting those Lisp objects that you create. Any
+objects passed to you as arguments should have been protected by whoever
+created them, so you don't in general have to protect them.
+
+ In particular, the arguments to any Lisp primitive are always
+automatically `GCPRO'ed, when called "normally" from Lisp code or
+bytecode. So only a few Lisp primitives that are called frequently from
+C code, such as `Fprogn' protect their arguments as a service to their
+caller. You don't need to protect your arguments when writing a new
+`DEFUN'.
+
+ `GCPRO'ing is perhaps the trickiest and most error-prone part of
+XEmacs coding. It is *extremely* important that you get this right and
+use a great deal of discipline when writing this code. *Note
+`GCPRO'ing: GCPROing, for full details on how to do this.
+
+ What `DEFUN' actually does is declare a global structure of type
+`Lisp_Subr' whose name begins with capital `SF' and which contains
+information about the primitive (e.g. a pointer to the function, its
+minimum and maximum allowed arguments, a string describing its Lisp
+name); `DEFUN' then begins a normal C function declaration using the
+`F...' name. The Lisp subr object that is the function definition of a
+primitive (i.e. the object in the function slot of the symbol that
+names the primitive) actually points to this `SF' structure; when
+`Feval' encounters a subr, it looks in the structure to find out how to
+call the C function.
+
+ Defining the C function is not enough to make a Lisp primitive
+available; you must also create the Lisp symbol for the primitive (the
+symbol is "interned"; *note Obarrays::.) and store a suitable subr
+object in its function cell. (If you don't do this, the primitive won't
+be seen by Lisp code.) The code looks like this:
+
+ DEFSUBR (FNAME);
+
+Here FNAME is the same name you used as the second argument to `DEFUN'.
+
+ This call to `DEFSUBR' should go in the `syms_of_*()' function at
+the end of the module. If no such function exists, create it and make
+sure to also declare it in `symsinit.h' and call it from the
+appropriate spot in `main()'. *Note General Coding Rules::.
+
+ Note that C code cannot call functions by name unless they are
+defined in C. The way to call a function written in Lisp from C is to
+use `Ffuncall', which embodies the Lisp function `funcall'. Since the
+Lisp function `funcall' accepts an unlimited number of arguments, in C
+it takes two: the number of Lisp-level arguments, and a one-dimensional
+array containing their values. The first Lisp-level argument is the
+Lisp function to call, and the rest are the arguments to pass to it.
+Since `Ffuncall' can call the evaluator, you must protect pointers from
+garbage collection around the call to `Ffuncall'. (However, `Ffuncall'
+explicitly protects all of its parameters, so you don't have to protect
+any pointers passed as parameters to it.)
+
+ The C functions `call0', `call1', `call2', and so on, provide handy
+ways to call a Lisp function conveniently with a fixed number of
+arguments. They work by calling `Ffuncall'.
+
+ `eval.c' is a very good file to look through for examples; `lisp.h'
+contains the definitions for important macros and functions.
+
+\1f
+File: internals.info, Node: Adding Global Lisp Variables, Next: Coding for Mule, Prev: Writing Lisp Primitives, Up: Rules When Writing New C Code
+
+Adding Global Lisp Variables
+============================
+
+ Global variables whose names begin with `Q' are constants whose
+value is a symbol of a particular name. The name of the variable should
+be derived from the name of the symbol using the same rules as for Lisp
+primitives. These variables are initialized using a call to
+`defsymbol()' in the `syms_of_*()' function. (This call interns a
+symbol, sets the C variable to the resulting Lisp object, and calls
+`staticpro()' on the C variable to tell the garbage-collection
+mechanism about this variable. What `staticpro()' does is add a
+pointer to the variable to a large global array; when
+garbage-collection happens, all pointers listed in the array are used
+as starting points for marking Lisp objects. This is important because
+it's quite possible that the only current reference to the object is
+the C variable. In the case of symbols, the `staticpro()' doesn't
+matter all that much because the symbol is contained in `obarray',
+which is itself `staticpro()'ed. However, it's possible that a naughty
+user could do something like uninterning the symbol out of `obarray' or
+even setting `obarray' to a different value [although this is likely to
+make XEmacs crash!].)
+
+ *Please note:* It is potentially deadly if you declare a `Q...'
+variable in two different modules. The two calls to `defsymbol()' are
+no problem, but some linkers will complain about multiply-defined
+symbols. The most insidious aspect of this is that often the link will
+succeed anyway, but then the resulting executable will sometimes crash
+in obscure ways during certain operations! To avoid this problem,
+declare any symbols with common names (such as `text') that are not
+obviously associated with this particular module in the module
+`general.c'.
+
+ Global variables whose names begin with `V' are variables that
+contain Lisp objects. The convention here is that all global variables
+of type `Lisp_Object' begin with `V', and all others don't (including
+integer and boolean variables that have Lisp equivalents). Most of the
+time, these variables have equivalents in Lisp, but some don't. Those
+that do are declared this way by a call to `DEFVAR_LISP()' in the
+`vars_of_*()' initializer for the module. What this does is create a
+special "symbol-value-forward" Lisp object that contains a pointer to
+the C variable, intern a symbol whose name is as specified in the call
+to `DEFVAR_LISP()', and set its value to the symbol-value-forward Lisp
+object; it also calls `staticpro()' on the C variable to tell the
+garbage-collection mechanism about the variable. When `eval' (or
+actually `symbol-value') encounters this special object in the process
+of retrieving a variable's value, it follows the indirection to the C
+variable and gets its value. `setq' does similar things so that the C
+variable gets changed.
+
+ Whether or not you `DEFVAR_LISP()' a variable, you need to
+initialize it in the `vars_of_*()' function; otherwise it will end up
+as all zeroes, which is the integer 0 (*not* `nil'), and this is
+probably not what you want. Also, if the variable is not
+`DEFVAR_LISP()'ed, *you must call* `staticpro()' on the C variable in
+the `vars_of_*()' function. Otherwise, the garbage-collection
+mechanism won't know that the object in this variable is in use, and
+will happily collect it and reuse its storage for another Lisp object,
+and you will be the one who's unhappy when you can't figure out how
+your variable got overwritten.
+
+\1f
+File: internals.info, Node: Coding for Mule, Next: Techniques for XEmacs Developers, Prev: Adding Global Lisp Variables, Up: Rules When Writing New C Code
+
+Coding for Mule
+===============
+
+ Although Mule support is not compiled by default in XEmacs, many
+people are using it, and we consider it crucial that new code works
+correctly with multibyte characters. This is not hard; it is only a
+matter of following several simple user-interface guidelines. Even if
+you never compile with Mule, with a little practice you will find it
+quite easy to code Mule-correctly.
+
+ Note that these guidelines are not necessarily tied to the current
+Mule implementation; they are also a good idea to follow on the grounds
+of code generalization for future I18N work.
+
+* Menu:
+
+* Character-Related Data Types::
+* Working With Character and Byte Positions::
+* Conversion to and from External Data::
+* General Guidelines for Writing Mule-Aware Code::
+* An Example of Mule-Aware Code::
+
+\1f
+File: internals.info, Node: Character-Related Data Types, Next: Working With Character and Byte Positions, Up: Coding for Mule
+
+Character-Related Data Types
+----------------------------
+
+ First, let's review the basic character-related datatypes used by
+XEmacs. Note that the separate `typedef's are not mandatory in the
+current implementation (all of them boil down to `unsigned char' or
+`int'), but they improve clarity of code a great deal, because one
+glance at the declaration can tell the intended use of the variable.
+
+`Emchar'
+ An `Emchar' holds a single Emacs character.
+
+ Obviously, the equality between characters and bytes is lost in
+ the Mule world. Characters can be represented by one or more
+ bytes in the buffer, and `Emchar' is the C type large enough to
+ hold any character.
+
+ Without Mule support, an `Emchar' is equivalent to an `unsigned
+ char'.
+
+`Bufbyte'
+ The data representing the text in a buffer or string is logically
+ a set of `Bufbyte's.
+
+ XEmacs does not work with character formats all the time; when
+ reading characters from the outside, it decodes them to an
+ internal format, and likewise encodes them when writing.
+ `Bufbyte' (in fact `unsigned char') is the basic unit of XEmacs
+ internal buffers and strings format.
+
+ One character can correspond to one or more `Bufbyte's. In the
+ current implementation, an ASCII character is represented by the
+ same `Bufbyte', and extended characters are represented by a
+ sequence of `Bufbyte's.
+
+ Without Mule support, a `Bufbyte' is equivalent to an `Emchar'.
+
+`Bufpos'
+`Charcount'
+ A `Bufpos' represents a character position in a buffer or string.
+ A `Charcount' represents a number (count) of characters.
+ Logically, subtracting two `Bufpos' values yields a `Charcount'
+ value. Although all of these are `typedef'ed to `int', we use
+ them in preference to `int' to make it clear what sort of position
+ is being used.
+
+ `Bufpos' and `Charcount' values are the only ones that are ever
+ visible to Lisp.
+
+`Bytind'
+`Bytecount'
+ A `Bytind' represents a byte position in a buffer or string. A
+ `Bytecount' represents the distance between two positions in bytes.
+ The relationship between `Bytind' and `Bytecount' is the same as
+ the relationship between `Bufpos' and `Charcount'.
+
+`Extbyte'
+`Extcount'
+ When dealing with the outside world, XEmacs works with `Extbyte's,
+ which are equivalent to `unsigned char'. Obviously, an `Extcount'
+ is the distance between two `Extbyte's. Extbytes and Extcounts
+ are not all that frequent in XEmacs code.
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: Working With Character and Byte Positions, Next: Conversion to and from External Data, Prev: Character-Related Data Types, Up: Coding for Mule
+
+Working With Character and Byte Positions
+-----------------------------------------
+
+ Now that we have defined the basic character-related types, we can
+look at the macros and functions designed for work with them and for
+conversion between them. Most of these macros are defined in
+`buffer.h', and we don't discuss all of them here, but only the most
+important ones. Examining the existing code is the best way to learn
+about them.
+
+`MAX_EMCHAR_LEN'
+ This preprocessor constant is the maximum number of buffer bytes
+ per Emacs character, i.e. the byte length of an `Emchar'. It is
+ useful when allocating temporary strings to keep a known number of
+ characters. For instance:
+
+ {
+ Charcount cclen;
+ ...
+ {
+ /* Allocate place for CCLEN characters. */
+ Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN);
+ ...
+
+ If you followed the previous section, you can guess that,
+ logically, multiplying a `Charcount' value with `MAX_EMCHAR_LEN'
+ produces a `Bytecount' value.
+
+ In the current Mule implementation, `MAX_EMCHAR_LEN' equals 4.
+ Without Mule, it is 1.
+
+`charptr_emchar'
+`set_charptr_emchar'
+ The `charptr_emchar' macro takes a `Bufbyte' pointer and returns
+ the `Emchar' stored at that position. If it were a function, its
+ prototype would be:
+
+ Emchar charptr_emchar (Bufbyte *p);
+
+ `set_charptr_emchar' stores an `Emchar' to the specified byte
+ position. It returns the number of bytes stored:
+
+ Bytecount set_charptr_emchar (Bufbyte *p, Emchar c);
+
+ It is important to note that `set_charptr_emchar' is safe only for
+ appending a character at the end of a buffer, not for overwriting a
+ character in the middle. This is because the width of characters
+ varies, and `set_charptr_emchar' cannot resize the string if it
+ writes, say, a two-byte character where a single-byte character
+ used to reside.
+
+ A typical use of `set_charptr_emchar' can be demonstrated by this
+ example, which copies characters from buffer BUF to a temporary
+ string of Bufbytes.
+
+ {
+ Bufpos pos;
+ for (pos = beg; pos < end; pos++)
+ {
+ Emchar c = BUF_FETCH_CHAR (buf, pos);
+ p += set_charptr_emchar (buf, c);
+ }
+ }
+
+ Note how `set_charptr_emchar' is used to store the `Emchar' and
+ increment the counter, at the same time.
+
+`INC_CHARPTR'
+`DEC_CHARPTR'
+ These two macros increment and decrement a `Bufbyte' pointer,
+ respectively. They will adjust the pointer by the appropriate
+ number of bytes according to the byte length of the character
+ stored there. Both macros assume that the memory address is
+ located at the beginning of a valid character.
+
+ Without Mule support, `INC_CHARPTR (p)' and `DEC_CHARPTR (p)'
+ simply expand to `p++' and `p--', respectively.
+
+`bytecount_to_charcount'
+ Given a pointer to a text string and a length in bytes, return the
+ equivalent length in characters.
+
+ Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc);
+
+`charcount_to_bytecount'
+ Given a pointer to a text string and a length in characters,
+ return the equivalent length in bytes.
+
+ Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc);
+
+`charptr_n_addr'
+ Return a pointer to the beginning of the character offset CC (in
+ characters) from P.
+
+ Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc);
+
+\1f
+File: internals.info, Node: Conversion to and from External Data, Next: General Guidelines for Writing Mule-Aware Code, Prev: Working With Character and Byte Positions, Up: Coding for Mule
+
+Conversion to and from External Data
+------------------------------------
+
+ When an external function, such as a C library function, returns a
+`char' pointer, you should almost never treat it as `Bufbyte'. This is
+because these returned strings may contain 8bit characters which can be
+misinterpreted by XEmacs, and cause a crash. Likewise, when exporting
+a piece of internal text to the outside world, you should always
+convert it to an appropriate external encoding, lest the internal stuff
+(such as the infamous \201 characters) leak out.
+
+ The interface to conversion between the internal and external
+representations of text are the numerous conversion macros defined in
+`buffer.h'. Before looking at them, we'll look at the external formats
+supported by these macros.
+
+ Currently meaningful formats are `FORMAT_BINARY', `FORMAT_FILENAME',
+`FORMAT_OS', and `FORMAT_CTEXT'. Here is a description of these.
+
+`FORMAT_BINARY'
+ Binary format. This is the simplest format and is what we use in
+ the absence of a more appropriate format. This converts according
+ to the `binary' coding system:
+
+ a. On input, bytes 0-255 are converted into characters 0-255.
+
+ b. On output, characters 0-255 are converted into bytes 0-255
+ and other characters are converted into `X'.
+
+`FORMAT_FILENAME'
+ Format used for filenames. In the original Mule, this is
+ user-definable with the `pathname-coding-system' variable. For
+ the moment, we just use the `binary' coding system.
+
+`FORMAT_OS'
+ Format used for the external Unix environment--`argv[]', stuff
+ from `getenv()', stuff from the `/etc/passwd' file, etc.
+
+ Perhaps should be the same as FORMAT_FILENAME.
+
+`FORMAT_CTEXT'
+ Compound-text format. This is the standard X format used for data
+ stored in properties, selections, and the like. This is an 8-bit
+ no-lock-shift ISO2022 coding system.
+
+ The macros to convert between these formats and the internal format,
+and vice versa, follow.
+
+`GET_CHARPTR_INT_DATA_ALLOCA'
+`GET_CHARPTR_EXT_DATA_ALLOCA'
+ These two are the most basic conversion macros.
+ `GET_CHARPTR_INT_DATA_ALLOCA' converts external data to internal
+ format, and `GET_CHARPTR_EXT_DATA_ALLOCA' converts the other way
+ around. The arguments each of these receives are PTR (pointer to
+ the text in external format), LEN (length of texts in bytes), FMT
+ (format of the external text), PTR_OUT (lvalue to which new text
+ should be copied), and LEN_OUT (lvalue which will be assigned the
+ length of the internal text in bytes). The resulting text is
+ stored to a stack-allocated buffer. If the text doesn't need
+ changing, these macros will do nothing, except for setting LEN_OUT.
+
+ The macros above take many arguments which makes them unwieldy.
+ For this reason, a number of convenience macros are defined with
+ obvious functionality, but accepting less arguments. The general
+ rule is that macros with `INT' in their name convert text to
+ internal Emacs representation, whereas the `EXT' macros convert to
+ external representation.
+
+`GET_C_CHARPTR_INT_DATA_ALLOCA'
+`GET_C_CHARPTR_EXT_DATA_ALLOCA'
+ As their names imply, these macros work on C char pointers, which
+ are zero-terminated, and thus do not need LEN or LEN_OUT
+ parameters.
+
+`GET_STRING_EXT_DATA_ALLOCA'
+`GET_C_STRING_EXT_DATA_ALLOCA'
+ These two macros convert a Lisp string into an external
+ representation. The difference between them is that
+ `GET_STRING_EXT_DATA_ALLOCA' stores its output to a generic
+ string, providing LEN_OUT, the length of the resulting external
+ string. On the other hand, `GET_C_STRING_EXT_DATA_ALLOCA' assumes
+ that the caller will be satisfied with output string being
+ zero-terminated.
+
+ Note that for Lisp strings only one conversion direction makes
+ sense.
+
+`GET_C_CHARPTR_EXT_BINARY_DATA_ALLOCA'
+`GET_CHARPTR_EXT_BINARY_DATA_ALLOCA'
+`GET_STRING_BINARY_DATA_ALLOCA'
+`GET_C_STRING_BINARY_DATA_ALLOCA'
+`GET_C_CHARPTR_EXT_FILENAME_DATA_ALLOCA'
+`...'
+ These macros convert internal text to a specific external
+ representation, with the external format being encoded into the
+ name of the macro. Note that the `GET_STRING_...' and
+ `GET_C_STRING...' macros lack the `EXT' tag, because they only
+ make sense in that direction.
+
+`GET_C_CHARPTR_INT_BINARY_DATA_ALLOCA'
+`GET_CHARPTR_INT_BINARY_DATA_ALLOCA'
+`GET_C_CHARPTR_INT_FILENAME_DATA_ALLOCA'
+`...'
+ These macros convert external text of a specific format to its
+ internal representation, with the external format being incoded
+ into the name of the macro.
+
+\1f
+File: internals.info, Node: General Guidelines for Writing Mule-Aware Code, Next: An Example of Mule-Aware Code, Prev: Conversion to and from External Data, Up: Coding for Mule
+
+General Guidelines for Writing Mule-Aware Code
+----------------------------------------------
+
+ This section contains some general guidance on how to write
+Mule-aware code, as well as some pitfalls you should avoid.
+
+*Never use `char' and `char *'.*
+ In XEmacs, the use of `char' and `char *' is almost always a
+ mistake. If you want to manipulate an Emacs character from "C",
+ use `Emchar'. If you want to examine a specific octet in the
+ internal format, use `Bufbyte'. If you want a Lisp-visible
+ character, use a `Lisp_Object' and `make_char'. If you want a
+ pointer to move through the internal text, use `Bufbyte *'. Also
+ note that you almost certainly do not need `Emchar *'.
+
+*Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'.*
+ The whole point of using different types is to avoid confusion
+ about the use of certain variables. Lest this effect be
+ nullified, you need to be careful about using the right types.
+
+*Always convert external data*
+ It is extremely important to always convert external data, because
+ XEmacs can crash if unexpected 8bit sequences are copied to its
+ internal buffers literally.
+
+ This means that when a system function, such as `readdir', returns
+ a string, you need to convert it using one of the conversion macros
+ described in the previous chapter, before passing it further to
+ Lisp. In the case of `readdir', you would use the
+ `GET_C_CHARPTR_INT_FILENAME_DATA_ALLOCA' macro.
+
+ Also note that many internal functions, such as `make_string',
+ accept Bufbytes, which removes the need for them to convert the
+ data they receive. This increases efficiency because that way
+ external data needs to be decoded only once, when it is read.
+ After that, it is passed around in internal format.
+
+\1f
+File: internals.info, Node: An Example of Mule-Aware Code, Prev: General Guidelines for Writing Mule-Aware Code, Up: Coding for Mule
+
+An Example of Mule-Aware Code
+-----------------------------
+
+ As an example of Mule-aware code, we shall will analyze the `string'
+function, which conses up a Lisp string from the character arguments it
+receives. Here is the definition, pasted from `alloc.c':
+
+ DEFUN ("string", Fstring, 0, MANY, 0, /*
+ Concatenate all the argument characters and make the result a string.
+ */
+ (int nargs, Lisp_Object *args))
+ {
+ Bufbyte *storage = alloca_array (Bufbyte, nargs * MAX_EMCHAR_LEN);
+ Bufbyte *p = storage;
+
+ for (; nargs; nargs--, args++)
+ {
+ Lisp_Object lisp_char = *args;
+ CHECK_CHAR_COERCE_INT (lisp_char);
+ p += set_charptr_emchar (p, XCHAR (lisp_char));
+ }
+ return make_string (storage, p - storage);
+ }
+
+ Now we can analyze the source line by line.
+
+ Obviously, string will be as long as there are arguments to the
+function. This is why we allocate `MAX_EMCHAR_LEN' * NARGS bytes on
+the stack, i.e. the worst-case number of bytes for NARGS `Emchar's to
+fit in the string.
+
+ Then, the loop checks that each element is a character, converting
+integers in the process. Like many other functions in XEmacs, this
+function silently accepts integers where characters are expected, for
+historical and compatibility reasons. Unless you know what you are
+doing, `CHECK_CHAR' will also suffice. `XCHAR (lisp_char)' extracts
+the `Emchar' from the `Lisp_Object', and `set_charptr_emchar' stores it
+to storage, increasing `p' in the process.
+
+ Other instructive examples of correct coding under Mule can be found
+all over the XEmacs code. For starters, I recommend
+`Fnormalize_menu_item_name' in `menubar.c'. After you have understood
+this section of the manual and studied the examples, you can proceed
+writing new Mule-aware code.
+
+\1f
+File: internals.info, Node: Techniques for XEmacs Developers, Prev: Coding for Mule, Up: Rules When Writing New C Code
+
+Techniques for XEmacs Developers
+================================
+
+ To make a quantified XEmacs, do: `make quantmacs'.
+
+ You simply can't dump Quantified and Purified images. Run the image
+like so: `quantmacs -batch -l loadup.el run-temacs XEMACS-ARGS...'.
+
+ Before you go through the trouble, are you compiling with all
+debugging and error-checking off? If not try that first. Be warned
+that while Quantify is directly responsible for quite a few
+optimizations which have been made to XEmacs, doing a run which
+generates results which can be acted upon is not necessarily a trivial
+task.
+
+ Also, if you're still willing to do some runs make sure you configure
+with the `--quantify' flag. That will keep Quantify from starting to
+record data until after the loadup is completed and will shut off
+recording right before it shuts down (which generates enough bogus data
+to throw most results off). It also enables three additional elisp
+commands: `quantify-start-recording-data',
+`quantify-stop-recording-data' and `quantify-clear-data'.
+
+ If you want to make XEmacs faster, target your favorite slow
+benchmark, run a profiler like Quantify, `gprof', or `tcov', and figure
+out where the cycles are going. Specific projects:
+
+ * Make the garbage collector faster. Figure out how to write an
+ incremental garbage collector.
+
+ * Write a compiler that takes bytecode and spits out C code.
+ Unfortunately, you will then need a C compiler and a more fully
+ developed module system.
+
+ * Speed up redisplay.
+
+ * Speed up syntax highlighting. Maybe moving some of the syntax
+ highlighting capabilities into C would make a difference.
+
+ * Implement tail recursion in Emacs Lisp (hard!).
+
+ Unfortunately, Emacs Lisp is slow, and is going to stay slow.
+Function calls in elisp are especially expensive. Iterating over a
+long list is going to be 30 times faster implemented in C than in Elisp.
+
+ To get started debugging XEmacs, take a look at the `gdbinit' and
+`dbxrc' files in the `src' directory. *Note Q2.1.15 - How to Debug an
+XEmacs problem with a debugger: (xemacs-faq)Q2.1.15 - How to Debug an
+XEmacs problem with a debugger.
+
+ After making source code changes, run `make check' to ensure that
+you haven't introduced any regressions. If you're feeling ambitious,
+you can try to improve the test suite in `tests/automated'.
+
+ Here are things to know when you create a new source file:
+
+ * All `.c' files should `#include <config.h>' first. Almost all
+ `.c' files should `#include "lisp.h"' second.
+
+ * Generated header files should be included using the `#include
+ <...>' syntax, not the `#include "..."' syntax. The generated
+ headers are:
+
+ `config.h puresize-adjust.h sheap-adjust.h paths.h Emacs.ad.h'
+
+ The basic rule is that you should assume builds using `--srcdir'
+ and the `#include <...>' syntax needs to be used when the
+ to-be-included generated file is in a potentially different
+ directory *at compile time*. The non-obvious C rule is that
+ `#include "..."' means to search for the included file in the
+ same directory as the including file, *not* in the current
+ directory.
+
+ * Header files should *not* include `<config.h>' and `"lisp.h"'. It
+ is the responsibility of the `.c' files that use it to do so.
+
+ * If the header uses `INLINE', either directly or through
+ `DECLARE_LRECORD', then it must be added to `inline.c''s includes.
+
+ * Try compiling at least once with
+
+ gcc --with-mule --with-union-type --error-checking=all
+
+ * Did I mention that you should run the test suite?
+ make check
+
+\1f
+File: internals.info, Node: A Summary of the Various XEmacs Modules, Next: Allocation of Objects in XEmacs Lisp, Prev: Rules When Writing New C Code, Up: Top
+
+A Summary of the Various XEmacs Modules
+***************************************
+
+ This is accurate as of XEmacs 20.0.
+
+* Menu:
+
+* Low-Level Modules::
+* Basic Lisp Modules::
+* Modules for Standard Editing Operations::
+* Editor-Level Control Flow Modules::
+* Modules for the Basic Displayable Lisp Objects::
+* Modules for other Display-Related Lisp Objects::
+* Modules for the Redisplay Mechanism::
+* Modules for Interfacing with the File System::
+* Modules for Other Aspects of the Lisp Interpreter and Object System::
+* Modules for Interfacing with the Operating System::
+* Modules for Interfacing with X Windows::
+* Modules for Internationalization::
+
+\1f
+File: internals.info, Node: Low-Level Modules, Next: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules
+
+Low-Level Modules
+=================
+
+ config.h
+
+ This is automatically generated from `config.h.in' based on the
+results of configure tests and user-selected optional features and
+contains preprocessor definitions specifying the nature of the
+environment in which XEmacs is being compiled.
+
+ paths.h
+
+ This is automatically generated from `paths.h.in' based on supplied
+configure values, and allows for non-standard installed configurations
+of the XEmacs directories. It's currently broken, though.
+
+ emacs.c
+ signal.c
+
+ `emacs.c' contains `main()' and other code that performs the most
+basic environment initializations and handles shutting down the XEmacs
+process (this includes `kill-emacs', the normal way that XEmacs is
+exited; `dump-emacs', which is used during the build process to write
+out the XEmacs executable; `run-emacs-from-temacs', which can be used
+to start XEmacs directly when temacs has finished loading all the Lisp
+code; and emergency code to handle crashes [XEmacs tries to auto-save
+all files before it crashes]).
+
+ Low-level code that directly interacts with the Unix signal
+mechanism, however, is in `signal.c'. Note that this code does not
+handle system dependencies in interfacing to signals; that is handled
+using the `syssignal.h' header file, described in section J below.
+
+ unexaix.c
+ unexalpha.c
+ unexapollo.c
+ unexconvex.c
+ unexec.c
+ unexelf.c
+ unexelfsgi.c
+ unexencap.c
+ unexenix.c
+ unexfreebsd.c
+ unexfx2800.c
+ unexhp9k3.c
+ unexhp9k800.c
+ unexmips.c
+ unexnext.c
+ unexsol2.c
+ unexsunos4.c
+
+ These modules contain code dumping out the XEmacs executable on
+various different systems. (This process is highly machine-specific and
+requires intimate knowledge of the executable format and the memory map
+of the process.) Only one of these modules is actually used; this is
+chosen by `configure'.
+
+ crt0.c
+ lastfile.c
+ pre-crt0.c
+
+ These modules are used in conjunction with the dump mechanism. On
+some systems, an alternative version of the C startup code (the actual
+code that receives control from the operating system when the process is
+started, and which calls `main()') is required so that the dumping
+process works properly; `crt0.c' provides this.
+
+ `pre-crt0.c' and `lastfile.c' should be the very first and very last
+file linked, respectively. (Actually, this is not really true.
+`lastfile.c' should be after all Emacs modules whose initialized data
+should be made constant, and before all other Emacs files and all
+libraries. In particular, the allocation modules `gmalloc.c',
+`alloca.c', etc. are normally placed past `lastfile.c', and all of the
+files that implement Xt widget classes *must* be placed after
+`lastfile.c' because they contain various structures that must be
+statically initialized and into which Xt writes at various times.)
+`pre-crt0.c' and `lastfile.c' contain exported symbols that are used to
+determine the start and end of XEmacs' initialized data space when
+dumping.
+
+ alloca.c
+ free-hook.c
+ getpagesize.h
+ gmalloc.c
+ malloc.c
+ mem-limits.h
+ ralloc.c
+ vm-limit.c
+
+ These handle basic C allocation of memory. `alloca.c' is an
+emulation of the stack allocation function `alloca()' on machines that
+lack this. (XEmacs makes extensive use of `alloca()' in its code.)
+
+ `gmalloc.c' and `malloc.c' are two implementations of the standard C
+functions `malloc()', `realloc()' and `free()'. They are often used in
+place of the standard system-provided `malloc()' because they usually
+provide a much faster implementation, at the expense of additional
+memory use. `gmalloc.c' is a newer implementation that is much more
+memory-efficient for large allocations than `malloc.c', and should
+always be preferred if it works. (At one point, `gmalloc.c' didn't work
+on some systems where `malloc.c' worked; but this should be fixed now.)
+
+ `ralloc.c' is the "relocating allocator". It provides functions
+similar to `malloc()', `realloc()' and `free()' that allocate memory
+that can be dynamically relocated in memory. The advantage of this is
+that allocated memory can be shuffled around to place all the free
+memory at the end of the heap, and the heap can then be shrunk,
+releasing the memory back to the operating system. The use of this can
+be controlled with the configure option `--rel-alloc'; if enabled,
+memory allocated for buffers will be relocatable, so that if a very
+large file is visited and the buffer is later killed, the memory can be
+released to the operating system. (The disadvantage of this mechanism
+is that it can be very slow. On systems with the `mmap()' system call,
+the XEmacs version of `ralloc.c' uses this to move memory around
+without actually having to block-copy it, which can speed things up;
+but it can still cause noticeable performance degradation.)
+
+ `free-hook.c' contains some debugging functions for checking for
+invalid arguments to `free()'.
+
+ `vm-limit.c' contains some functions that warn the user when memory
+is getting low. These are callback functions that are called by
+`gmalloc.c' and `malloc.c' at appropriate times.
+
+ `getpagesize.h' provides a uniform interface for retrieving the size
+of a page in virtual memory. `mem-limits.h' provides a uniform
+interface for retrieving the total amount of available virtual memory.
+Both are similar in spirit to the `sys*.h' files described in section
+J, below.
+
+ blocktype.c
+ blocktype.h
+ dynarr.c
+
+ These implement a couple of basic C data types to facilitate memory
+allocation. The `Blocktype' type efficiently manages the allocation of
+fixed-size blocks by minimizing the number of times that `malloc()' and
+`free()' are called. It allocates memory in large chunks, subdivides
+the chunks into blocks of the proper size, and returns the blocks as
+requested. When blocks are freed, they are placed onto a linked list,
+so they can be efficiently reused. This data type is not much used in
+XEmacs currently, because it's a fairly new addition.
+
+ The `Dynarr' type implements a "dynamic array", which is similar to
+a standard C array but has no fixed limit on the number of elements it
+can contain. Dynamic arrays can hold elements of any type, and when
+you add a new element, the array automatically resizes itself if it
+isn't big enough. Dynarrs are extensively used in the redisplay
+mechanism.
+
+ inline.c
+
+ This module is used in connection with inline functions (available in
+some compilers). Often, inline functions need to have a corresponding
+non-inline function that does the same thing. This module is where they
+reside. It contains no actual code, but defines some special flags that
+cause inline functions defined in header files to be rendered as actual
+functions. It then includes all header files that contain any inline
+function definitions, so that each one gets a real function equivalent.
+
+ debug.c
+ debug.h
+
+ These functions provide a system for doing internal consistency
+checks during code development. This system is not currently used;
+instead the simpler `assert()' macro is used along with the various
+checks provided by the `--error-check-*' configuration options.
+
+ prefix-args.c
+
+ This is actually the source for a small, self-contained program used
+during building.
+
+ universe.h
+
+ This is not currently used.
+
+\1f
+File: internals.info, Node: Basic Lisp Modules, Next: Modules for Standard Editing Operations, Prev: Low-Level Modules, Up: A Summary of the Various XEmacs Modules
+
+Basic Lisp Modules
+==================
+
+ emacsfns.h
+ lisp-disunion.h
+ lisp-union.h
+ lisp.h
+ lrecord.h
+ symsinit.h
+
+ These are the basic header files for all XEmacs modules. Each module
+includes `lisp.h', which brings the other header files in. `lisp.h'
+contains the definitions of the structures and extractor and
+constructor macros for the basic Lisp objects and various other basic
+definitions for the Lisp environment, as well as some general-purpose
+definitions (e.g. `min()' and `max()'). `lisp.h' includes either
+`lisp-disunion.h' or `lisp-union.h', depending on whether
+`USE_UNION_TYPE' is defined. These files define the typedef of the
+Lisp object itself (as described above) and the low-level macros that
+hide the actual implementation of the Lisp object. All extractor and
+constructor macros for particular types of Lisp objects are defined in
+terms of these low-level macros.
+
+ As a general rule, all typedefs should go into the typedefs section
+of `lisp.h' rather than into a module-specific header file even if the
+structure is defined elsewhere. This allows function prototypes that
+use the typedef to be placed into other header files. Forward structure
+declarations (i.e. a simple declaration like `struct foo;' where the
+structure itself is defined elsewhere) should be placed into the
+typedefs section as necessary.
+
+ `lrecord.h' contains the basic structures and macros that implement
+all record-type Lisp objects - i.e. all objects whose type is a field
+in their C structure, which includes all objects except the few most
+basic ones.
+
+ `lisp.h' contains prototypes for most of the exported functions in
+the various modules. Lisp primitives defined using `DEFUN' that need
+to be called by C code should be declared using `EXFUN'. Other
+function prototypes should be placed either into the appropriate
+section of `lisp.h', or into a module-specific header file, depending
+on how general-purpose the function is and whether it has
+special-purpose argument types requiring definitions not in `lisp.h'.)
+All initialization functions are prototyped in `symsinit.h'.
+
+ alloc.c
+ pure.c
+ puresize.h
+
+ The large module `alloc.c' implements all of the basic allocation and
+garbage collection for Lisp objects. The most commonly used Lisp
+objects are allocated in chunks, similar to the Blocktype data type
+described above; others are allocated in individually `malloc()'ed
+blocks. This module provides the foundation on which all other aspects
+of the Lisp environment sit, and is the first module initialized at
+startup.
+
+ Note that `alloc.c' provides a series of generic functions that are
+not dependent on any particular object type, and interfaces to
+particular types of objects using a standardized interface of
+type-specific methods. This scheme is a fundamental principle of
+object-oriented programming and is heavily used throughout XEmacs. The
+great advantage of this is that it allows for a clean separation of
+functionality into different modules - new classes of Lisp objects, new
+event interfaces, new device types, new stream interfaces, etc. can be
+added transparently without affecting code anywhere else in XEmacs.
+Because the different subsystems are divided into general and specific
+code, adding a new subtype within a subsystem will in general not
+require changes to the generic subsystem code or affect any of the other
+subtypes in the subsystem; this provides a great deal of robustness to
+the XEmacs code.
+
+ `pure.c' contains the declaration of the "purespace" array. Pure
+space is a hack used to place some constant Lisp data into the code
+segment of the XEmacs executable, even though the data needs to be
+initialized through function calls. (See above in section VIII for more
+info about this.) During startup, certain sorts of data is
+automatically copied into pure space, and other data is copied manually
+in some of the basic Lisp files by calling the function `purecopy',
+which copies the object if possible (this only works in temacs, of
+course) and returns the new object. In particular, while temacs is
+executing, the Lisp reader automatically copies all compiled-function
+objects that it reads into pure space. Since compiled-function objects
+are large, are never modified, and typically comprise the majority of
+the contents of a compiled-Lisp file, this works well. While XEmacs is
+running, any attempt to modify an object that resides in pure space
+causes an error. Objects in pure space are never garbage collected -
+almost all of the time, they're intended to be permanent, and in any
+case you can't write into pure space to set the mark bits.
+
+ `puresize.h' contains the declaration of the size of the pure space
+array. This depends on the optional features that are compiled in, any
+extra purespace requested by the user at compile time, and certain other
+factors (e.g. 64-bit machines need more pure space because their Lisp
+objects are larger). The smallest size that suffices should be used, so
+that there's no wasted space. If there's not enough pure space, you
+will get an error during the build process, specifying how much more
+pure space is needed.
+
+ eval.c
+ backtrace.h
+
+ This module contains all of the functions to handle the flow of
+control. This includes the mechanisms of defining functions, calling
+functions, traversing stack frames, and binding variables; the control
+primitives and other special forms such as `while', `if', `eval',
+`let', `and', `or', `progn', etc.; handling of non-local exits,
+unwind-protects, and exception handlers; entering the debugger; methods
+for the subr Lisp object type; etc. It does *not* include the `read'
+function, the `print' function, or the handling of symbols and obarrays.
+
+ `backtrace.h' contains some structures related to stack frames and
+the flow of control.
+
+ lread.c
+
+ This module implements the Lisp reader and the `read' function,
+which converts text into Lisp objects, according to the read syntax of
+the objects, as described above. This is similar to the parser that is
+a part of all compilers.
+
+ print.c
+
+ This module implements the Lisp print mechanism and the `print'
+function and related functions. This is the inverse of the Lisp reader
+- it converts Lisp objects to a printed, textual representation.
+(Hopefully something that can be read back in using `read' to get an
+equivalent object.)
+
+ general.c
+ symbols.c
+ symeval.h
+
+ `symbols.c' implements the handling of symbols, obarrays, and
+retrieving the values of symbols. Much of the code is devoted to
+handling the special "symbol-value-magic" objects that define special
+types of variables - this includes buffer-local variables, variable
+aliases, variables that forward into C variables, etc. This module is
+initialized extremely early (right after `alloc.c'), because it is here
+that the basic symbols `t' and `nil' are created, and those symbols are
+used everywhere throughout XEmacs.
+
+ `symeval.h' contains the definitions of symbol structures and the
+`DEFVAR_LISP()' and related macros for declaring variables.
+
+ data.c
+ floatfns.c
+ fns.c
+
+ These modules implement the methods and standard Lisp primitives for
+all the basic Lisp object types other than symbols (which are described
+above). `data.c' contains all the predicates (primitives that return
+whether an object is of a particular type); the integer arithmetic
+functions; and the basic accessor and mutator primitives for the various
+object types. `fns.c' contains all the standard predicates for working
+with sequences (where, abstractly speaking, a sequence is an ordered set
+of objects, and can be represented by a list, string, vector, or
+bit-vector); it also contains `equal', perhaps on the grounds that bulk
+of the operation of `equal' is comparing sequences. `floatfns.c'
+contains methods and primitives for floats and floating-point
+arithmetic.
+
+ bytecode.c
+ bytecode.h
+
+ `bytecode.c' implements the byte-code interpreter and
+compiled-function objects, and `bytecode.h' contains associated
+structures. Note that the byte-code *compiler* is written in Lisp.
+
+\1f
+File: internals.info, Node: Modules for Standard Editing Operations, Next: Editor-Level Control Flow Modules, Prev: Basic Lisp Modules, Up: A Summary of the Various XEmacs Modules
+
+Modules for Standard Editing Operations
+=======================================
+
+ buffer.c
+ buffer.h
+ bufslots.h
+
+ `buffer.c' implements the "buffer" Lisp object type. This includes
+functions that create and destroy buffers; retrieve buffers by name or
+by other properties; manipulate lists of buffers (remember that buffers
+are permanent objects and stored in various ordered lists); retrieve or
+change buffer properties; etc. It also contains the definitions of all
+the built-in buffer-local variables (which can be viewed as buffer
+properties). It does *not* contain code to manipulate buffer-local
+variables (that's in `symbols.c', described above); or code to
+manipulate the text in a buffer.
+
+ `buffer.h' defines the structures associated with a buffer and the
+various macros for retrieving text from a buffer and special buffer
+positions (e.g. `point', the default location for text insertion). It
+also contains macros for working with buffer positions and converting
+between their representations as character offsets and as byte offsets
+(under MULE, they are different, because characters can be multi-byte).
+It is one of the largest header files.
+
+ `bufslots.h' defines the fields in the buffer structure that
+correspond to the built-in buffer-local variables. It is its own
+header file because it is included many times in `buffer.c', as a way
+of iterating over all the built-in buffer-local variables.
+
+ insdel.c
+ insdel.h
+
+ `insdel.c' contains low-level functions for inserting and deleting
+text in a buffer, keeping track of changed regions for use by
+redisplay, and calling any before-change and after-change functions
+that may have been registered for the buffer. It also contains the
+actual functions that convert between byte offsets and character
+offsets.
+
+ `insdel.h' contains associated headers.
+
+ marker.c
+
+ This module implements the "marker" Lisp object type, which
+conceptually is a pointer to a text position in a buffer that moves
+around as text is inserted and deleted, so as to remain in the same
+relative position. This module doesn't actually move the markers around
+- that's handled in `insdel.c'. This module just creates them and
+implements the primitives for working with them. As markers are simple
+objects, this does not entail much.
+
+ Note that the standard arithmetic primitives (e.g. `+') accept
+markers in place of integers and automatically substitute the value of
+`marker-position' for the marker, i.e. an integer describing the
+current buffer position of the marker.
+
+ extents.c
+ extents.h
+
+ This module implements the "extent" Lisp object type, which is like
+a marker that works over a range of text rather than a single position.
+Extents are also much more complex and powerful than markers and have a
+more efficient (and more algorithmically complex) implementation. The
+implementation is described in detail in comments in `extents.c'.
+
+ The code in `extents.c' works closely with `insdel.c' so that
+extents are properly moved around as text is inserted and deleted.
+There is also code in `extents.c' that provides information needed by
+the redisplay mechanism for efficient operation. (Remember that extents
+can have display properties that affect [sometimes drastically, as in
+the `invisible' property] the display of the text they cover.)
+
+ editfns.c
+
+ `editfns.c' contains the standard Lisp primitives for working with a
+buffer's text, and calls the low-level functions in `insdel.c'. It
+also contains primitives for working with `point' (the default buffer
+insertion location).
+
+ `editfns.c' also contains functions for retrieving various
+characteristics from the external environment: the current time, the
+process ID of the running XEmacs process, the name of the user who ran
+this XEmacs process, etc. It's not clear why this code is in
+`editfns.c'.
+
+ callint.c
+ cmds.c
+ commands.h
+
+ These modules implement the basic "interactive" commands, i.e.
+user-callable functions. Commands, as opposed to other functions, have
+special ways of getting their parameters interactively (by querying the
+user), as opposed to having them passed in a normal function
+invocation. Many commands are not really meant to be called from other
+Lisp functions, because they modify global state in a way that's often
+undesired as part of other Lisp functions.
+
+ `callint.c' implements the mechanism for querying the user for
+parameters and calling interactive commands. The bulk of this module is
+code that parses the interactive spec that is supplied with an
+interactive command.
+
+ `cmds.c' implements the basic, most commonly used editing commands:
+commands to move around the current buffer and insert and delete
+characters. These commands are implemented using the Lisp primitives
+defined in `editfns.c'.
+
+ `commands.h' contains associated structure definitions and
+prototypes.
+
+ regex.c
+ regex.h
+ search.c
+
+ `search.c' implements the Lisp primitives for searching for text in
+a buffer, and some of the low-level algorithms for doing this. In
+particular, the fast fixed-string Boyer-Moore search algorithm is
+implemented in `search.c'. The low-level algorithms for doing
+regular-expression searching, however, are implemented in `regex.c' and
+`regex.h'. These two modules are largely independent of XEmacs, and
+are similar to (and based upon) the regular-expression routines used in
+`grep' and other GNU utilities.
+
+ doprnt.c
+
+ `doprnt.c' implements formatted-string processing, similar to
+`printf()' command in C.
+
+ undo.c
+
+ This module implements the undo mechanism for tracking buffer
+changes. Most of this could be implemented in Lisp.
+
+\1f
+File: internals.info, Node: Editor-Level Control Flow Modules, Next: Modules for the Basic Displayable Lisp Objects, Prev: Modules for Standard Editing Operations, Up: A Summary of the Various XEmacs Modules
+
+Editor-Level Control Flow Modules
+=================================
+
+ event-Xt.c
+ event-stream.c
+ event-tty.c
+ events.c
+ events.h
+
+ These implement the handling of events (user input and other system
+notifications).
+
+ `events.c' and `events.h' define the "event" Lisp object type and
+primitives for manipulating it.
+
+ `event-stream.c' implements the basic functions for working with
+event queues, dispatching an event by looking it up in relevant keymaps
+and such, and handling timeouts; this includes the primitives
+`next-event' and `dispatch-event', as well as related primitives such
+as `sit-for', `sleep-for', and `accept-process-output'.
+(`event-stream.c' is one of the hairiest and trickiest modules in
+XEmacs. Beware! You can easily mess things up here.)
+
+ `event-Xt.c' and `event-tty.c' implement the low-level interfaces
+onto retrieving events from Xt (the X toolkit) and from TTY's (using
+`read()' and `select()'), respectively. The event interface enforces a
+clean separation between the specific code for interfacing with the
+operating system and the generic code for working with events, by
+defining an API of basic, low-level event methods; `event-Xt.c' and
+`event-tty.c' are two different implementations of this API. To add
+support for a new operating system (e.g. NeXTstep), one merely needs to
+provide another implementation of those API functions.
+
+ Note that the choice of whether to use `event-Xt.c' or `event-tty.c'
+is made at compile time! Or at the very latest, it is made at startup
+time. `event-Xt.c' handles events for *both* X and TTY frames;
+`event-tty.c' is only used when X support is not compiled into XEmacs.
+The reason for this is that there is only one event loop in XEmacs:
+thus, it needs to be able to receive events from all different kinds of
+frames.
+
+ keymap.c
+ keymap.h
+
+ `keymap.c' and `keymap.h' define the "keymap" Lisp object type and
+associated methods and primitives. (Remember that keymaps are objects
+that associate event descriptions with functions to be called to
+"execute" those events; `dispatch-event' looks up events in the
+relevant keymaps.)
+
+ keyboard.c
+
+ `keyboard.c' contains functions that implement the actual editor
+command loop - i.e. the event loop that cyclically retrieves and
+dispatches events. This code is also rather tricky, just like
+`event-stream.c'.
+
+ macros.c
+ macros.h
+
+ These two modules contain the basic code for defining keyboard
+macros. These functions don't actually do much; most of the code that
+handles keyboard macros is mixed in with the event-handling code in
+`event-stream.c'.
+
+ minibuf.c
+
+ This contains some miscellaneous code related to the minibuffer
+(most of the minibuffer code was moved into Lisp by Richard Mlynarik).
+This includes the primitives for completion (although filename
+completion is in `dired.c'), the lowest-level interface to the
+minibuffer (if the command loop were cleaned up, this too could be in
+Lisp), and code for dealing with the echo area (this, too, was mostly
+moved into Lisp, and the only code remaining is code to call out to
+Lisp or provide simple bootstrapping implementations early in temacs,
+before the echo-area Lisp code is loaded).
+
+\1f
+File: internals.info, Node: Modules for the Basic Displayable Lisp Objects, Next: Modules for other Display-Related Lisp Objects, Prev: Editor-Level Control Flow Modules, Up: A Summary of the Various XEmacs Modules
+
+Modules for the Basic Displayable Lisp Objects
+==============================================
+
+ device-ns.h
+ device-stream.c
+ device-stream.h
+ device-tty.c
+ device-tty.h
+ device-x.c
+ device-x.h
+ device.c
+ device.h
+
+ These modules implement the "device" Lisp object type. This
+abstracts a particular screen or connection on which frames are
+displayed. As with Lisp objects, event interfaces, and other
+subsystems, the device code is separated into a generic component that
+contains a standardized interface (in the form of a set of methods) onto
+particular device types.
+
+ The device subsystem defines all the methods and provides method
+services for not only device operations but also for the frame, window,
+menubar, scrollbar, toolbar, and other displayable-object subsystems.
+The reason for this is that all of these subsystems have the same
+subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do.
+
+ frame-ns.h
+ frame-tty.c
+ frame-x.c
+ frame-x.h
+ frame.c
+ frame.h
+
+ Each device contains one or more frames in which objects (e.g. text)
+are displayed. A frame corresponds to a window in the window system;
+usually this is a top-level window but it could potentially be one of a
+number of overlapping child windows within a top-level window, using the
+MDI (Multiple Document Interface) protocol in Microsoft Windows or a
+similar scheme.
+
+ The `frame-*' files implement the "frame" Lisp object type and
+provide the generic and device-type-specific operations on frames (e.g.
+raising, lowering, resizing, moving, etc.).
+
+ window.c
+ window.h
+
+ Each frame consists of one or more non-overlapping "windows" (better
+known as "panes" in standard window-system terminology) in which a
+buffer's text can be displayed. Windows can also have scrollbars
+displayed around their edges.
+
+ `window.c' and `window.h' implement the "window" Lisp object type
+and provide code to manage windows. Since windows have no associated
+resources in the window system (the window system knows only about the
+frame; no child windows or anything are used for XEmacs windows), there
+is no device-type-specific code here; all of that code is part of the
+redisplay mechanism or the code for particular object types such as
+scrollbars.
+
+\1f
+File: internals.info, Node: Modules for other Display-Related Lisp Objects, Next: Modules for the Redisplay Mechanism, Prev: Modules for the Basic Displayable Lisp Objects, Up: A Summary of the Various XEmacs Modules
+
+Modules for other Display-Related Lisp Objects
+==============================================
+
+ faces.c
+ faces.h
+
+ bitmaps.h
+ glyphs-ns.h
+ glyphs-x.c
+ glyphs-x.h
+ glyphs.c
+ glyphs.h
+
+ objects-ns.h
+ objects-tty.c
+ objects-tty.h
+ objects-x.c
+ objects-x.h
+ objects.c
+ objects.h
+
+ menubar-x.c
+ menubar.c
+
+ scrollbar-x.c
+ scrollbar-x.h
+ scrollbar.c
+ scrollbar.h
+
+ toolbar-x.c
+ toolbar.c
+ toolbar.h
+
+ font-lock.c
+
+ This file provides C support for syntax highlighting - i.e.
+highlighting different syntactic constructs of a source file in
+different colors, for easy reading. The C support is provided so that
+this is fast.
+
+ dgif_lib.c
+ gif_err.c
+ gif_lib.h
+ gifalloc.c
+
+ These modules decode GIF-format image files, for use with glyphs.
+
+\1f
+File: internals.info, Node: Modules for the Redisplay Mechanism, Next: Modules for Interfacing with the File System, Prev: Modules for other Display-Related Lisp Objects, Up: A Summary of the Various XEmacs Modules
+
+Modules for the Redisplay Mechanism
+===================================
+
+ redisplay-output.c
+ redisplay-tty.c
+ redisplay-x.c
+ redisplay.c
+ redisplay.h
+
+ These files provide the redisplay mechanism. As with many other
+subsystems in XEmacs, there is a clean separation between the general
+and device-specific support.
+
+ `redisplay.c' contains the bulk of the redisplay engine. These
+functions update the redisplay structures (which describe how the screen
+is to appear) to reflect any changes made to the state of any
+displayable objects (buffer, frame, window, etc.) since the last time
+that redisplay was called. These functions are highly optimized to
+avoid doing more work than necessary (since redisplay is called
+extremely often and is potentially a huge time sink), and depend heavily
+on notifications from the objects themselves that changes have occurred,
+so that redisplay doesn't explicitly have to check each possible object.
+The redisplay mechanism also contains a great deal of caching to further
+speed things up; some of this caching is contained within the various
+displayable objects.
+
+ `redisplay-output.c' goes through the redisplay structures and
+converts them into calls to device-specific methods to actually output
+the screen changes.
+
+ `redisplay-x.c' and `redisplay-tty.c' are two implementations of
+these redisplay output methods, for X frames and TTY frames,
+respectively.
+
+ indent.c
+
+ This module contains various functions and Lisp primitives for
+converting between buffer positions and screen positions. These
+functions call the redisplay mechanism to do most of the work, and then
+examine the redisplay structures to get the necessary information. This
+module needs work.
+
+ termcap.c
+ terminfo.c
+ tparam.c
+
+ These files contain functions for working with the termcap
+(BSD-style) and terminfo (System V style) databases of terminal
+capabilities and escape sequences, used when XEmacs is displaying in a
+TTY.
+
+ cm.c
+ cm.h
+
+ These files provide some miscellaneous TTY-output functions and
+should probably be merged into `redisplay-tty.c'.
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: Modules for Interfacing with the File System, Next: Modules for Other Aspects of the Lisp Interpreter and Object System, Prev: Modules for the Redisplay Mechanism, Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with the File System
+============================================
+
+ lstream.c
+ lstream.h
+
+ These modules implement the "stream" Lisp object type. This is an
+internal-only Lisp object that implements a generic buffering stream.
+The idea is to provide a uniform interface onto all sources and sinks of
+data, including file descriptors, stdio streams, chunks of memory, Lisp
+buffers, Lisp strings, etc. That way, I/O functions can be written to
+the stream interface and can transparently handle all possible sources
+and sinks. (For example, the `read' function can read data from a
+file, a string, a buffer, or even a function that is called repeatedly
+to return data, without worrying about where the data is coming from or
+what-size chunks it is returned in.)
+
+ Note that in the C code, streams are called "lstreams" (for "Lisp
+streams") to distinguish them from other kinds of streams, e.g. stdio
+streams and C++ I/O streams.
+
+ Similar to other subsystems in XEmacs, lstreams are separated into
+generic functions and a set of methods for the different types of
+lstreams. `lstream.c' provides implementations of many different types
+of streams; others are provided, e.g., in `mule-coding.c'.
+
+ fileio.c
+
+ This implements the basic primitives for interfacing with the file
+system. This includes primitives for reading files into buffers,
+writing buffers into files, checking for the presence or accessibility
+of files, canonicalizing file names, etc. Note that these primitives
+are usually not invoked directly by the user: There is a great deal of
+higher-level Lisp code that implements the user commands such as
+`find-file' and `save-buffer'. This is similar to the distinction
+between the lower-level primitives in `editfns.c' and the higher-level
+user commands in `commands.c' and `simple.el'.
+
+ filelock.c
+
+ This file provides functions for detecting clashes between different
+processes (e.g. XEmacs and some external process, or two different
+XEmacs processes) modifying the same file. (XEmacs can optionally use
+the `lock/' subdirectory to provide a form of "locking" between
+different XEmacs processes.) This module is also used by the low-level
+functions in `insdel.c' to ensure that, if the first modification is
+being made to a buffer whose corresponding file has been externally
+modified, the user is made aware of this so that the buffer can be
+synched up with the external changes if necessary.
+
+ filemode.c
+
+ This file provides some miscellaneous functions that construct a
+`rwxr-xr-x'-type permissions string (as might appear in an `ls'-style
+directory listing) given the information returned by the `stat()'
+system call.
+
+ dired.c
+ ndir.h
+
+ These files implement the XEmacs interface to directory searching.
+This includes a number of primitives for determining the files in a
+directory and for doing filename completion. (Remember that generic
+completion is handled by a different mechanism, in `minibuf.c'.)
+
+ `ndir.h' is a header file used for the directory-searching emulation
+functions provided in `sysdep.c' (see section J below), for systems
+that don't provide any directory-searching functions. (On those
+systems, directories can be read directly as files, and parsed.)
+
+ realpath.c
+
+ This file provides an implementation of the `realpath()' function
+for expanding symbolic links, on systems that don't implement it or have
+a broken implementation.
+
+\1f
+File: internals.info, Node: Modules for Other Aspects of the Lisp Interpreter and Object System, Next: Modules for Interfacing with the Operating System, Prev: Modules for Interfacing with the File System, Up: A Summary of the Various XEmacs Modules
+
+Modules for Other Aspects of the Lisp Interpreter and Object System
+===================================================================
+
+ elhash.c
+ elhash.h
+ hash.c
+ hash.h
+
+ These files provide two implementations of hash tables. Files
+`hash.c' and `hash.h' provide a generic C implementation of hash tables
+which can stand independently of XEmacs. Files `elhash.c' and
+`elhash.h' provide a separate implementation of hash tables that can
+store only Lisp objects, and knows about Lispy things like garbage
+collection, and implement the "hash-table" Lisp object type.
+
+ specifier.c
+ specifier.h
+
+ This module implements the "specifier" Lisp object type. This is
+primarily used for displayable properties, and allows for values that
+are specific to a particular buffer, window, frame, device, or device
+class, as well as a default value existing. This is used, for example,
+to control the height of the horizontal scrollbar or the appearance of
+the `default', `bold', or other faces. The specifier object consists
+of a number of specifications, each of which maps from a buffer,
+window, etc. to a value. The function `specifier-instance' looks up a
+value given a window (from which a buffer, frame, and device can be
+derived).
+
+ chartab.c
+ chartab.h
+ casetab.c
+
+ `chartab.c' and `chartab.h' implement the "char table" Lisp object
+type, which maps from characters or certain sorts of character ranges
+to Lisp objects. The implementation of this object type is optimized
+for the internal representation of characters. Char tables come in
+different types, which affect the allowed object types to which a
+character can be mapped and also dictate certain other properties of
+the char table.
+
+ `casetab.c' implements one sort of char table, the "case table",
+which maps characters to other characters of possibly different case.
+These are used by XEmacs to implement case-changing primitives and to
+do case-insensitive searching.
+
+ syntax.c
+ syntax.h
+
+ This module implements "syntax tables", another sort of char table
+that maps characters into syntax classes that define the syntax of these
+characters (e.g. a parenthesis belongs to a class of `open' characters
+that have corresponding `close' characters and can be nested). This
+module also implements the Lisp "scanner", a set of primitives for
+scanning over text based on syntax tables. This is used, for example,
+to find the matching parenthesis in a command such as `forward-sexp',
+and by `font-lock.c' to locate quoted strings, comments, etc.
+
+ casefiddle.c
+
+ This module implements various Lisp primitives for upcasing,
+downcasing and capitalizing strings or regions of buffers.
+
+ rangetab.c
+
+ This module implements the "range table" Lisp object type, which
+provides for a mapping from ranges of integers to arbitrary Lisp
+objects.
+
+ opaque.c
+ opaque.h
+
+ This module implements the "opaque" Lisp object type, an
+internal-only Lisp object that encapsulates an arbitrary block of memory
+so that it can be managed by the Lisp allocation system. To create an
+opaque object, you call `make_opaque()', passing a pointer to a block
+of memory. An object is created that is big enough to hold the memory,
+which is copied into the object's storage. The object will then stick
+around as long as you keep pointers to it, after which it will be
+automatically reclaimed.
+
+ Opaque objects can also have an arbitrary "mark method" associated
+with them, in case the block of memory contains other Lisp objects that
+need to be marked for garbage-collection purposes. (If you need other
+object methods, such as a finalize method, you should just go ahead and
+create a new Lisp object type - it's not hard.)
+
+ abbrev.c
+
+ This function provides a few primitives for doing dynamic
+abbreviation expansion. In XEmacs, most of the code for this has been
+moved into Lisp. Some C code remains for speed and because the
+primitive `self-insert-command' (which is executed for all
+self-inserting characters) hooks into the abbrev mechanism.
+(`self-insert-command' is itself in C only for speed.)
+
+ doc.c
+
+ This function provides primitives for retrieving the documentation
+strings of functions and variables. These documentation strings contain
+certain special markers that get dynamically expanded (e.g. a
+reverse-lookup is performed on some named functions to retrieve their
+current key bindings). Some documentation strings (in particular, for
+the built-in primitives and pre-loaded Lisp functions) are stored
+externally in a file `DOC' in the `lib-src/' directory and need to be
+fetched from that file. (Part of the build stage involves building this
+file, and another part involves constructing an index for this file and
+embedding it into the executable, so that the functions in `doc.c' do
+not have to search the entire `DOC' file to find the appropriate
+documentation string.)
+
+ md5.c
+
+ This function provides a Lisp primitive that implements the MD5
+secure hashing scheme, used to create a large hash value of a string of
+data such that the data cannot be derived from the hash value. This is
+used for various security applications on the Internet.
+
+\1f
+File: internals.info, Node: Modules for Interfacing with the Operating System, Next: Modules for Interfacing with X Windows, Prev: Modules for Other Aspects of the Lisp Interpreter and Object System, Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with the Operating System
+=================================================
+
+ callproc.c
+ process.c
+ process.h
+
+ These modules allow XEmacs to spawn and communicate with subprocesses
+and network connections.
+
+ `callproc.c' implements (through the `call-process' primitive) what
+are called "synchronous subprocesses". This means that XEmacs runs a
+program, waits till it's done, and retrieves its output. A typical
+example might be calling the `ls' program to get a directory listing.
+
+ `process.c' and `process.h' implement "asynchronous subprocesses".
+This means that XEmacs starts a program and then continues normally,
+not waiting for the process to finish. Data can be sent to the process
+or retrieved from it as it's running. This is used for the `shell'
+command (which provides a front end onto a shell program such as
+`csh'), the mail and news readers implemented in XEmacs, etc. The
+result of calling `start-process' to start a subprocess is a process
+object, a particular kind of object used to communicate with the
+subprocess. You can send data to the process by passing the process
+object and the data to `send-process', and you can specify what happens
+to data retrieved from the process by setting properties of the process
+object. (When the process sends data, XEmacs receives a process event,
+which says that there is data ready. When `dispatch-event' is called
+on this event, it reads the data from the process and does something
+with it, as specified by the process object's properties. Typically,
+this means inserting the data into a buffer or calling a function.)
+Another property of the process object is called the "sentinel", which
+is a function that is called when the process terminates.
+
+ Process objects are also used for network connections (connections
+to a process running on another machine). Network connections are
+started with `open-network-stream' but otherwise work just like
+subprocesses.
+
+ sysdep.c
+ sysdep.h
+
+ These modules implement most of the low-level, messy operating-system
+interface code. This includes various device control (ioctl) operations
+for file descriptors, TTY's, pseudo-terminals, etc. (usually this stuff
+is fairly system-dependent; thus the name of this module), and emulation
+of standard library functions and system calls on systems that don't
+provide them or have broken versions.
+
+ sysdir.h
+ sysfile.h
+ sysfloat.h
+ sysproc.h
+ syspwd.h
+ syssignal.h
+ systime.h
+ systty.h
+ syswait.h
+
+ These header files provide consistent interfaces onto
+system-dependent header files and system calls. The idea is that,
+instead of including a standard header file like `<sys/param.h>' (which
+may or may not exist on various systems) or having to worry about
+whether all system provide a particular preprocessor constant, or
+having to deal with the four different paradigms for manipulating
+signals, you just include the appropriate `sys*.h' header file, which
+includes all the right system header files, defines and missing
+preprocessor constants, provides a uniform interface onto system calls,
+etc.
+
+ `sysdir.h' provides a uniform interface onto directory-querying
+functions. (In some cases, this is in conjunction with emulation
+functions in `sysdep.c'.)
+
+ `sysfile.h' includes all the necessary header files for standard
+system calls (e.g. `read()'), ensures that all necessary `open()' and
+`stat()' preprocessor constants are defined, and possibly (usually)
+substitutes sugared versions of `read()', `write()', etc. that
+automatically restart interrupted I/O operations.
+
+ `sysfloat.h' includes the necessary header files for floating-point
+operations.
+
+ `sysproc.h' includes the necessary header files for calling
+`select()', `fork()', `execve()', socket operations, and the like, and
+ensures that the `FD_*()' macros for descriptor-set manipulations are
+available.
+
+ `syspwd.h' includes the necessary header files for obtaining
+information from `/etc/passwd' (the functions are emulated under VMS).
+
+ `syssignal.h' includes the necessary header files for
+signal-handling and provides a uniform interface onto the different
+signal-handling and signal-blocking paradigms.
+
+ `systime.h' includes the necessary header files and provides uniform
+interfaces for retrieving the time of day, setting file
+access/modification times, getting the amount of time used by the XEmacs
+process, etc.
+
+ `systty.h' buffers against the infinitude of different ways of
+controlling TTY's.
+
+ `syswait.h' provides a uniform way of retrieving the exit status
+from a `wait()'ed-on process (some systems use a union, others use an
+int).
+
+ hpplay.c
+ libsst.c
+ libsst.h
+ libst.h
+ linuxplay.c
+ nas.c
+ sgiplay.c
+ sound.c
+ sunplay.c
+
+ These files implement the ability to play various sounds on some
+types of computers. You have to configure your XEmacs with sound
+support in order to get this capability.
+
+ `sound.c' provides the generic interface. It implements various
+Lisp primitives and variables that let you specify which sounds should
+be played in certain conditions. (The conditions are identified by
+symbols, which are passed to `ding' to make a sound. Various standard
+functions call this function at certain times; if sound support does
+not exist, a simple beep results.
+
+ `sgiplay.c', `sunplay.c', `hpplay.c', and `linuxplay.c' interface to
+the machine's speaker for various different kind of machines. This is
+called "native" sound.
+
+ `nas.c' interfaces to a computer somewhere else on the network using
+the NAS (Network Audio Server) protocol, playing sounds on that
+machine. This allows you to run XEmacs on a remote machine, with its
+display set to your local machine, and have the sounds be made on your
+local machine, provided that you have a NAS server running on your local
+machine.
+
+ `libsst.c', `libsst.h', and `libst.h' provide some additional
+functions for playing sound on a Sun SPARC but are not currently in use.
+
+ tooltalk.c
+ tooltalk.h
+
+ These two modules implement an interface to the ToolTalk protocol,
+which is an interprocess communication protocol implemented on some
+versions of Unix. ToolTalk is a high-level protocol that allows
+processes to register themselves as providers of particular services;
+other processes can then request a service without knowing or caring
+exactly who is providing the service. It is similar in spirit to the
+DDE protocol provided under Microsoft Windows. ToolTalk is a part of
+the new CDE (Common Desktop Environment) specification and is used to
+connect the parts of the SPARCWorks development environment.
+
+ getloadavg.c
+
+ This module provides the ability to retrieve the system's current
+load average. (The way to do this is highly system-specific,
+unfortunately, and requires a lot of special-case code.)
+
+ sunpro.c
+
+ This module provides a small amount of code used internally at Sun to
+keep statistics on the usage of XEmacs.
+
+ broken-sun.h
+ strcmp.c
+ strcpy.c
+ sunOS-fix.c
+
+ These files provide replacement functions and prototypes to fix
+numerous bugs in early releases of SunOS 4.1.
+
+ hftctl.c
+
+ This module provides some terminal-control code necessary on
+versions of AIX prior to 4.1.
+
+ msdos.c
+ msdos.h
+
+ These modules are used for MS-DOS support, which does not work in
+XEmacs.
+
+\1f
+File: internals.info, Node: Modules for Interfacing with X Windows, Next: Modules for Internationalization, Prev: Modules for Interfacing with the Operating System, Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with X Windows
+======================================
+
+ Emacs.ad.h
+
+ A file generated from `Emacs.ad', which contains XEmacs-supplied
+fallback resources (so that XEmacs has pretty defaults).
+
+ EmacsFrame.c
+ EmacsFrame.h
+ EmacsFrameP.h
+
+ These modules implement an Xt widget class that encapsulates a frame.
+This is for ease in integrating with Xt. The EmacsFrame widget covers
+the entire X window except for the menubar; the scrollbars are
+positioned on top of the EmacsFrame widget.
+
+ *Warning:* Abandon hope, all ye who enter here. This code took an
+ungodly amount of time to get right, and is likely to fall apart
+mercilessly at the slightest change. Such is life under Xt.
+
+ EmacsManager.c
+ EmacsManager.h
+ EmacsManagerP.h
+
+ These modules implement a simple Xt manager (i.e. composite) widget
+class that simply lets its children set whatever geometry they want.
+It's amazing that Xt doesn't provide this standardly, but on second
+thought, it makes sense, considering how amazingly broken Xt is.
+
+ EmacsShell-sub.c
+ EmacsShell.c
+ EmacsShell.h
+ EmacsShellP.h
+
+ These modules implement two Xt widget classes that are subclasses of
+the TopLevelShell and TransientShell classes. This is necessary to deal
+with more brokenness that Xt has sadistically thrust onto the backs of
+developers.
+
+ xgccache.c
+ xgccache.h
+
+ These modules provide functions for maintenance and caching of GC's
+(graphics contexts) under the X Window System. This code is junky and
+needs to be rewritten.
+
+ xselect.c
+
+ This module provides an interface to the X Window System's concept of
+"selections", the standard way for X applications to communicate with
+each other.
+
+ xintrinsic.h
+ xintrinsicp.h
+ xmmanagerp.h
+ xmprimitivep.h
+
+ These header files are similar in spirit to the `sys*.h' files and
+buffer against different implementations of Xt and Motif.
+
+ * `xintrinsic.h' should be included in place of `<Intrinsic.h>'.
+
+ * `xintrinsicp.h' should be included in place of `<IntrinsicP.h>'.
+
+ * `xmmanagerp.h' should be included in place of `<XmManagerP.h>'.
+
+ * `xmprimitivep.h' should be included in place of `<XmPrimitiveP.h>'.
+
+ xmu.c
+ xmu.h
+
+ These files provide an emulation of the Xmu library for those systems
+(i.e. HPUX) that don't provide it as a standard part of X.
+
+ ExternalClient-Xlib.c
+ ExternalClient.c
+ ExternalClient.h
+ ExternalClientP.h
+ ExternalShell.c
+ ExternalShell.h
+ ExternalShellP.h
+ extw-Xlib.c
+ extw-Xlib.h
+ extw-Xt.c
+ extw-Xt.h
+
+ These files provide the "external widget" interface, which allows an
+XEmacs frame to appear as a widget in another application. To do this,
+you have to configure with `--external-widget'.
+
+ `ExternalShell*' provides the server (XEmacs) side of the connection.
+
+ `ExternalClient*' provides the client (other application) side of
+the connection. These files are not compiled into XEmacs but are
+compiled into libraries that are then linked into your application.
+
+ `extw-*' is common code that is used for both the client and server.
+
+ Don't touch this code; something is liable to break if you do.
+
+\1f
+File: internals.info, Node: Modules for Internationalization, Prev: Modules for Interfacing with X Windows, Up: A Summary of the Various XEmacs Modules
+
+Modules for Internationalization
+================================
+
+ mule-canna.c
+ mule-ccl.c
+ mule-charset.c
+ mule-charset.h
+ mule-coding.c
+ mule-coding.h
+ mule-mcpath.c
+ mule-mcpath.h
+ mule-wnnfns.c
+ mule.c
+
+ These files implement the MULE (Asian-language) support. Note that
+MULE actually provides a general interface for all sorts of languages,
+not just Asian languages (although they are generally the most
+complicated to support). This code is still in beta.
+
+ `mule-charset.*' and `mule-coding.*' provide the heart of the XEmacs
+MULE support. `mule-charset.*' implements the "charset" Lisp object
+type, which encapsulates a character set (an ordered one- or
+two-dimensional set of characters, such as US ASCII or JISX0208 Japanese
+Kanji).
+
+ `mule-coding.*' implements the "coding-system" Lisp object type,
+which encapsulates a method of converting between different encodings.
+An encoding is a representation of a stream of characters, possibly
+from multiple character sets, using a stream of bytes or words, and
+defines (e.g.) which escape sequences are used to specify particular
+character sets, how the indices for a character are converted into bytes
+(sometimes this involves setting the high bit; sometimes complicated
+rearranging of the values takes place, as in the Shift-JIS encoding),
+etc.
+
+ `mule-ccl.c' provides the CCL (Code Conversion Language)
+interpreter. CCL is similar in spirit to Lisp byte code and is used to
+implement converters for custom encodings.
+
+ `mule-canna.c' and `mule-wnnfns.c' implement interfaces to external
+programs used to implement the Canna and WNN input methods,
+respectively. This is currently in beta.
+
+ `mule-mcpath.c' provides some functions to allow for pathnames
+containing extended characters. This code is fragmentary, obsolete, and
+completely non-working. Instead, PATHNAME-CODING-SYSTEM is used to
+specify conversions of names of files and directories. The standard C
+I/O functions like `open()' are wrapped so that conversion occurs
+automatically.
+
+ `mule.c' provides a few miscellaneous things that should probably be
+elsewhere.
+
+ intl.c
+
+ This provides some miscellaneous internationalization code for
+implementing message translation and interfacing to the Ximp input
+method. None of this code is currently working.
+
+ iso-wide.h
+
+ This contains leftover code from an earlier implementation of
+Asian-language support, and is not currently used.
+
+\1f
+File: internals.info, Node: Allocation of Objects in XEmacs Lisp, Next: Events and the Event Loop, Prev: A Summary of the Various XEmacs Modules, Up: Top
+
+Allocation of Objects in XEmacs Lisp
+************************************
+
+* Menu:
+
+* Introduction to Allocation::
+* Garbage Collection::
+* GCPROing::
+* Garbage Collection - Step by Step::
+* Integers and Characters::
+* Allocation from Frob Blocks::
+* lrecords::
+* Low-level allocation::
+* Pure Space::
+* Cons::
+* Vector::
+* Bit Vector::
+* Symbol::
+* Marker::
+* String::
+* Compiled Function::
+
+\1f
+File: internals.info, Node: Introduction to Allocation, Next: Garbage Collection, Up: Allocation of Objects in XEmacs Lisp
+
+Introduction to Allocation
+==========================
+
+ Emacs Lisp, like all Lisps, has garbage collection. This means that
+the programmer never has to explicitly free (destroy) an object; it
+happens automatically when the object becomes inaccessible. Most
+experts agree that garbage collection is a necessity in a modern,
+high-level language. Its omission from C stems from the fact that C was
+originally designed to be a nice abstract layer on top of assembly
+language, for writing kernels and basic system utilities rather than
+large applications.
+
+ Lisp objects can be created by any of a number of Lisp primitives.
+Most object types have one or a small number of basic primitives for
+creating objects. For conses, the basic primitive is `cons'; for
+vectors, the primitives are `make-vector' and `vector'; for symbols,
+the primitives are `make-symbol' and `intern'; etc. Some Lisp objects,
+especially those that are primarily used internally, have no
+corresponding Lisp primitives. Every Lisp object, though, has at least
+one C primitive for creating it.
+
+ Recall from section (VII) that a Lisp object, as stored in a 32-bit
+or 64-bit word, has a mark bit, a few tag bits, and a "value" that
+occupies the remainder of the bits. We can separate the different Lisp
+object types into four broad categories:
+
+ * (a) Those for whom the value directly represents the contents of
+ the Lisp object. Only two types are in this category: integers and
+ characters. No special allocation or garbage collection is
+ necessary for such objects. Lisp objects of these types do not
+ need to be `GCPRO'ed.
+
+ In the remaining three categories, the value is a pointer to a
+structure.
+
+ * (b) Those for whom the tag directly specifies the type. Recall
+ that there are only three tag bits; this means that at most five
+ types can be specified this way. The most commonly-used types are
+ stored in this format; this includes conses, strings, vectors, and
+ sometimes symbols. With the exception of vectors, objects in this
+ category are allocated in "frob blocks", i.e. large blocks of
+ memory that are subdivided into individual objects. This saves a
+ lot on malloc overhead, since there are typically quite a lot of
+ these objects around, and the objects are small. (A cons, for
+ example, occupies 8 bytes on 32-bit machines - 4 bytes for each of
+ the two objects it contains.) Vectors are individually
+ `malloc()'ed since they are of variable size. (It would be
+ possible, and desirable, to allocate vectors of certain small
+ sizes out of frob blocks, but it isn't currently done.) Strings
+ are handled specially: Each string is allocated in two parts, a
+ fixed size structure containing a length and a data pointer, and
+ the actual data of the string. The former structure is allocated
+ in frob blocks as usual, and the latter data is stored in "string
+ chars blocks" and is relocated during garbage collection to
+ eliminate holes.
+
+ In the remaining two categories, the type is stored in the object
+itself. The tag for all such objects is the generic "lrecord"
+(Lisp_Record) tag. The first four bytes (or eight, for 64-bit machines)
+of the object's structure are a pointer to a structure that describes
+the object's type, which includes method pointers and a pointer to a
+string naming the type. Note that it's possible to save some space by
+using a one- or two-byte tag, rather than a four- or eight-byte pointer
+to store the type, but it's not clear it's worth making the change.
+
+ * (c) Those lrecords that are allocated in frob blocks (see above).
+ This includes the objects that are most common and relatively
+ small, and includes floats, compiled functions, symbols (when not
+ in category (b)), extents, events, and markers. With the cleanup
+ of frob blocks done in 19.12, it's not terribly hard to add more
+ objects to this category, but it's a bit trickier than adding an
+ object type to type (d) (esp. if the object needs a finalization
+ method), and is not likely to save much space unless the object is
+ small and there are many of them. (In fact, if there are very few
+ of them, it might actually waste space.)
+
+ * (d) Those lrecords that are individually `malloc()'ed. These are
+ called "lcrecords". All other types are in this category. Adding
+ a new type to this category is comparatively easy, and all types
+ added since 19.8 (when the current allocation scheme was devised,
+ by Richard Mlynarik), with the exception of the character type,
+ have been in this category.
+
+ Note that bit vectors are a bit of a special case. They are simple
+lrecords as in category (c), but are individually `malloc()'ed like
+vectors. You can basically view them as exactly like vectors except
+that their type is stored in lrecord fashion rather than in
+directly-tagged fashion.
+
+ Note that FSF Emacs redesigned their object system in 19.29 to follow
+a similar scheme. However, given RMS's expressed dislike for data
+abstraction, the FSF scheme is not nearly as clean or as easy to
+extend. (FSF calls items of type (c) `Lisp_Misc' and items of type (d)
+`Lisp_Vectorlike', with separate tags for each, although
+`Lisp_Vectorlike' is also used for vectors.)
+
+\1f
+File: internals.info, Node: Garbage Collection, Next: GCPROing, Prev: Introduction to Allocation, Up: Allocation of Objects in XEmacs Lisp
+
+Garbage Collection
+==================
+
+ Garbage collection is simple in theory but tricky to implement.
+Emacs Lisp uses the oldest garbage collection method, called "mark and
+sweep". Garbage collection begins by starting with all accessible
+locations (i.e. all variables and other slots where Lisp objects might
+occur) and recursively traversing all objects accessible from those
+slots, marking each one that is found. We then go through all of
+memory and free each object that is not marked, and unmarking each
+object that is marked. Note that "all of memory" means all currently
+allocated objects. Traversing all these objects means traversing all
+frob blocks, all vectors (which are chained in one big list), and all
+lcrecords (which are likewise chained).
+
+ Note that, when an object is marked, the mark has to occur inside of
+the object's structure, rather than in the 32-bit `Lisp_Object' holding
+the object's pointer; i.e. you can't just set the pointer's mark bit.
+This is because there may be many pointers to the same object. This
+means that the method of marking an object can differ depending on the
+type. The different marking methods are approximately as follows:
+
+ 1. For conses, the mark bit of the car is set.
+
+ 2. For strings, the mark bit of the string's plist is set.
+
+ 3. For symbols when not lrecords, the mark bit of the symbol's plist
+ is set.
+
+ 4. For vectors, the length is negated after adding 1.
+
+ 5. For lrecords, the pointer to the structure describing the type is
+ changed (see below).
+
+ 6. Integers and characters do not need to be marked, since no
+ allocation occurs for them.
+
+ The details of this are in the `mark_object()' function.
+
+ Note that any code that operates during garbage collection has to be
+especially careful because of the fact that some objects may be marked
+and as such may not look like they normally do. In particular:
+
+ Some object pointers may have their mark bit set. This will make
+ `FOOBARP()' predicates fail. Use `GC_FOOBARP()' to deal with this.
+
+ * Even if you clear the mark bit, `FOOBARP()' will still fail for
+ lrecords because the implementation pointer has been changed (see
+ below). `GC_FOOBARP()' will correctly deal with this.
+
+ * Vectors have their size field munged, so anything that looks at
+ this field will fail.
+
+ * Note that `XFOOBAR()' macros *will* work correctly on object
+ pointers with their mark bit set, because the logical shift
+ operations that remove the tag also remove the mark bit.
+
+ Finally, note that garbage collection can be invoked explicitly by
+calling `garbage-collect' but is also called automatically by `eval',
+once a certain amount of memory has been allocated since the last
+garbage collection (according to `gc-cons-threshold').
+
+\1f
+File: internals.info, Node: GCPROing, Next: Garbage Collection - Step by Step, Prev: Garbage Collection, Up: Allocation of Objects in XEmacs Lisp
+
+`GCPRO'ing
+==========
+
+ `GCPRO'ing is one of the ugliest and trickiest parts of Emacs
+internals. The basic idea is that whenever garbage collection occurs,
+all in-use objects must be reachable somehow or other from one of the
+roots of accessibility. The roots of accessibility are:
+
+ 1. All objects that have been `staticpro()'d. This is used for any
+ global C variables that hold Lisp objects. A call to
+ `staticpro()' happens implicitly as a result of any symbols
+ declared with `defsymbol()' and any variables declared with
+ `DEFVAR_FOO()'. You need to explicitly call `staticpro()' (in the
+ `vars_of_foo()' method of a module) for other global C variables
+ holding Lisp objects. (This typically includes internal lists and
+ such things.)
+
+ Note that `obarray' is one of the `staticpro()'d things.
+ Therefore, all functions and variables get marked through this.
+
+ 2. Any shadowed bindings that are sitting on the `specpdl' stack.
+
+ 3. Any objects sitting in currently active (Lisp) stack frames,
+ catches, and condition cases.
+
+ 4. A couple of special-case places where active objects are located.
+
+ 5. Anything currently marked with `GCPRO'.
+
+ Marking with `GCPRO' is necessary because some C functions (quite a
+lot, in fact), allocate objects during their operation. Quite
+frequently, there will be no other pointer to the object while the
+function is running, and if a garbage collection occurs and the object
+needs to be referenced again, bad things will happen. The solution is
+to mark those objects with `GCPRO'. Unfortunately this is easy to
+forget, and there is basically no way around this problem. Here are
+some rules, though:
+
+ 1. For every `GCPRON', there have to be declarations of `struct gcpro
+ gcpro1, gcpro2', etc.
+
+ 2. You *must* `UNGCPRO' anything that's `GCPRO'ed, and you *must not*
+ `UNGCPRO' if you haven't `GCPRO'ed. Getting either of these wrong
+ will lead to crashes, often in completely random places unrelated
+ to where the problem lies.
+
+ 3. The way this actually works is that all currently active `GCPRO's
+ are chained through the `struct gcpro' local variables, with the
+ variable `gcprolist' pointing to the head of the list and the nth
+ local `gcpro' variable pointing to the first `gcpro' variable in
+ the next enclosing stack frame. Each `GCPRO'ed thing is an
+ lvalue, and the `struct gcpro' local variable contains a pointer to
+ this lvalue. This is why things will mess up badly if you don't
+ pair up the `GCPRO's and `UNGCPRO's - you will end up with
+ `gcprolist's containing pointers to `struct gcpro's or local
+ `Lisp_Object' variables in no-longer-active stack frames.
+
+ 4. It is actually possible for a single `struct gcpro' to protect a
+ contiguous array of any number of values, rather than just a
+ single lvalue. To effect this, call `GCPRON' as usual on the
+ first object in the array and then set `gcproN.nvars'.
+
+ 5. *Strings are relocated.* What this means in practice is that the
+ pointer obtained using `XSTRING_DATA()' is liable to change at any
+ time, and you should never keep it around past any function call,
+ or pass it as an argument to any function that might cause a
+ garbage collection. This is why a number of functions accept
+ either a "non-relocatable" `char *' pointer or a relocatable Lisp
+ string, and only access the Lisp string's data at the very last
+ minute. In some cases, you may end up having to `alloca()' some
+ space and copy the string's data into it.
+
+ 6. By convention, if you have to nest `GCPRO''s, use `NGCPRON' (along
+ with `struct gcpro ngcpro1, ngcpro2', etc.), `NNGCPRON', etc.
+ This avoids compiler warnings about shadowed locals.
+
+ 7. It is *always* better to err on the side of extra `GCPRO's rather
+ than too few. The extra cycles spent on this are almost never
+ going to make a whit of difference in the speed of anything.
+
+ 8. The general rule to follow is that caller, not callee, `GCPRO's.
+ That is, you should not have to explicitly `GCPRO' any Lisp objects
+ that are passed in as parameters.
+
+ One exception from this rule is if you ever plan to change the
+ parameter value, and store a new object in it. In that case, you
+ *must* `GCPRO' the parameter, because otherwise the new object
+ will not be protected.
+
+ So, if you create any Lisp objects (remember, this happens in all
+ sorts of circumstances, e.g. with `Fcons()', etc.), you are
+ responsible for `GCPRO'ing them, unless you are *absolutely sure*
+ that there's no possibility that a garbage-collection can occur
+ while you need to use the object. Even then, consider `GCPRO'ing.
+
+ 9. A garbage collection can occur whenever anything calls `Feval', or
+ whenever a QUIT can occur where execution can continue past this.
+ (Remember, this is almost anywhere.)
+
+ 10. If you have the *least smidgeon of doubt* about whether you need
+ to `GCPRO', you should `GCPRO'.
+
+ 11. Beware of `GCPRO'ing something that is uninitialized. If you have
+ any shade of doubt about this, initialize all your variables to
+ `Qnil'.
+
+ 12. Be careful of traps, like calling `Fcons()' in the argument to
+ another function. By the "caller protects" law, you should be
+ `GCPRO'ing the newly-created cons, but you aren't. A certain
+ number of functions that are commonly called on freshly created
+ stuff (e.g. `nconc2()', `Fsignal()'), break the "caller protects"
+ law and go ahead and `GCPRO' their arguments so as to simplify
+ things, but make sure and check if it's OK whenever doing
+ something like this.
+
+ 13. Once again, remember to `GCPRO'! Bugs resulting from insufficient
+ `GCPRO'ing are intermittent and extremely difficult to track down,
+ often showing up in crashes inside of `garbage-collect' or in
+ weirdly corrupted objects or even in incorrect values in a totally
+ different section of code.
+
+ Given the extremely error-prone nature of the `GCPRO' scheme, and
+the difficulties in tracking down, it should be considered a deficiency
+in the XEmacs code. A solution to this problem would involve
+implementing so-called "conservative" garbage collection for the C
+stack. That involves looking through all of stack memory and treating
+anything that looks like a reference to an object as a reference. This
+will result in a few objects not getting collected when they should, but
+it obviates the need for `GCPRO'ing, and allows garbage collection to
+happen at any point at all, such as during object allocation.
+
+\1f
+File: internals.info, Node: Garbage Collection - Step by Step, Next: Integers and Characters, Prev: GCPROing, Up: Allocation of Objects in XEmacs Lisp
+
+Garbage Collection - Step by Step
+=================================
+
+* Menu:
+
+* Invocation::
+* garbage_collect_1::
+* mark_object::
+* gc_sweep::
+* sweep_lcrecords_1::
+* compact_string_chars::
+* sweep_strings::
+* sweep_bit_vectors_1::
+
+\1f
+File: internals.info, Node: Invocation, Next: garbage_collect_1, Up: Garbage Collection - Step by Step
+
+Invocation
+----------
+
+ The first thing that anyone should know about garbage collection is:
+when and how the garbage collector is invoked. One might think that this
+could happen every time new memory is allocated, e.g. new objects are
+created, but this is *not* the case. Instead, we have the following
+situation:
+
+ The entry point of any process of garbage collection is an invocation
+of the function `garbage_collect_1' in file `alloc.c'. The invocation
+can occur *explicitly* by calling the function `Fgarbage_collect' (in
+addition this function provides information about the freed memory), or
+can occur *implicitly* in four different situations:
+ 1. In function `main_1' in file `emacs.c'. This function is called at
+ each startup of xemacs. The garbage collection is invoked after all
+ initial creations are completed, but only if a special internal
+ error checking-constant `ERROR_CHECK_GC' is defined.
+
+ 2. In function `disksave_object_finalization' in file `alloc.c'. The
+ only purpose of this function is to clear the objects from memory
+ which need not be stored with xemacs when we dump out an
+ executable. This is only done by `Fdump_emacs' or by
+ `Fdump_emacs_data' respectively (both in `emacs.c'). The actual
+ clearing is accomplished by making these objects unreachable and
+ starting a garbage collection. The function is only used while
+ building xemacs.
+
+ 3. In function `Feval / eval' in file `eval.c'. Each time the well
+ known and often used function eval is called to evaluate a form,
+ one of the first things that could happen, is a potential call of
+ `garbage_collect_1'. There exist three global variables,
+ `consing_since_gc' (counts the created cons-cells since the last
+ garbage collection), `gc_cons_threshold' (a specified threshold
+ after which a garbage collection occurs) and `always_gc'. If
+ `always_gc' is set or if the threshold is exceeded, the garbage
+ collection will start.
+
+ 4. In function `Ffuncall / funcall' in file `eval.c'. This function
+ evaluates calls of elisp functions and works according to `Feval'.
+
+ The upshot is that garbage collection can basically occur everywhere
+`Feval', respectively `Ffuncall', is used - either directly or through
+another function. Since calls to these two functions are hidden in
+various other functions, many calls to `garabge_collect_1' are not
+obviously foreseeable, and therefore unexpected. Instances where they
+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.
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: garbage_collect_1, Next: mark_object, Prev: Invocation, Up: Garbage Collection - Step by Step
+
+`garbage_collect_1'
+-------------------
+
+ We can now describe exactly what happens after the invocation takes
+place.
+ 1. There are several cases in which the garbage collector is left
+ immediately: when we are already garbage collecting
+ (`gc_in_progress'), when the garbage collection is somehow
+ forbidden (`gc_currently_forbidden'), when we are currently
+ displaying something (`in_display') or when we are preparing for
+ the armageddon of the whole system (`preparing_for_armageddon').
+
+ 2. Next the correct frame in which to put all the output occurring
+ during garbage collecting is determined. In order to be able to
+ restore the old display's state after displaying the message, some
+ data about the current cursor position has to be saved. The
+ variables `pre_gc_curser' and `cursor_changed' take care of that.
+
+ 3. The state of `gc_currently_forbidden' must be restored after the
+ garbage collection, no matter what happens during the process. We
+ accomplish this by `record_unwind_protect'ing the suitable function
+ `restore_gc_inhibit' together with the current value of
+ `gc_currently_forbidden'.
+
+ 4. If we are concurrently running an interactive xemacs session, the
+ next step is simply to show the garbage collector's cursor/message.
+
+ 5. The following steps are the intrinsic steps of the garbage
+ collector, therefore `gc_in_progress' is set.
+
+ 6. For debugging purposes, it is possible to copy the current C stack
+ frame. However, this seems to be a currently unused feature.
+
+ 7. Before actually starting to go over all live objects, references to
+ objects that are no longer used are pruned. We only have to do
+ this for events (`clear_event_resource') and for specifiers
+ (`cleanup_specifiers').
+
+ 8. Now the mark phase begins and marks all accessible elements. In
+ order to start from all slots that serve as roots of
+ accessibility, the function `mark_object' is called for each root
+ individually to go out from there to mark all reachable objects.
+ All roots that are traversed are shown in their processed order:
+ * all constant symbols and static variables that are registered
+ via `staticpro' in the array `staticvec'. *Note Adding
+ Global Lisp Variables::.
+
+ * all Lisp objects that are created in C functions and that
+ must be protected from freeing them. They are registered in
+ the global list `gcprolist'. *Note GCPROing::.
+
+ * all local variables (i.e. their name fields `symbol' and old
+ values `old_values') that are bound during the evaluation by
+ the Lisp engine. They are stored in `specbinding' structs
+ pushed on a stack called `specpdl'. *Note Dynamic Binding;
+ The specbinding Stack; Unwind-Protects::.
+
+ * all catch blocks that the Lisp engine encounters during the
+ evaluation cause the creation of structs `catchtag' inserted
+ in the list `catchlist'. Their tag (`tag') and value (`val'
+ fields are freshly created objects and therefore have to be
+ marked. *Note Catch and Throw::.
+
+ * every function application pushes new structs `backtrace' on
+ the call stack of the Lisp engine (`backtrace_list'). The
+ unique parts that have to be marked are the fields for each
+ function (`function') and all their arguments (`args').
+ *Note Evaluation::.
+
+ * all objects that are used by the redisplay engine that must
+ not be freed are marked by a special function called
+ `mark_redisplay' (in `redisplay.c').
+
+ * all objects created for profiling purposes are allocated by C
+ functions instead of using the lisp allocation mechanisms. In
+ order to receive the right ones during the sweep phase, they
+ also have to be marked manually. That is done by the function
+ `mark_profiling_info'
+
+ 9. Hash tables in Xemacs belong to a kind of special objects that
+ make use of a concept often called 'weak pointers'. To make a
+ long story short, these kind of pointers are not followed during
+ the estimation of the live objects during garbage collection. Any
+ object referenced only by weak pointers is collected anyway, and
+ the reference to it is cleared. In hash tables there are different
+ usage patterns of them, manifesting in different types of hash
+ tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak'
+ (internally also 'key-car-weak' and 'value-car-weak') hash tables,
+ each clearing entries depending on different conditions. More
+ information can be found in the documentation to the function
+ `make-hash-table'.
+
+ Because there are complicated dependency rules about when and what
+ to mark while processing weak hash tables, the standard `marker'
+ method is only active if it is marking non-weak hash tables. As
+ soon as a weak component is in the table, the hash table entries
+ are ignored while marking. Instead their marking is done each
+ separately by the function `finish_marking_weak_hash_tables'. This
+ function iterates over each hash table entry `hentries' for each
+ weak hash table in `Vall_weak_hash_tables'. Depending on the type
+ of a table, the appropriate action is performed. If a table is
+ acting as `HASH_TABLE_KEY_WEAK', and a key already marked,
+ everything reachable from the `value' component is marked. If it is
+ acting as a `HASH_TABLE_VALUE_WEAK' and the value component is
+ already marked, the marking starts beginning only from the `key'
+ component. If it is a `HASH_TABLE_KEY_CAR_WEAK' and the car of
+ the key entry is already marked, we mark both the `key' and
+ `value' components. Finally, if the table is of the type
+ `HASH_TABLE_VALUE_CAR_WEAK' and the car of the value components is
+ already marked, again both the `key' and the `value' components
+ get marked.
+
+ Again, there are lists with comparable properties called weak
+ lists. There exist different peculiarities of their types called
+ `simple', `assoc', `key-assoc' and `value-assoc'. You can find
+ further details about them in the description to the function
+ `make-weak-list'. The scheme of their marking is similar: all weak
+ lists are listed in `Qall_weak_lists', therefore we iterate over
+ them. The marking is advanced until we hit an already marked pair.
+ Then we know that during a former run all the rest has been marked
+ completely. Again, depending on the special type of the weak list,
+ our jobs differ. If it is a `WEAK_LIST_SIMPLE' and the elem is
+ marked, we mark the `cons' part. If it is a `WEAK_LIST_ASSOC' and
+ not a pair or a pair with both marked car and cdr, we mark the
+ `cons' and the `elem'. If it is a `WEAK_LIST_KEY_ASSOC' and not a
+ pair or a pair with a marked car of the elem, we mark the `cons'
+ and the `elem'. Finally, if it is a `WEAK_LIST_VALUE_ASSOC' and
+ not a pair or a pair with a marked cdr of the elem, we mark both
+ the `cons' and the `elem'.
+
+ Since, by marking objects in reach from weak hash tables and weak
+ lists, other objects could get marked, this perhaps implies
+ further marking of other weak objects, both finishing functions
+ are redone as long as yet unmarked objects get freshly marked.
+
+ 10. After completing the special marking for the weak hash tables and
+ for the weak lists, all entries that point to objects that are
+ going to be swept in the further process are useless, and
+ therefore have to be removed from the table or the list.
+
+ The function `prune_weak_hash_tables' does the job for weak hash
+ tables. Totally unmarked hash tables are removed from the list
+ `Vall_weak_hash_tables'. The other ones are treated more carefully
+ by scanning over all entries and removing one as soon as one of
+ the components `key' and `value' is unmarked.
+
+ The same idea applies to the weak lists. It is accomplished by
+ `prune_weak_lists': An unmarked list is pruned from
+ `Vall_weak_lists' immediately. A marked list is treated more
+ carefully by going over it and removing just the unmarked pairs.
+
+ 11. The function `prune_specifiers' checks all listed specifiers held
+ in `Vall_speficiers' and removes the ones from the lists that are
+ unmarked.
+
+ 12. All syntax tables are stored in a list called
+ `Vall_syntax_tables'. The function `prune_syntax_tables' walks
+ through it and unlinks the tables that are unmarked.
+
+ 13. Next, we will attack the complete sweeping - the function
+ `gc_sweep' which holds the predominance.
+
+ 14. First, all the variables with respect to garbage collection are
+ reset. `consing_since_gc' - the counter of the created cells since
+ the last garbage collection - is set back to 0, and
+ `gc_in_progress' is not `true' anymore.
+
+ 15. In case the session is interactive, the displayed cursor and
+ message are removed again.
+
+ 16. The state of `gc_inhibit' is restored to the former value by
+ unwinding the stack.
+
+ 17. A small memory reserve is always held back that can be reached by
+ `breathing_space'. If nothing more is left, we create a new reserve
+ and exit.
+
+\1f
+File: internals.info, Node: mark_object, Next: gc_sweep, Prev: garbage_collect_1, Up: Garbage Collection - Step by Step
+
+`mark_object'
+-------------
+
+ The first thing that is checked while marking an object is whether
+the object is a real Lisp object `Lisp_Type_Record' or just an integer
+or a character. Integers and characters are the only two types that are
+stored directly - without another level of indirection, and therefore
+they don´t have to be marked and collected. *Note How Lisp Objects Are
+Represented in C::.
+
+ The second case is the one we have to handle. It is the one when we
+are dealing with a pointer to a Lisp object. But, there exist also three
+possibilities, that prevent us from doing anything while marking: The
+object is read only which prevents it from being garbage collected,
+i.e. marked (`C_READONLY_RECORD_HEADER'). The object in question is
+already marked, and need not be marked for the second time (checked by
+`MARKED_RECORD_HEADER_P'). If it is a special, unmarkable object
+(`UNMARKABLE_RECORD_HEADER_P', apparently, these are objects that sit
+in some CONST space, and can therefore not be marked, see
+`this_one_is_unmarkable' in `alloc.c').
+
+ Now, the actual marking is feasible. We do so by once using the macro
+`MARK_RECORD_HEADER' to mark the object itself (actually the special
+flag in the lrecord header), and calling its special marker "method"
+`marker' if available. The marker method marks every other object that
+is in reach from our current object. Note, that these marker methods
+should not call `mark_object' recursively, but instead should return
+the next object from where further marking has to be performed.
+
+ In case another object was returned, as mentioned before, we
+reiterate the whole `mark_object' process beginning with this next
+object.
+
+\1f
+File: internals.info, Node: gc_sweep, Next: sweep_lcrecords_1, Prev: mark_object, Up: Garbage Collection - Step by Step
+
+`gc_sweep'
+----------
+
+ The job of this function is to free all unmarked records from
+memory. As we know, there are different types of objects implemented
+and managed, and consequently different ways to free them from memory.
+*Note Introduction to Allocation::.
+
+ We start with all objects stored through `lcrecords'. All bulkier
+objects are allocated and handled using that scheme of `lcrecords'.
+Each object is `malloc'ed separately instead of placing it in one of
+the contiguous frob blocks. All types that are currently stored using
+`lcrecords'´s `alloc_lcrecord' and `make_lcrecord_list' are the types:
+vectors, buffers, char-table, char-table-entry, console, weak-list,
+database, device, ldap, hash-table, command-builder, extent-auxiliary,
+extent-info, face, coding-system, frame, image-instance, glyph,
+popup-data, gui-item, keymap, charset, color_instance, font_instance,
+opaque, opaque-list, process, range-table, specifier,
+symbol-value-buffer-local, symbol-value-lisp-magic,
+symbol-value-varalias, toolbar-button, tooltalk-message,
+tooltalk-pattern, window, and window-configuration. We take care of
+them in the fist place in order to be able to handle and to finalize
+items stored in them more easily. The function `sweep_lcrecords_1' as
+described below is doing the whole job for us. For a description about
+the internals: *Note lrecords::.
+
+ Our next candidates are the other objects that behave quite
+differently than everything else: the strings. They consists of two
+parts, a fixed-size portion (`struct Lisp_string') holding the string's
+length, its property list and a pointer to the second part, and the
+actual string data, which is stored in string-chars blocks comparable to
+frob blocks. In this block, the data is not only freed, but also a
+compression of holes is made, i.e. all strings are relocated together.
+*Note String::. This compacting phase is performed by the function
+`compact_string_chars', the actual sweeping by the function
+`sweep_strings' is described below.
+
+ After that, the other types are swept step by step using functions
+`sweep_conses', `sweep_bit_vectors_1', `sweep_compiled_functions',
+`sweep_floats', `sweep_symbols', `sweep_extents', `sweep_markers' and
+`sweep_extents'. They are the fixed-size types cons, floats,
+compiled-functions, symbol, marker, extent, and event stored in
+so-called "frob blocks", and therefore we can basically do the same on
+every type objects, using the same macros, especially defined only to
+handle everything with respect to fixed-size blocks. The only fixed-size
+type that is not handled here are the fixed-size portion of strings,
+because we took special care of them earlier.
+
+ The only big exceptions are bit vectors stored differently and
+therefore treated differently by the function `sweep_bit_vectors_1'
+described later.
+
+ At first, we need some brief information about how these fixed-size
+types are managed in general, in order to understand how the sweeping
+is done. They have all a fixed size, and are therefore stored in big
+blocks of memory - allocated at once - that can hold a certain amount
+of objects of one type. The macro `DECLARE_FIXED_TYPE_ALLOC' creates
+the suitable structures for every type. More precisely, we have the
+block struct (holding a pointer to the previous block `prev' and the
+objects in `block[]'), a pointer to current block
+(`current_..._block)') and its last index (`current_..._block_index'),
+and a pointer to the free list that will be created. Also a macro
+`FIXED_TYPE_FROM_BLOCK' plus some related macros exists that are used
+to obtain a new object, either from the free list
+`ALLOCATE_FIXED_TYPE_1' if there is an unused object of that type
+stored or by allocating a completely new block using
+`ALLOCATE_FIXED_TYPE_FROM_BLOCK'.
+
+ The rest works as follows: all of them define a macro `UNMARK_...'
+that is used to unmark the object. They define a macro
+`ADDITIONAL_FREE_...' that defines additional work that has to be done
+when converting an object from in use to not in use (so far, only
+markers use it in order to unchain them). Then, they all call the macro
+`SWEEP_FIXED_TYPE_BLOCK' instantiated with their type name and their
+struct name.
+
+ This call in particular does the following: we go over all blocks
+starting with the current moving towards the oldest. For each block,
+we look at every object in it. If the object already freed (checked
+with `FREE_STRUCT_P' using the first pointer of the object), or if it is
+set to read only (`C_READONLY_RECORD_HEADER_P', nothing must be done.
+If it is unmarked (checked with `MARKED_RECORD_HEADER_P'), it is put in
+the free list and set free (using the macro `FREE_FIXED_TYPE',
+otherwise it stays in the block, but is unmarked (by `UNMARK_...').
+While going through one block, we note if the whole block is empty. If
+so, the whole block is freed (using `xfree') and the free list state is
+set to the state it had before handling this block.
+
+\1f
+File: internals.info, Node: sweep_lcrecords_1, Next: compact_string_chars, Prev: gc_sweep, Up: Garbage Collection - Step by Step
+
+`sweep_lcrecords_1'
+-------------------
+
+ After nullifying the complete lcrecord statistics, we go over all
+lcrecords two separate times. They are all chained together in a list
+with a head called `all_lcrecords'.
+
+ The first loop calls for each object its `finalizer' method, but only
+in the case that it is not read only (`C_READONLY_RECORD_HEADER_P)', it
+is not already marked (`MARKED_RECORD_HEADER_P'), it is not already in
+a free list (list of freed objects, field `free') and finally it owns a
+finalizer method.
+
+ The second loop actually frees the appropriate objects again by
+iterating through the whole list. In case an object is read only or
+marked, it has to persist, otherwise it is manually freed by calling
+`xfree'. During this loop, the lcrecord statistics are kept up to date
+by calling `tick_lcrecord_stats' with the right arguments,
+
+\1f
+File: internals.info, Node: compact_string_chars, Next: sweep_strings, Prev: sweep_lcrecords_1, Up: Garbage Collection - Step by Step
+
+`compact_string_chars'
+----------------------
+
+ The purpose of this function is to compact all the data parts of the
+strings that are held in so-called `string_chars_block', i.e. the
+strings that do not exceed a certain maximal length.
+
+ The procedure with which this is done is as follows. We are keeping
+two positions in the `string_chars_block's using two pointer/integer
+pairs, namely `from_sb'/`from_pos' and `to_sb'/`to_pos'. They stand for
+the actual positions, from where to where, to copy the actually handled
+string.
+
+ While going over all chained `string_char_block's and their held
+strings, staring at `first_string_chars_block', both pointers are
+advanced and eventually a string is copied from `from_sb' to `to_sb',
+depending on the status of the pointed at strings.
+
+ More precisely, we can distinguish between the following actions.
+ * The string at `from_sb''s position could be marked as free, which
+ is indicated by an invalid pointer to the pointer that should
+ point back to the fixed size string object, and which is checked by
+ `FREE_STRUCT_P'. In this case, the `from_sb'/`from_pos' is
+ advanced to the next string, and nothing has to be copied.
+
+ * Also, if a string object itself is unmarked, nothing has to be
+ copied. We likewise advance the `from_sb'/`from_pos' pair as
+ described above.
+
+ * In all other cases, we have a marked string at hand. The string
+ data must be moved from the from-position to the to-position. In
+ case there is not enough space in the actual `to_sb'-block, we
+ advance this pointer to the beginning of the next block before
+ copying. In case the from and to positions are different, we
+ perform the actual copying using the library function `memmove'.
+
+ After compacting, the pointer to the current `string_chars_block',
+sitting in `current_string_chars_block', is reset on the last block to
+which we moved a string, i.e. `to_block', and all remaining blocks (we
+know that they just carry garbage) are explicitly `xfree'd.
+
+\1f
+File: internals.info, Node: sweep_strings, Next: sweep_bit_vectors_1, Prev: compact_string_chars, Up: Garbage Collection - Step by Step
+
+`sweep_strings'
+---------------
+
+ The sweeping for the fixed sized string objects is essentially
+exactly the same as it is for all other fixed size types. As before,
+the freeing into the suitable free list is done by using the macro
+`SWEEP_FIXED_SIZE_BLOCK' after defining the right macros
+`UNMARK_string' and `ADDITIONAL_FREE_string'. These two definitions are
+a little bit special compared to the ones used for the other fixed size
+types.
+
+ `UNMARK_string' is defined the same way except some additional code
+used for updating the bookkeeping information.
+
+ For strings, `ADDITIONAL_FREE_string' has to do something in
+addition: in case, the string was not allocated in a
+`string_chars_block' because it exceeded the maximal length, and
+therefore it was `malloc'ed separately, we know also `xfree' it
+explicitly.
+
+\1f
+File: internals.info, Node: sweep_bit_vectors_1, Prev: sweep_strings, Up: Garbage Collection - Step by Step
+
+`sweep_bit_vectors_1'
+---------------------
+
+ Bit vectors are also one of the rare types that are `malloc'ed
+individually. Consequently, while sweeping, all further needless bit
+vectors must be freed by hand. This is done, as one might imagine, the
+expected way: since they are all registered in a list called
+`all_bit_vectors', all elements of that list are traversed, all
+unmarked bit vectors are unlinked by calling `xfree' and all of them
+become unmarked. In addition, the bookkeeping information used for
+garbage collector's output purposes is updated.
+
+\1f
+File: internals.info, Node: Integers and Characters, Next: Allocation from Frob Blocks, Prev: Garbage Collection - Step by Step, Up: Allocation of Objects in XEmacs Lisp
+
+Integers and Characters
+=======================
+
+ Integer and character Lisp objects are created from integers using
+the macros `XSETINT()' and `XSETCHAR()' or the equivalent functions
+`make_int()' and `make_char()'. (These are actually macros on most
+systems.) These functions basically just do some moving of bits
+around, since the integral value of the object is stored directly in
+the `Lisp_Object'.
+
+ `XSETINT()' and the like will truncate values given to them that are
+too big; i.e. you won't get the value you expected but the tag bits
+will at least be correct.
+
+\1f
+File: internals.info, Node: Allocation from Frob Blocks, Next: lrecords, Prev: Integers and Characters, Up: Allocation of Objects in XEmacs Lisp
+
+Allocation from Frob Blocks
+===========================
+
+ The uninitialized memory required by a `Lisp_Object' of a particular
+type is allocated using `ALLOCATE_FIXED_TYPE()'. This only occurs
+inside of the lowest-level object-creating functions in `alloc.c':
+`Fcons()', `make_float()', `Fmake_byte_code()', `Fmake_symbol()',
+`allocate_extent()', `allocate_event()', `Fmake_marker()', and
+`make_uninit_string()'. The idea is that, for each type, there are a
+number of frob blocks (each 2K in size); each frob block is divided up
+into object-sized chunks. Each frob block will have some of these
+chunks that are currently assigned to objects, and perhaps some that are
+free. (If a frob block has nothing but free chunks, it is freed at the
+end of the garbage collection cycle.) The free chunks are stored in a
+free list, which is chained by storing a pointer in the first four bytes
+of the chunk. (Except for the free chunks at the end of the last frob
+block, which are handled using an index which points past the end of the
+last-allocated chunk in the last frob block.) `ALLOCATE_FIXED_TYPE()'
+first tries to retrieve a chunk from the free list; if that fails, it
+calls `ALLOCATE_FIXED_TYPE_FROM_BLOCK()', which looks at the end of the
+last frob block for space, and creates a new frob block if there is
+none. (There are actually two versions of these macros, one of which is
+more defensive but less efficient and is used for error-checking.)
+
+\1f
+File: internals.info, Node: lrecords, Next: Low-level allocation, Prev: Allocation from Frob Blocks, Up: Allocation of Objects in XEmacs Lisp
+
+lrecords
+========
+
+ [see `lrecord.h']
+
+ All lrecords have at the beginning of their structure a `struct
+lrecord_header'. This just contains a pointer to a `struct
+lrecord_implementation', which is a structure containing method pointers
+and such. There is one of these for each type, and it is a global,
+constant, statically-declared structure that is declared in the
+`DEFINE_LRECORD_IMPLEMENTATION()' macro. (This macro actually declares
+an array of two `struct lrecord_implementation' structures. The first
+one contains all the standard method pointers, and is used in all
+normal circumstances. During garbage collection, however, the lrecord
+is "marked" by bumping its implementation pointer by one, so that it
+points to the second structure in the array. This structure contains a
+special indication in it that it's a "marked-object" structure: the
+finalize method is the special function `this_marks_a_marked_record()',
+and all other methods are null pointers. At the end of garbage
+collection, all lrecords will either be reclaimed or unmarked by
+decrementing their implementation pointers, so this second structure
+pointer will never remain past garbage collection.
+
+ Simple lrecords (of type (c) above) just have a `struct
+lrecord_header' at their beginning. lcrecords, however, actually have a
+`struct lcrecord_header'. This, in turn, has a `struct lrecord_header'
+at its beginning, so sanity is preserved; but it also has a pointer
+used to chain all lcrecords together, and a special ID field used to
+distinguish one lcrecord from another. (This field is used only for
+debugging and could be removed, but the space gain is not significant.)
+
+ Simple lrecords are created using `ALLOCATE_FIXED_TYPE()', just like
+for other frob blocks. The only change is that the implementation
+pointer must be initialized correctly. (The implementation structure for
+an lrecord, or rather the pointer to it, is named `lrecord_float',
+`lrecord_extent', `lrecord_buffer', etc.)
+
+ lcrecords are created using `alloc_lcrecord()'. This takes a size
+to allocate and an implementation pointer. (The size needs to be passed
+because some lcrecords, such as window configurations, are of variable
+size.) This basically just `malloc()'s the storage, initializes the
+`struct lcrecord_header', and chains the lcrecord onto the head of the
+list of all lcrecords, which is stored in the variable `all_lcrecords'.
+The calls to `alloc_lcrecord()' generally occur in the lowest-level
+allocation function for each lrecord type.
+
+ Whenever you create an lrecord, you need to call either
+`DEFINE_LRECORD_IMPLEMENTATION()' or
+`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()'. This needs to be specified
+in a C file, at the top level. What this actually does is define and
+initialize the implementation structure for the lrecord. (And possibly
+declares a function `error_check_foo()' that implements the `XFOO()'
+macro when error-checking is enabled.) The arguments to the macros are
+the actual type name (this is used to construct the C variable name of
+the lrecord implementation structure and related structures using the
+`##' macro concatenation operator), a string that names the type on the
+Lisp level (this may not be the same as the C type name; typically, the
+C type name has underscores, while the Lisp string has dashes), various
+method pointers, and the name of the C structure that contains the
+object. The methods are used to encapsulate type-specific information
+about the object, such as how to print it or mark it for garbage
+collection, so that it's easy to add new object types without having to
+add a specific case for each new type in a bunch of different places.
+
+ The difference between `DEFINE_LRECORD_IMPLEMENTATION()' and
+`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()' is that the former is used
+for fixed-size object types and the latter is for variable-size object
+types. Most object types are fixed-size; some complex types, however
+(e.g. window configurations), are variable-size. Variable-size object
+types have an extra method, which is called to determine the actual
+size of a particular object of that type. (Currently this is only used
+for keeping allocation statistics.)
+
+ For the purpose of keeping allocation statistics, the allocation
+engine keeps a list of all the different types that exist. Note that,
+since `DEFINE_LRECORD_IMPLEMENTATION()' is a macro that is specified at
+top-level, there is no way for it to add to the list of all existing
+types. What happens instead is that each implementation structure
+contains in it a dynamically assigned number that is particular to that
+type. (Or rather, it contains a pointer to another structure that
+contains this number. This evasiveness is done so that the
+implementation structure can be declared const.) In the sweep stage of
+garbage collection, each lrecord is examined to see if its
+implementation structure has its dynamically-assigned number set. If
+not, it must be a new type, and it is added to the list of known types
+and a new number assigned. The number is used to index into an array
+holding the number of objects of each type and the total memory
+allocated for objects of that type. The statistics in this array are
+also computed during the sweep stage. These statistics are returned by
+the call to `garbage-collect' and are printed out at the end of the
+loadup phase.
+
+ Note that for every type defined with a `DEFINE_LRECORD_*()' macro,
+there needs to be a `DECLARE_LRECORD_IMPLEMENTATION()' somewhere in a
+`.h' file, and this `.h' file needs to be included by `inline.c'.
+
+ Furthermore, there should generally be a set of `XFOOBAR()',
+`FOOBARP()', etc. macros in a `.h' (or occasionally `.c') file. To
+create one of these, copy an existing model and modify as necessary.
+
+ The various methods in the lrecord implementation structure are:
+
+ 1. A "mark" method. This is called during the marking stage and
+ passed a function pointer (usually the `mark_object()' function),
+ 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
+ reduce the recursion depth, and consequently should be the most
+ heavily nested sub-object, such as a long list.)
+
+ *Please note:* When the mark method is called, garbage collection
+ is in progress, and special precautions need to be taken when
+ accessing objects; see section (B) above.
+
+ If your mark method does not need to do anything, it can be `NULL'.
+
+ 2. A "print" method. This is called to create a printed
+ representation of the object, whenever `princ', `prin1', or the
+ like is called. It is passed the object, a stream to which the
+ output is to be directed, and an `escapeflag' which indicates
+ whether the object's printed representation should be "escaped" so
+ that it is readable. (This corresponds to the difference between
+ `princ' and `prin1'.) Basically, "escaped" means that strings will
+ have quotes around them and confusing characters in the strings
+ such as quotes, backslashes, and newlines will be backslashed; and
+ that special care will be taken to make symbols print in a
+ readable fashion (e.g. symbols that look like numbers will be
+ backslashed). Other readable objects should perhaps pass
+ `escapeflag' on when sub-objects are printed, so that readability
+ is preserved when necessary (or if not, always pass in a 1 for
+ `escapeflag'). Non-readable objects should in general ignore
+ `escapeflag', except that some use it as an indication that more
+ verbose output should be given.
+
+ Sub-objects are printed using `print_internal()', which takes
+ exactly the same arguments as are passed to the print method.
+
+ Literal C strings should be printed using `write_c_string()', or
+ `write_string_1()' for non-null-terminated strings.
+
+ Functions that do not have a readable representation should check
+ the `print_readably' flag and signal an error if it is set.
+
+ If you specify NULL for the print method, the
+ `default_object_printer()' will be used.
+
+ 3. A "finalize" method. This is called at the beginning of the sweep
+ stage on lcrecords that are about to be freed, and should be used
+ to perform any extra object cleanup. This typically involves
+ freeing any extra `malloc()'ed memory associated with the object,
+ releasing any operating-system and window-system resources
+ associated with the object (e.g. pixmaps, fonts), etc.
+
+ The finalize method can be NULL if nothing needs to be done.
+
+ WARNING #1: The finalize method is also called at the end of the
+ dump phase; this time with the for_disksave parameter set to
+ non-zero. The object is *not* about to disappear, so you have to
+ make sure to *not* free any extra `malloc()'ed memory if you're
+ going to need it later. (Also, signal an error if there are any
+ operating-system and window-system resources here, because they
+ can't be dumped.)
+
+ Finalize methods should, as a rule, set to zero any pointers after
+ they've been freed, and check to make sure pointers are not zero
+ before freeing. Although I'm pretty sure that finalize methods
+ are not called twice on the same object (except for the
+ `for_disksave' proviso), we've gotten nastily burned in some cases
+ by not doing this.
+
+ WARNING #2: The finalize method is *only* called for lcrecords,
+ *not* for simply lrecords. If you need a finalize method for
+ simple lrecords, you have to stick it in the
+ `ADDITIONAL_FREE_foo()' macro in `alloc.c'.
+
+ WARNING #3: Things are in an *extremely* bizarre state when
+ `ADDITIONAL_FREE_foo()' is called, so you have to be incredibly
+ careful when writing one of these functions. See the comment in
+ `gc_sweep()'. If you ever have to add one of these, consider
+ using an lcrecord or dealing with the problem in a different
+ fashion.
+
+ 4. An "equal" method. This compares the two objects for similarity,
+ when `equal' is called. It should compare the contents of the
+ objects in some reasonable fashion. It is passed the two objects
+ and a "depth" value, which is used to catch circular objects. To
+ compare sub-Lisp-objects, call `internal_equal()' and bump the
+ depth value by one. If this value gets too high, a
+ `circular-object' error will be signaled.
+
+ If this is NULL, objects are `equal' only when they are `eq', i.e.
+ identical.
+
+ 5. A "hash" method. This is used to hash objects when they are to be
+ compared with `equal'. The rule here is that if two objects are
+ `equal', they *must* hash to the same value; i.e. your hash
+ function should use some subset of the sub-fields of the object
+ that are compared in the "equal" method. If you specify this
+ method as `NULL', the object's pointer will be used as the hash,
+ which will *fail* if the object has an `equal' method, so don't do
+ this.
+
+ To hash a sub-Lisp-object, call `internal_hash()'. Bump the depth
+ by one, just like in the "equal" method.
+
+ To convert a Lisp object directly into a hash value (using its
+ pointer), use `LISP_HASH()'. This is what happens when the hash
+ method is NULL.
+
+ To hash two or more values together into a single value, use
+ `HASH2()', `HASH3()', `HASH4()', etc.
+
+ 6. "getprop", "putprop", "remprop", and "plist" methods. These are
+ used for object types that have properties. I don't feel like
+ documenting them here. If you create one of these objects, you
+ have to use different macros to define them, i.e.
+ `DEFINE_LRECORD_IMPLEMENTATION_WITH_PROPS()' or
+ `DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION_WITH_PROPS()'.
+
+ 7. A "size_in_bytes" method, when the object is of variable-size.
+ (i.e. declared with a `_SEQUENCE_IMPLEMENTATION' macro.) This
+ should simply return the object's size in bytes, exactly as you
+ might expect. For an example, see the methods for window
+ configurations and opaques.
+
+\1f
+File: internals.info, Node: Low-level allocation, Next: Pure Space, Prev: lrecords, Up: Allocation of Objects in XEmacs Lisp
+
+Low-level allocation
+====================
+
+ Memory that you want to allocate directly should be allocated using
+`xmalloc()' rather than `malloc()'. This implements error-checking on
+the return value, and once upon a time did some more vital stuff (i.e.
+`BLOCK_INPUT', which is no longer necessary). Free using `xfree()',
+and realloc using `xrealloc()'. Note that `xmalloc()' will do a
+non-local exit if the memory can't be allocated. (Many functions,
+however, do not expect this, and thus XEmacs will likely crash if this
+happens. *This is a bug.* If you can, you should strive to make your
+function handle this OK. However, it's difficult in the general
+circumstance, perhaps requiring extra unwind-protects and such.)
+
+ Note that XEmacs provides two separate replacements for the standard
+`malloc()' library function. These are called "old GNU malloc"
+(`malloc.c') and "new GNU malloc" (`gmalloc.c'), respectively. New GNU
+malloc is better in pretty much every way than old GNU malloc, and
+should be used if possible. (It used to be that on some systems, the
+old one worked but the new one didn't. I think this was due
+specifically to a bug in SunOS, which the new one now works around; so
+I don't think the old one ever has to be used any more.) The primary
+difference between both of these mallocs and the standard system malloc
+is that they are much faster, at the expense of increased space. The
+basic idea is that memory is allocated in fixed chunks of powers of
+two. This allows for basically constant malloc time, since the various
+chunks can just be kept on a number of free lists. (The standard system
+malloc typically allocates arbitrary-sized chunks and has to spend some
+time, sometimes a significant amount of time, walking the heap looking
+for a free block to use and cleaning things up.) The new GNU malloc
+improves on things by allocating large objects in chunks of 4096 bytes
+rather than in ever larger powers of two, which results in ever larger
+wastage. There is a slight speed loss here, but it's of doubtful
+significance.
+
+ NOTE: Apparently there is a third-generation GNU malloc that is
+significantly better than the new GNU malloc, and should probably be
+included in XEmacs.
+
+ There is also the relocating allocator, `ralloc.c'. This actually
+moves blocks of memory around so that the `sbrk()' pointer shrunk and
+virtual memory released back to the system. On some systems, this is a
+big win. On all systems, it causes a noticeable (and sometimes huge)
+speed penalty, so I turn it off by default. `ralloc.c' only works with
+the new GNU malloc in `gmalloc.c'. There are also two versions of
+`ralloc.c', one that uses `mmap()' rather than block copies to move
+data around. This purports to be faster, although that depends on the
+amount of data that would have had to be block copied and the
+system-call overhead for `mmap()'. I don't know exactly how this
+works, except that the relocating-allocation routines are pretty much
+used only for the memory allocated for a buffer, which is the biggest
+consumer of space, esp. of space that may get freed later.
+
+ Note that the GNU mallocs have some "memory warning" facilities.
+XEmacs taps into them and issues a warning through the standard warning
+system, when memory gets to 75%, 85%, and 95% full. (On some systems,
+the memory warnings are not functional.)
+
+ Allocated memory that is going to be used to make a Lisp object is
+created using `allocate_lisp_storage()'. This calls `xmalloc()' but
+also verifies that the pointer to the memory can fit into a Lisp word
+(remember that some bits are taken away for a type tag and a mark bit).
+If not, an error is issued through `memory_full()'.
+`allocate_lisp_storage()' is called by `alloc_lcrecord()',
+`ALLOCATE_FIXED_TYPE()', and the vector and bit-vector creation
+routines. These routines also call `INCREMENT_CONS_COUNTER()' at the
+appropriate times; this keeps statistics on how much memory is
+allocated, so that garbage-collection can be invoked when the threshold
+is reached.
+
+\1f
+File: internals.info, Node: Pure Space, Next: Cons, Prev: Low-level allocation, Up: Allocation of Objects in XEmacs Lisp
+
+Pure Space
+==========
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Cons, Next: Vector, Prev: Pure Space, Up: Allocation of Objects in XEmacs Lisp
+
+Cons
+====
+
+ Conses are allocated in standard frob blocks. The only thing to
+note is that conses can be explicitly freed using `free_cons()' and
+associated functions `free_list()' and `free_alist()'. This
+immediately puts the conses onto the cons free list, and decrements the
+statistics on memory allocation appropriately. This is used to good
+effect by some extremely commonly-used code, to avoid generating extra
+objects and thereby triggering GC sooner. However, you have to be
+*extremely* careful when doing this. If you mess this up, you will get
+BADLY BURNED, and it has happened before.
+
+\1f
+File: internals.info, Node: Vector, Next: Bit Vector, Prev: Cons, Up: Allocation of Objects in XEmacs Lisp
+
+Vector
+======
+
+ As mentioned above, each vector is `malloc()'ed individually, and
+all are threaded through the variable `all_vectors'. Vectors are
+marked strangely during garbage collection, by kludging the size field.
+Note that the `struct Lisp_Vector' is declared with its `contents'
+field being a *stretchy* array of one element. It is actually
+`malloc()'ed with the right size, however, and access to any element
+through the `contents' array works fine.
+
+\1f
+File: internals.info, Node: Bit Vector, Next: Symbol, Prev: Vector, Up: Allocation of Objects in XEmacs Lisp
+
+Bit Vector
+==========
+
+ Bit vectors work exactly like vectors, except for more complicated
+code to access an individual bit, and except for the fact that bit
+vectors are lrecords while vectors are not. (The only difference here is
+that there's an lrecord implementation pointer at the beginning and the
+tag field in bit vector Lisp words is "lrecord" rather than "vector".)
+
+\1f
+File: internals.info, Node: Symbol, Next: Marker, Prev: Bit Vector, Up: Allocation of Objects in XEmacs Lisp
+
+Symbol
+======
+
+ Symbols are also allocated in frob blocks. Note that the code
+exists for symbols to be either lrecords (category (c) above) or simple
+types (category (b) above), and are lrecords by default (I think),
+although there is no good reason for this.
+
+ Note that symbols in the awful horrible obarray structure are
+chained through their `next' field.
+
+ Remember that `intern' looks up a symbol in an obarray, creating one
+if necessary.
+
+\1f
+File: internals.info, Node: Marker, Next: String, Prev: Symbol, Up: Allocation of Objects in XEmacs Lisp
+
+Marker
+======
+
+ Markers are allocated in frob blocks, as usual. They are kept in a
+buffer unordered, but in a doubly-linked list so that they can easily
+be removed. (Formerly this was a singly-linked list, but in some cases
+garbage collection took an extraordinarily long time due to the O(N^2)
+time required to remove lots of markers from a buffer.) Markers are
+removed from a buffer in the finalize stage, in
+`ADDITIONAL_FREE_marker()'.
+
+\1f
+File: internals.info, Node: String, Next: Compiled Function, Prev: Marker, Up: Allocation of Objects in XEmacs Lisp
+
+String
+======
+
+ As mentioned above, strings are a special case. A string is
+logically two parts, a fixed-size object (containing the length,
+property list, and a pointer to the actual data), and the actual data
+in the string. The fixed-size object is a `struct Lisp_String' and is
+allocated in frob blocks, as usual. The actual data is stored in
+special "string-chars blocks", which are 8K blocks of memory.
+Currently-allocated strings are simply laid end to end in these
+string-chars blocks, with a pointer back to the `struct Lisp_String'
+stored before each string in the string-chars block. When a new string
+needs to be allocated, the remaining space at the end of the last
+string-chars block is used if there's enough, and a new string-chars
+block is created otherwise.
+
+ There are never any holes in the string-chars blocks due to the
+string compaction and relocation that happens at the end of garbage
+collection. During the sweep stage of garbage collection, when objects
+are reclaimed, the garbage collector goes through all string-chars
+blocks, looking for unused strings. Each chunk of string data is
+preceded by a pointer to the corresponding `struct Lisp_String', which
+indicates both whether the string is used and how big the string is,
+i.e. how to get to the next chunk of string data. Holes are compressed
+by block-copying the next string into the empty space and relocating the
+pointer stored in the corresponding `struct Lisp_String'. *This means
+you have to be careful with strings in your code.* See the section
+above on `GCPRO'ing.
+
+ Note that there is one situation not handled: a string that is too
+big to fit into a string-chars block. Such strings, called "big
+strings", are all `malloc()'ed as their own block. (#### Although it
+would make more sense for the threshold for big strings to be somewhat
+lower, e.g. 1/2 or 1/4 the size of a string-chars block. It seems that
+this was indeed the case formerly - indeed, the threshold was set at
+1/8 - but Mly forgot about this when rewriting things for 19.8.)
+
+ Note also that the string data in string-chars blocks is padded as
+necessary so that proper alignment constraints on the `struct
+Lisp_String' back pointers are maintained.
+
+ Finally, strings can be resized. This happens in Mule when a
+character is substituted with a different-length character, or during
+modeline frobbing. (You could also export this to Lisp, but it's not
+done so currently.) Resizing a string is a potentially tricky process.
+If the change is small enough that the padding can absorb it, nothing
+other than a simple memory move needs to be done. Keep in mind,
+however, that the string can't shrink too much because the offset to the
+next string in the string-chars block is computed by looking at the
+length and rounding to the nearest multiple of four or eight. If the
+string would shrink or expand beyond the correct padding, new string
+data needs to be allocated at the end of the last string-chars block and
+the data moved appropriately. This leaves some dead string data, which
+is marked by putting a special marker of 0xFFFFFFFF in the `struct
+Lisp_String' pointer before the data (there's no real `struct
+Lisp_String' to point to and relocate), and storing the size of the dead
+string data (which would normally be obtained from the now-non-existent
+`struct Lisp_String') at the beginning of the dead string data gap.
+The string compactor recognizes this special 0xFFFFFFFF marker and
+handles it correctly.
+
+\1f
+File: internals.info, Node: Compiled Function, Prev: String, Up: Allocation of Objects in XEmacs Lisp
+
+Compiled Function
+=================
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Events and the Event Loop, Next: Evaluation; Stack Frames; Bindings, Prev: Allocation of Objects in XEmacs Lisp, Up: Top
+
+Events and the Event Loop
+*************************
+
+* Menu:
+
+* Introduction to Events::
+* Main Loop::
+* Specifics of the Event Gathering Mechanism::
+* Specifics About the Emacs Event::
+* The Event Stream Callback Routines::
+* Other Event Loop Functions::
+* Converting Events::
+* Dispatching Events; The Command Builder::
+
+\1f
+File: internals.info, Node: Introduction to Events, Next: Main Loop, Up: Events and the Event Loop
+
+Introduction to Events
+======================
+
+ An event is an object that encapsulates information about an
+interesting occurrence in the operating system. Events are generated
+either by user action, direct (e.g. typing on the keyboard or moving
+the mouse) or indirect (moving another window, thereby generating an
+expose event on an Emacs frame), or as a result of some other typically
+asynchronous action happening, such as output from a subprocess being
+ready or a timer expiring. Events come into the system in an
+asynchronous fashion (typically through a callback being called) and
+are converted into a synchronous event queue (first-in, first-out) in a
+process that we will call "collection".
+
+ Note that each application has its own event queue. (It is
+immaterial whether the collection process directly puts the events in
+the proper application's queue, or puts them into a single system
+queue, which is later split up.)
+
+ The most basic level of event collection is done by the operating
+system or window system. Typically, XEmacs does its own event
+collection as well. Often there are multiple layers of collection in
+XEmacs, with events from various sources being collected into a queue,
+which is then combined with other sources to go into another queue
+(i.e. a second level of collection), with perhaps another level on top
+of this, etc.
+
+ XEmacs has its own types of events (called "Emacs events"), which
+provides an abstract layer on top of the system-dependent nature of the
+most basic events that are received. Part of the complex nature of the
+XEmacs event collection process involves converting from the
+operating-system events into the proper Emacs events - there may not be
+a one-to-one correspondence.
+
+ Emacs events are documented in `events.h'; I'll discuss them later.
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: Main Loop, Next: Specifics of the Event Gathering Mechanism, Prev: Introduction to Events, Up: Events and the Event Loop
+
+Main Loop
+=========
+
+ The "command loop" is the top-level loop that the editor is always
+running. It loops endlessly, calling `next-event' to retrieve an event
+and `dispatch-event' to execute it. `dispatch-event' does the
+appropriate thing with non-user events (process, timeout, magic, eval,
+mouse motion); this involves calling a Lisp handler function, redrawing
+a newly-exposed part of a frame, reading subprocess output, etc. For
+user events, `dispatch-event' looks up the event in relevant keymaps or
+menubars; when a full key sequence or menubar selection is reached, the
+appropriate function is executed. `dispatch-event' may have to keep
+state across calls; this is done in the "command-builder" structure
+associated with each console (remember, there's usually only one
+console), and the engine that looks up keystrokes and constructs full
+key sequences is called the "command builder". This is documented
+elsewhere.
+
+ The guts of the command loop are in `command_loop_1()'. This
+function doesn't catch errors, though - that's the job of
+`command_loop_2()', which is a condition-case (i.e. error-trapping)
+wrapper around `command_loop_1()'. `command_loop_1()' never returns,
+but may get thrown out of.
+
+ When an error occurs, `cmd_error()' is called, which usually invokes
+the Lisp error handler in `command-error'; however, a default error
+handler is provided if `command-error' is `nil' (e.g. during startup).
+The purpose of the error handler is simply to display the error message
+and do associated cleanup; it does not need to throw anywhere. When
+the error handler finishes, the condition-case in `command_loop_2()'
+will finish and `command_loop_2()' will reinvoke `command_loop_1()'.
+
+ `command_loop_2()' is invoked from three places: from
+`initial_command_loop()' (called from `main()' at the end of internal
+initialization), from the Lisp function `recursive-edit', and from
+`call_command_loop()'.
+
+ `call_command_loop()' is called when a macro is started and when the
+minibuffer is entered; normal termination of the macro or minibuffer
+causes a throw out of the recursive command loop. (To
+`execute-kbd-macro' for macros and `exit' for minibuffers. Note also
+that the low-level minibuffer-entering function,
+`read-minibuffer-internal', provides its own error handling and does
+not need `command_loop_2()''s error encapsulation; so it tells
+`call_command_loop()' to invoke `command_loop_1()' directly.)
+
+ Note that both read-minibuffer-internal and recursive-edit set up a
+catch for `exit'; this is why `abort-recursive-edit', which throws to
+this catch, exits out of either one.
+
+ `initial_command_loop()', called from `main()', sets up a catch for
+`top-level' when invoking `command_loop_2()', allowing functions to
+throw all the way to the top level if they really need to. Before
+invoking `command_loop_2()', `initial_command_loop()' calls
+`top_level_1()', which handles all of the startup stuff (creating the
+initial frame, handling the command-line options, loading the user's
+`.emacs' file, etc.). The function that actually does this is in Lisp
+and is pointed to by the variable `top-level'; normally this function is
+`normal-top-level'. `top_level_1()' is just an error-handling wrapper
+similar to `command_loop_2()'. Note also that `initial_command_loop()'
+sets up a catch for `top-level' when invoking `top_level_1()', just
+like when it invokes `command_loop_2()'.
+
+\1f
+File: internals.info, Node: Specifics of the Event Gathering Mechanism, Next: Specifics About the Emacs Event, Prev: Main Loop, Up: Events and the Event Loop
+
+Specifics of the Event Gathering Mechanism
+==========================================
+
+ Here is an approximate diagram of the collection processes at work
+in XEmacs, under TTY's (TTY's are simpler than X so we'll look at this
+first):
+
+ asynch. asynch. asynch. asynch. [Collectors in
+ kbd events kbd events process process the OS]
+ | | output output
+ | | | |
+ | | | | SIGINT, [signal handlers
+ | | | | SIGQUIT, in XEmacs]
+ V V V V SIGWINCH,
+ file file file file SIGALRM
+ desc. desc. desc. desc. |
+ (TTY) (TTY) (pipe) (pipe) |
+ | | | | fake timeouts
+ | | | | file |
+ | | | | desc. |
+ | | | | (pipe) |
+ | | | | | |
+ | | | | | |
+ | | | | | |
+ V V V V V V
+ ------>-----------<----------------<----------------
+ |
+ |
+ | [collected using select() in emacs_tty_next_event()
+ | and converted to the appropriate Emacs event]
+ |
+ |
+ V (above this line is TTY-specific)
+ Emacs -----------------------------------------------
+ event (below this line is the generic event mechanism)
+ |
+ |
+ was there if not, call
+ a SIGINT? emacs_tty_next_event()
+ | |
+ | |
+ | |
+ V V
+ --->------<----
+ |
+ | [collected in event_stream_next_event();
+ | SIGINT is converted using maybe_read_quit_event()]
+ V
+ Emacs
+ event
+ |
+ \---->------>----- maybe_kbd_translate() ---->---\
+ |
+ |
+ |
+ command event queue |
+ if not from command
+ (contains events that were event queue, call
+ read earlier but not processed, event_stream_next_event()
+ typically when waiting in a |
+ sit-for, sleep-for, etc. for |
+ a particular event to be received) |
+ | |
+ | |
+ V V
+ ---->------------------------------------<----
+ |
+ | [collected in
+ | next_event_internal()]
+ |
+ unread- unread- event from |
+ command- command- keyboard else, call
+ events event macro next_event_internal()
+ | | | |
+ | | | |
+ | | | |
+ V V V V
+ --------->----------------------<------------
+ |
+ | [collected in `next-event', which may loop
+ | more than once if the event it gets is on
+ | a dead frame, device, etc.]
+ |
+ |
+ V
+ feed into top-level event loop,
+ which repeatedly calls `next-event'
+ and then dispatches the event
+ using `dispatch-event'
+
+ Notice the separation between TTY-specific and generic event
+mechanism. When using the Xt-based event loop, the TTY-specific stuff
+is replaced but the rest stays the same.
+
+ It's also important to realize that only one different kind of
+system-specific event loop can be operating at a time, and must be able
+to receive all kinds of events simultaneously. For the two existing
+event loops (implemented in `event-tty.c' and `event-Xt.c',
+respectively), the TTY event loop *only* handles TTY consoles, while
+the Xt event loop handles *both* TTY and X consoles. This situation is
+different from all of the output handlers, where you simply have one
+per console type.
+
+ Here's the Xt Event Loop Diagram (notice that below a certain point,
+it's the same as the above diagram):
+
+ asynch. asynch. asynch. asynch. [Collectors in
+ kbd kbd process process the OS]
+ events events output output
+ | | | |
+ | | | | asynch. asynch. [Collectors in the
+ | | | | X X OS and X Window System]
+ | | | | events events
+ | | | | | |
+ | | | | | |
+ | | | | | | SIGINT, [signal handlers
+ | | | | | | SIGQUIT, in XEmacs]
+ | | | | | | SIGWINCH,
+ | | | | | | SIGALRM
+ | | | | | | |
+ | | | | | | |
+ | | | | | | | timeouts
+ | | | | | | | |
+ | | | | | | | |
+ | | | | | | V |
+ V V V V V V fake |
+ file file file file file file file |
+ desc. desc. desc. desc. desc. desc. desc. |
+ (TTY) (TTY) (pipe) (pipe) (socket) (socket) (pipe) |
+ | | | | | | | |
+ | | | | | | | |
+ | | | | | | | |
+ V V V V V V V V
+ --->----------------------------------------<---------<------
+ | | |
+ | | |[collected using select() in
+ | | | _XtWaitForSomething(), called
+ | | | from XtAppProcessEvent(), called
+ | | | in emacs_Xt_next_event();
+ | | | dispatched to various callbacks]
+ | | |
+ | | |
+ emacs_Xt_ p_s_callback(), | [popup_selection_callback]
+ event_handler() x_u_v_s_callback(),| [x_update_vertical_scrollbar_
+ | x_u_h_s_callback(),| callback]
+ | search_callback() | [x_update_horizontal_scrollbar_
+ | | | callback]
+ | | |
+ | | |
+ enqueue_Xt_ signal_special_ |
+ dispatch_event() Xt_user_event() |
+ [maybe multiple | |
+ times, maybe 0 | |
+ times] | |
+ | enqueue_Xt_ |
+ | dispatch_event() |
+ | | |
+ | | |
+ V V |
+ -->----------<-- |
+ | |
+ | |
+ dispatch Xt_what_callback()
+ event sets flags
+ queue |
+ | |
+ | |
+ | |
+ | |
+ ---->-----------<--------
+ |
+ |
+ | [collected and converted as appropriate in
+ | emacs_Xt_next_event()]
+ |
+ |
+ V (above this line is Xt-specific)
+ Emacs ------------------------------------------------
+ event (below this line is the generic event mechanism)
+ |
+ |
+ was there if not, call
+ a SIGINT? emacs_Xt_next_event()
+ | |
+ | |
+ | |
+ V V
+ --->-------<----
+ |
+ | [collected in event_stream_next_event();
+ | SIGINT is converted using maybe_read_quit_event()]
+ V
+ Emacs
+ event
+ |
+ \---->------>----- maybe_kbd_translate() -->-----\
+ |
+ |
+ |
+ command event queue |
+ if not from command
+ (contains events that were event queue, call
+ read earlier but not processed, event_stream_next_event()
+ typically when waiting in a |
+ sit-for, sleep-for, etc. for |
+ a particular event to be received) |
+ | |
+ | |
+ V V
+ ---->----------------------------------<------
+ |
+ | [collected in
+ | next_event_internal()]
+ |
+ unread- unread- event from |
+ command- command- keyboard else, call
+ events event macro next_event_internal()
+ | | | |
+ | | | |
+ | | | |
+ V V V V
+ --------->----------------------<------------
+ |
+ | [collected in `next-event', which may loop
+ | more than once if the event it gets is on
+ | a dead frame, device, etc.]
+ |
+ |
+ V
+ feed into top-level event loop,
+ which repeatedly calls `next-event'
+ and then dispatches the event
+ using `dispatch-event'
+
+\1f
+File: internals.info, Node: Specifics About the Emacs Event, Next: The Event Stream Callback Routines, Prev: Specifics of the Event Gathering Mechanism, Up: Events and the Event Loop
+
+Specifics About the Emacs Event
+===============================
+
+\1f
+File: internals.info, Node: The Event Stream Callback Routines, Next: Other Event Loop Functions, Prev: Specifics About the Emacs Event, Up: Events and the Event Loop
+
+The Event Stream Callback Routines
+==================================
+
+\1f
+File: internals.info, Node: Other Event Loop Functions, Next: Converting Events, Prev: The Event Stream Callback Routines, Up: Events and the Event Loop
+
+Other Event Loop Functions
+==========================
+
+ `detect_input_pending()' and `input-pending-p' look for input by
+calling `event_stream->event_pending_p' and looking in
+`[V]unread-command-event' and the `command_event_queue' (they do not
+check for an executing keyboard macro, though).
+
+ `discard-input' cancels any command events pending (and any keyboard
+macros currently executing), and puts the others onto the
+`command_event_queue'. There is a comment about a "race condition",
+which is not a good sign.
+
+ `next-command-event' and `read-char' are higher-level interfaces to
+`next-event'. `next-command-event' gets the next "command" event (i.e.
+keypress, mouse event, menu selection, or scrollbar action), calling
+`dispatch-event' on any others. `read-char' calls `next-command-event'
+and uses `event_to_character()' to return the character equivalent.
+With the right kind of input method support, it is possible for
+(read-char) to return a Kanji character.
+
+\1f
+File: internals.info, Node: Converting Events, Next: Dispatching Events; The Command Builder, Prev: Other Event Loop Functions, Up: Events and the Event Loop
+
+Converting Events
+=================
+
+ `character_to_event()', `event_to_character()',
+`event-to-character', and `character-to-event' convert between
+characters and keypress events corresponding to the characters. If the
+event was not a keypress, `event_to_character()' returns -1 and
+`event-to-character' returns `nil'. These functions convert between
+character representation and the split-up event representation (keysym
+plus mod keys).
+
+\1f
+File: internals.info, Node: Dispatching Events; The Command Builder, Prev: Converting Events, Up: Events and the Event Loop
+
+Dispatching Events; The Command Builder
+=======================================
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Evaluation; Stack Frames; Bindings, Next: Symbols and Variables, Prev: Events and the Event Loop, Up: Top
+
+Evaluation; Stack Frames; Bindings
+**********************************
+
+* Menu:
+
+* Evaluation::
+* Dynamic Binding; The specbinding Stack; Unwind-Protects::
+* Simple Special Forms::
+* Catch and Throw::
+
+\1f
+File: internals.info, Node: Evaluation, Next: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings
+
+Evaluation
+==========
+
+ `Feval()' evaluates the form (a Lisp object) that is passed to it.
+Note that evaluation is only non-trivial for two types of objects:
+symbols and conses. A symbol is evaluated simply by calling
+`symbol-value' on it and returning the value.
+
+ Evaluating a cons means calling a function. First, `eval' checks to
+see if garbage-collection is necessary, and calls `garbage_collect_1()'
+if so. It then increases the evaluation depth by 1 (`lisp_eval_depth',
+which is always less than `max_lisp_eval_depth') and adds an element to
+the linked list of `struct backtrace''s (`backtrace_list'). Each such
+structure contains a pointer to the function being called plus a list
+of the function's arguments. Originally these values are stored
+unevalled, and as they are evaluated, the backtrace structure is
+updated. Garbage collection pays attention to the objects pointed to
+in the backtrace structures (garbage collection might happen while a
+function is being called or while an argument is being evaluated, and
+there could easily be no other references to the arguments in the
+argument list; once an argument is evaluated, however, the unevalled
+version is not needed by eval, and so the backtrace structure is
+changed).
+
+ At this point, the function to be called is determined by looking at
+the car of the cons (if this is a symbol, its function definition is
+retrieved and the process repeated). The function should then consist
+of either a `Lisp_Subr' (built-in function written in C), a
+`Lisp_Compiled_Function' object, or a cons whose car is one of the
+symbols `autoload', `macro' or `lambda'.
+
+ If the function is a `Lisp_Subr', the lisp object points to a
+`struct Lisp_Subr' (created by `DEFUN()'), which contains a pointer to
+the C function, a minimum and maximum number of arguments (or possibly
+the special constants `MANY' or `UNEVALLED'), a pointer to the symbol
+referring to that subr, and a couple of other things. If the subr
+wants its arguments `UNEVALLED', they are passed raw as a list.
+Otherwise, an array of evaluated arguments is created and put into the
+backtrace structure, and either passed whole (`MANY') or each argument
+is passed as a C argument.
+
+ If the function is a `Lisp_Compiled_Function',
+`funcall_compiled_function()' is called. If the function is a lambda
+list, `funcall_lambda()' is called. If the function is a macro, [.....
+fill in] is done. If the function is an autoload, `do_autoload()' is
+called to load the definition and then eval starts over [explain this
+more].
+
+ When `Feval()' exits, the evaluation depth is reduced by one, the
+debugger is called if appropriate, and the current backtrace structure
+is removed from the list.
+
+ Both `funcall_compiled_function()' and `funcall_lambda()' need to go
+through the list of formal parameters to the function and bind them to
+the actual arguments, checking for `&rest' and `&optional' symbols in
+the formal parameters and making sure the number of actual arguments is
+correct. `funcall_compiled_function()' can do this a little more
+efficiently, since the formal parameter list can be checked for sanity
+when the compiled function object is created.
+
+ `funcall_lambda()' simply calls `Fprogn' to execute the code in the
+lambda list.
+
+ `funcall_compiled_function()' calls the real byte-code interpreter
+`execute_optimized_program()' on the byte-code instructions, which are
+converted into an internal form for faster execution.
+
+ When a compiled function is executed for the first time by
+`funcall_compiled_function()', or when it is `Fpurecopy()'ed during the
+dump phase of building XEmacs, the byte-code instructions are converted
+from a `Lisp_String' (which is inefficient to access, especially in the
+presence of MULE) into a `Lisp_Opaque' object containing an array of
+unsigned char, which can be directly executed by the byte-code
+interpreter. At this time the byte code is also analyzed for validity
+and transformed into a more optimized form, so that
+`execute_optimized_program()' can really fly.
+
+ Here are some of the optimizations performed by the internal
+byte-code transformer:
+ 1. References to the `constants' array are checked for out-of-range
+ indices, so that the byte interpreter doesn't have to.
+
+ 2. References to the `constants' array that will be used as a Lisp
+ variable are checked for being correct non-constant (i.e. not `t',
+ `nil', or `keywordp') symbols, so that the byte interpreter
+ doesn't have to.
+
+ 3. The maxiumum number of variable bindings in the byte-code is
+ pre-computed, so that space on the `specpdl' stack can be
+ pre-reserved once for the whole function execution.
+
+ 4. All byte-code jumps are relative to the current program counter
+ instead of the start of the program, thereby saving a register.
+
+ 5. One-byte relative jumps are converted from the byte-code form of
+ unsigned chars offset by 127 to machine-friendly signed chars.
+
+ Of course, this transformation of the `instructions' should not be
+visible to the user, so `Fcompiled_function_instructions()' needs to
+know how to convert the optimized opaque object back into a Lisp string
+that is identical to the original string from the `.elc' file.
+(Actually, the resulting string may (rarely) contain slightly
+different, yet equivalent, byte code.)
+
+ `Ffuncall()' implements Lisp `funcall'. `(funcall fun x1 x2 x3
+...)' is equivalent to `(eval (list fun (quote x1) (quote x2) (quote
+x3) ...))'. `Ffuncall()' contains its own code to do the evaluation,
+however, and is very similar to `Feval()'.
+
+ From the performance point of view, it is worth knowing that most of
+the time in Lisp evaluation is spent executing `Lisp_Subr' and
+`Lisp_Compiled_Function' objects via `Ffuncall()' (not `Feval()').
+
+ `Fapply()' implements Lisp `apply', which is very similar to
+`funcall' except that if the last argument is a list, the result is the
+same as if each of the arguments in the list had been passed separately.
+`Fapply()' does some business to expand the last argument if it's a
+list, then calls `Ffuncall()' to do the work.
+
+ `apply1()', `call0()', `call1()', `call2()', and `call3()' call a
+function, passing it the argument(s) given (the arguments are given as
+separate C arguments rather than being passed as an array). `apply1()'
+uses `Fapply()' while the others use `Ffuncall()' to do the real work.
+
+\1f
+File: internals.info, Node: Dynamic Binding; The specbinding Stack; Unwind-Protects, Next: Simple Special Forms, Prev: Evaluation, Up: Evaluation; Stack Frames; Bindings
+
+Dynamic Binding; The specbinding Stack; Unwind-Protects
+=======================================================
+
+ struct specbinding
+ {
+ Lisp_Object symbol;
+ Lisp_Object old_value;
+ Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
+ };
+
+ `struct specbinding' is used for local-variable bindings and
+unwind-protects. `specpdl' holds an array of `struct specbinding''s,
+`specpdl_ptr' points to the beginning of the free bindings in the
+array, `specpdl_size' specifies the total number of binding slots in
+the array, and `max_specpdl_size' specifies the maximum number of
+bindings the array can be expanded to hold. `grow_specpdl()' increases
+the size of the `specpdl' array, multiplying its size by 2 but never
+exceeding `max_specpdl_size' (except that if this number is less than
+400, it is first set to 400).
+
+ `specbind()' binds a symbol to a value and is used for local
+variables and `let' forms. The symbol and its old value (which might
+be `Qunbound', indicating no prior value) are recorded in the specpdl
+array, and `specpdl_size' is increased by 1.
+
+ `record_unwind_protect()' implements an "unwind-protect", which,
+when placed around a section of code, ensures that some specified
+cleanup routine will be executed even if the code exits abnormally
+(e.g. through a `throw' or quit). `record_unwind_protect()' simply
+adds a new specbinding to the `specpdl' array and stores the
+appropriate information in it. The cleanup routine can either be a C
+function, which is stored in the `func' field, or a `progn' form, which
+is stored in the `old_value' field.
+
+ `unbind_to()' removes specbindings from the `specpdl' array until
+the specified position is reached. Each specbinding can be one of
+three types:
+
+ 1. an unwind-protect with a C cleanup function (`func' is not 0, and
+ `old_value' holds an argument to be passed to the function);
+
+ 2. an unwind-protect with a Lisp form (`func' is 0, `symbol' is
+ `nil', and `old_value' holds the form to be executed with
+ `Fprogn()'); or
+
+ 3. a local-variable binding (`func' is 0, `symbol' is not `nil', and
+ `old_value' holds the old value, which is stored as the symbol's
+ value).
+
+\1f
+File: internals.info, Node: Simple Special Forms, Next: Catch and Throw, Prev: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings
+
+Simple Special Forms
+====================
+
+ `or', `and', `if', `cond', `progn', `prog1', `prog2', `setq',
+`quote', `function', `let*', `let', `while'
+
+ All of these are very simple and work as expected, calling `Feval()'
+or `Fprogn()' as necessary and (in the case of `let' and `let*') using
+`specbind()' to create bindings and `unbind_to()' to undo the bindings
+when finished.
+
+ Note that, with the exeption of `Fprogn', these functions are
+typically called in real life only in interpreted code, since the byte
+compiler knows how to convert calls to these functions directly into
+byte code.
+
+\1f
+File: internals.info, Node: Catch and Throw, Prev: Simple Special Forms, Up: Evaluation; Stack Frames; Bindings
+
+Catch and Throw
+===============
+
+ struct catchtag
+ {
+ Lisp_Object tag;
+ Lisp_Object val;
+ struct catchtag *next;
+ struct gcpro *gcpro;
+ jmp_buf jmp;
+ struct backtrace *backlist;
+ int lisp_eval_depth;
+ int pdlcount;
+ };
+
+ `catch' is a Lisp function that places a catch around a body of
+code. A catch is a means of non-local exit from the code. When a catch
+is created, a tag is specified, and executing a `throw' to this tag
+will exit from the body of code caught with this tag, and its value will
+be the value given in the call to `throw'. If there is no such call,
+the code will be executed normally.
+
+ Information pertaining to a catch is held in a `struct catchtag',
+which is placed at the head of a linked list pointed to by `catchlist'.
+`internal_catch()' is passed a C function to call (`Fprogn()' when
+Lisp `catch' is called) and arguments to give it, and places a catch
+around the function. Each `struct catchtag' is held in the stack frame
+of the `internal_catch()' instance that created the catch.
+
+ `internal_catch()' is fairly straightforward. It stores into the
+`struct catchtag' the tag name and the current values of
+`backtrace_list', `lisp_eval_depth', `gcprolist', and the offset into
+the `specpdl' array, sets a jump point with `_setjmp()' (storing the
+jump point into the `struct catchtag'), and calls the function.
+Control will return to `internal_catch()' either when the function
+exits normally or through a `_longjmp()' to this jump point. In the
+latter case, `throw' will store the value to be returned into the
+`struct catchtag' before jumping. When it's done, `internal_catch()'
+removes the `struct catchtag' from the catchlist and returns the proper
+value.
+
+ `Fthrow()' goes up through the catchlist until it finds one with a
+matching tag. It then calls `unbind_catch()' to restore everything to
+what it was when the appropriate catch was set, stores the return value
+in the `struct catchtag', and jumps (with `_longjmp()') to its jump
+point.
+
+ `unbind_catch()' removes all catches from the catchlist until it
+finds the correct one. Some of the catches might have been placed for
+error-trapping, and if so, the appropriate entries on the handlerlist
+must be removed (see "errors"). `unbind_catch()' also restores the
+values of `gcprolist', `backtrace_list', and `lisp_eval', and calls
+`unbind_to()' to undo any specbindings created since the catch.
+
+\1f
+File: internals.info, Node: Symbols and Variables, Next: Buffers and Textual Representation, Prev: Evaluation; Stack Frames; Bindings, Up: Top
+
+Symbols and Variables
+*********************
+
+* Menu:
+
+* Introduction to Symbols::
+* Obarrays::
+* Symbol Values::
+
+\1f
+File: internals.info, Node: Introduction to Symbols, Next: Obarrays, Up: Symbols and Variables
+
+Introduction to Symbols
+=======================
+
+ A symbol is basically just an object with four fields: a name (a
+string), a value (some Lisp object), a function (some Lisp object), and
+a property list (usually a list of alternating keyword/value pairs).
+What makes symbols special is that there is usually only one symbol with
+a given name, and the symbol is referred to by name. This makes a
+symbol a convenient way of calling up data by name, i.e. of implementing
+variables. (The variable's value is stored in the "value slot".)
+Similarly, functions are referenced by name, and the definition of the
+function is stored in a symbol's "function slot". This means that
+there can be a distinct function and variable with the same name. The
+property list is used as a more general mechanism of associating
+additional values with particular names, and once again the namespace is
+independent of the function and variable namespaces.
+
+\1f
+File: internals.info, Node: Obarrays, Next: Symbol Values, Prev: Introduction to Symbols, Up: Symbols and Variables
+
+Obarrays
+========
+
+ The identity of symbols with their names is accomplished through a
+structure called an obarray, which is just a poorly-implemented hash
+table mapping from strings to symbols whose name is that string. (I say
+"poorly implemented" because an obarray appears in Lisp as a vector
+with some hidden fields rather than as its own opaque type. This is an
+Emacs Lisp artifact that should be fixed.)
+
+ Obarrays are implemented as a vector of some fixed size (which should
+be a prime for best results), where each "bucket" of the vector
+contains one or more symbols, threaded through a hidden `next' field in
+the symbol. Lookup of a symbol in an obarray, and adding a symbol to
+an obarray, is accomplished through standard hash-table techniques.
+
+ The standard Lisp function for working with symbols and obarrays is
+`intern'. This looks up a symbol in an obarray given its name; if it's
+not found, a new symbol is automatically created with the specified
+name, added to the obarray, and returned. This is what happens when the
+Lisp reader encounters a symbol (or more precisely, encounters the name
+of a symbol) in some text that it is reading. There is a standard
+obarray called `obarray' that is used for this purpose, although the
+Lisp programmer is free to create his own obarrays and `intern' symbols
+in them.
+
+ Note that, once a symbol is in an obarray, it stays there until
+something is done about it, and the standard obarray `obarray' always
+stays around, so once you use any particular variable name, a
+corresponding symbol will stay around in `obarray' until you exit
+XEmacs.
+
+ Note that `obarray' itself is a variable, and as such there is a
+symbol in `obarray' whose name is `"obarray"' and which contains
+`obarray' as its value.
+
+ Note also that this call to `intern' occurs only when in the Lisp
+reader, not when the code is executed (at which point the symbol is
+already around, stored as such in the definition of the function).
+
+ You can create your own obarray using `make-vector' (this is
+horrible but is an artifact) and intern symbols into that obarray.
+Doing that will result in two or more symbols with the same name.
+However, at most one of these symbols is in the standard `obarray': You
+cannot have two symbols of the same name in any particular obarray.
+Note that you cannot add a symbol to an obarray in any fashion other
+than using `intern': i.e. you can't take an existing symbol and put it
+in an existing obarray. Nor can you change the name of an existing
+symbol. (Since obarrays are vectors, you can violate the consistency of
+things by storing directly into the vector, but let's ignore that
+possibility.)
+
+ Usually symbols are created by `intern', but if you really want, you
+can explicitly create a symbol using `make-symbol', giving it some
+name. The resulting symbol is not in any obarray (i.e. it is
+"uninterned"), and you can't add it to any obarray. Therefore its
+primary purpose is as a symbol to use in macros to avoid namespace
+pollution. It can also be used as a carrier of information, but cons
+cells could probably be used just as well.
+
+ You can also use `intern-soft' to look up a symbol but not create a
+new one, and `unintern' to remove a symbol from an obarray. This
+returns the removed symbol. (Remember: You can't put the symbol back
+into any obarray.) Finally, `mapatoms' maps over all of the symbols in
+an obarray.
+
+\1f
+File: internals.info, Node: Symbol Values, Prev: Obarrays, Up: Symbols and Variables
+
+Symbol Values
+=============
+
+ The value field of a symbol normally contains a Lisp object.
+However, a symbol can be "unbound", meaning that it logically has no
+value. This is internally indicated by storing a special Lisp object,
+called "the unbound marker" and stored in the global variable
+`Qunbound'. The unbound marker is of a special Lisp object type called
+"symbol-value-magic". It is impossible for the Lisp programmer to
+directly create or access any object of this type.
+
+ *You must not let any "symbol-value-magic" object escape to the Lisp
+level.* Printing any of these objects will cause the message `INTERNAL
+EMACS BUG' to appear as part of the print representation. (You may see
+this normally when you call `debug_print()' from the debugger on a Lisp
+object.) If you let one of these objects escape to the Lisp level, you
+will violate a number of assumptions contained in the C code and make
+the unbound marker not function right.
+
+ When a symbol is created, its value field (and function field) are
+set to `Qunbound'. The Lisp programmer can restore these conditions
+later using `makunbound' or `fmakunbound', and can query to see whether
+the value of function fields are "bound" (i.e. have a value other than
+`Qunbound') using `boundp' and `fboundp'. The fields are set to a
+normal Lisp object using `set' (or `setq') and `fset'.
+
+ Other symbol-value-magic objects are used as special markers to
+indicate variables that have non-normal properties. This includes any
+variables that are tied into C variables (setting the variable magically
+sets some global variable in the C code, and likewise for retrieving the
+variable's value), variables that magically tie into slots in the
+current buffer, variables that are buffer-local, etc. The
+symbol-value-magic object is stored in the value cell in place of a
+normal object, and the code to retrieve a symbol's value (i.e.
+`symbol-value') knows how to do special things with them. This means
+that you should not just fetch the value cell directly if you want a
+symbol's value.
+
+ The exact workings of this are rather complex and involved and are
+well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'.
+
+\1f
+File: internals.info, Node: Buffers and Textual Representation, Next: MULE Character Sets and Encodings, Prev: Symbols and Variables, Up: Top
+
+Buffers and Textual Representation
+**********************************
+
+* Menu:
+
+* Introduction to Buffers:: A buffer holds a block of text such as a file.
+* The Text in a Buffer:: Representation of the text in a buffer.
+* Buffer Lists:: Keeping track of all buffers.
+* Markers and Extents:: Tagging locations within a buffer.
+* Bufbytes and Emchars:: Representation of individual characters.
+* The Buffer Object:: The Lisp object corresponding to a buffer.
+
+\1f
+File: internals.info, Node: Introduction to Buffers, Next: The Text in a Buffer, Up: Buffers and Textual Representation
+
+Introduction to Buffers
+=======================
+
+ A buffer is logically just a Lisp object that holds some text. In
+this, it is like a string, but a buffer is optimized for frequent
+insertion and deletion, while a string is not. Furthermore:
+
+ 1. Buffers are "permanent" objects, i.e. once you create them, they
+ remain around, and need to be explicitly deleted before they go
+ away.
+
+ 2. Each buffer has a unique name, which is a string. Buffers are
+ normally referred to by name. In this respect, they are like
+ symbols.
+
+ 3. Buffers have a default insertion position, called "point".
+ Inserting text (unless you explicitly give a position) goes at
+ point, and moves point forward past the text. This is what is
+ going on when you type text into Emacs.
+
+ 4. Buffers have lots of extra properties associated with them.
+
+ 5. Buffers can be "displayed". What this means is that there exist a
+ number of "windows", which are objects that correspond to some
+ visible section of your display, and each window has an associated
+ buffer, and the current contents of the buffer are shown in that
+ section of the display. The redisplay mechanism (which takes care
+ of doing this) knows how to look at the text of a buffer and come
+ up with some reasonable way of displaying this. Many of the
+ properties of a buffer control how the buffer's text is displayed.
+
+ 6. One buffer is distinguished and called the "current buffer". It is
+ stored in the variable `current_buffer'. Buffer operations operate
+ on this buffer by default. When you are typing text into a
+ buffer, the buffer you are typing into is always `current_buffer'.
+ Switching to a different window changes the current buffer. Note
+ that Lisp code can temporarily change the current buffer using
+ `set-buffer' (often enclosed in a `save-excursion' so that the
+ former current buffer gets restored when the code is finished).
+ However, calling `set-buffer' will NOT cause a permanent change in
+ the current buffer. The reason for this is that the top-level
+ event loop sets `current_buffer' to the buffer of the selected
+ window, each time it finishes executing a user command.
+
+ Make sure you understand the distinction between "current buffer"
+and "buffer of the selected window", and the distinction between
+"point" of the current buffer and "window-point" of the selected
+window. (This latter distinction is explained in detail in the section
+on windows.)
+
+\1f
+File: internals.info, Node: The Text in a Buffer, Next: Buffer Lists, Prev: Introduction to Buffers, Up: Buffers and Textual Representation
+
+The Text in a Buffer
+====================
+
+ The text in a buffer consists of a sequence of zero or more
+characters. A "character" is an integer that logically represents a
+letter, number, space, or other unit of text. Most of the characters
+that you will typically encounter belong to the ASCII set of characters,
+but there are also characters for various sorts of accented letters,
+special symbols, Chinese and Japanese ideograms (i.e. Kanji, Katakana,
+etc.), Cyrillic and Greek letters, etc. The actual number of possible
+characters is quite large.
+
+ For now, we can view a character as some non-negative integer that
+has some shape that defines how it typically appears (e.g. as an
+uppercase A). (The exact way in which a character appears depends on the
+font used to display the character.) The internal type of characters in
+the C code is an `Emchar'; this is just an `int', but using a symbolic
+type makes the code clearer.
+
+ Between every character in a buffer is a "buffer position" or
+"character position". We can speak of the character before or after a
+particular buffer position, and when you insert a character at a
+particular position, all characters after that position end up at new
+positions. When we speak of the character "at" a position, we really
+mean the character after the position. (This schizophrenia between a
+buffer position being "between" a character and "on" a character is
+rampant in Emacs.)
+
+ Buffer positions are numbered starting at 1. This means that
+position 1 is before the first character, and position 0 is not valid.
+If there are N characters in a buffer, then buffer position N+1 is
+after the last one, and position N+2 is not valid.
+
+ The internal makeup of the Emchar integer varies depending on whether
+we have compiled with MULE support. If not, the Emchar integer is an
+8-bit integer with possible values from 0 - 255. 0 - 127 are the
+standard ASCII characters, while 128 - 255 are the characters from the
+ISO-8859-1 character set. If we have compiled with MULE support, an
+Emchar is a 19-bit integer, with the various bits having meanings
+according to a complex scheme that will be detailed later. The
+characters numbered 0 - 255 still have the same meanings as for the
+non-MULE case, though.
+
+ Internally, the text in a buffer is represented in a fairly simple
+fashion: as a contiguous array of bytes, with a "gap" of some size in
+the middle. Although the gap is of some substantial size in bytes,
+there is no text contained within it: From the perspective of the text
+in the buffer, it does not exist. The gap logically sits at some buffer
+position, between two characters (or possibly at the beginning or end of
+the buffer). Insertion of text in a buffer at a particular position is
+always accomplished by first moving the gap to that position (i.e.
+through some block moving of text), then writing the text into the
+beginning of the gap, thereby shrinking the gap. If the gap shrinks
+down to nothing, a new gap is created. (What actually happens is that a
+new gap is "created" at the end of the buffer's text, which requires
+nothing more than changing a couple of indices; then the gap is "moved"
+to the position where the insertion needs to take place by moving up in
+memory all the text after that position.) Similarly, deletion occurs
+by moving the gap to the place where the text is to be deleted, and
+then simply expanding the gap to include the deleted text.
+("Expanding" and "shrinking" the gap as just described means just that
+the internal indices that keep track of where the gap is located are
+changed.)
+
+ Note that the total amount of memory allocated for a buffer text
+never decreases while the buffer is live. Therefore, if you load up a
+20-megabyte file and then delete all but one character, there will be a
+20-megabyte gap, which won't get any smaller (except by inserting
+characters back again). Once the buffer is killed, the memory allocated
+for the buffer text will be freed, but it will still be sitting on the
+heap, taking up virtual memory, and will not be released back to the
+operating system. (However, if you have compiled XEmacs with rel-alloc,
+the situation is different. In this case, the space *will* be released
+back to the operating system. However, this tends to result in a
+noticeable speed penalty.)
+
+ Astute readers may notice that the text in a buffer is represented as
+an array of *bytes*, while (at least in the MULE case) an Emchar is a
+19-bit integer, which clearly cannot fit in a byte. This means (of
+course) that the text in a buffer uses a different representation from
+an Emchar: specifically, the 19-bit Emchar becomes a series of one to
+four bytes. The conversion between these two representations is complex
+and will be described later.
+
+ In the non-MULE case, everything is very simple: An Emchar is an
+8-bit value, which fits neatly into one byte.
+
+ If we are given a buffer position and want to retrieve the character
+at that position, we need to follow these steps:
+
+ 1. Pretend there's no gap, and convert the buffer position into a
+ "byte index" that indexes to the appropriate byte in the buffer's
+ stream of textual bytes. By convention, byte indices begin at 1,
+ just like buffer positions. In the non-MULE case, byte indices
+ and buffer positions are identical, since one character equals one
+ byte.
+
+ 2. Convert the byte index into a "memory index", which takes the gap
+ into account. The memory index is a direct index into the block of
+ memory that stores the text of a buffer. This basically just
+ involves checking to see if the byte index is past the gap, and if
+ so, adding the size of the gap to it. By convention, memory
+ indices begin at 1, just like buffer positions and byte indices,
+ and when referring to the position that is "at" the gap, we always
+ use the memory position at the *beginning*, not at the end, of the
+ gap.
+
+ 3. Fetch the appropriate bytes at the determined memory position.
+
+ 4. Convert these bytes into an Emchar.
+
+ In the non-Mule case, (3) and (4) boil down to a simple one-byte
+memory access.
+
+ Note that we have defined three types of positions in a buffer:
+
+ 1. "buffer positions" or "character positions", typedef `Bufpos'
+
+ 2. "byte indices", typedef `Bytind'
+
+ 3. "memory indices", typedef `Memind'
+
+ All three typedefs are just `int's, but defining them this way makes
+things a lot clearer.
+
+ Most code works with buffer positions. In particular, all Lisp code
+that refers to text in a buffer uses buffer positions. Lisp code does
+not know that byte indices or memory indices exist.
+
+ Finally, we have a typedef for the bytes in a buffer. This is a
+`Bufbyte', which is an unsigned char. Referring to them as Bufbytes
+underscores the fact that we are working with a string of bytes in the
+internal Emacs buffer representation rather than in one of a number of
+possible alternative representations (e.g. EUC-encoded text, etc.).
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: Buffer Lists, Next: Markers and Extents, Prev: The Text in a Buffer, Up: Buffers and Textual Representation
+
+Buffer Lists
+============
+
+ Recall earlier that buffers are "permanent" objects, i.e. that they
+remain around until explicitly deleted. This entails that there is a
+list of all the buffers in existence. This list is actually an
+assoc-list (mapping from the buffer's name to the buffer) and is stored
+in the global variable `Vbuffer_alist'.
+
+ The order of the buffers in the list is important: the buffers are
+ordered approximately from most-recently-used to least-recently-used.
+Switching to a buffer using `switch-to-buffer', `pop-to-buffer', etc.
+and switching windows using `other-window', etc. usually brings the
+new current buffer to the front of the list. `switch-to-buffer',
+`other-buffer', etc. look at the beginning of the list to find an
+alternative buffer to suggest. You can also explicitly move a buffer
+to the end of the list using `bury-buffer'.
+
+ In addition to the global ordering in `Vbuffer_alist', each frame
+has its own ordering of the list. These lists always contain the same
+elements as in `Vbuffer_alist' although possibly in a different order.
+`buffer-list' normally returns the list for the selected frame. This
+allows you to work in separate frames without things interfering with
+each other.
+
+ The standard way to look up a buffer given a name is `get-buffer',
+and the standard way to create a new buffer is `get-buffer-create',
+which looks up a buffer with a given name, creating a new one if
+necessary. These operations correspond exactly with the symbol
+operations `intern-soft' and `intern', respectively. You can also
+force a new buffer to be created using `generate-new-buffer', which
+takes a name and (if necessary) makes a unique name from this by
+appending a number, and then creates the buffer. This is basically
+like the symbol operation `gensym'.
+
+\1f
+File: internals.info, Node: Markers and Extents, Next: Bufbytes and Emchars, Prev: Buffer Lists, Up: Buffers and Textual Representation
+
+Markers and Extents
+===================
+
+ Among the things associated with a buffer are things that are
+logically attached to certain buffer positions. This can be used to
+keep track of a buffer position when text is inserted and deleted, so
+that it remains at the same spot relative to the text around it; to
+assign properties to particular sections of text; etc. There are two
+such objects that are useful in this regard: they are "markers" and
+"extents".
+
+ A "marker" is simply a flag placed at a particular buffer position,
+which is moved around as text is inserted and deleted. Markers are
+used for all sorts of purposes, such as the `mark' that is the other
+end of textual regions to be cut, copied, etc.
+
+ An "extent" is similar to two markers plus some associated
+properties, and is used to keep track of regions in a buffer as text is
+inserted and deleted, and to add properties (e.g. fonts) to particular
+regions of text. The external interface of extents is explained
+elsewhere.
+
+ The important thing here is that markers and extents simply contain
+buffer positions in them as integers, and every time text is inserted or
+deleted, these positions must be updated. In order to minimize the
+amount of shuffling that needs to be done, the positions in markers and
+extents (there's one per marker, two per extent) and stored in Meminds.
+This means that they only need to be moved when the text is physically
+moved in memory; since the gap structure tries to minimize this, it also
+minimizes the number of marker and extent indices that need to be
+adjusted. Look in `insdel.c' for the details of how this works.
+
+ One other important distinction is that markers are "temporary"
+while extents are "permanent". This means that markers disappear as
+soon as there are no more pointers to them, and correspondingly, there
+is no way to determine what markers are in a buffer if you are just
+given the buffer. Extents remain in a buffer until they are detached
+(which could happen as a result of text being deleted) or the buffer is
+deleted, and primitives do exist to enumerate the extents in a buffer.
+
+\1f
+File: internals.info, Node: Bufbytes and Emchars, Next: The Buffer Object, Prev: Markers and Extents, Up: Buffers and Textual Representation
+
+Bufbytes and Emchars
+====================
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: The Buffer Object, Prev: Bufbytes and Emchars, Up: Buffers and Textual Representation
+
+The Buffer Object
+=================
+
+ Buffers contain fields not directly accessible by the Lisp
+programmer. We describe them here, naming them by the names used in
+the C code. Many are accessible indirectly in Lisp programs via Lisp
+primitives.
+
+`name'
+ The buffer name is a string that names the buffer. It is
+ guaranteed to be unique. *Note Buffer Names: (lispref)Buffer
+ Names.
+
+`save_modified'
+ This field contains the time when the buffer was last saved, as an
+ integer. *Note Buffer Modification: (lispref)Buffer Modification.
+
+`modtime'
+ This field contains the modification time of the visited file. It
+ is set when the file is written or read. Every time the buffer is
+ written to the file, this field is compared to the modification
+ time of the file. *Note Buffer Modification: (lispref)Buffer
+ Modification.
+
+`auto_save_modified'
+ This field contains the time when the buffer was last auto-saved.
+
+`last_window_start'
+ This field contains the `window-start' position in the buffer as of
+ the last time the buffer was displayed in a window.
+
+`undo_list'
+ This field points to the buffer's undo list. *Note Undo:
+ (lispref)Undo.
+
+`syntax_table_v'
+ This field contains the syntax table for the buffer. *Note Syntax
+ Tables: (lispref)Syntax Tables.
+
+`downcase_table'
+ This field contains the conversion table for converting text to
+ lower case. *Note Case Tables: (lispref)Case Tables.
+
+`upcase_table'
+ This field contains the conversion table for converting text to
+ upper case. *Note Case Tables: (lispref)Case Tables.
+
+`case_canon_table'
+ This field contains the conversion table for canonicalizing text
+ for case-folding search. *Note Case Tables: (lispref)Case Tables.
+
+`case_eqv_table'
+ This field contains the equivalence table for case-folding search.
+ *Note Case Tables: (lispref)Case Tables.
+
+`display_table'
+ This field contains the buffer's display table, or `nil' if it
+ doesn't have one. *Note Display Tables: (lispref)Display Tables.
+
+`markers'
+ This field contains the chain of all markers that currently point
+ into the buffer. Deletion of text in the buffer, and motion of
+ the buffer's gap, must check each of these markers and perhaps
+ update it. *Note Markers: (lispref)Markers.
+
+`backed_up'
+ This field is a flag that tells whether a backup file has been
+ made for the visited file of this buffer.
+
+`mark'
+ This field contains the mark for the buffer. The mark is a marker,
+ hence it is also included on the list `markers'. *Note The Mark:
+ (lispref)The Mark.
+
+`mark_active'
+ This field is non-`nil' if the buffer's mark is active.
+
+`local_var_alist'
+ This field contains the association list describing the variables
+ local in this buffer, and their values, with the exception of
+ local variables that have special slots in the buffer object.
+ (Those slots are omitted from this table.) *Note Buffer-Local
+ Variables: (lispref)Buffer-Local Variables.
+
+`modeline_format'
+ This field contains a Lisp object which controls how to display
+ the mode line for this buffer. *Note Modeline Format:
+ (lispref)Modeline Format.
+
+`base_buffer'
+ This field holds the buffer's base buffer (if it is an indirect
+ buffer), or `nil'.
+
+\1f
+File: internals.info, Node: MULE Character Sets and Encodings, Next: The Lisp Reader and Compiler, Prev: Buffers and Textual Representation, Up: Top
+
+MULE Character Sets and Encodings
+*********************************
+
+ Recall that there are two primary ways that text is represented in
+XEmacs. The "buffer" representation sees the text as a series of bytes
+(Bufbytes), with a variable number of bytes used per character. The
+"character" representation sees the text as a series of integers
+(Emchars), one per character. The character representation is a cleaner
+representation from a theoretical standpoint, and is thus used in many
+cases when lots of manipulations on a string need to be done. However,
+the buffer representation is the standard representation used in both
+Lisp strings and buffers, and because of this, it is the "default"
+representation that text comes in. The reason for using this
+representation is that it's compact and is compatible with ASCII.
+
+* Menu:
+
+* Character Sets::
+* Encodings::
+* Internal Mule Encodings::
+* CCL::
+
+\1f
+File: internals.info, Node: Character Sets, Next: Encodings, Up: MULE Character Sets and Encodings
+
+Character Sets
+==============
+
+ A character set (or "charset") is an ordered set of characters. A
+particular character in a charset is indexed using one or more
+"position codes", which are non-negative integers. The number of
+position codes needed to identify a particular character in a charset is
+called the "dimension" of the charset. In XEmacs/Mule, all charsets
+have dimension 1 or 2, and the size of all charsets (except for a few
+special cases) is either 94, 96, 94 by 94, or 96 by 96. The range of
+position codes used to index characters from any of these types of
+character sets is as follows:
+
+ Charset type Position code 1 Position code 2
+ ------------------------------------------------------------
+ 94 33 - 126 N/A
+ 96 32 - 127 N/A
+ 94x94 33 - 126 33 - 126
+ 96x96 32 - 127 32 - 127
+
+ Note that in the above cases position codes do not start at an
+expected value such as 0 or 1. The reason for this will become clear
+later.
+
+ For example, Latin-1 is a 96-character charset, and JISX0208 (the
+Japanese national character set) is a 94x94-character charset.
+
+ [Note that, although the ranges above define the *valid* position
+codes for a charset, some of the slots in a particular charset may in
+fact be empty. This is the case for JISX0208, for example, where (e.g.)
+all the slots whose first position code is in the range 118 - 127 are
+empty.]
+
+ There are three charsets that do not follow the above rules. All of
+them have one dimension, and have ranges of position codes as follows:
+
+ Charset name Position code 1
+ ------------------------------------
+ ASCII 0 - 127
+ Control-1 0 - 31
+ Composite 0 - some large number
+
+ (The upper bound of the position code for composite characters has
+not yet been determined, but it will probably be at least 16,383).
+
+ ASCII is the union of two subsidiary character sets: Printing-ASCII
+(the printing ASCII character set, consisting of position codes 33 -
+126, like for a standard 94-character charset) and Control-ASCII (the
+non-printing characters that would appear in a binary file with codes 0
+- 32 and 127).
+
+ Control-1 contains the non-printing characters that would appear in a
+binary file with codes 128 - 159.
+
+ Composite contains characters that are generated by overstriking one
+or more characters from other charsets.
+
+ Note that some characters in ASCII, and all characters in Control-1,
+are "control" (non-printing) characters. These have no printed
+representation but instead control some other function of the printing
+(e.g. TAB or 8 moves the current character position to the next tab
+stop). All other characters in all charsets are "graphic" (printing)
+characters.
+
+ When a binary file is read in, the bytes in the file are assigned to
+character sets as follows:
+
+ Bytes Character set Range
+ --------------------------------------------------
+ 0 - 127 ASCII 0 - 127
+ 128 - 159 Control-1 0 - 31
+ 160 - 255 Latin-1 32 - 127
+
+ This is a bit ad-hoc but gets the job done.
+
+\1f
+File: internals.info, Node: Encodings, Next: Internal Mule Encodings, Prev: Character Sets, Up: MULE Character Sets and Encodings
+
+Encodings
+=========
+
+ An "encoding" is a way of numerically representing characters from
+one or more character sets. If an encoding only encompasses one
+character set, then the position codes for the characters in that
+character set could be used directly. This is not possible, however, if
+more than one character set is to be used in the encoding.
+
+ For example, the conversion detailed above between bytes in a binary
+file and characters is effectively an encoding that encompasses the
+three character sets ASCII, Control-1, and Latin-1 in a stream of 8-bit
+bytes.
+
+ Thus, an encoding can be viewed as a way of encoding characters from
+a specified group of character sets using a stream of bytes, each of
+which contains a fixed number of bits (but not necessarily 8, as in the
+common usage of "byte").
+
+ Here are descriptions of a couple of common encodings:
+
+* Menu:
+
+* Japanese EUC (Extended Unix Code)::
+* JIS7::
+
+\1f
+File: internals.info, Node: Japanese EUC (Extended Unix Code), Next: JIS7, Up: Encodings
+
+Japanese EUC (Extended Unix Code)
+---------------------------------
+
+ This encompasses the character sets Printing-ASCII,
+Japanese-JISX0201, and Japanese-JISX0208-Kana (half-width katakana, the
+right half of JISX0201). It uses 8-bit bytes.
+
+ Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character
+charsets, while Japanese-JISX0208 is a 94x94-character charset.
+
+ The encoding is as follows:
+
+ Character set Representation (PC=position-code)
+ ------------- --------------
+ Printing-ASCII PC1
+ Japanese-JISX0201-Kana 0x8E | PC1 + 0x80
+ Japanese-JISX0208 PC1 + 0x80 | PC2 + 0x80
+ Japanese-JISX0212 PC1 + 0x80 | PC2 + 0x80
+
+\1f
+File: internals.info, Node: JIS7, Prev: Japanese EUC (Extended Unix Code), Up: Encodings
+
+JIS7
+----
+
+ This encompasses the character sets Printing-ASCII,
+Japanese-JISX0201-Roman (the left half of JISX0201; this character set
+is very similar to Printing-ASCII and is a 94-character charset),
+Japanese-JISX0208, and Japanese-JISX0201-Kana. It uses 7-bit bytes.
+
+ Unlike Japanese EUC, this is a "modal" encoding, which means that
+there are multiple states that the encoding can be in, which affect how
+the bytes are to be interpreted. Special sequences of bytes (called
+"escape sequences") are used to change states.
+
+ The encoding is as follows:
+
+ Character set Representation (PC=position-code)
+ ------------- --------------
+ Printing-ASCII PC1
+ Japanese-JISX0201-Roman PC1
+ Japanese-JISX0201-Kana PC1
+ Japanese-JISX0208 PC1 PC2
+
+
+ Escape sequence ASCII equivalent Meaning
+ --------------- ---------------- -------
+ 0x1B 0x28 0x4A ESC ( J invoke Japanese-JISX0201-Roman
+ 0x1B 0x28 0x49 ESC ( I invoke Japanese-JISX0201-Kana
+ 0x1B 0x24 0x42 ESC $ B invoke Japanese-JISX0208
+ 0x1B 0x28 0x42 ESC ( B invoke Printing-ASCII
+
+ Initially, Printing-ASCII is invoked.
+
+\1f
+File: internals.info, Node: Internal Mule Encodings, Next: CCL, Prev: Encodings, Up: MULE Character Sets and Encodings
+
+Internal Mule Encodings
+=======================
+
+ In XEmacs/Mule, each character set is assigned a unique number,
+called a "leading byte". This is used in the encodings of a character.
+Leading bytes are in the range 0x80 - 0xFF (except for ASCII, which has
+a leading byte of 0), although some leading bytes are reserved.
+
+ Charsets whose leading byte is in the range 0x80 - 0x9F are called
+"official" and are used for built-in charsets. Other charsets are
+called "private" and have leading bytes in the range 0xA0 - 0xFF; these
+are user-defined charsets.
+
+ More specifically:
+
+ Character set Leading byte
+ ------------- ------------
+ ASCII 0
+ Composite 0x80
+ Dimension-1 Official 0x81 - 0x8D
+ (0x8E is free)
+ Control-1 0x8F
+ Dimension-2 Official 0x90 - 0x99
+ (0x9A - 0x9D are free;
+ 0x9E and 0x9F are reserved)
+ Dimension-1 Private 0xA0 - 0xEF
+ Dimension-2 Private 0xF0 - 0xFF
+
+ There are two internal encodings for characters in XEmacs/Mule. One
+is called "string encoding" and is an 8-bit encoding that is used for
+representing characters in a buffer or string. It uses 1 to 4 bytes per
+character. The other is called "character encoding" and is a 19-bit
+encoding that is used for representing characters individually in a
+variable.
+
+ (In the following descriptions, we'll ignore composite characters for
+the moment. We also give a general (structural) overview first,
+followed later by the exact details.)
+
+* Menu:
+
+* Internal String Encoding::
+* Internal Character Encoding::
+
+\1f
+File: internals.info, Node: Internal String Encoding, Next: Internal Character Encoding, Up: Internal Mule Encodings
+
+Internal String Encoding
+------------------------
+
+ ASCII characters are encoded using their position code directly.
+Other characters are encoded using their leading byte followed by their
+position code(s) with the high bit set. Characters in private character
+sets have their leading byte prefixed with a "leading byte prefix",
+which is either 0x9E or 0x9F. (No character sets are ever assigned these
+leading bytes.) Specifically:
+
+ Character set Encoding (PC=position-code, LB=leading-byte)
+ ------------- --------
+ ASCII PC-1 |
+ Control-1 LB | PC1 + 0xA0 |
+ Dimension-1 official LB | PC1 + 0x80 |
+ Dimension-1 private 0x9E | LB | PC1 + 0x80 |
+ Dimension-2 official LB | PC1 + 0x80 | PC2 + 0x80 |
+ Dimension-2 private 0x9F | LB | PC1 + 0x80 | PC2 + 0x80
+
+ The basic characteristic of this encoding is that the first byte of
+all characters is in the range 0x00 - 0x9F, and the second and
+following bytes of all characters is in the range 0xA0 - 0xFF. This
+means that it is impossible to get out of sync, or more specifically:
+
+ 1. Given any byte position, the beginning of the character it is
+ within can be determined in constant time.
+
+ 2. Given any byte position at the beginning of a character, the
+ beginning of the next character can be determined in constant time.
+
+ 3. Given any byte position at the beginning of a character, the
+ beginning of the previous character can be determined in constant
+ time.
+
+ 4. Textual searches can simply treat encoded strings as if they were
+ encoded in a one-byte-per-character fashion rather than the actual
+ multi-byte encoding.
+
+ None of the standard non-modal encodings meet all of these
+conditions. For example, EUC satisfies only (2) and (3), while
+Shift-JIS and Big5 (not yet described) satisfy only (2). (All non-modal
+encodings must satisfy (2), in order to be unambiguous.)
+
+\1f
+File: internals.info, Node: Internal Character Encoding, Prev: Internal String Encoding, Up: Internal Mule Encodings
+
+Internal Character Encoding
+---------------------------
+
+ One 19-bit word represents a single character. The word is
+separated into three fields:
+
+ Bit number: 18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
+ <------------> <------------------> <------------------>
+ Field: 1 2 3
+
+ Note that fields 2 and 3 hold 7 bits each, while field 1 holds 5
+bits.
+
+ Character set Field 1 Field 2 Field 3
+ ------------- ------- ------- -------
+ ASCII 0 0 PC1
+ range: (00 - 7F)
+ Control-1 0 1 PC1
+ range: (00 - 1F)
+ Dimension-1 official 0 LB - 0x80 PC1
+ range: (01 - 0D) (20 - 7F)
+ Dimension-1 private 0 LB - 0x80 PC1
+ range: (20 - 6F) (20 - 7F)
+ Dimension-2 official LB - 0x8F PC1 PC2
+ range: (01 - 0A) (20 - 7F) (20 - 7F)
+ Dimension-2 private LB - 0xE1 PC1 PC2
+ range: (0F - 1E) (20 - 7F) (20 - 7F)
+ Composite 0x1F ? ?
+
+ Note that character codes 0 - 255 are the same as the "binary
+encoding" described above.
+
+\1f
+File: internals.info, Node: CCL, Prev: Internal Mule Encodings, Up: MULE Character Sets and Encodings
+
+CCL
+===
+
+ CCL PROGRAM SYNTAX:
+ CCL_PROGRAM := (CCL_MAIN_BLOCK
+ [ CCL_EOF_BLOCK ])
+
+ CCL_MAIN_BLOCK := CCL_BLOCK
+ CCL_EOF_BLOCK := CCL_BLOCK
+
+ CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...])
+ STATEMENT :=
+ SET | IF | BRANCH | LOOP | REPEAT | BREAK
+ | READ | WRITE
+
+ SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION)
+ | INT-OR-CHAR
+
+ EXPRESSION := ARG | (EXPRESSION OP ARG)
+
+ IF := (if EXPRESSION CCL_BLOCK CCL_BLOCK)
+ BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
+ LOOP := (loop STATEMENT [STATEMENT ...])
+ BREAK := (break)
+ REPEAT := (repeat)
+ | (write-repeat [REG | INT-OR-CHAR | string])
+ | (write-read-repeat REG [INT-OR-CHAR | string | ARRAY]?)
+ READ := (read REG) | (read REG REG)
+ | (read-if REG ARITH_OP ARG CCL_BLOCK CCL_BLOCK)
+ | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
+ WRITE := (write REG) | (write REG REG)
+ | (write INT-OR-CHAR) | (write STRING) | STRING
+ | (write REG ARRAY)
+ END := (end)
+
+ REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
+ ARG := REG | INT-OR-CHAR
+ OP := + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
+ | < | > | == | <= | >= | !=
+ SELF_OP :=
+ += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
+ ARRAY := '[' INT-OR-CHAR ... ']'
+ INT-OR-CHAR := INT | CHAR
+
+ MACHINE CODE:
+
+ The machine code consists of a vector of 32-bit words.
+ The first such word specifies the start of the EOF section of the code;
+ this is the code executed to handle any stuff that needs to be done
+ (e.g. designating back to ASCII and left-to-right mode) after all
+ other encoded/decoded data has been written out. This is not used for
+ charset CCL programs.
+
+ REGISTER: 0..7 -- refered by RRR or rrr
+
+ OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT
+ TTTTT (5-bit): operator type
+ RRR (3-bit): register number
+ XXXXXXXXXXXXXXXX (15-bit):
+ CCCCCCCCCCCCCCC: constant or address
+ 000000000000rrr: register number
+
+ AAAA: 00000 +
+ 00001 -
+ 00010 *
+ 00011 /
+ 00100 %
+ 00101 &
+ 00110 |
+ 00111 ~
+
+ 01000 <<
+ 01001 >>
+ 01010 <8
+ 01011 >8
+ 01100 //
+ 01101 not used
+ 01110 not used
+ 01111 not used
+
+ 10000 <
+ 10001 >
+ 10010 ==
+ 10011 <=
+ 10100 >=
+ 10101 !=
+
+ OPERATORS: TTTTT RRR XX..
+
+ SetCS: 00000 RRR C...C RRR = C...C
+ SetCL: 00001 RRR ..... RRR = c...c
+ c.............c
+ SetR: 00010 RRR ..rrr RRR = rrr
+ SetA: 00011 RRR ..rrr RRR = array[rrr]
+ C.............C size of array = C...C
+ c.............c contents = c...c
+
+ Jump: 00100 000 c...c jump to c...c
+ JumpCond: 00101 RRR c...c if (!RRR) jump to c...c
+ WriteJump: 00110 RRR c...c Write1 RRR, jump to c...c
+ WriteReadJump: 00111 RRR c...c Write1, Read1 RRR, jump to c...c
+ WriteCJump: 01000 000 c...c Write1 C...C, jump to c...c
+ C...C
+ WriteCReadJump: 01001 RRR c...c Write1 C...C, Read1 RRR,
+ C.............C and jump to c...c
+ WriteSJump: 01010 000 c...c WriteS, jump to c...c
+ C.............C
+ S.............S
+ ...
+ WriteSReadJump: 01011 RRR c...c WriteS, Read1 RRR, jump to c...c
+ C.............C
+ S.............S
+ ...
+ WriteAReadJump: 01100 RRR c...c WriteA, Read1 RRR, jump to c...c
+ C.............C size of array = C...C
+ c.............c contents = c...c
+ ...
+ Branch: 01101 RRR C...C if (RRR >= 0 && RRR < C..)
+ c.............c branch to (RRR+1)th address
+ Read1: 01110 RRR ... read 1-byte to RRR
+ Read2: 01111 RRR ..rrr read 2-byte to RRR and rrr
+ ReadBranch: 10000 RRR C...C Read1 and Branch
+ c.............c
+ ...
+ Write1: 10001 RRR ..... write 1-byte RRR
+ Write2: 10010 RRR ..rrr write 2-byte RRR and rrr
+ WriteC: 10011 000 ..... write 1-char C...CC
+ C.............C
+ WriteS: 10100 000 ..... write C..-byte of string
+ C.............C
+ S.............S
+ ...
+ WriteA: 10101 RRR ..... write array[RRR]
+ C.............C size of array = C...C
+ c.............c contents = c...c
+ ...
+ End: 10110 000 ..... terminate the execution
+
+ SetSelfCS: 10111 RRR C...C RRR AAAAA= C...C
+ ..........AAAAA
+ SetSelfCL: 11000 RRR ..... RRR AAAAA= c...c
+ c.............c
+ ..........AAAAA
+ SetSelfR: 11001 RRR ..Rrr RRR AAAAA= rrr
+ ..........AAAAA
+ SetExprCL: 11010 RRR ..Rrr RRR = rrr AAAAA c...c
+ c.............c
+ ..........AAAAA
+ SetExprR: 11011 RRR ..rrr RRR = rrr AAAAA Rrr
+ ............Rrr
+ ..........AAAAA
+ JumpCondC: 11100 RRR c...c if !(RRR AAAAA C..) jump to c...c
+ C.............C
+ ..........AAAAA
+ JumpCondR: 11101 RRR c...c if !(RRR AAAAA rrr) jump to c...c
+ ............rrr
+ ..........AAAAA
+ ReadJumpCondC: 11110 RRR c...c Read1 and JumpCondC
+ C.............C
+ ..........AAAAA
+ ReadJumpCondR: 11111 RRR c...c Read1 and JumpCondR
+ ............rrr
+ ..........AAAAA
+
+\1f
+File: internals.info, Node: The Lisp Reader and Compiler, Next: Lstreams, Prev: MULE Character Sets and Encodings, Up: Top
+
+The Lisp Reader and Compiler
+****************************
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Lstreams, Next: Consoles; Devices; Frames; Windows, Prev: The Lisp Reader and Compiler, Up: Top
+
+Lstreams
+********
+
+ An "lstream" is an internal Lisp object that provides a generic
+buffering stream implementation. Conceptually, you send data to the
+stream or read data from the stream, not caring what's on the other end
+of the stream. The other end could be another stream, a file
+descriptor, a stdio stream, a fixed block of memory, a reallocating
+block of memory, etc. The main purpose of the stream is to provide a
+standard interface and to do buffering. Macros are defined to read or
+write characters, so the calling functions do not have to worry about
+blocking data together in order to achieve efficiency.
+
+* Menu:
+
+* Creating an Lstream:: Creating an lstream object.
+* Lstream Types:: Different sorts of things that are streamed.
+* Lstream Functions:: Functions for working with lstreams.
+* Lstream Methods:: Creating new lstream types.
+
+\1f
+File: internals.info, Node: Creating an Lstream, Next: Lstream Types, Up: Lstreams
+
+Creating an Lstream
+===================
+
+ Lstreams come in different types, depending on what is being
+interfaced to. Although the primitive for creating new lstreams is
+`Lstream_new()', generally you do not call this directly. Instead, you
+call some type-specific creation function, which creates the lstream
+and initializes it as appropriate for the particular type.
+
+ All lstream creation functions take a MODE argument, specifying what
+mode the lstream should be opened as. This controls whether the
+lstream is for input and output, and optionally whether data should be
+blocked up in units of MULE characters. Note that some types of
+lstreams can only be opened for input; others only for output; and
+others can be opened either way. #### Richard Mlynarik thinks that
+there should be a strict separation between input and output streams,
+and he's probably right.
+
+ MODE is a string, one of
+
+`"r"'
+ Open for reading.
+
+`"w"'
+ Open for writing.
+
+`"rc"'
+ Open for reading, but "read" never returns partial MULE characters.
+
+`"wc"'
+ Open for writing, but never writes partial MULE characters.
+
+\1f
+File: internals.info, Node: Lstream Types, Next: Lstream Functions, Prev: Creating an Lstream, Up: Lstreams
+
+Lstream Types
+=============
+
+stdio
+
+filedesc
+
+lisp-string
+
+fixed-buffer
+
+resizing-buffer
+
+dynarr
+
+lisp-buffer
+
+print
+
+decoding
+
+encoding
+\1f
+File: internals.info, Node: Lstream Functions, Next: Lstream Methods, Prev: Lstream Types, Up: Lstreams
+
+Lstream Functions
+=================
+
+ - Function: Lstream * Lstream_new (Lstream_implementation *IMP, CONST
+ char *MODE)
+ Allocate and return a new Lstream. This function is not really
+ meant to be called directly; rather, each stream type should
+ provide its own stream creation function, which creates the stream
+ and does any other necessary creation stuff (e.g. opening a file).
+
+ - Function: void Lstream_set_buffering (Lstream *LSTR,
+ Lstream_buffering BUFFERING, int BUFFERING_SIZE)
+ Change the buffering of a stream. See `lstream.h'. By default the
+ buffering is `STREAM_BLOCK_BUFFERED'.
+
+ - Function: int Lstream_flush (Lstream *LSTR)
+ Flush out any pending unwritten data in the stream. Clear any
+ buffered input data. Returns 0 on success, -1 on error.
+
+ - Macro: int Lstream_putc (Lstream *STREAM, int C)
+ Write out one byte to the stream. This is a macro and so it is
+ very efficient. The C argument is only evaluated once but the
+ STREAM argument is evaluated more than once. Returns 0 on
+ success, -1 on error.
+
+ - Macro: int Lstream_getc (Lstream *STREAM)
+ Read one byte from the stream. This is a macro and so it is very
+ efficient. The STREAM argument is evaluated more than once.
+ Return value is -1 for EOF or error.
+
+ - Macro: void Lstream_ungetc (Lstream *STREAM, int C)
+ Push one byte back onto the input queue. This will be the next
+ byte read from the stream. Any number of bytes can be pushed back
+ and will be read in the reverse order they were pushed back - most
+ recent first. (This is necessary for consistency - if there are a
+ number of bytes that have been unread and I read and unread a
+ byte, it needs to be the first to be read again.) This is a macro
+ and so it is very efficient. The C argument is only evaluated
+ once but the STREAM argument is evaluated more than once.
+
+ - Function: int Lstream_fputc (Lstream *STREAM, int C)
+ - Function: int Lstream_fgetc (Lstream *STREAM)
+ - Function: void Lstream_fungetc (Lstream *STREAM, int C)
+ Function equivalents of the above macros.
+
+ - Function: int Lstream_read (Lstream *STREAM, void *DATA, int SIZE)
+ Read SIZE bytes of DATA from the stream. Return the number of
+ bytes read. 0 means EOF. -1 means an error occurred and no bytes
+ were read.
+
+ - Function: int Lstream_write (Lstream *STREAM, void *DATA, int SIZE)
+ Write SIZE bytes of DATA to the stream. Return the number of
+ bytes written. -1 means an error occurred and no bytes were
+ written.
+
+ - Function: void Lstream_unread (Lstream *STREAM, void *DATA, int SIZE)
+ Push back SIZE bytes of DATA onto the input queue. The next call
+ to `Lstream_read()' with the same size will read the same bytes
+ back. Note that this will be the case even if there is other
+ pending unread data.
+
+ - Function: int Lstream_close (Lstream *STREAM)
+ Close the stream. All data will be flushed out.
+
+ - Function: void Lstream_reopen (Lstream *STREAM)
+ Reopen a closed stream. This enables I/O on it again. This is not
+ meant to be called except from a wrapper routine that reinitializes
+ variables and such - the close routine may well have freed some
+ necessary storage structures, for example.
+
+ - Function: void Lstream_rewind (Lstream *STREAM)
+ Rewind the stream to the beginning.
+
+\1f
+File: internals.info, Node: Lstream Methods, Prev: Lstream Functions, Up: Lstreams
+
+Lstream Methods
+===============
+
+ - Lstream Method: int reader (Lstream *STREAM, unsigned char *DATA,
+ int SIZE)
+ Read some data from the stream's end and store it into DATA, which
+ can hold SIZE bytes. Return the number of bytes read. A return
+ value of 0 means no bytes can be read at this time. This may be
+ because of an EOF, or because there is a granularity greater than
+ one byte that the stream imposes on the returned data, and SIZE is
+ less than this granularity. (This will happen frequently for
+ streams that need to return whole characters, because
+ `Lstream_read()' calls the reader function repeatedly until it has
+ the number of bytes it wants or until 0 is returned.) The lstream
+ functions do not treat a 0 return as EOF or do anything special;
+ however, the calling function will interpret any 0 it gets back as
+ EOF. This will normally not happen unless the caller calls
+ `Lstream_read()' with a very small size.
+
+ This function can be `NULL' if the stream is output-only.
+
+ - Lstream Method: int writer (Lstream *STREAM, CONST unsigned char
+ *DATA, int SIZE)
+ Send some data to the stream's end. Data to be sent is in DATA
+ and is SIZE bytes. Return the number of bytes sent. This
+ function can send and return fewer bytes than is passed in; in that
+ case, the function will just be called again until there is no
+ data left or 0 is returned. A return value of 0 means that no
+ more data can be currently stored, but there is no error; the data
+ will be squirreled away until the writer can accept data. (This is
+ useful, e.g., if you're dealing with a non-blocking file
+ descriptor and are getting `EWOULDBLOCK' errors.) This function
+ can be `NULL' if the stream is input-only.
+
+ - Lstream Method: int rewinder (Lstream *STREAM)
+ Rewind the stream. If this is `NULL', the stream is not seekable.
+
+ - Lstream Method: int seekable_p (Lstream *STREAM)
+ Indicate whether this stream is seekable - i.e. it can be rewound.
+ This method is ignored if the stream does not have a rewind
+ method. If this method is not present, the result is determined
+ by whether a rewind method is present.
+
+ - Lstream Method: int flusher (Lstream *STREAM)
+ Perform any additional operations necessary to flush the data in
+ this stream.
+
+ - Lstream Method: int pseudo_closer (Lstream *STREAM)
+
+ - Lstream Method: int closer (Lstream *STREAM)
+ Perform any additional operations necessary to close this stream
+ down. May be `NULL'. This function is called when
+ `Lstream_close()' is called or when the stream is
+ garbage-collected. When this function is called, all pending data
+ in the stream will already have been written out.
+
+ - Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void
+ (*MARKFUN) (Lisp_Object))
+ Mark this object for garbage collection. Same semantics as a
+ standard `Lisp_Object' marker. This function can be `NULL'.
+
+\1f
+File: internals.info, Node: Consoles; Devices; Frames; Windows, Next: The Redisplay Mechanism, Prev: Lstreams, Up: Top
+
+Consoles; Devices; Frames; Windows
+**********************************
+
+* Menu:
+
+* Introduction to Consoles; Devices; Frames; Windows::
+* Point::
+* Window Hierarchy::
+* The Window Object::
+
+\1f
+File: internals.info, Node: Introduction to Consoles; Devices; Frames; Windows, Next: Point, Up: Consoles; Devices; Frames; Windows
+
+Introduction to Consoles; Devices; Frames; Windows
+==================================================
+
+ A window-system window that you see on the screen is called a
+"frame" in Emacs terminology. Each frame is subdivided into one or
+more non-overlapping panes, called (confusingly) "windows". Each
+window displays the text of a buffer in it. (See above on Buffers.) Note
+that buffers and windows are independent entities: Two or more windows
+can be displaying the same buffer (potentially in different locations),
+and a buffer can be displayed in no windows.
+
+ A single display screen that contains one or more frames is called a
+"display". Under most circumstances, there is only one display.
+However, more than one display can exist, for example if you have a
+"multi-headed" console, i.e. one with a single keyboard but multiple
+displays. (Typically in such a situation, the various displays act like
+one large display, in that the mouse is only in one of them at a time,
+and moving the mouse off of one moves it into another.) In some cases,
+the different displays will have different characteristics, e.g. one
+color and one mono.
+
+ XEmacs can display frames on multiple displays. It can even deal
+simultaneously with frames on multiple keyboards (called "consoles" in
+XEmacs terminology). Here is one case where this might be useful: You
+are using XEmacs on your workstation at work, and leave it running.
+Then you go home and dial in on a TTY line, and you can use the
+already-running XEmacs process to display another frame on your local
+TTY.
+
+ Thus, there is a hierarchy console -> display -> frame -> window.
+There is a separate Lisp object type for each of these four concepts.
+Furthermore, there is logically a "selected console", "selected
+display", "selected frame", and "selected window". Each of these
+objects is distinguished in various ways, such as being the default
+object for various functions that act on objects of that type. Note
+that every containing object rememembers the "selected" object among
+the objects that it contains: e.g. not only is there a selected window,
+but every frame remembers the last window in it that was selected, and
+changing the selected frame causes the remembered window within it to
+become the selected window. Similar relationships apply for consoles
+to devices and devices to frames.
+
+\1f
+File: internals.info, Node: Point, Next: Window Hierarchy, Prev: Introduction to Consoles; Devices; Frames; Windows, Up: Consoles; Devices; Frames; Windows
+
+Point
+=====
+
+ Recall that every buffer has a current insertion position, called
+"point". Now, two or more windows may be displaying the same buffer,
+and the text cursor in the two windows (i.e. `point') can be in two
+different places. You may ask, how can that be, since each buffer has
+only one value of `point'? The answer is that each window also has a
+value of `point' that is squirreled away in it. There is only one
+selected window, and the value of "point" in that buffer corresponds to
+that window. When the selected window is changed from one window to
+another displaying the same buffer, the old value of `point' is stored
+into the old window's "point" and the value of `point' from the new
+window is retrieved and made the value of `point' in the buffer. This
+means that `window-point' for the selected window is potentially
+inaccurate, and if you want to retrieve the correct value of `point'
+for a window, you must special-case on the selected window and retrieve
+the buffer's point instead. This is related to why
+`save-window-excursion' does not save the selected window's value of
+`point'.
+
+\1f
+File: internals.info, Node: Window Hierarchy, Next: The Window Object, Prev: Point, Up: Consoles; Devices; Frames; Windows
+
+Window Hierarchy
+================
+
+ If a frame contains multiple windows (panes), they are always created
+by splitting an existing window along the horizontal or vertical axis.
+Terminology is a bit confusing here: to "split a window horizontally"
+means to create two side-by-side windows, i.e. to make a *vertical* cut
+in a window. Likewise, to "split a window vertically" means to create
+two windows, one above the other, by making a *horizontal* cut.
+
+ If you split a window and then split again along the same axis, you
+will end up with a number of panes all arranged along the same axis.
+The precise way in which the splits were made should not be important,
+and this is reflected internally. Internally, all windows are arranged
+in a tree, consisting of two types of windows, "combination" windows
+(which have children, and are covered completely by those children) and
+"leaf" windows, which have no children and are visible. Every
+combination window has two or more children, all arranged along the same
+axis. There are (logically) two subtypes of windows, depending on
+whether their children are horizontally or vertically arrayed. There is
+always one root window, which is either a leaf window (if the frame
+contains only one window) or a combination window (if the frame contains
+more than one window). In the latter case, the root window will have
+two or more children, either horizontally or vertically arrayed, and
+each of those children will be either a leaf window or another
+combination window.
+
+ Here are some rules:
+
+ 1. Horizontal combination windows can never have children that are
+ horizontal combination windows; same for vertical.
+
+ 2. Only leaf windows can be split (obviously) and this splitting does
+ one of two things: (a) turns the leaf window into a combination
+ window and creates two new leaf children, or (b) turns the leaf
+ window into one of the two new leaves and creates the other leaf.
+ Rule (1) dictates which of these two outcomes happens.
+
+ 3. Every combination window must have at least two children.
+
+ 4. Leaf windows can never become combination windows. They can be
+ deleted, however. If this results in a violation of (3), the
+ parent combination window also gets deleted.
+
+ 5. All functions that accept windows must be prepared to accept
+ combination windows, and do something sane (e.g. signal an error
+ if so). Combination windows *do* escape to the Lisp level.
+
+ 6. All windows have three fields governing their contents: these are
+ "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
+ "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.
+
+ 8. The list of children for a window is threaded through the `next'
+ and `prev' fields of each child window.
+
+ 9. *Deleted windows can be undeleted*. This happens as a result of
+ restoring a window configuration, and is unlike frames, displays,
+ and consoles, which, once deleted, can never be restored.
+ Deleting a window does nothing except set a special `dead' bit to
+ 1 and clear out the `next', `prev', `hchild', and `vchild' fields,
+ for GC purposes.
+
+ 10. Most frames actually have two top-level windows - one for the
+ minibuffer and one (the "root") for everything else. The modeline
+ (if present) separates these two. The `next' field of the root
+ points to the minibuffer, and the `prev' field of the minibuffer
+ points to the root. The other `next' and `prev' fields are `nil',
+ and the frame points to both of these windows. Minibuffer-less
+ frames have no minibuffer window, and the `next' and `prev' of the
+ root window are `nil'. Minibuffer-only frames have no root
+ window, and the `next' of the minibuffer window is `nil' but the
+ `prev' points to itself. (#### This is an artifact that should be
+ fixed.)
+
+\1f
+File: internals.info, Node: The Window Object, Prev: Window Hierarchy, Up: Consoles; Devices; Frames; Windows
+
+The Window Object
+=================
+
+ Windows have the following accessible fields:
+
+`frame'
+ The frame that this window is on.
+
+`mini_p'
+ Non-`nil' if this window is a minibuffer window.
+
+`buffer'
+ The buffer that the window is displaying. This may change often
+ during the life of the window.
+
+`dedicated'
+ Non-`nil' if this window is dedicated to its buffer.
+
+`pointm'
+ This is the value of point in the current buffer when this window
+ is selected; when it is not selected, it retains its previous
+ value.
+
+`start'
+ The position in the buffer that is the first character to be
+ displayed in the window.
+
+`force_start'
+ If this flag is non-`nil', it says that the window has been
+ scrolled explicitly by the Lisp program. This affects what the
+ next redisplay does if point is off the screen: instead of
+ scrolling the window to show the text around point, it moves point
+ to a location that is on the screen.
+
+`last_modified'
+ The `modified' field of the window's buffer, as of the last time a
+ redisplay completed in this window.
+
+`last_point'
+ The buffer's value of point, as of the last time a redisplay
+ completed in this window.
+
+`left'
+ This is the left-hand edge of the window, measured in columns.
+ (The leftmost column on the screen is column 0.)
+
+`top'
+ This is the top edge of the window, measured in lines. (The top
+ line on the screen is line 0.)
+
+`height'
+ The height of the window, measured in lines.
+
+`width'
+ The width of the window, measured in columns.
+
+`next'
+ This is the window that is the next in the chain of siblings. It
+ is `nil' in a window that is the rightmost or bottommost of a
+ group of siblings.
+
+`prev'
+ This is the window that is the previous in the chain of siblings.
+ It is `nil' in a window that is the leftmost or topmost of a group
+ of siblings.
+
+`parent'
+ Internally, XEmacs arranges windows in a tree; each group of
+ siblings has a parent window whose area includes all the siblings.
+ This field points to a window's parent.
+
+ Parent windows do not display buffers, and play little role in
+ display except to shape their child windows. Emacs Lisp programs
+ usually have no access to the parent windows; they operate on the
+ windows at the leaves of the tree, which actually display buffers.
+
+`hscroll'
+ This is the number of columns that the display in the window is
+ scrolled horizontally to the left. Normally, this is 0.
+
+`use_time'
+ This is the last time that the window was selected. The function
+ `get-lru-window' uses this field.
+
+`display_table'
+ The window's display table, or `nil' if none is specified for it.
+
+`update_mode_line'
+ Non-`nil' means this window's mode line needs to be updated.
+
+`base_line_number'
+ The line number of a certain position in the buffer, or `nil'.
+ This is used for displaying the line number of point in the mode
+ line.
+
+`base_line_pos'
+ The position in the buffer for which the line number is known, or
+ `nil' meaning none is known.
+
+`region_showing'
+ If the region (or part of it) is highlighted in this window, this
+ field holds the mark position that made one end of that region.
+ Otherwise, this field is `nil'.
+
--- /dev/null
+This is Info file ../../info/internals.info, produced by Makeinfo
+version 1.68 from the input file internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals). XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+ Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
+Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: internals.info, Node: The Redisplay Mechanism, Next: Extents, Prev: Consoles; Devices; Frames; Windows, Up: Top
+
+The Redisplay Mechanism
+***********************
+
+ The redisplay mechanism is one of the most complicated sections of
+XEmacs, especially from a conceptual standpoint. This is doubly so
+because, unlike for the basic aspects of the Lisp interpreter, the
+computer science theories of how to efficiently handle redisplay are not
+well-developed.
+
+ When working with the redisplay mechanism, remember the Golden Rules
+of Redisplay:
+
+ 1. It Is Better To Be Correct Than Fast.
+
+ 2. Thou Shalt Not Run Elisp From Within Redisplay.
+
+ 3. It Is Better To Be Fast Than Not To Be.
+
+* Menu:
+
+* Critical Redisplay Sections::
+* Line Start Cache::
+* Redisplay Piece by Piece::
+
+\1f
+File: internals.info, Node: Critical Redisplay Sections, Next: Line Start Cache, Up: The Redisplay Mechanism
+
+Critical Redisplay Sections
+===========================
+
+ Within this section, we are defenseless and assume that the
+following cannot happen:
+
+ 1. garbage collection
+
+ 2. Lisp code evaluation
+
+ 3. frame size changes
+
+ We ensure (3) by calling `hold_frame_size_changes()', which will
+cause any pending frame size changes to get put on hold till after the
+end of the critical section. (1) follows automatically if (2) is met.
+#### Unfortunately, there are some places where Lisp code can be called
+within this section. We need to remove them.
+
+ If `Fsignal()' is called during this critical section, we will
+`abort()'.
+
+ If garbage collection is called during this critical section, we
+simply return. #### We should abort instead.
+
+ #### If a frame-size change does occur we should probably actually
+be preempting redisplay.
+
+\1f
+File: internals.info, Node: Line Start Cache, Next: Redisplay Piece by Piece, Prev: Critical Redisplay Sections, Up: The Redisplay Mechanism
+
+Line Start Cache
+================
+
+ The traditional scrolling code in Emacs breaks in a variable height
+world. It depends on the key assumption that the number of lines that
+can be displayed at any given time is fixed. This led to a complete
+separation of the scrolling code from the redisplay code. In order to
+fully support variable height lines, the scrolling code must actually be
+tightly integrated with redisplay. Only redisplay can determine how
+many lines will be displayed on a screen for any given starting point.
+
+ What is ideally wanted is a complete list of the starting buffer
+position for every possible display line of a buffer along with the
+height of that display line. Maintaining such a full list would be very
+expensive. We settle for having it include information for all areas
+which we happen to generate anyhow (i.e. the region currently being
+displayed) and for those areas we need to work with.
+
+ In order to ensure that the cache accurately represents what
+redisplay would actually show, it is necessary to invalidate it in many
+situations. If the buffer changes, the starting positions may no longer
+be correct. If a face or an extent has changed then the line heights
+may have altered. These events happen frequently enough that the cache
+can end up being constantly disabled. With this potentially constant
+invalidation when is the cache ever useful?
+
+ Even if the cache is invalidated before every single usage, it is
+necessary. Scrolling often requires knowledge about display lines which
+are actually above or below the visible region. The cache provides a
+convenient light-weight method of storing this information for multiple
+display regions. This knowledge is necessary for the scrolling code to
+always obey the First Golden Rule of Redisplay.
+
+ If the cache already contains all of the information that the
+scrolling routines happen to need so that it doesn't have to go
+generate it, then we are able to obey the Third Golden Rule of
+Redisplay. The first thing we do to help out the cache is to always
+add the displayed region. This region had to be generated anyway, so
+the cache ends up getting the information basically for free. In those
+cases where a user is simply scrolling around viewing a buffer there is
+a high probability that this is sufficient to always provide the needed
+information. The second thing we can do is be smart about invalidating
+the cache.
+
+ TODO - Be smart about invalidating the cache. Potential places:
+
+ * Insertions at end-of-line which don't cause line-wraps do not
+ alter the starting positions of any display lines. These types of
+ buffer modifications should not invalidate the cache. This is
+ actually a large optimization for redisplay speed as well.
+
+ * Buffer modifications frequently only affect the display of lines
+ at and below where they occur. In these situations we should only
+ invalidate the part of the cache starting at where the
+ modification occurs.
+
+ In case you're wondering, the Second Golden Rule of Redisplay is not
+applicable.
+
+\1f
+File: internals.info, Node: Redisplay Piece by Piece, Prev: Line Start Cache, Up: The Redisplay Mechanism
+
+Redisplay Piece by Piece
+========================
+
+ As you can begin to see redisplay is complex and also not well
+documented. Chuck no longer works on XEmacs so this section is my take
+on the workings of redisplay.
+
+ Redisplay happens in three phases:
+
+ 1. Determine desired display in area that needs redisplay.
+ Implemented by `redisplay.c'
+
+ 2. Compare desired display with current display Implemented by
+ `redisplay-output.c'
+
+ 3. Output changes Implemented by `redisplay-output.c',
+ `redisplay-x.c', `redisplay-msw.c' and `redisplay-tty.c'
+
+ Steps 1 and 2 are device-independant and relatively complex. Step 3
+is mostly device-dependent.
+
+ Determining the desired display
+
+ Display attributes are stored in `display_line' structures. Each
+`display_line' consists of a set of `display_block''s and each
+`display_block' contains a number of `rune''s. Generally dynarr's of
+`display_line''s are held by each window representing the current
+display and the desired display.
+
+ The `display_line' structures are tighly tied to buffers which
+presents a problem for redisplay as this connection is bogus for the
+modeline. Hence the `display_line' generation routines are duplicated
+for generating the modeline. This means that the modeline display code
+has many bugs that the standard redisplay code does not.
+
+ The guts of `display_line' generation are in `create_text_block',
+which creates a single display line for the desired locale. This
+incrementally parses the characters on the current line and generates
+redisplay structures for each.
+
+ Gutter redisplay is different. Because the data to display is stored
+in a string we cannot use `create_text_block'. Instead we use
+`create_text_string_block' which performs the same function as
+`create_text_block' but for strings. Many of the complexities of
+`create_text_block' to do with cursor handling and selective display
+have been removed.
+
+\1f
+File: internals.info, Node: Extents, Next: Faces, Prev: The Redisplay Mechanism, Up: Top
+
+Extents
+*******
+
+* Menu:
+
+* Introduction to Extents:: Extents are ranges over text, with properties.
+* Extent Ordering:: How extents are ordered internally.
+* Format of the Extent Info:: The extent information in a buffer or string.
+* Zero-Length Extents:: A weird special case.
+* Mathematics of Extent Ordering:: A rigorous foundation.
+* Extent Fragments:: Cached information useful for redisplay.
+
+\1f
+File: internals.info, Node: Introduction to Extents, Next: Extent Ordering, Up: Extents
+
+Introduction to Extents
+=======================
+
+ Extents are regions over a buffer, with a start and an end position
+denoting the region of the buffer included in the extent. In addition,
+either end can be closed or open, meaning that the endpoint is or is
+not logically included in the extent. Insertion of a character at a
+closed endpoint causes the character to go inside the extent; insertion
+at an open endpoint causes the character to go outside.
+
+ Extent endpoints are stored using memory indices (see `insdel.c'),
+to minimize the amount of adjusting that needs to be done when
+characters are inserted or deleted.
+
+ (Formerly, extent endpoints at the gap could be either before or
+after the gap, depending on the open/closedness of the endpoint. The
+intent of this was to make it so that insertions would automatically go
+inside or out of extents as necessary with no further work needing to
+be done. It didn't work out that way, however, and just ended up
+complexifying and buggifying all the rest of the code.)
+
+\1f
+File: internals.info, Node: Extent Ordering, Next: Format of the Extent Info, Prev: Introduction to Extents, Up: Extents
+
+Extent Ordering
+===============
+
+ Extents are compared using memory indices. There are two orderings
+for extents and both orders are kept current at all times. The normal
+or "display" order is as follows:
+
+ Extent A is ``less than'' extent B,
+ that is, earlier in the display order,
+ if: A-start < B-start,
+ or if: A-start = B-start, and A-end > B-end
+
+ So if two extents begin at the same position, the larger of them is
+the earlier one in the display order (`EXTENT_LESS' is true).
+
+ For the e-order, the same thing holds:
+
+ Extent A is ``less than'' extent B in e-order,
+ that is, later in the buffer,
+ if: A-end < B-end,
+ or if: A-end = B-end, and A-start > B-start
+
+ So if two extents end at the same position, the smaller of them is
+the earlier one in the e-order (`EXTENT_E_LESS' is true).
+
+ The display order and the e-order are complementary orders: any
+theorem about the display order also applies to the e-order if you swap
+all occurrences of "display order" and "e-order", "less than" and
+"greater than", and "extent start" and "extent end".
+
+\1f
+File: internals.info, Node: Format of the Extent Info, Next: Zero-Length Extents, Prev: Extent Ordering, Up: Extents
+
+Format of the Extent Info
+=========================
+
+ An extent-info structure consists of a list of the buffer or string's
+extents and a "stack of extents" that lists all of the extents over a
+particular position. The stack-of-extents info is used for
+optimization purposes - it basically caches some info that might be
+expensive to compute. Certain otherwise hard computations are easy
+given the stack of extents over a particular position, and if the stack
+of extents over a nearby position is known (because it was calculated
+at some prior point in time), it's easy to move the stack of extents to
+the proper position.
+
+ Given that the stack of extents is an optimization, and given that
+it requires memory, a string's stack of extents is wiped out each time
+a garbage collection occurs. Therefore, any time you retrieve the
+stack of extents, it might not be there. If you need it to be there,
+use the `_force' version.
+
+ Similarly, a string may or may not have an extent_info structure.
+(Generally it won't if there haven't been any extents added to the
+string.) So use the `_force' version if you need the extent_info
+structure to be there.
+
+ A list of extents is maintained as a double gap array: one gap array
+is ordered by start index (the "display order") and the other is
+ordered by end index (the "e-order"). Note that positions in an extent
+list should logically be conceived of as referring *to* a particular
+extent (as is the norm in programs) rather than sitting between two
+extents. Note also that callers of these functions should not be aware
+of the fact that the extent list is implemented as an array, except for
+the fact that positions are integers (this should be generalized to
+handle integers and linked list equally well).
+
+\1f
+File: internals.info, Node: Zero-Length Extents, Next: Mathematics of Extent Ordering, Prev: Format of the Extent Info, Up: Extents
+
+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
+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
+extent.) Zero-length extents are primarily used to represent
+annotations, and behave as follows:
+
+ 1. Insertion at the position of a zero-length extent expands the
+ extent if both endpoints are closed; goes after the extent if it
+ is closed-open; and goes before the extent if it is open-closed.
+
+ 2. Deletion of a character on a side of a zero-length extent whose
+ corresponding endpoint is closed causes the extent to be detached
+ if it is detachable; if the extent is not detachable or the
+ corresponding endpoint is open, the extent remains in the buffer,
+ moving as necessary.
+
+ Note that closed-open, non-detachable zero-length extents behave
+exactly like markers and that open-closed, non-detachable zero-length
+extents behave like the "point-type" marker in Mule.
+
+\1f
+File: internals.info, Node: Mathematics of Extent Ordering, Next: Extent Fragments, Prev: Zero-Length Extents, Up: Extents
+
+Mathematics of Extent Ordering
+==============================
+
+ The extents in a buffer are ordered by "display order" because that
+is that order that the redisplay mechanism needs to process them in.
+The e-order is an auxiliary ordering used to facilitate operations over
+extents. The operations that can be performed on the ordered list of
+extents in a buffer are
+
+ 1. Locate where an extent would go if inserted into the list.
+
+ 2. Insert an extent into the list.
+
+ 3. Remove an extent from the list.
+
+ 4. Map over all the extents that overlap a range.
+
+ (4) requires being able to determine the first and last extents that
+overlap a range.
+
+ NOTE: "overlap" is used as follows:
+
+ * two ranges overlap if they have at least one point in common.
+ Whether the endpoints are open or closed makes a difference here.
+
+ * a point overlaps a range if the point is contained within the
+ range; this is equivalent to treating a point P as the range [P,
+ P].
+
+ * In the case of an *extent* overlapping a point or range, the extent
+ is normally treated as having closed endpoints. This applies
+ consistently in the discussion of stacks of extents and such below.
+ Note that this definition of overlap is not necessarily consistent
+ with the extents that `map-extents' maps over, since `map-extents'
+ sometimes pays attention to whether the endpoints of an extents
+ are open or closed. But for our purposes, it greatly simplifies
+ things to treat all extents as having closed endpoints.
+
+ First, define >, <, <=, etc. as applied to extents to mean
+comparison according to the display order. Comparison between an
+extent E and an index I means comparison between E and the range [I, I].
+
+ Also define e>, e<, e<=, etc. to mean comparison according to the
+e-order.
+
+ For any range R, define R(0) to be the starting index of the range
+and R(1) to be the ending index of the range.
+
+ For any extent E, define E(next) to be the extent directly following
+E, and E(prev) to be the extent directly preceding E. Assume E(next)
+and E(prev) can be determined from E in constant time. (This is
+because we store the extent list as a doubly linked list.)
+
+ Similarly, define E(e-next) and E(e-prev) to be the extents directly
+following and preceding E in the e-order.
+
+ Now:
+
+ Let R be a range. Let F be the first extent overlapping R. Let L
+be the last extent overlapping R.
+
+ Theorem 1: R(1) lies between L and L(next), i.e. L <= R(1) < L(next).
+
+ This follows easily from the definition of display order. The basic
+reason that this theorem applies is that the display order sorts by
+increasing starting index.
+
+ Therefore, we can determine L just by looking at where we would
+insert R(1) into the list, and if we know F and are moving forward over
+extents, we can easily determine when we've hit L by comparing the
+extent we're at to R(1).
+
+ Theorem 2: F(e-prev) e< [1, R(0)] e<= F.
+
+ This is the analog of Theorem 1, and applies because the e-order
+sorts by increasing ending index.
+
+ Therefore, F can be found in the same amount of time as operation
+(1), i.e. the time that it takes to locate where an extent would go if
+inserted into the e-order list.
+
+ If the lists were stored as balanced binary trees, then operation (1)
+would take logarithmic time, which is usually quite fast. However,
+currently they're stored as simple doubly-linked lists, and instead we
+do some caching to try to speed things up.
+
+ Define a "stack of extents" (or "SOE") as the set of extents
+(ordered in the display order) that overlap an index I, together with
+the SOE's "previous" extent, which is an extent that precedes I in the
+e-order. (Hopefully there will not be very many extents between I and
+the previous extent.)
+
+ Now:
+
+ Let I be an index, let S be the stack of extents on I, let F be the
+first extent in S, and let P be S's previous extent.
+
+ Theorem 3: The first extent in S is the first extent that overlaps
+any range [I, J].
+
+ Proof: Any extent that overlaps [I, J] but does not include I must
+have a start index > I, and thus be greater than any extent in S.
+
+ Therefore, finding the first extent that overlaps a range R is the
+same as finding the first extent that overlaps R(0).
+
+ Theorem 4: Let I2 be an index such that I2 > I, and let F2 be the
+first extent that overlaps I2. Then, either F2 is in S or F2 is
+greater than any extent in S.
+
+ Proof: If F2 does not include I then its start index is greater than
+I and thus it is greater than any extent in S, including F. Otherwise,
+F2 includes I and thus is in S, and thus F2 >= F.
+
+\1f
+File: internals.info, Node: Extent Fragments, Prev: Mathematics of Extent Ordering, Up: Extents
+
+Extent Fragments
+================
+
+ Imagine that the buffer is divided up into contiguous,
+non-overlapping "runs" of text such that no extent starts or ends
+within a run (extents that abut the run don't count).
+
+ An extent fragment is a structure that holds data about the run that
+contains a particular buffer position (if the buffer position is at the
+junction of two runs, the run after the position is used) - the
+beginning and end of the run, a list of all of the extents in that run,
+the "merged face" that results from merging all of the faces
+corresponding to those extents, the begin and end glyphs at the
+beginning of the run, etc. This is the information that redisplay needs
+in order to display this run.
+
+ Extent fragments have to be very quick to update to a new buffer
+position when moving linearly through the buffer. They rely on the
+stack-of-extents code, which does the heavy-duty algorithmic work of
+determining which extents overly a particular position.
+
+\1f
+File: internals.info, Node: Faces, Next: Glyphs, Prev: Extents, Up: Top
+
+Faces
+*****
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Glyphs, Next: Specifiers, Prev: Faces, Up: Top
+
+Glyphs
+******
+
+ Glyphs are graphical elements that can be displayed in XEmacs
+buffers or gutters. We use the term graphical element here in the
+broadest possible sense since glyphs can be as mundane as text to as
+arcane as a native tab widget.
+
+ In XEmacs, glyphs represent the uninstantiated state of graphical
+elements, i.e. they hold all the information necessary to produce an
+image on-screen but the image does not exist at this stage.
+
+ Glyphs are lazily instantiated by calling one of the glyph
+functions. This usually occurs within redisplay when `Fglyph_height' is
+called. Instantiation causes an image-instance to be created and
+cached. This cache is on a device basis for all glyphs except
+glyph-widgets, and on a window basis for glyph widgets. The caching is
+done by `image_instantiate' and is necessary because it is generally
+possible to display an image-instance in multiple domains. For instance
+if we create a Pixmap, we can actually display this on multiple windows
+- even though we only need a single Pixmap instance to do this. If
+caching wasn't done then it would be necessary to create
+image-instances for every displayable occurrance of a glyph - and every
+usage - and this would be extremely memory and cpu intensive.
+
+ Widget-glyphs (a.k.a native widgets) are not cached in this way.
+This is because widget-glyph image-instances on screen are toolkit
+windows, and thus cannot be reused in multiple XEmacs domains. Thus
+widget-glyphs are cached on a window basis.
+
+ Any action on a glyph first consults the cache before actually
+instantiating a widget.
+
+Widget-Glyphs in the MS-WIndows Environment
+===========================================
+
+ To Do
+
+Widget-Glyphs in the X Environment
+==================================
+
+ Widget-glyphs under X make heavy use of lwlib for manipulating the
+native toolkit objects. This is primarily so that different toolkits can
+be supported for widget-glyphs, just as they are supported for features
+such as menubars etc.
+
+ Lwlib is extremely poorly documented and quite hairy so here is my
+understanding of what goes on.
+
+ Lwlib maintains a set of widget_instances which mirror the
+hierarchical state of Xt widgets. I think this is so that widgets can
+be updated and manipulated generically by the lwlib library. For
+instance update_one_widget_instance can cope with multiple types of
+widget and multiple types of toolkit. Each element in the widget
+hierarchy is updated from its corresponding widget_instance by walking
+the widget_instance tree recursively.
+
+ This has desirable properties such as lw_modify_all_widgets which is
+called from glyphs-x.c and updates all the properties of a widget
+without having to know what the widget is or what toolkit it is from.
+Unfortunately this also has hairy properrties such as making the lwlib
+code quite complex. And of course lwlib has to know at some level what
+the widget is and how to set its properties.
+
+\1f
+File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top
+
+Specifiers
+**********
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Menus, Next: Subprocesses, Prev: Specifiers, Up: Top
+
+Menus
+*****
+
+ A menu is set by setting the value of the variable `current-menubar'
+(which may be buffer-local) and then calling `set-menubar-dirty-flag'
+to signal a change. This will cause the menu to be redrawn at the next
+redisplay. The format of the data in `current-menubar' is described in
+`menubar.c'.
+
+ Internally the data in current-menubar is parsed into a tree of
+`widget_value's' (defined in `lwlib.h'); this is accomplished by the
+recursive function `menu_item_descriptor_to_widget_value()', called by
+`compute_menubar_data()'. Such a tree is deallocated using
+`free_widget_value()'.
+
+ `update_screen_menubars()' is one of the external entry points.
+This checks to see, for each screen, if that screen's menubar needs to
+be updated. This is the case if
+
+ 1. `set-menubar-dirty-flag' was called since the last redisplay.
+ (This function sets the C variable menubar_has_changed.)
+
+ 2. The buffer displayed in the screen has changed.
+
+ 3. The screen has no menubar currently displayed.
+
+ `set_screen_menubar()' is called for each such screen. This
+function calls `compute_menubar_data()' to create the tree of
+widget_value's, then calls `lw_create_widget()',
+`lw_modify_all_widgets()', and/or `lw_destroy_all_widgets()' to create
+the X-Toolkit widget associated with the menu.
+
+ `update_psheets()', the other external entry point, actually changes
+the menus being displayed. It uses the widgets fixed by
+`update_screen_menubars()' and calls various X functions to ensure that
+the menus are displayed properly.
+
+ The menubar widget is set up so that `pre_activate_callback()' is
+called when the menu is first selected (i.e. mouse button goes down),
+and `menubar_selection_callback()' is called when an item is selected.
+`pre_activate_callback()' calls the function in activate-menubar-hook,
+which can change the menubar (this is described in `menubar.c'). If
+the menubar is changed, `set_screen_menubars()' is called.
+`menubar_selection_callback()' enqueues a menu event, putting in it a
+function to call (either `eval' or `call-interactively') and its
+argument, which is the callback function or form given in the menu's
+description.
+
+\1f
+File: internals.info, Node: Subprocesses, Next: Interface to X Windows, Prev: Menus, Up: Top
+
+Subprocesses
+************
+
+ The fields of a process are:
+
+`name'
+ A string, the name of the process.
+
+`command'
+ A list containing the command arguments that were used to start
+ this process.
+
+`filter'
+ A function used to accept output from the process instead of a
+ buffer, or `nil'.
+
+`sentinel'
+ A function called whenever the process receives a signal, or `nil'.
+
+`buffer'
+ The associated buffer of the process.
+
+`pid'
+ An integer, the Unix process ID.
+
+`childp'
+ A flag, non-`nil' if this is really a child process. It is `nil'
+ for a network connection.
+
+`mark'
+ A marker indicating the position of the end of the last output
+ from this process inserted into the buffer. This is often but not
+ always the end of the buffer.
+
+`kill_without_query'
+ If this is non-`nil', killing XEmacs while this process is still
+ running does not ask for confirmation about killing the process.
+
+`raw_status_low'
+`raw_status_high'
+ These two fields record 16 bits each of the process status
+ returned by the `wait' system call.
+
+`status'
+ The process status, as `process-status' should return it.
+
+`tick'
+`update_tick'
+ If these two fields are not equal, a change in the status of the
+ process needs to be reported, either by running the sentinel or by
+ inserting a message in the process buffer.
+
+`pty_flag'
+ Non-`nil' if communication with the subprocess uses a PTY; `nil'
+ if it uses a pipe.
+
+`infd'
+ The file descriptor for input from the process.
+
+`outfd'
+ The file descriptor for output to the process.
+
+`subtty'
+ The file descriptor for the terminal that the subprocess is using.
+ (On some systems, there is no need to record this, so the value is
+ `-1'.)
+
+`tty_name'
+ The name of the terminal that the subprocess is using, or `nil' if
+ it is using pipes.
+
+\1f
+File: internals.info, Node: Interface to X Windows, Next: Index, Prev: Subprocesses, Up: Top
+
+Interface to X Windows
+**********************
+
+ Not yet documented.
+
+\1f
+File: internals.info, Node: Index, Prev: Interface to X Windows, Up: Top
+
+Index
+*****
+
+* Menu:
+
+* Amdahl Corporation: XEmacs.
+* Andreessen, Marc: XEmacs.
+* asynchronous subprocesses: Modules for Interfacing with the Operating System.
+* Baur, Steve: XEmacs.
+* Benson, Eric: Lucid Emacs.
+* bridge, playing: XEmacs From the Outside.
+* Buchholz, Martin: XEmacs.
+* Bufbyte: Character-Related Data Types.
+* Bufpos: Character-Related Data Types.
+* Bytecount: Character-Related Data Types.
+* bytecount_to_charcount: Working With Character and Byte Positions.
+* Bytind: Character-Related Data Types.
+* C vs. Lisp: The Lisp Language.
+* caller-protects (GCPRO rule): Writing Lisp Primitives.
+* case table: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* Charcount: Character-Related Data Types.
+* charcount_to_bytecount: Working With Character and Byte Positions.
+* charptr_emchar: Working With Character and Byte Positions.
+* charptr_n_addr: Working With Character and Byte Positions.
+* closer: Lstream Methods.
+* closure: The XEmacs Object System (Abstractly Speaking).
+* Coding for Mule: Coding for Mule.
+* Common Lisp: The Lisp Language.
+* compact_string_chars: compact_string_chars.
+* conservative garbage collection: GCPROing.
+* copy-on-write: General Coding Rules.
+* critical redisplay sections: Critical Redisplay Sections.
+* DEC_CHARPTR: Working With Character and Byte Positions.
+* Devin, Matthieu: Lucid Emacs.
+* display order of extents: Mathematics of Extent Ordering.
+* dynamic array: Low-Level Modules.
+* dynamic scoping: The Lisp Language.
+* dynamic types: The Lisp Language.
+* Emchar: Character-Related Data Types.
+* Energize: Lucid Emacs.
+* Epoch <1>: XEmacs.
+* Epoch: Lucid Emacs.
+* Extbyte: Character-Related Data Types.
+* Extcount: Character-Related Data Types.
+* extent fragment: Extent Fragments.
+* extent mathematics: Mathematics of Extent Ordering.
+* extent ordering: Mathematics of Extent Ordering.
+* extents, display order: Mathematics of Extent Ordering.
+* external widget: Modules for Interfacing with X Windows.
+* flusher: Lstream Methods.
+* Free Software Foundation: A History of Emacs.
+* frob block: Introduction to Allocation.
+* FSF: A History of Emacs.
+* FSF Emacs <1>: GNU Emacs 20.
+* FSF Emacs: GNU Emacs 19.
+* garbage collection: Garbage Collection.
+* garbage collection protection: Writing Lisp Primitives.
+* garbage collection step by step: Garbage Collection - Step by Step.
+* garbage collection, conservative: GCPROing.
+* garbage collection, invocation: Invocation.
+* garbage_collect_1: garbage_collect_1.
+* gc_sweep: gc_sweep.
+* GNU Emacs 19: GNU Emacs 19.
+* GNU Emacs 20: GNU Emacs 20.
+* Gosling, James <1>: Through Version 18.
+* Gosling, James: The Lisp Language.
+* Great Usenet Renaming: Through Version 18.
+* Hackers (Steven Levy): A History of Emacs.
+* hierarchy of windows: Window Hierarchy.
+* history of Emacs: A History of Emacs.
+* Illinois, University of: XEmacs.
+* INC_CHARPTR: Working With Character and Byte Positions.
+* interactive: Modules for Standard Editing Operations.
+* interning: The XEmacs Object System (Abstractly Speaking).
+* ITS (Incompatible Timesharing System): A History of Emacs.
+* Java: The Lisp Language.
+* Java vs. Lisp: The Lisp Language.
+* Jones, Kyle: XEmacs.
+* Kaplan, Simon: XEmacs.
+* Levy, Steven: A History of Emacs.
+* line start cache: Line Start Cache.
+* Lisp vs. C: The Lisp Language.
+* Lisp vs. Java: The Lisp Language.
+* lstream: Modules for Interfacing with the File System.
+* Lstream_close: Lstream Functions.
+* Lstream_fgetc: Lstream Functions.
+* Lstream_flush: Lstream Functions.
+* Lstream_fputc: Lstream Functions.
+* Lstream_fungetc: Lstream Functions.
+* Lstream_getc: Lstream Functions.
+* Lstream_new: Lstream Functions.
+* Lstream_putc: Lstream Functions.
+* Lstream_read: Lstream Functions.
+* Lstream_reopen: Lstream Functions.
+* Lstream_rewind: Lstream Functions.
+* Lstream_set_buffering: Lstream Functions.
+* Lstream_ungetc: Lstream Functions.
+* Lstream_unread: Lstream Functions.
+* Lstream_write: Lstream Functions.
+* Lucid Emacs: Lucid Emacs.
+* Lucid Inc.: Lucid Emacs.
+* mark and sweep: Garbage Collection.
+* mark method <1>: lrecords.
+* mark method: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* mark_object: mark_object.
+* marker: Lstream Methods.
+* mathematics of extents: Mathematics of Extent Ordering.
+* MAX_EMCHAR_LEN: Working With Character and Byte Positions.
+* merging attempts: XEmacs.
+* MIT: A History of Emacs.
+* Mlynarik, Richard: GNU Emacs 19.
+* MULE merged XEmacs appears: XEmacs.
+* NAS: Modules for Interfacing with the Operating System.
+* native sound: Modules for Interfacing with the Operating System.
+* network connections: Modules for Interfacing with the Operating System.
+* network sound: Modules for Interfacing with the Operating System.
+* Niksic, Hrvoje: XEmacs.
+* pane: Modules for the Basic Displayable Lisp Objects.
+* permanent objects: The XEmacs Object System (Abstractly Speaking).
+* pi, calculating: XEmacs From the Outside.
+* pseudo_closer: Lstream Methods.
+* pure space: Basic Lisp Modules.
+* read syntax: The XEmacs Object System (Abstractly Speaking).
+* read-eval-print: XEmacs From the Outside.
+* reader: Lstream Methods.
+* record type: How Lisp Objects Are Represented in C.
+* Redisplay Piece by Piece: Redisplay Piece by Piece.
+* relocating allocator: Low-Level Modules.
+* rename to XEmacs: XEmacs.
+* rewinder: Lstream Methods.
+* RMS: A History of Emacs.
+* scanner: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* scoping, dynamic: The Lisp Language.
+* seekable_p: Lstream Methods.
+* selections: Modules for Interfacing with X Windows.
+* set_charptr_emchar: Working With Character and Byte Positions.
+* Sexton, Harlan: Lucid Emacs.
+* sound, native: Modules for Interfacing with the Operating System.
+* sound, network: Modules for Interfacing with the Operating System.
+* SPARCWorks: XEmacs.
+* Stallman, Richard: A History of Emacs.
+* subprocesses, asynchronous: Modules for Interfacing with the Operating System.
+* subprocesses, synchronous: Modules for Interfacing with the Operating System.
+* Sun Microsystems: XEmacs.
+* sweep_bit_vectors_1: sweep_bit_vectors_1.
+* sweep_lcrecords_1: sweep_lcrecords_1.
+* sweep_strings: sweep_strings.
+* synchronous subprocesses: Modules for Interfacing with the Operating System.
+* taxes, doing: XEmacs From the Outside.
+* TECO: A History of Emacs.
+* temporary objects: The XEmacs Object System (Abstractly Speaking).
+* Thompson, Chuck: XEmacs.
+* types, dynamic: The Lisp Language.
+* University of Illinois: XEmacs.
+* Win-Emacs: XEmacs.
+* window (in Emacs): Modules for the Basic Displayable Lisp Objects.
+* window hierarchy: Window Hierarchy.
+* window point internals: The Window Object.
+* Wing, Ben: XEmacs.
+* writer: Lstream Methods.
+* XEmacs: XEmacs.
+* XEmacs goes it alone: XEmacs.
+* Zawinski, Jamie: Lucid Emacs.
+
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+Indirect:
+lispref.info-1: 2387
+lispref.info-2: 48394
+lispref.info-3: 96933
+lispref.info-4: 146792
+lispref.info-5: 195517
+lispref.info-6: 243211
+lispref.info-7: 291472
+lispref.info-8: 340630
+lispref.info-9: 387982
+lispref.info-10: 436629
+lispref.info-11: 484512
+lispref.info-12: 531109
+lispref.info-13: 579014
+lispref.info-14: 627229
+lispref.info-15: 675480
+lispref.info-16: 724640
+lispref.info-17: 771866
+lispref.info-18: 818656
+lispref.info-19: 865712
+lispref.info-20: 914446
+lispref.info-21: 963810
+lispref.info-22: 1010651
+lispref.info-23: 1057664
+lispref.info-24: 1107066
+lispref.info-25: 1156744
+lispref.info-26: 1206642
+lispref.info-27: 1255865
+lispref.info-28: 1304640
+lispref.info-29: 1353618
+lispref.info-30: 1394929
+lispref.info-31: 1444081
+lispref.info-32: 1493295
+lispref.info-33: 1542879
+lispref.info-34: 1591063
+lispref.info-35: 1636699
+lispref.info-36: 1678018
+lispref.info-37: 1722965
+lispref.info-38: 1772661
+lispref.info-39: 1821723
+lispref.info-40: 1871108
+lispref.info-41: 1921004
+lispref.info-42: 1969995
+lispref.info-43: 2014504
+lispref.info-44: 2052883
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f2387
+Node: Copying\7f48394
+Node: Introduction\7f67552
+Node: Caveats\7f69143
+Node: Lisp History\7f70872
+Node: Conventions\7f72128
+Node: Some Terms\7f72943
+Node: nil and t\7f73664
+Node: Evaluation Notation\7f75341
+Node: Printing Notation\7f76254
+Node: Error Messages\7f77128
+Node: Buffer Text Notation\7f77569
+Node: Format of Descriptions\7f78444
+Node: A Sample Function Description\7f79298
+Node: A Sample Variable Description\7f83284
+Node: Acknowledgements\7f84192
+Node: Lisp Data Types\7f86170
+Node: Printed Representation\7f88725
+Node: Comments\7f90768
+Node: Primitive Types\7f91666
+Node: Programming Types\7f93325
+Node: Integer Type\7f95277
+Node: Floating Point Type\7f96314
+Node: Character Type\7f96933
+Node: Symbol Type\7f104839
+Node: Sequence Type\7f107534
+Node: Cons Cell Type\7f109055
+Node: Dotted Pair Notation\7f113538
+Node: Association List Type\7f115659
+Node: Array Type\7f116542
+Node: String Type\7f118008
+Node: Vector Type\7f120689
+Node: Bit Vector Type\7f121461
+Node: Function Type\7f122323
+Node: Macro Type\7f123439
+Node: Primitive Function Type\7f124136
+Node: Compiled-Function Type\7f125663
+Node: Autoload Type\7f126217
+Node: Char Table Type\7f127231
+Node: Hash Table Type\7f127405
+Node: Range Table Type\7f128560
+Node: Weak List Type\7f129413
+Node: Editing Types\7f129563
+Node: Buffer Type\7f131190
+Node: Marker Type\7f133226
+Node: Extent Type\7f133950
+Node: Window Type\7f135218
+Node: Frame Type\7f136629
+Node: Device Type\7f137424
+Node: Console Type\7f138250
+Node: Window Configuration Type\7f139451
+Node: Event Type\7f140149
+Node: Process Type\7f140313
+Node: Stream Type\7f141348
+Node: Keymap Type\7f142473
+Node: Syntax Table Type\7f143011
+Node: Display Table Type\7f144035
+Node: Database Type\7f144474
+Node: Charset Type\7f144640
+Node: Coding System Type\7f144804
+Node: ToolTalk Message Type\7f144988
+Node: ToolTalk Pattern Type\7f145187
+Node: Window-System Types\7f145359
+Node: Face Type\7f146505
+Node: Glyph Type\7f146636
+Node: Specifier Type\7f146792
+Node: Font Instance Type\7f146965
+Node: Color Instance Type\7f147155
+Node: Image Instance Type\7f147352
+Node: Toolbar Button Type\7f147550
+Node: Subwindow Type\7f147743
+Node: X Resource Type\7f147922
+Node: Type Predicates\7f148075
+Node: Equality Predicates\7f157205
+Node: Numbers\7f162010
+Node: Integer Basics\7f163465
+Node: Float Basics\7f165815
+Node: Predicates on Numbers\7f167557
+Node: Comparison of Numbers\7f169190
+Node: Numeric Conversions\7f173011
+Node: Arithmetic Operations\7f174477
+Node: Rounding Operations\7f179942
+Node: Bitwise Operations\7f181047
+Node: Math Functions\7f189982
+Node: Random Numbers\7f192298
+Node: Strings and Characters\7f194064
+Node: String Basics\7f195517
+Node: Predicates for Strings\7f197939
+Node: Creating Strings\7f198702
+Node: Predicates for Characters\7f204030
+Node: Character Codes\7f205101
+Node: Text Comparison\7f206514
+Node: String Conversion\7f209876
+Node: Modifying Strings\7f213554
+Node: String Properties\7f214195
+Node: Formatting Strings\7f214838
+Node: Character Case\7f224446
+Node: Case Tables\7f227593
+Node: Char Tables\7f231492
+Node: Char Table Types\7f232884
+Node: Working With Char Tables\7f234459
+Node: Lists\7f236408
+Node: Cons Cells\7f237531
+Node: Lists as Boxes\7f238867
+Node: List-related Predicates\7f241509
+Node: List Elements\7f243211
+Node: Building Lists\7f248240
+Node: Modifying Lists\7f254235
+Node: Setcar\7f255047
+Node: Setcdr\7f257468
+Node: Rearrangement\7f259978
+Node: Sets And Lists\7f265537
+Node: Association Lists\7f269766
+Node: Property Lists\7f279267
+Node: Working With Normal Plists\7f280815
+Node: Working With Lax Plists\7f283083
+Node: Converting Plists To/From Alists\7f285323
+Node: Weak Lists\7f286671
+Node: Sequences Arrays Vectors\7f288836
+Node: Sequence Functions\7f291472
+Node: Arrays\7f295133
+Node: Array Functions\7f298198
+Node: Vectors\7f300731
+Node: Vector Functions\7f302229
+Node: Bit Vectors\7f304803
+Node: Bit Vector Functions\7f305648
+Node: Symbols\7f307899
+Node: Symbol Components\7f308948
+Node: Definitions\7f313127
+Node: Creating Symbols\7f315352
+Node: Symbol Properties\7f322390
+Node: Plists and Alists\7f323906
+Node: Symbol Plists\7f325656
+Node: Other Plists\7f327466
+Node: Evaluation\7f329244
+Node: Intro Eval\7f330049
+Node: Eval\7f333540
+Node: Forms\7f337960
+Node: Self-Evaluating Forms\7f339117
+Node: Symbol Forms\7f340630
+Node: Classifying Lists\7f341547
+Node: Function Indirection\7f342303
+Node: Function Forms\7f345418
+Node: Macro Forms\7f346417
+Node: Special Forms\7f348017
+Node: Autoloading\7f350351
+Node: Quoting\7f350849
+Node: Control Structures\7f352212
+Node: Sequencing\7f353834
+Node: Conditionals\7f356699
+Node: Combining Conditions\7f360122
+Node: Iteration\7f363392
+Node: Nonlocal Exits\7f365177
+Node: Catch and Throw\7f365879
+Node: Examples of Catch\7f369723
+Node: Errors\7f371742
+Node: Signaling Errors\7f373231
+Node: Processing of Errors\7f376299
+Node: Handling Errors\7f377629
+Node: Error Symbols\7f384535
+Node: Cleanups\7f387982
+Node: Variables\7f391762
+Node: Global Variables\7f393531
+Node: Constant Variables\7f394607
+Node: Local Variables\7f395233
+Node: Void Variables\7f400177
+Node: Defining Variables\7f403688
+Node: Accessing Variables\7f410853
+Node: Setting Variables\7f412279
+Node: Variable Scoping\7f416798
+Node: Scope\7f418397
+Node: Extent\7f419922
+Node: Impl of Scope\7f421401
+Node: Using Scoping\7f423364
+Node: Buffer-Local Variables\7f424886
+Node: Intro to Buffer-Local\7f425722
+Node: Creating Buffer-Local\7f428265
+Node: Default Value\7f433485
+Node: Variable Aliases\7f436629
+Node: Functions\7f438415
+Node: What Is a Function\7f439509
+Node: Lambda Expressions\7f443556
+Node: Lambda Components\7f444466
+Node: Simple Lambda\7f446298
+Node: Argument List\7f447957
+Node: Function Documentation\7f451685
+Node: Function Names\7f453627
+Node: Defining Functions\7f456201
+Node: Calling Functions\7f459243
+Node: Mapping Functions\7f463092
+Node: Anonymous Functions\7f465445
+Node: Function Cells\7f468690
+Node: Inline Functions\7f473500
+Node: Related Topics\7f475310
+Node: Macros\7f476363
+Node: Simple Macro\7f477647
+Node: Expansion\7f478382
+Node: Compiling Macros\7f481356
+Node: Defining Macros\7f483194
+Node: Backquote\7f484512
+Node: Problems with Macros\7f486910
+Node: Argument Evaluation\7f487605
+Node: Surprising Local Vars\7f490506
+Node: Eval During Expansion\7f492574
+Node: Repeated Expansion\7f494268
+Node: Customization\7f496179
+Node: Common Keywords\7f496648
+Node: Group Definitions\7f499493
+Node: Variable Definitions\7f501686
+Node: Customization Types\7f506669
+Node: Simple Types\7f508105
+Node: Composite Types\7f510262
+Node: Splicing into Lists\7f514952
+Node: Type Keywords\7f516787
+Node: Loading\7f520307
+Node: How Programs Do Loading\7f521980
+Node: Autoload\7f531109
+Node: Repeated Loading\7f537189
+Node: Named Features\7f539303
+Node: Unloading\7f545736
+Node: Hooks for Loading\7f547892
+Node: Byte Compilation\7f548609
+Node: Speed of Byte-Code\7f550526
+Node: Compilation Functions\7f551733
+Node: Docs and Compilation\7f558122
+Node: Dynamic Loading\7f560775
+Node: Eval During Compile\7f563139
+Node: Compiled-Function Objects\7f564404
+Node: Disassembly\7f569203
+Node: Debugging\7f576457
+Node: Debugger\7f577869
+Node: Error Debugging\7f579014
+Node: Infinite Loops\7f581767
+Node: Function Debugging\7f583011
+Node: Explicit Debug\7f585801
+Node: Using Debugger\7f586573
+Node: Debugger Commands\7f588437
+Node: Invoking the Debugger\7f592754
+Node: Internals of Debugger\7f596669
+Node: Syntax Errors\7f601546
+Node: Excess Open\7f602794
+Node: Excess Close\7f604669
+Node: Compilation Errors\7f606090
+Node: Edebug\7f607378
+Node: Using Edebug\7f609485
+Node: Instrumenting\7f612182
+Node: Edebug Execution Modes\7f615671
+Node: Jumping\7f618781
+Node: Edebug Misc\7f621124
+Node: Breakpoints\7f622513
+Node: Global Break Condition\7f625319
+Node: Embedded Breakpoints\7f626274
+Node: Trapping Errors\7f627229
+Node: Edebug Views\7f629305
+Node: Edebug Eval\7f631270
+Node: Eval List\7f632447
+Node: Reading in Edebug\7f635832
+Node: Printing in Edebug\7f636631
+Node: Tracing\7f638346
+Node: Coverage Testing\7f640232
+Node: The Outside Context\7f642273
+Node: Checking Whether to Stop\7f643222
+Node: Edebug Display Update\7f643868
+Node: Edebug Recursive Edit\7f645890
+Node: Instrumenting Macro Calls\7f647544
+Node: Specification List\7f650026
+Node: Backtracking\7f659437
+Node: Debugging Backquote\7f661375
+Node: Specification Examples\7f665081
+Node: Edebug Options\7f667148
+Node: Read and Print\7f672485
+Node: Streams Intro\7f673462
+Node: Input Streams\7f675480
+Node: Input Functions\7f680381
+Node: Output Streams\7f682441
+Node: Output Functions\7f686493
+Node: Output Variables\7f690793
+Node: Minibuffers\7f695592
+Node: Intro to Minibuffers\7f696677
+Node: Text from Minibuffer\7f699005
+Node: Object from Minibuffer\7f703668
+Node: Minibuffer History\7f706865
+Node: Completion\7f709775
+Node: Basic Completion\7f711750
+Node: Minibuffer Completion\7f716757
+Node: Completion Commands\7f719992
+Node: High-Level Completion\7f724640
+Node: Reading File Names\7f728664
+Node: Programmed Completion\7f732353
+Node: Yes-or-No Queries\7f734563
+Node: Multiple Queries\7f740259
+Node: Minibuffer Misc\7f744324
+Node: Command Loop\7f749193
+Node: Command Overview\7f750539
+Node: Defining Commands\7f753823
+Node: Using Interactive\7f754571
+Node: Interactive Codes\7f759345
+Node: Interactive Examples\7f765149
+Node: Interactive Call\7f766463
+Node: Command Loop Info\7f771866
+Node: Events\7f776845
+Node: Event Types\7f778305
+Node: Event Contents\7f780228
+Node: Event Predicates\7f784704
+Node: Accessing Mouse Event Positions\7f786029
+Node: Frame-Level Event Position Info\7f786728
+Node: Window-Level Event Position Info\7f787768
+Node: Event Text Position Info\7f789532
+Node: Event Glyph Position Info\7f792024
+Node: Event Toolbar Position Info\7f793347
+Node: Other Event Position Info\7f794018
+Node: Accessing Other Event Info\7f794427
+Node: Working With Events\7f796047
+Node: Converting Events\7f801975
+Node: Reading Input\7f804928
+Node: Key Sequence Input\7f805930
+Node: Reading One Event\7f807884
+Node: Dispatching an Event\7f810645
+Node: Quoted Character Input\7f811096
+Node: Peeking and Discarding\7f812444
+Node: Waiting\7f816348
+Node: Quitting\7f818656
+Node: Prefix Command Arguments\7f823064
+Node: Recursive Editing\7f828151
+Node: Disabling Commands\7f832948
+Node: Command History\7f835016
+Node: Keyboard Macros\7f836755
+Node: Keymaps\7f838973
+Node: Keymap Terminology\7f840550
+Node: Format of Keymaps\7f843480
+Node: Creating Keymaps\7f843891
+Node: Inheritance and Keymaps\7f845970
+Node: Key Sequences\7f848342
+Node: Prefix Keys\7f852912
+Node: Active Keymaps\7f856497
+Node: Key Lookup\7f865712
+Node: Functions for Key Lookup\7f870876
+Node: Changing Key Bindings\7f876579
+Node: Key Binding Commands\7f883466
+Node: Scanning Keymaps\7f885532
+Node: Other Keymap Functions\7f894044
+Node: Menus\7f894666
+Node: Menu Format\7f895208
+Node: Menubar Format\7f903793
+Node: Menubar\7f904418
+Node: Modifying Menus\7f907532
+Node: Menu Filters\7f912550
+Node: Pop-Up Menus\7f914446
+Node: Menu Accelerators\7f916652
+Node: Creating Menu Accelerators\7f917374
+Node: Keyboard Menu Traversal\7f918692
+Node: Menu Accelerator Functions\7f919419
+Node: Buffers Menu\7f922454
+Node: Dialog Boxes\7f923748
+Node: Dialog Box Format\7f923915
+Node: Dialog Box Functions\7f925285
+Node: Toolbar\7f925683
+Node: Toolbar Intro\7f926008
+Node: Toolbar Descriptor Format\7f928419
+Node: Specifying the Toolbar\7f932913
+Node: Other Toolbar Variables\7f936521
+Node: Scrollbars\7f940948
+Node: Drag and Drop\7f941084
+Node: Supported Protocols\7f942160
+Node: OffiX DND\7f942663
+Node: CDE dt\7f943670
+Node: MSWindows OLE\7f944261
+Node: Loose ends\7f944432
+Node: Drop Interface\7f944824
+Node: Drag Interface\7f945846
+Node: Modes\7f946020
+Node: Major Modes\7f946971
+Node: Major Mode Conventions\7f949887
+Node: Example Major Modes\7f955842
+Node: Auto Major Mode\7f963810
+Node: Mode Help\7f971260
+Node: Derived Modes\7f972361
+Node: Minor Modes\7f974552
+Node: Minor Mode Conventions\7f975854
+Node: Keymaps and Minor Modes\7f978718
+Node: Modeline Format\7f979553
+Node: Modeline Data\7f981322
+Node: Modeline Variables\7f985594
+Node: %-Constructs\7f990310
+Node: Hooks\7f993221
+Node: Documentation\7f999985
+Node: Documentation Basics\7f1001408
+Node: Accessing Documentation\7f1004460
+Node: Keys in Documentation\7f1010651
+Node: Describing Characters\7f1014114
+Node: Help Functions\7f1016468
+Node: Obsoleteness\7f1022911
+Node: Files\7f1025905
+Node: Visiting Files\7f1027830
+Node: Visiting Functions\7f1029335
+Node: Subroutines of Visiting\7f1034383
+Node: Saving Buffers\7f1036459
+Node: Reading from Files\7f1042552
+Node: Writing to Files\7f1044709
+Node: File Locks\7f1047426
+Node: Information about Files\7f1050479
+Node: Testing Accessibility\7f1051240
+Node: Kinds of Files\7f1054980
+Node: Truenames\7f1056661
+Node: File Attributes\7f1057664
+Node: Changing File Attributes\7f1062804
+Node: File Names\7f1068210
+Node: File Name Components\7f1069819
+Node: Directory Names\7f1072920
+Node: Relative File Names\7f1076373
+Node: File Name Expansion\7f1077451
+Node: Unique File Names\7f1081358
+Node: File Name Completion\7f1082973
+Node: User Name Completion\7f1085634
+Node: Contents of Directories\7f1086974
+Node: Create/Delete Dirs\7f1090287
+Node: Magic File Names\7f1091393
+Node: Partial Files\7f1097023
+Node: Intro to Partial Files\7f1097251
+Node: Creating a Partial File\7f1098491
+Node: Detached Partial Files\7f1099426
+Node: Format Conversion\7f1100548
+Node: Files and MS-DOS\7f1107066
+Node: Backups and Auto-Saving\7f1109130
+Node: Backup Files\7f1109805
+Node: Making Backups\7f1111202
+Node: Rename or Copy\7f1113951
+Node: Numbered Backups\7f1116444
+Node: Backup Names\7f1118689
+Node: Auto-Saving\7f1121972
+Node: Reverting\7f1130114
+Node: Buffers\7f1133272
+Node: Buffer Basics\7f1134687
+Node: Current Buffer\7f1136740
+Node: Buffer Names\7f1141430
+Node: Buffer File Name\7f1144635
+Node: Buffer Modification\7f1148755
+Node: Modification Time\7f1150951
+Node: Read Only Buffers\7f1154326
+Node: The Buffer List\7f1156744
+Node: Creating Buffers\7f1161574
+Node: Killing Buffers\7f1163723
+Node: Indirect Buffers\7f1167454
+Node: Windows\7f1170026
+Node: Basic Windows\7f1171504
+Node: Splitting Windows\7f1174602
+Node: Deleting Windows\7f1181473
+Node: Selecting Windows\7f1184154
+Node: Cyclic Window Ordering\7f1187283
+Node: Buffers and Windows\7f1191907
+Node: Displaying Buffers\7f1193748
+Node: Choosing Window\7f1198926
+Node: Window Point\7f1206642
+Node: Window Start\7f1208688
+Node: Vertical Scrolling\7f1213178
+Node: Horizontal Scrolling\7f1219315
+Node: Size of Window\7f1222824
+Node: Position of Window\7f1227542
+Node: Resizing Windows\7f1229782
+Node: Window Configurations\7f1235211
+Node: Frames\7f1238636
+Node: Creating Frames\7f1240405
+Node: Frame Properties\7f1241746
+Node: Property Access\7f1242562
+Node: Initial Properties\7f1243411
+Node: X Frame Properties\7f1245897
+Node: Size and Position\7f1250531
+Node: Frame Name\7f1252527
+Node: Frame Titles\7f1253441
+Node: Deleting Frames\7f1255265
+Node: Finding All Frames\7f1255865
+Node: Frames and Windows\7f1257859
+Node: Minibuffers and Frames\7f1259564
+Node: Input Focus\7f1260483
+Node: Visibility of Frames\7f1263561
+Node: Raising and Lowering\7f1265480
+Node: Frame Configurations\7f1267857
+Node: Frame Hooks\7f1268451
+Node: Consoles and Devices\7f1270258
+Node: Basic Console Functions\7f1273002
+Node: Basic Device Functions\7f1273425
+Node: Console Types and Device Classes\7f1274141
+Node: Connecting to a Console or Device\7f1276338
+Node: The Selected Console and Device\7f1278501
+Node: Console and Device I/O\7f1279527
+Node: Positions\7f1280291
+Node: Point\7f1281260
+Node: Motion\7f1284353
+Node: Character Motion\7f1285120
+Node: Word Motion\7f1287357
+Node: Buffer End Motion\7f1288858
+Node: Text Lines\7f1290355
+Node: Screen Lines\7f1294950
+Node: List Motion\7f1299013
+Node: Skipping Characters\7f1302421
+Node: Excursions\7f1304640
+Node: Narrowing\7f1307675
+Node: Markers\7f1313002
+Node: Overview of Markers\7f1313904
+Node: Predicates on Markers\7f1318597
+Node: Creating Markers\7f1319843
+Node: Information from Markers\7f1323880
+Node: Changing Markers\7f1324978
+Node: The Mark\7f1326356
+Node: The Region\7f1334850
+Node: Text\7f1340537
+Node: Near Point\7f1343239
+Node: Buffer Contents\7f1346961
+Node: Comparing Text\7f1348367
+Node: Insertion\7f1349775
+Node: Commands for Insertion\7f1353618
+Node: Deletion\7f1356576
+Node: User-Level Deletion\7f1360173
+Node: The Kill Ring\7f1364303
+Node: Kill Ring Concepts\7f1366477
+Node: Kill Functions\7f1367531
+Node: Yank Commands\7f1369436
+Node: Low-Level Kill Ring\7f1371307
+Node: Internals of Kill Ring\7f1374093
+Node: Undo\7f1376873
+Node: Maintaining Undo\7f1381202
+Node: Filling\7f1383822
+Node: Margins\7f1389818
+Node: Auto Filling\7f1393748
+Node: Sorting\7f1394929
+Node: Columns\7f1404230
+Node: Indentation\7f1406746
+Node: Primitive Indent\7f1407525
+Node: Mode-Specific Indent\7f1408769
+Node: Region Indent\7f1411280
+Node: Relative Indent\7f1414228
+Node: Indent Tabs\7f1416610
+Node: Motion by Indent\7f1417932
+Node: Case Changes\7f1418711
+Node: Text Properties\7f1421962
+Node: Examining Properties\7f1423777
+Node: Changing Properties\7f1425644
+Node: Property Search\7f1429239
+Node: Special Properties\7f1433950
+Node: Saving Properties\7f1434231
+Node: Substitution\7f1437373
+Node: Registers\7f1440644
+Node: Transposition\7f1443187
+Node: Change Hooks\7f1444081
+Node: Transformations\7f1446121
+Node: Searching and Matching\7f1450506
+Node: String Search\7f1451637
+Node: Regular Expressions\7f1456361
+Node: Syntax of Regexps\7f1457728
+Node: Regexp Example\7f1472108
+Node: Regexp Search\7f1474278
+Node: POSIX Regexps\7f1480366
+Node: Search and Replace\7f1482201
+Node: Match Data\7f1485566
+Node: Simple Match Data\7f1486696
+Node: Replacing Match\7f1490961
+Node: Entire Match Data\7f1493295
+Node: Saving Match Data\7f1495286
+Node: Searching and Case\7f1496669
+Node: Standard Regexps\7f1498703
+Node: Syntax Tables\7f1500901
+Node: Syntax Basics\7f1502017
+Node: Syntax Descriptors\7f1504992
+Node: Syntax Class Table\7f1506842
+Node: Syntax Flags\7f1512880
+Node: Syntax Table Functions\7f1516097
+Node: Motion and Syntax\7f1519961
+Node: Parsing Expressions\7f1521413
+Node: Standard Syntax Tables\7f1527482
+Node: Syntax Table Internals\7f1528326
+Node: Abbrevs\7f1529353
+Node: Abbrev Mode\7f1531157
+Node: Abbrev Tables\7f1531877
+Node: Defining Abbrevs\7f1533410
+Node: Abbrev Files\7f1535315
+Node: Abbrev Expansion\7f1537089
+Node: Standard Abbrev Tables\7f1541720
+Node: Extents\7f1542879
+Node: Intro to Extents\7f1544122
+Node: Creating and Modifying Extents\7f1548116
+Node: Extent Endpoints\7f1549625
+Node: Finding Extents\7f1552890
+Node: Mapping Over Extents\7f1556641
+Node: Extent Properties\7f1562759
+Node: Detached Extents\7f1572903
+Node: Extent Parents\7f1574762
+Node: Duplicable Extents\7f1576457
+Node: Extents and Events\7f1579680
+Node: Atomic Extents\7f1581588
+Node: Specifiers\7f1582035
+Node: Introduction to Specifiers\7f1583838
+Node: Specifiers In-Depth\7f1586148
+Node: Specifier Instancing\7f1591063
+Node: Specifier Types\7f1594325
+Node: Adding Specifications\7f1599399
+Node: Retrieving Specifications\7f1608762
+Node: Specifier Tag Functions\7f1612497
+Node: Specifier Instancing Functions\7f1615731
+Node: Specifier Example\7f1619138
+Node: Creating Specifiers\7f1622244
+Node: Specifier Validation Functions\7f1624493
+Node: Other Specification Functions\7f1626877
+Node: Faces and Window-System Objects\7f1630696
+Node: Faces\7f1631020
+Node: Merging Faces\7f1632639
+Node: Basic Face Functions\7f1634600
+Node: Face Properties\7f1636699
+Node: Face Convenience Functions\7f1646258
+Node: Other Face Display Functions\7f1649391
+Node: Fonts\7f1650204
+Node: Font Specifiers\7f1650905
+Node: Font Instances\7f1651146
+Node: Font Instance Names\7f1652113
+Node: Font Instance Size\7f1652954
+Node: Font Instance Characteristics\7f1654240
+Node: Font Convenience Functions\7f1655409
+Node: Colors\7f1656699
+Node: Color Specifiers\7f1657139
+Node: Color Instances\7f1657366
+Node: Color Instance Properties\7f1658110
+Node: Color Convenience Functions\7f1658736
+Node: Glyphs\7f1659789
+Node: Glyph Functions\7f1661381
+Node: Creating Glyphs\7f1661788
+Node: Glyph Properties\7f1663375
+Node: Glyph Convenience Functions\7f1672542
+Node: Glyph Dimensions\7f1676489
+Node: Images\7f1677569
+Node: Image Specifiers\7f1678018
+Node: Image Instantiator Conversion\7f1689442
+Node: Image Instances\7f1690807
+Node: Image Instance Types\7f1691558
+Node: Image Instance Functions\7f1694213
+Node: Glyph Types\7f1698783
+Node: Mouse Pointer\7f1700555
+Node: Redisplay Glyphs\7f1703558
+Node: Subwindows\7f1704591
+Node: Annotations\7f1704834
+Node: Annotation Basics\7f1705851
+Node: Annotation Primitives\7f1709789
+Node: Annotation Properties\7f1711118
+Node: Locating Annotations\7f1714158
+Node: Margin Primitives\7f1714995
+Node: Annotation Hooks\7f1716889
+Node: Display\7f1717549
+Node: Refresh Screen\7f1718527
+Node: Truncation\7f1720438
+Node: The Echo Area\7f1722965
+Node: Warnings\7f1729401
+Node: Invisible Text\7f1733837
+Node: Selective Display\7f1736417
+Node: Overlay Arrow\7f1740544
+Node: Temporary Displays\7f1741898
+Node: Blinking\7f1746019
+Node: Usual Display\7f1748203
+Node: Display Tables\7f1750753
+Node: Display Table Format\7f1751557
+Node: Active Display Table\7f1753001
+Node: Character Descriptors\7f1754193
+Node: Beeping\7f1754951
+Node: Hash Tables\7f1759717
+Node: Introduction to Hash Tables\7f1760325
+Node: Working With Hash Tables\7f1766350
+Node: Weak Hash Tables\7f1767467
+Node: Range Tables\7f1769266
+Node: Introduction to Range Tables\7f1769955
+Node: Working With Range Tables\7f1770386
+Node: Databases\7f1771271
+Node: Connecting to a Database\7f1771570
+Node: Working With a Database\7f1772661
+Node: Other Database Functions\7f1773519
+Node: Processes\7f1774093
+Node: Subprocess Creation\7f1776317
+Node: Synchronous Processes\7f1779610
+Node: MS-DOS Subprocesses\7f1786308
+Node: Asynchronous Processes\7f1787382
+Node: Deleting Processes\7f1791086
+Node: Process Information\7f1792957
+Node: Input to Processes\7f1796885
+Node: Signals to Processes\7f1799154
+Node: Output from Processes\7f1803574
+Node: Process Buffers\7f1804386
+Node: Filter Functions\7f1807255
+Node: Accepting Output\7f1812822
+Node: Sentinels\7f1814349
+Node: Process Window Size\7f1817842
+Node: Transaction Queues\7f1818191
+Node: Network\7f1819889
+Node: System Interface\7f1821723
+Node: Starting Up\7f1822993
+Node: Start-up Summary\7f1823587
+Node: Init File\7f1827141
+Node: Terminal-Specific\7f1829525
+Node: Command Line Arguments\7f1832684
+Node: Getting Out\7f1836173
+Node: Killing XEmacs\7f1836742
+Node: Suspending XEmacs\7f1838411
+Node: System Environment\7f1841727
+Node: User Identification\7f1848392
+Node: Time of Day\7f1851922
+Node: Time Conversion\7f1854711
+Node: Timers\7f1859753
+Node: Terminal Input\7f1861926
+Node: Input Modes\7f1862429
+Node: Translating Input\7f1864842
+Node: Recording Input\7f1869007
+Node: Terminal Output\7f1871108
+Node: Flow Control\7f1874731
+Node: Batch Mode\7f1878524
+Node: X-Windows\7f1879906
+Node: X Selections\7f1880718
+Node: X Server\7f1882928
+Node: Resources\7f1883329
+Node: Server Data\7f1888470
+Node: Grabs\7f1889677
+Node: X Miscellaneous\7f1891258
+Node: ToolTalk Support\7f1893643
+Node: XEmacs ToolTalk API Summary\7f1893860
+Node: Sending Messages\7f1895160
+Node: Example of Sending Messages\7f1895411
+Node: Elisp Interface for Sending Messages\7f1896473
+Node: Receiving Messages\7f1902866
+Node: Example of Receiving Messages\7f1903089
+Node: Elisp Interface for Receiving Messages\7f1903925
+Node: LDAP Support\7f1907750
+Node: Building XEmacs with LDAP support\7f1908246
+Node: XEmacs LDAP API\7f1909224
+Node: LDAP Variables\7f1909954
+Node: The High-Level LDAP API\7f1912431
+Node: The Low-Level LDAP API\7f1913544
+Node: The LDAP Lisp Object\7f1913818
+Node: Opening and Closing a LDAP Connection\7f1914371
+Node: Searching on a LDAP Server (Low-level)\7f1916154
+Node: Syntax of Search Filters\7f1917549
+Node: Internationalization\7f1918847
+Node: I18N Levels 1 and 2\7f1919184
+Node: I18N Level 3\7f1919890
+Node: Level 3 Basics\7f1920171
+Node: Level 3 Primitives\7f1921004
+Node: Dynamic Messaging\7f1922610
+Node: Domain Specification\7f1923073
+Node: Documentation String Extraction\7f1924976
+Node: I18N Level 4\7f1925894
+Node: MULE\7f1926086
+Node: Internationalization Terminology\7f1927197
+Node: Charsets\7f1935736
+Node: Charset Properties\7f1936432
+Node: Basic Charset Functions\7f1941118
+Node: Charset Property Functions\7f1943299
+Node: Predefined Charsets\7f1945342
+Node: MULE Characters\7f1948262
+Node: Composite Characters\7f1949109
+Node: ISO 2022\7f1950363
+Node: Coding Systems\7f1956085
+Node: Coding System Types\7f1958007
+Node: EOL Conversion\7f1959826
+Node: Coding System Properties\7f1961009
+Node: Basic Coding System Functions\7f1964861
+Node: Coding System Property Functions\7f1966765
+Node: Encoding and Decoding Text\7f1967323
+Node: Detection of Textual Encoding\7f1968459
+Node: Big5 and Shift-JIS Functions\7f1969995
+Node: CCL\7f1971083
+Node: CCL Syntax\7f1974187
+Node: CCL Statements\7f1975775
+Node: CCL Expressions\7f1980423
+Node: Calling CCL\7f1983575
+Node: CCL Examples\7f1986565
+Node: Category Tables\7f1986702
+Node: Tips\7f1989061
+Node: Style Tips\7f1989702
+Node: Compilation Tips\7f1999222
+Node: Documentation Tips\7f2001138
+Node: Comment Tips\7f2006647
+Node: Library Headers\7f2009649
+Node: Building XEmacs and Object Allocation\7f2013621
+Node: Building XEmacs\7f2014504
+Node: Pure Storage\7f2020839
+Node: Garbage Collection\7f2023627
+Node: Standard Errors\7f2034766
+Node: Standard Buffer-Local Variables\7f2038975
+Node: Standard Keymaps\7f2041651
+Node: Standard Hooks\7f2045383
+Node: Index\7f2052883
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
+
+ This Info file contains the third edition of the XEmacs Lisp
+Reference Manual, corresponding to XEmacs version 21.0.
+
+* Menu:
+
+* Copying:: Conditions for copying and changing XEmacs.
+* Introduction:: Introduction and conventions used.
+
+* Lisp Data Types:: Data types of objects in XEmacs Lisp.
+* Numbers:: Numbers and arithmetic functions.
+* Strings and Characters:: Strings, and functions that work on them.
+* Lists:: Lists, cons cells, and related functions.
+* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences.
+ Certain functions act on any kind of sequence.
+ The description of vectors is here as well.
+* Symbols:: Symbols represent names, uniquely.
+
+* Evaluation:: How Lisp expressions are evaluated.
+* Control Structures:: Conditionals, loops, nonlocal exits.
+* Variables:: Using symbols in programs to stand for values.
+* Functions:: A function is a Lisp program
+ that can be invoked from other functions.
+* Macros:: Macros are a way to extend the Lisp language.
+* Customization:: Writing customization declarations.
+
+* Loading:: Reading files of Lisp code into Lisp.
+* Byte Compilation:: Compilation makes programs run faster.
+* Debugging:: Tools and tips for debugging Lisp programs.
+
+* Read and Print:: Converting Lisp objects to text and back.
+* Minibuffers:: Using the minibuffer to read input.
+* Command Loop:: How the editor command loop works,
+ and how you can call its subroutines.
+* Keymaps:: Defining the bindings from keys to commands.
+* Menus:: Defining pull-down and pop-up menus.
+* Dialog Boxes:: Creating dialog boxes.
+* Toolbar:: Controlling the toolbar.
+* Scrollbars:: Controlling the scrollbars.
+* Drag and Drop:: Generic API to inter-application communication
+ via specific protocols.
+* Modes:: Defining major and minor modes.
+* Documentation:: Writing and using documentation strings.
+
+* Files:: Accessing files.
+* Backups and Auto-Saving:: Controlling how backups and auto-save
+ files are made.
+* Buffers:: Creating and using buffer objects.
+* Windows:: Manipulating windows and displaying buffers.
+* Frames:: Making multiple X windows.
+* Consoles and Devices:: Opening frames on multiple TTY's or X displays.
+* Positions:: Buffer positions and motion functions.
+* Markers:: Markers represent positions and update
+ automatically when the text is changed.
+
+* Text:: Examining and changing text in buffers.
+* Searching and Matching:: Searching buffers for strings or regexps.
+* Syntax Tables:: The syntax table controls word and list parsing.
+* Abbrevs:: How Abbrev mode works, and its data structures.
+
+* Extents:: Extents are regions of text with particular
+ display characteristics.
+* Specifiers:: How faces and glyphs are specified.
+* Faces and Window-System Objects::
+ A face is a set of display characteristics
+ specifying how text is to be displayed.
+* Glyphs:: General interface to pixmaps displayed in a
+ buffer or frame.
+* Annotations:: Higher-level interface to glyphs in a buffer.
+* Display:: Parameters controlling screen usage.
+ The bell. Waiting for input.
+
+* Hash Tables:: Fast data structures for mappings.
+* Range Tables:: Keeping track of ranges of numbers.
+* Databases:: An interface to standard DBM and DB databases.
+
+* Processes:: Running and communicating with subprocesses.
+* System Interface:: Getting the user id, system type, environment
+ variables, and other such things.
+* X-Windows:: Functions specific to the X Window System.
+* ToolTalk Support:: Interfacing with the ToolTalk message service.
+* LDAP Support:: Interfacing with the Lightweight Directory
+ Access Protocol.
+* Internationalization:: How Emacs supports different languages and
+ cultural conventions.
+* MULE:: Specifics of the Asian-language support.
+
+Appendices
+
+* Tips:: Advice for writing Lisp programs.
+* Building XEmacs and Object Allocation::
+ Behind-the-scenes information about XEmacs.
+* Standard Errors:: List of all error symbols.
+* Standard Buffer-Local Variables:: List of variables local in all buffers.
+* Standard Keymaps:: List of standard keymaps.
+* Standard Hooks:: List of standard hook variables.
+
+* Index:: Index including concepts, functions, variables,
+ and other terms.
+
+ -- The Detailed Node Listing --
+
+Here are other nodes that are inferiors of those already listed,
+mentioned here so you can get to them in one step:
+
+Introduction
+
+* Caveats:: Flaws and a request for help.
+* Lisp History:: XEmacs Lisp is descended from Maclisp.
+* Conventions:: How the manual is formatted.
+* Acknowledgements:: The authors, editors, and sponsors of this manual.
+
+Conventions
+
+* Some Terms:: Explanation of terms we use in this manual.
+* nil and t:: How the symbols `nil' and `t' are used.
+* Evaluation Notation:: The format we use for examples of evaluation.
+* Printing Notation:: The format we use for examples that print output.
+* Error Messages:: The format we use for examples of errors.
+* Buffer Text Notation:: The format we use for buffer contents in examples.
+* Format of Descriptions:: Notation for describing functions, variables, etc.
+
+Format of Descriptions
+
+* A Sample Function Description::
+* A Sample Variable Description::
+
+Lisp Data Types
+
+* Printed Representation:: How Lisp objects are represented as text.
+* Comments:: Comments and their formatting conventions.
+* Programming Types:: Types found in all Lisp systems.
+* Editing Types:: Types specific to XEmacs.
+* Type Predicates:: Tests related to types.
+* Equality Predicates:: Tests of equality between any two objects.
+
+Programming Types
+
+* Integer Type:: Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type:: The representation of letters, numbers and
+ control characters.
+* Sequence Type:: Both lists and arrays are classified as sequences.
+* Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
+* Array Type:: Arrays include strings and vectors.
+* String Type:: An (efficient) array of characters.
+* Vector Type:: One-dimensional arrays.
+* Symbol Type:: A multi-use object that refers to a function,
+ variable, property list, or itself.
+* Function Type:: A piece of executable code you can call from elsewhere.
+* Macro Type:: A method of expanding an expression into another
+ expression, more fundamental but less pretty.
+* Primitive Function Type:: A function written in C, callable from Lisp.
+* Compiled-Function Type:: A function written in Lisp, then compiled.
+* Autoload Type:: A type used for automatically loading seldom-used
+ functions.
+
+Cons Cell Type
+
+* Dotted Pair Notation:: An alternative syntax for lists.
+* Association List Type:: A specially constructed list.
+
+Editing Types
+
+* Buffer Type:: The basic object of editing.
+* Window Type:: What makes buffers visible.
+* Window Configuration Type::Save what the screen looks like.
+* Marker Type:: A position in a buffer.
+* Process Type:: A process running on the underlying OS.
+* Stream Type:: Receive or send characters.
+* Keymap Type:: What function a keystroke invokes.
+* Syntax Table Type:: What a character means.
+
+Numbers
+
+* Integer Basics:: Representation and range of integers.
+* Float Basics:: Representation and range of floating point.
+* Predicates on Numbers:: Testing for numbers.
+* Comparison of Numbers:: Equality and inequality predicates.
+* Arithmetic Operations:: How to add, subtract, multiply and divide.
+* Bitwise Operations:: Logical and, or, not, shifting.
+* Numeric Conversions:: Converting float to integer and vice versa.
+* Math Functions:: Trig, exponential and logarithmic functions.
+* Random Numbers:: Obtaining random integers, predictable or not.
+
+Strings and Characters
+
+* Basics: String Basics. Basic properties of strings and characters.
+* Predicates for Strings:: Testing whether an object is a string or char.
+* Creating Strings:: Functions to allocate new strings.
+* Predicates for Characters:: Testing whether an object is a character.
+* Character Codes:: Each character has an equivalent integer.
+* Text Comparison:: Comparing characters or strings.
+* String Conversion:: Converting characters or strings and vice versa.
+* Modifying Strings:: Changing characters in a string.
+* String Properties:: Additional information attached to strings.
+* Formatting Strings:: `format': XEmacs's analog of `printf'.
+* Character Case:: Case conversion functions.
+* Char Tables:: Mapping from characters to Lisp objects.
+* Case Tables:: Customizing case conversion.
+
+Lists
+
+* Cons Cells:: How lists are made out of cons cells.
+* Lists as Boxes:: Graphical notation to explain lists.
+* List-related Predicates:: Is this object a list? Comparing two lists.
+* List Elements:: Extracting the pieces of a list.
+* Building Lists:: Creating list structure.
+* Modifying Lists:: Storing new pieces into an existing list.
+* Sets And Lists:: A list can represent a finite mathematical set.
+* Association Lists:: A list can represent a finite relation or mapping.
+* Property Lists:: A different way to represent a finite mapping.
+* Weak Lists:: A list with special garbage-collection behavior.
+
+Modifying Existing List Structure
+
+* Setcar:: Replacing an element in a list.
+* Setcdr:: Replacing part of the list backbone.
+ This can be used to remove or add elements.
+* Rearrangement:: Reordering the elements in a list; combining lists.
+
+Sequences, Arrays, and Vectors
+
+* Sequence Functions:: Functions that accept any kind of sequence.
+* Arrays:: Characteristics of arrays in XEmacs Lisp.
+* Array Functions:: Functions specifically for arrays.
+* Vectors:: Functions specifically for vectors.
+
+Symbols
+
+* Symbol Components:: Symbols have names, values, function definitions
+ and property lists.
+* Definitions:: A definition says how a symbol will be used.
+* Creating Symbols:: How symbols are kept unique.
+* Symbol Properties:: Each symbol has a property list
+ for recording miscellaneous information.
+
+Evaluation
+
+* Intro Eval:: Evaluation in the scheme of things.
+* Eval:: How to invoke the Lisp interpreter explicitly.
+* Forms:: How various sorts of objects are evaluated.
+* Quoting:: Avoiding evaluation (to put constants in
+ the program).
+
+Kinds of Forms
+
+* Self-Evaluating Forms:: Forms that evaluate to themselves.
+* Symbol Forms:: Symbols evaluate as variables.
+* Classifying Lists:: How to distinguish various sorts of list forms.
+* Function Forms:: Forms that call functions.
+* Macro Forms:: Forms that call macros.
+* Special Forms:: "Special forms" are idiosyncratic primitives,
+ most of them extremely important.
+* Autoloading:: Functions set up to load files
+ containing their real definitions.
+
+Control Structures
+
+* Sequencing:: Evaluation in textual order.
+* Conditionals:: `if', `cond'.
+* Combining Conditions:: `and', `or', `not'.
+* Iteration:: `while' loops.
+* Nonlocal Exits:: Jumping out of a sequence.
+
+Nonlocal Exits
+
+* Catch and Throw:: Nonlocal exits for the program's own purposes.
+* Examples of Catch:: Showing how such nonlocal exits can be written.
+* Errors:: How errors are signaled and handled.
+* Cleanups:: Arranging to run a cleanup form if an
+ error happens.
+
+Errors
+
+* Signaling Errors:: How to report an error.
+* Processing of Errors:: What XEmacs does when you report an error.
+* Handling Errors:: How you can trap errors and continue execution.
+* Error Symbols:: How errors are classified for trapping them.
+
+Variables
+
+* Global Variables:: Variable values that exist permanently, everywhere.
+* Constant Variables:: Certain "variables" have values that never change.
+* Local Variables:: Variable values that exist only temporarily.
+* Void Variables:: Symbols that lack values.
+* Defining Variables:: A definition says a symbol is used as a variable.
+* Accessing Variables:: Examining values of variables whose names
+ are known only at run time.
+* Setting Variables:: Storing new values in variables.
+* Variable Scoping:: How Lisp chooses among local and global values.
+* Buffer-Local Variables:: Variable values in effect only in one buffer.
+
+Scoping Rules for Variable Bindings
+
+* Scope:: Scope means where in the program a value
+ is visible. Comparison with other languages.
+* Extent:: Extent means how long in time a value exists.
+* Impl of Scope:: Two ways to implement dynamic scoping.
+* Using Scoping:: How to use dynamic scoping carefully and
+ avoid problems.
+
+Buffer-Local Variables
+
+* Intro to Buffer-Local:: Introduction and concepts.
+* Creating Buffer-Local:: Creating and destroying buffer-local bindings.
+* Default Value:: The default value is seen in buffers
+ that don't have their own local values.
+
+Functions
+
+* What Is a Function:: Lisp functions vs primitives; terminology.
+* Lambda Expressions:: How functions are expressed as Lisp objects.
+* Function Names:: A symbol can serve as the name of a function.
+* Defining Functions:: Lisp expressions for defining functions.
+* Calling Functions:: How to use an existing function.
+* Mapping Functions:: Applying a function to each element of a list, etc.
+* Anonymous Functions:: Lambda-expressions are functions with no names.
+* Function Cells:: Accessing or setting the function definition
+ of a symbol.
+* Related Topics:: Cross-references to specific Lisp primitives
+ that have a special bearing on how
+ functions work.
+
+Lambda Expressions
+
+* Lambda Components:: The parts of a lambda expression.
+* Simple Lambda:: A simple example.
+* Argument List:: Details and special features of argument lists.
+* Function Documentation:: How to put documentation in a function.
+
+Macros
+
+* 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.
+
+Loading
+
+* How Programs Do Loading:: The `load' function and others.
+* Autoload:: Setting up a function to autoload.
+* Named Features:: Loading a library if it isn't already loaded.
+* Repeated Loading:: Precautions about loading a file twice.
+
+Byte Compilation
+
+* Compilation Functions:: Byte compilation functions.
+* Disassembly:: Disassembling byte-code; how to read byte-code.
+
+Debugging Lisp Programs
+
+* 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.
+
+The Lisp Debugger
+
+* Error Debugging:: Entering the debugger when an error happens.
+* 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.
+
+Debugging Invalid Lisp Syntax
+
+* Excess Open:: How to find a spurious open paren or missing close.
+* Excess Close:: How to find a spurious close paren or missing open.
+
+Reading and Printing Lisp Objects
+
+* 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.
+
+Minibuffers
+
+* Intro to Minibuffers:: Basic information about minibuffers.
+* Text from Minibuffer:: How to read a straight text string.
+* Object from Minibuffer:: How to read a Lisp object or expression.
+* Completion:: How to invoke and customize completion.
+* Yes-or-No Queries:: Asking a question with a simple answer.
+* Minibuffer Misc:: Various customization hooks and variables.
+
+Completion
+
+* Basic Completion:: Low-level functions for completing strings.
+ (These are too low level to use the minibuffer.)
+* Minibuffer Completion:: Invoking the minibuffer with completion.
+* Completion Commands:: Minibuffer commands that do completion.
+* High-Level Completion:: Convenient special cases of completion
+ (reading buffer name, file name, etc.)
+* Reading File Names:: Using completion to read file names.
+* Programmed Completion:: Finding the completions for a given file name.
+
+Command Loop
+
+* Command Overview:: How the command loop reads commands.
+* Defining Commands:: Specifying how a function should read arguments.
+* Interactive Call:: Calling a command, so that it will read arguments.
+* Command Loop Info:: Variables set by the command loop for you to examine.
+* Events:: What input looks like when you read it.
+* Reading Input:: How to read input events from the keyboard or mouse.
+* Waiting:: Waiting for user input or elapsed time.
+* Quitting:: How `C-g' works. How to catch or defer quitting.
+* Prefix Command Arguments:: How the commands to set prefix args work.
+* Recursive Editing:: Entering a recursive edit,
+ and why you usually shouldn't.
+* Disabling Commands:: How the command loop handles disabled commands.
+* Command History:: How the command history is set up, and how accessed.
+* Keyboard Macros:: How keyboard macros are implemented.
+
+Defining Commands
+
+* Using Interactive:: General rules for `interactive'.
+* Interactive Codes:: The standard letter-codes for reading arguments
+ in various ways.
+* Interactive Examples:: Examples of how to read interactive arguments.
+
+Events
+
+* Event Types:: Events come in different types.
+* Event Contents:: What the contents of each event type are.
+* Event Predicates:: Querying whether an event is of a
+ particular type.
+* Accessing Mouse Event Positions::
+ Determining where a mouse event occurred,
+ and over what.
+* Accessing Other Event Info:: Accessing non-positional event info.
+* Working With Events:: Creating, copying, and destroying events.
+* Converting Events:: Converting between events, keys, and
+ characters.
+
+Accessing Mouse Event Positions
+
+* Frame-Level Event Position Info::
+* Window-Level Event Position Info::
+* Event Text Position Info::
+* Event Glyph Position Info::
+* Event Toolbar Position Info::
+* Other Event Position Info::
+
+Reading Input
+
+* 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.
+
+Keymaps
+
+* Keymap Terminology:: Definitions of terms pertaining to keymaps.
+* Format of Keymaps:: What a keymap looks like as a Lisp object.
+* Creating Keymaps:: Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+ of another keymap.
+* Key Sequences:: How to specify key sequences.
+* Prefix Keys:: Defining a key with a keymap as its definition.
+* Active Keymaps:: Each buffer has a local keymap
+ to override the standard (global) bindings.
+ Each minor mode can also override them.
+* Key Lookup:: How extracting elements from keymaps works.
+* Functions for Key Lookup:: How to request key lookup.
+* Changing Key Bindings:: Redefining a key in a keymap.
+* Key Binding Commands:: Interactive interfaces for redefining keys.
+* Scanning Keymaps:: Looking through all keymaps, for printing help.
+* Other Keymap Functions:: Miscellaneous keymap functions.
+
+Menus
+
+* Menu Format:: Format of a menu description.
+* Menubar Format:: How to specify a menubar.
+* Menubar:: Functions for controlling the menubar.
+* Modifying Menus:: Modifying a menu description.
+* Pop-Up Menus:: Functions for specifying pop-up menus.
+* Menu Filters:: Filter functions for the default menubar.
+* Buffers Menu:: The menu that displays the list of buffers.
+
+Dialog Boxes
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+Toolbar
+
+* Toolbar Intro:: An introduction.
+* Toolbar Descriptor Format:: How to create a toolbar.
+* Specifying the Toolbar:: Setting a toolbar.
+* Other Toolbar Variables:: Controlling the size of toolbars.
+
+Scrollbars
+
+Major and Minor Modes
+
+* Major Modes:: Defining major modes.
+* Minor Modes:: Defining minor modes.
+* Modeline Format:: Customizing the text that appears in the modeline.
+* Hooks:: How to use hooks; how to write code that
+ provides hooks.
+
+Major Modes
+
+* Major Mode Conventions:: Coding conventions for keymaps, etc.
+* Example Major Modes:: Text mode and Lisp modes.
+* Auto Major Mode:: How XEmacs chooses the major mode automatically.
+* Mode Help:: Finding out how to use a mode.
+
+Minor Modes
+
+* Minor Mode Conventions:: Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+
+Modeline Format
+
+* Modeline Data:: The data structure that controls the modeline.
+* Modeline Variables:: Variables used in that data structure.
+* %-Constructs:: Putting information into a modeline.
+
+Documentation
+
+* Documentation Basics:: Good style for doc strings.
+ Where to put them. How XEmacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation:: Substituting current key bindings.
+* Describing Characters:: Making printable descriptions of
+ non-printing characters and key sequences.
+* Help Functions:: Subroutines used by XEmacs help facilities.
+
+Files
+
+* Visiting Files:: Reading files into Emacs buffers for editing.
+* Saving Buffers:: Writing changed buffers back into files.
+* Reading from Files:: Reading files into other buffers.
+* 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.
+* Contents of Directories:: Getting a list of the files in a directory.
+* Changing File Attributes:: Renaming files, changing protection, etc.
+* File Names:: Decomposing and expanding file names.
+
+Visiting Files
+
+* Visiting Functions:: The usual interface functions for visiting.
+* Subroutines of Visiting:: Lower-level subroutines that they use.
+
+Information about Files
+
+* Testing Accessibility:: Is a given file readable? Writable?
+* Kinds of Files:: Is it a directory? A link?
+* File Attributes:: How large is it? Any other names? Etc.
+
+File Names
+
+* 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.
+
+Backups and Auto-Saving
+
+* Backup Files:: How backup files are made; how their names
+ are chosen.
+* Auto-Saving:: How auto-save files are made; how their
+ names are chosen.
+* Reverting:: `revert-buffer', and how to customize
+ what it does.
+
+Backup Files
+
+* Making Backups:: How XEmacs makes backup files, and when.
+* Rename or Copy:: Two alternatives: renaming the old file
+ or copying it.
+* Numbered Backups:: Keeping multiple backups for each source file.
+* Backup Names:: How backup file names are computed; customization.
+
+Buffers
+
+* Buffer Basics:: What is a buffer?
+* 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.
+* Current Buffer:: Designating a buffer as current
+ so primitives will access its contents.
+
+Windows
+
+* 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.
+* 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.
+* Resizing Windows:: Changing the size of a window.
+* Window Configurations:: Saving and restoring the state of the screen.
+
+Frames
+
+* Creating Frames:: Creating additional frames.
+* Frame Properties:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
+* Deleting Frames:: Frames last until explicitly deleted.
+* Finding All Frames:: How to examine all existing frames.
+* Frames and Windows:: A frame contains windows;
+ display of text always works through windows.
+* Minibuffers and Frames:: How a frame finds the minibuffer to use.
+* Input Focus:: Specifying the selected frame.
+* Visibility of Frames:: Frames may be visible or invisible, or icons.
+* Raising and Lowering:: Raising a frame makes it hide other X windows;
+ lowering it makes the others hide them.
+* Frame Hooks:: Hooks for customizing frame behavior.
+
+Positions
+
+* Point:: The special position where editing takes place.
+* Motion:: Changing point.
+* Excursions:: Temporary motion and buffer changes.
+* Narrowing:: Restricting editing to a portion of the buffer.
+
+Motion
+
+* Character Motion:: Moving in terms of characters.
+* Word Motion:: Moving in terms of words.
+* Buffer End Motion:: Moving to the beginning or end of the buffer.
+* Text Lines:: Moving in terms of lines of text.
+* Screen Lines:: Moving in terms of lines as displayed.
+* List Motion:: Moving by parsing lists and sexps.
+* Skipping Characters:: Skipping characters belonging to a certain set.
+
+Markers
+
+* 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".
+
+Text
+
+* Near Point:: Examining text in the vicinity of point.
+* Buffer Contents:: Examining text in a general fashion.
+* Comparing Text:: Comparing substrings of buffers.
+* Insertion:: Adding new text to a buffer.
+* Commands for Insertion:: User-level commands to insert text.
+* Deletion:: Removing text from a buffer.
+* User-Level Deletion:: User-level commands to delete text.
+* The Kill Ring:: Where removed text sometimes is saved for later use.
+* Undo:: Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+ How to control how much information is kept.
+* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
+* Auto Filling:: How auto-fill mode is implemented to break lines.
+* Sorting:: Functions for sorting parts of the buffer.
+* Columns:: Computing horizontal positions, and using them.
+* Indentation:: Functions to insert or adjust indentation.
+* Case Changes:: Case conversion of parts of the buffer.
+* Text Properties:: Assigning Lisp property lists to text characters.
+* Substitution:: Replacing a given character wherever it appears.
+* Registers:: How registers are implemented. Accessing the text or
+ position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
+* Change Hooks:: Supplying functions to be run when text is changed.
+
+The Kill Ring
+
+* 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.
+
+Indentation
+
+* 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.
+
+Searching and Matching
+
+* String Search:: Search for an exact match.
+* Regular Expressions:: Describing classes of strings.
+* Regexp Search:: Searching for a match for a regexp.
+* Match Data:: Finding out which part of the text matched
+ various parts of a regexp, after regexp search.
+* Saving Match Data:: Saving and restoring this information.
+* Standard Regexps:: Useful regexps for finding sentences, pages,...
+* Searching and Case:: Case-independent or case-significant searching.
+
+Regular Expressions
+
+* Syntax of Regexps:: Rules for writing regular expressions.
+* Regexp Example:: Illustrates regular expression syntax.
+
+Syntax Tables
+
+* Syntax Descriptors:: How characters are classified.
+* Syntax Table Functions:: How to create, examine and alter syntax tables.
+* 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.
+
+Syntax Descriptors
+
+* Syntax Class Table:: Table of syntax classes.
+* Syntax Flags:: Additional flags each character can have.
+
+Abbrevs And Abbrev Expansion
+
+* Abbrev Mode:: Setting up XEmacs for abbreviation.
+* Tables: Abbrev Tables. Creating and working with abbrev tables.
+* Defining Abbrevs:: Specifying abbreviations and their expansions.
+* Files: Abbrev Files. Saving abbrevs in files.
+* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables:: Abbrev tables used by various major modes.
+
+Extents
+
+* 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.
+
+Specifiers
+
+* Introduction to Specifiers:: Specifiers provide a clean way for
+ display and other properties to vary
+ (under user control) in a wide variety
+ of contexts.
+* Specifiers In-Depth:: Gory details about specifier innards.
+* Specifier Instancing:: Instancing means obtaining the "value" of
+ a specifier in a particular context.
+* Specifier Types:: Specifiers come in different flavors.
+* Adding Specifications:: Specifications control a specifier's "value"
+ by giving conditions under which a
+ particular value is valid.
+* Retrieving Specifications:: Querying a specifier's specifications.
+* Specifier Instancing Functions::
+ Functions to instance a specifier.
+* Specifier Example:: Making all this stuff clearer.
+* Creating Specifiers:: Creating specifiers for your own use.
+* Specifier Validation Functions::
+ Validating the components of a specifier.
+* Other Specification Functions::
+ Other ways of working with specifications.
+
+Faces and Window-System Objects
+
+* Faces:: Controlling the way text looks.
+* Fonts:: Controlling the typeface of text.
+* Colors:: Controlling the color of text and pixmaps.
+
+Faces
+
+* Merging Faces:: How XEmacs decides which face to use
+ for a character.
+* Basic Face Functions:: How to define and examine faces.
+* Face Properties:: How to access and modify a face's properties.
+* Face Convenience Functions:: Convenience functions for accessing
+ particular properties of a face.
+* Other Face Display Functions:: Other functions pertaining to how a
+ a face appears.
+
+Fonts
+
+* 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.
+
+Colors
+
+* Color Specifiers:: Specifying how a color will appear.
+* Color Instances:: What a color specifier gets instanced as.
+* Color Instance Properties:: Properties of color instances.
+* Color Convenience Functions:: Convenience functions that automatically
+ instance and retrieve the properties
+ of a color specifier.
+
+Glyphs
+
+* Glyph Functions:: Functions for working with glyphs.
+* Images:: Graphical images displayed in a frame.
+* Glyph Types:: Each glyph has a particular type.
+* Mouse Pointer:: Controlling the mouse pointer.
+* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+* Subwindows:: Inserting an externally-controlled subwindow
+ into a buffer.
+
+Glyph Functions
+
+* Creating Glyphs:: Creating new glyphs.
+* Glyph Properties:: Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions::
+ Convenience functions for accessing particular
+ properties of a glyph.
+* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+
+Images
+
+* 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.
+
+Image Instances
+
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+
+Annotations
+
+* Annotation Basics:: Introduction to annotations.
+* Annotation Primitives:: Creating and deleting annotations.
+* Annotation Properties:: Retrieving and changing the characteristics
+ of an annotation.
+* Margin Primitives:: Controlling the size of the margins.
+* Locating Annotations:: Looking for annotations in a buffer.
+* Annotation Hooks:: Hooks called at certain times during an
+ annotation's lifetime.
+
+Hash Tables
+
+* 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.
+
+Range Tables
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+ integers to values.
+* Working With Range Tables:: Range table functions.
+
+
+XEmacs Display
+
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Selective Display:: Hiding part of the buffer text.
+* 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.
+
+Processes
+
+* Subprocess Creation:: Functions that start subprocesses.
+* Synchronous Processes:: Details of using synchronous subprocesses.
+* Asynchronous Processes:: Starting up an asynchronous subprocess.
+* Deleting Processes:: Eliminating an asynchronous subprocess.
+* Process Information:: Accessing run-status and other attributes.
+* Input to Processes:: Sending input to an asynchronous subprocess.
+* Signals to Processes:: Stopping, continuing or interrupting
+ an asynchronous subprocess.
+* Output from Processes:: Collecting output from an asynchronous subprocess.
+* Sentinels:: Sentinels run when process run-status changes.
+* Network:: Opening network connections.
+
+Receiving Output from Processes
+
+* Process Buffers:: If no filter, output is put in a buffer.
+* Filter Functions:: Filter functions accept output from the process.
+* Accepting Output:: How to wait until process output arrives.
+
+Operating System Interface
+
+* Starting Up:: Customizing XEmacs start-up processing.
+* Getting Out:: How exiting works (permanent or temporary).
+* System Environment:: Distinguish the name and kind of system.
+* Terminal Input:: Recording terminal input for debugging.
+* Terminal Output:: Recording terminal output for debugging.
+* Flow Control:: How to turn output flow control on or off.
+* Batch Mode:: Running XEmacs without terminal interaction.
+
+Starting Up XEmacs
+
+* Start-up Summary:: Sequence of actions XEmacs performs at start-up.
+* Init File:: Details on reading the init file (`.emacs').
+* Terminal-Specific:: How the terminal-specific Lisp file is read.
+* Command Line Arguments:: How command line arguments are processed,
+ and how you can customize them.
+
+Getting out of XEmacs
+
+* Killing XEmacs:: Exiting XEmacs irreversibly.
+* Suspending XEmacs:: Exiting XEmacs reversibly.
+
+X-Windows
+
+* X Selections:: Transferring text to and from other X clients.
+* X Server:: Information about the X server connected to
+ a particular device.
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+* Grabs:: Restricting access to the server by other apps.
+* X Miscellaneous:: Other X-specific functions and variables.
+
+ToolTalk Support
+
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
+
+LDAP Support
+
+* 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
+
+XEmacs LDAP API
+
+* 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
+
+The Low-Level LDAP API
+
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Searching on a LDAP Server (Low-level)::
+
+Internationalization
+
+* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
+* I18N Level 3:: Support for localized messages.
+* I18N Level 4:: Support for Asian languages.
+
+MULE
+
+* Internationalization Terminology::
+ Definition of various internationalization terms.
+* Charsets:: Sets of related characters.
+* MULE Characters:: Working with characters in XEmacs/MULE.
+* Composite Characters:: Making new characters by overstriking other ones.
+* ISO 2022:: An international standard for charsets and encodings.
+* Coding Systems:: Ways of representing a string of chars using integers.
+* CCL:: A special language for writing fast converters.
+* Category Tables:: Subdividing charsets into groups.
+
+Tips
+
+* Style Tips:: Writing clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
+
+Building XEmacs and Object Allocation
+
+* 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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Variable Aliases, Prev: Buffer-Local Variables, Up: Variables
+
+Variable Aliases
+================
+
+ You can define a variable as an "alias" for another. Any time you
+reference the former variable, the current value of the latter is
+returned. Any time you change the value of the former variable, the
+value of the latter is actually changed. This is useful in cases where
+you want to rename a variable but still make old code work (*note
+Obsoleteness::.).
+
+ - Function: defvaralias VARIABLE ALIAS
+ This function defines VARIABLE as an alias for ALIAS.
+ Thenceforth, any operations performed on VARIABLE will actually be
+ performed on ALIAS. Both VARIABLE and ALIAS should be symbols.
+ If ALIAS is `nil', remove any aliases for VARIABLE. ALIAS can
+ itself be aliased, and the chain of variable aliases will be
+ followed appropriately. If VARIABLE already has a value, this
+ value will be shadowed until the alias is removed, at which point
+ it will be restored. Currently VARIABLE cannot be a built-in
+ variable, a variable that has a buffer-local value in any buffer,
+ or the symbols `nil' or `t'.
+
+ - Function: variable-alias VARIABLE
+ 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
+ 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
+ not a symbol, just return it. Signal a
+ `cyclic-variable-indirection' error if there is a loop in the
+ variable chain of symbols.
+
+\1f
+File: lispref.info, Node: Functions, Next: Macros, Prev: Variables, Up: Top
+
+Functions
+*********
+
+ A Lisp program is composed mainly of Lisp functions. This chapter
+explains what functions are, how they accept arguments, and how to
+define them.
+
+* Menu:
+
+* What Is a Function:: Lisp functions vs. primitives; terminology.
+* Lambda Expressions:: How functions are expressed as Lisp objects.
+* Function Names:: A symbol can serve as the name of a function.
+* Defining Functions:: Lisp expressions for defining functions.
+* Calling Functions:: How to use an existing function.
+* Mapping Functions:: Applying a function to each element of a list, etc.
+* Anonymous Functions:: Lambda expressions are functions with no names.
+* Function Cells:: Accessing or setting the function definition
+ of a symbol.
+* Inline Functions:: Defining functions that the compiler will open code.
+* Related Topics:: Cross-references to specific Lisp primitives
+ that have a special bearing on how functions work.
+
+\1f
+File: lispref.info, Node: What Is a Function, Next: Lambda Expressions, Up: Functions
+
+What Is a Function?
+===================
+
+ In a general sense, a function is a rule for carrying on a
+computation given several values called "arguments". The result of the
+computation is called the value of the function. The computation can
+also have side effects: lasting changes in the values of variables or
+the contents of data structures.
+
+ Here are important terms for functions in XEmacs Lisp and for other
+function-like objects.
+
+"function"
+ In XEmacs Lisp, a "function" is anything that can be applied to
+ arguments in a Lisp program. In some cases, we use it more
+ specifically to mean a function written in Lisp. Special forms and
+ macros are not functions.
+
+"primitive"
+ A "primitive" is a function callable from Lisp that is written in
+ C, such as `car' or `append'. These functions are also called
+ "built-in" functions or "subrs". (Special forms are also
+ considered primitives.)
+
+ Usually the reason that a function is a primitives is because it is
+ fundamental, because it provides a low-level interface to operating
+ system services, or because it needs to run fast. Primitives can
+ be modified or added only by changing the C sources and
+ recompiling the editor. See *Note Writing Lisp Primitives:
+ (internals)Writing Lisp Primitives.
+
+"lambda expression"
+ A "lambda expression" is a function written in Lisp. These are
+ described in the following section. *Note Lambda Expressions::.
+
+"special form"
+ A "special form" is a primitive that is like a function but does
+ not evaluate all of its arguments in the usual way. It may
+ evaluate only some of the arguments, or may evaluate them in an
+ unusual order, or several times. Many special forms are described
+ in *Note Control Structures::.
+
+"macro"
+ A "macro" is a construct defined in Lisp by the programmer. It
+ differs from a function in that it translates a Lisp expression
+ that you write into an equivalent expression to be evaluated
+ instead of the original expression. Macros enable Lisp
+ programmers to do the sorts of things that special forms can do.
+ *Note Macros::, for how to define and use macros.
+
+"command"
+ A "command" is an object that `command-execute' can invoke; it is
+ a possible definition for a key sequence. Some functions are
+ commands; a function written in Lisp is a command if it contains an
+ interactive declaration (*note Defining Commands::.). Such a
+ function can be called from Lisp expressions like other functions;
+ in this case, the fact that the function is a command makes no
+ difference.
+
+ Keyboard macros (strings and vectors) are commands also, even
+ though they are not functions. A symbol is a command if its
+ function definition is a command; such symbols can be invoked with
+ `M-x'. The symbol is a function as well if the definition is a
+ function. *Note Command Overview::.
+
+"keystroke command"
+ A "keystroke command" is a command that is bound to a key sequence
+ (typically one to three keystrokes). The distinction is made here
+ merely to avoid confusion with the meaning of "command" in
+ non-Emacs editors; for Lisp programs, the distinction is normally
+ unimportant.
+
+"compiled function"
+ A "compiled function" is a function that has been compiled by the
+ byte compiler. *Note Compiled-Function Type::.
+
+ - Function: subrp OBJECT
+ This function returns `t' if OBJECT is a built-in function (i.e.,
+ a Lisp primitive).
+
+ (subrp 'message) ; `message' is a symbol,
+ => nil ; not a subr object.
+ (subrp (symbol-function 'message))
+ => t
+
+ - Function: compiled-function-p OBJECT
+ This function returns `t' if OBJECT is a compiled function. For
+ example:
+
+ (compiled-function-p (symbol-function 'next-line))
+ => t
+
+\1f
+File: lispref.info, Node: Lambda Expressions, Next: Function Names, Prev: What Is a Function, Up: Functions
+
+Lambda Expressions
+==================
+
+ A function written in Lisp is a list that looks like this:
+
+ (lambda (ARG-VARIABLES...)
+ [DOCUMENTATION-STRING]
+ [INTERACTIVE-DECLARATION]
+ BODY-FORMS...)
+
+Such a list is called a "lambda expression". In XEmacs Lisp, it
+actually is valid as an expression--it evaluates to itself. In some
+other Lisp dialects, a lambda expression is not a valid expression at
+all. In either case, its main use is not to be evaluated as an
+expression, but to be called as a function.
+
+* Menu:
+
+* Lambda Components:: The parts of a lambda expression.
+* Simple Lambda:: A simple example.
+* Argument List:: Details and special features of argument lists.
+* Function Documentation:: How to put documentation in a function.
+
+\1f
+File: lispref.info, Node: Lambda Components, Next: Simple Lambda, Up: Lambda Expressions
+
+Components of a Lambda Expression
+---------------------------------
+
+ A function written in Lisp (a "lambda expression") is a list that
+looks like this:
+
+ (lambda (ARG-VARIABLES...)
+ [DOCUMENTATION-STRING]
+ [INTERACTIVE-DECLARATION]
+ BODY-FORMS...)
+
+ The first element of a lambda expression is always the symbol
+`lambda'. This indicates that the list represents a function. The
+reason functions are defined to start with `lambda' is so that other
+lists, intended for other uses, will not accidentally be valid as
+functions.
+
+ The second element is a list of symbols-the argument variable names.
+This is called the "lambda list". When a Lisp function is called, the
+argument values are matched up against the variables in the lambda
+list, which are given local bindings with the values provided. *Note
+Local Variables::.
+
+ The documentation string is a Lisp string object placed within the
+function definition to describe the function for the XEmacs help
+facilities. *Note Function Documentation::.
+
+ The interactive declaration is a list of the form `(interactive
+CODE-STRING)'. This declares how to provide arguments if the function
+is used interactively. Functions with this declaration are called
+"commands"; they can be called using `M-x' or bound to a key.
+Functions not intended to be called in this way should not have
+interactive declarations. *Note Defining Commands::, for how to write
+an interactive declaration.
+
+ The rest of the elements are the "body" of the function: the Lisp
+code to do the work of the function (or, as a Lisp programmer would say,
+"a list of Lisp forms to evaluate"). The value returned by the
+function is the value returned by the last element of the body.
+
+\1f
+File: lispref.info, Node: Simple Lambda, Next: Argument List, Prev: Lambda Components, Up: Lambda Expressions
+
+A Simple Lambda-Expression Example
+----------------------------------
+
+ Consider for example the following function:
+
+ (lambda (a b c) (+ a b c))
+
+We can call this function by writing it as the CAR of an expression,
+like this:
+
+ ((lambda (a b c) (+ a b c))
+ 1 2 3)
+
+This call evaluates the body of the lambda expression with the variable
+`a' bound to 1, `b' bound to 2, and `c' bound to 3. Evaluation of the
+body adds these three numbers, producing the result 6; therefore, this
+call to the function returns the value 6.
+
+ Note that the arguments can be the results of other function calls,
+as in this example:
+
+ ((lambda (a b c) (+ a b c))
+ 1 (* 2 3) (- 5 4))
+
+This evaluates the arguments `1', `(* 2 3)', and `(- 5 4)' from left to
+right. Then it applies the lambda expression to the argument values 1,
+6 and 1 to produce the value 8.
+
+ It is not often useful to write a lambda expression as the CAR of a
+form in this way. You can get the same result, of making local
+variables and giving them values, using the special form `let' (*note
+Local Variables::.). And `let' is clearer and easier to use. In
+practice, lambda expressions are either stored as the function
+definitions of symbols, to produce named functions, or passed as
+arguments to other functions (*note Anonymous Functions::.).
+
+ However, calls to explicit lambda expressions were very useful in the
+old days of Lisp, before the special form `let' was invented. At that
+time, they were the only way to bind and initialize local variables.
+
+\1f
+File: lispref.info, Node: Argument List, Next: Function Documentation, Prev: Simple Lambda, Up: Lambda Expressions
+
+Advanced Features of Argument Lists
+-----------------------------------
+
+ Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
+three argument variables, so it must be called with three arguments: if
+you try to call it with only two arguments or four arguments, you get a
+`wrong-number-of-arguments' error.
+
+ It is often convenient to write a function that allows certain
+arguments to be omitted. For example, the function `substring' accepts
+three arguments--a string, the start index and the end index--but the
+third argument defaults to the LENGTH of the string if you omit it. It
+is also convenient for certain functions to accept an indefinite number
+of arguments, as the functions `list' and `+' do.
+
+ To specify optional arguments that may be omitted when a function is
+called, simply include the keyword `&optional' before the optional
+arguments. To specify a list of zero or more extra arguments, include
+the keyword `&rest' before one final argument.
+
+ Thus, the complete syntax for an argument list is as follows:
+
+ (REQUIRED-VARS...
+ [&optional OPTIONAL-VARS...]
+ [&rest REST-VAR])
+
+The square brackets indicate that the `&optional' and `&rest' clauses,
+and the variables that follow them, are optional.
+
+ A call to the function requires one actual argument for each of the
+REQUIRED-VARS. There may be actual arguments for zero or more of the
+OPTIONAL-VARS, and there cannot be any actual arguments beyond that
+unless the lambda list uses `&rest'. In that case, there may be any
+number of extra actual arguments.
+
+ If actual arguments for the optional and rest variables are omitted,
+then they always default to `nil'. There is no way for the function to
+distinguish between an explicit argument of `nil' and an omitted
+argument. However, the body of the function is free to consider `nil'
+an abbreviation for some other meaningful value. This is what
+`substring' does; `nil' as the third argument to `substring' means to
+use the length of the string supplied.
+
+ Common Lisp note: Common Lisp allows the function to specify what
+ default value to use when an optional argument is omitted; XEmacs
+ Lisp always uses `nil'.
+
+ For example, an argument list that looks like this:
+
+ (a b &optional c d &rest e)
+
+binds `a' and `b' to the first two actual arguments, which are
+required. If one or two more arguments are provided, `c' and `d' are
+bound to them respectively; any arguments after the first four are
+collected into a list and `e' is bound to that list. If there are only
+two arguments, `c' is `nil'; if two or three arguments, `d' is `nil';
+if four arguments or fewer, `e' is `nil'.
+
+ There is no way to have required arguments following optional
+ones--it would not make sense. To see why this must be so, suppose
+that `c' in the example were optional and `d' were required. Suppose
+three actual arguments are given; which variable would the third
+argument be for? Similarly, it makes no sense to have any more
+arguments (either required or optional) after a `&rest' argument.
+
+ Here are some examples of argument lists and proper calls:
+
+ ((lambda (n) (1+ n)) ; One required:
+ 1) ; requires exactly one argument.
+ => 2
+ ((lambda (n &optional n1) ; One required and one optional:
+ (if n1 (+ n n1) (1+ n))) ; 1 or 2 arguments.
+ 1 2)
+ => 3
+ ((lambda (n &rest ns) ; One required and one rest:
+ (+ n (apply '+ ns))) ; 1 or more arguments.
+ 1 2 3 4 5)
+ => 15
+
+\1f
+File: lispref.info, Node: Function Documentation, Prev: Argument List, Up: Lambda Expressions
+
+Documentation Strings of Functions
+----------------------------------
+
+ A lambda expression may optionally have a "documentation string" just
+after the lambda list. This string does not affect execution of the
+function; it is a kind of comment, but a systematized comment which
+actually appears inside the Lisp world and can be used by the XEmacs
+help facilities. *Note Documentation::, for how the
+DOCUMENTATION-STRING is accessed.
+
+ It is a good idea to provide documentation strings for all the
+functions in your program, even those that are only called from within
+your program. Documentation strings are like comments, except that they
+are easier to access.
+
+ The first line of the documentation string should stand on its own,
+because `apropos' displays just this first line. It should consist of
+one or two complete sentences that summarize the function's purpose.
+
+ The start of the documentation string is usually indented in the
+source file, but since these spaces come before the starting
+double-quote, they are not part of the string. Some people make a
+practice of indenting any additional lines of the string so that the
+text lines up in the program source. *This is a mistake.* The
+indentation of the following lines is inside the string; what looks
+nice in the source code will look ugly when displayed by the help
+commands.
+
+ You may wonder how the documentation string could be optional, since
+there are required components of the function that follow it (the body).
+Since evaluation of a string returns that string, without any side
+effects, it has no effect if it is not the last form in the body.
+Thus, in practice, there is no confusion between the first form of the
+body and the documentation string; if the only body form is a string
+then it serves both as the return value and as the documentation.
+
+\1f
+File: lispref.info, Node: Function Names, Next: Defining Functions, Prev: Lambda Expressions, Up: Functions
+
+Naming a Function
+=================
+
+ In most computer languages, every function has a name; the idea of a
+function without a name is nonsensical. In Lisp, a function in the
+strictest sense has no name. It is simply a list whose first element is
+`lambda', or a primitive subr-object.
+
+ However, a symbol can serve as the name of a function. This happens
+when you put the function in the symbol's "function cell" (*note Symbol
+Components::.). Then the symbol itself becomes a valid, callable
+function, equivalent to the list or subr-object that its function cell
+refers to. The contents of the function cell are also called the
+symbol's "function definition". The procedure of using a symbol's
+function definition in place of the symbol is called "symbol function
+indirection"; see *Note Function Indirection::.
+
+ In practice, nearly all functions are given names in this way and
+referred to through their names. For example, the symbol `car' works
+as a function and does what it does because the primitive subr-object
+`#<subr car>' is stored in its function cell.
+
+ We give functions names because it is convenient to refer to them by
+their names in Lisp expressions. For primitive subr-objects such as
+`#<subr car>', names are the only way you can refer to them: there is
+no read syntax for such objects. For functions written in Lisp, the
+name is more convenient to use in a call than an explicit lambda
+expression. Also, a function with a name can refer to itself--it can
+be recursive. Writing the function's name in its own definition is much
+more convenient than making the function definition point to itself
+(something that is not impossible but that has various disadvantages in
+practice).
+
+ We often identify functions with the symbols used to name them. For
+example, we often speak of "the function `car'", not distinguishing
+between the symbol `car' and the primitive subr-object that is its
+function definition. For most purposes, there is no need to
+distinguish.
+
+ Even so, keep in mind that a function need not have a unique name.
+While a given function object *usually* appears in the function cell of
+only one symbol, this is just a matter of convenience. It is easy to
+store it in several symbols using `fset'; then each of the symbols is
+equally well a name for the same function.
+
+ A symbol used as a function name may also be used as a variable;
+these two uses of a symbol are independent and do not conflict.
+
+\1f
+File: lispref.info, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions
+
+Defining Functions
+==================
+
+ We usually give a name to a function when it is first created. This
+is called "defining a function", and it is done with the `defun'
+special form.
+
+ - Special Form: defun NAME ARGUMENT-LIST BODY-FORMS
+ `defun' is the usual way to define new Lisp functions. It defines
+ the symbol NAME as a function that looks like this:
+
+ (lambda ARGUMENT-LIST . BODY-FORMS)
+
+ `defun' stores this lambda expression in the function cell of
+ NAME. It returns the value NAME, but usually we ignore this value.
+
+ As described previously (*note Lambda Expressions::.),
+ ARGUMENT-LIST is a list of argument names and may include the
+ keywords `&optional' and `&rest'. Also, the first two forms in
+ BODY-FORMS may be a documentation string and an interactive
+ declaration.
+
+ There is no conflict if the same symbol NAME is also used as a
+ variable, since the symbol's value cell is independent of the
+ function cell. *Note Symbol Components::.
+
+ Here are some examples:
+
+ (defun foo () 5)
+ => foo
+ (foo)
+ => 5
+
+ (defun bar (a &optional b &rest c)
+ (list a b c))
+ => bar
+ (bar 1 2 3 4 5)
+ => (1 2 (3 4 5))
+ (bar 1)
+ => (1 nil nil)
+ (bar)
+ error--> Wrong number of arguments.
+
+ (defun capitalize-backwards ()
+ "Upcase the last letter of a word."
+ (interactive)
+ (backward-word 1)
+ (forward-word 1)
+ (backward-char 1)
+ (capitalize-word 1))
+ => capitalize-backwards
+
+ Be careful not to redefine existing functions unintentionally.
+ `defun' redefines even primitive functions such as `car' without
+ any hesitation or notification. Redefining a function already
+ defined is often done deliberately, and there is no way to
+ distinguish deliberate redefinition from unintentional
+ redefinition.
+
+ - Function: define-function NAME DEFINITION
+ - Function: defalias NAME DEFINITION
+ These equivalent special forms define the symbol NAME as a
+ function, with definition DEFINITION (which can be any valid Lisp
+ function).
+
+ The proper place to use `define-function' or `defalias' is where a
+ specific function name is being defined--especially where that
+ name appears explicitly in the source file being loaded. This is
+ because `define-function' and `defalias' record which file defined
+ the function, just like `defun'. (*note Unloading::.).
+
+ By contrast, in programs that manipulate function definitions for
+ other purposes, it is better to use `fset', which does not keep
+ such records.
+
+ See also `defsubst', which defines a function like `defun' and tells
+the Lisp compiler to open-code it. *Note Inline Functions::.
+
+\1f
+File: lispref.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions
+
+Calling Functions
+=================
+
+ Defining functions is only half the battle. Functions don't do
+anything until you "call" them, i.e., tell them to run. Calling a
+function is also known as "invocation".
+
+ The most common way of invoking a function is by evaluating a list.
+For example, evaluating the list `(concat "a" "b")' calls the function
+`concat' with arguments `"a"' and `"b"'. *Note Evaluation::, for a
+description of evaluation.
+
+ When you write a list as an expression in your program, the function
+name is part of the program. This means that you choose which function
+to call, and how many arguments to give it, when you write the program.
+Usually that's just what you want. Occasionally you need to decide at
+run time which function to call. To do that, use the functions
+`funcall' and `apply'.
+
+ - Function: funcall FUNCTION &rest ARGUMENTS
+ `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
+ FUNCTION returns.
+
+ Since `funcall' is a function, all of its arguments, including
+ FUNCTION, are evaluated before `funcall' is called. This means
+ that you can use any expression to obtain the function to be
+ called. It also means that `funcall' does not see the expressions
+ you write for the ARGUMENTS, only their values. These values are
+ *not* evaluated a second time in the act of calling FUNCTION;
+ `funcall' enters the normal procedure for calling a function at the
+ place where the arguments have already been evaluated.
+
+ The argument FUNCTION must be either a Lisp function or a
+ primitive function. Special forms and macros are not allowed,
+ because they make sense only when given the "unevaluated" argument
+ expressions. `funcall' cannot provide these because, as we saw
+ above, it never knows them in the first place.
+
+ (setq f 'list)
+ => list
+ (funcall f 'x 'y 'z)
+ => (x y z)
+ (funcall f 'x 'y '(z))
+ => (x y (z))
+ (funcall 'and t nil)
+ error--> Invalid function: #<subr and>
+
+ Compare these example with the examples of `apply'.
+
+ - Function: apply FUNCTION &rest ARGUMENTS
+ `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
+ with one difference: the last of ARGUMENTS is a list of arguments
+ to give to FUNCTION, rather than a single argument. We also say
+ that `apply' "spreads" this list so that each individual element
+ becomes an argument.
+
+ `apply' returns the result of calling FUNCTION. As with
+ `funcall', FUNCTION must either be a Lisp function or a primitive
+ function; special forms and macros do not make sense in `apply'.
+
+ (setq f 'list)
+ => list
+ (apply f 'x 'y 'z)
+ error--> Wrong type argument: listp, z
+ (apply '+ 1 2 '(3 4))
+ => 10
+ (apply '+ '(1 2 3 4))
+ => 10
+
+ (apply 'append '((a b c) nil (x y z) nil))
+ => (a b c x y z)
+
+ For an interesting example of using `apply', see the description of
+ `mapcar', in *Note Mapping Functions::.
+
+ It is common for Lisp functions to accept functions as arguments or
+find them in data structures (especially in hook variables and property
+lists) and call them using `funcall' or `apply'. Functions that accept
+function arguments are often called "functionals".
+
+ Sometimes, when you call a functional, it is useful to supply a no-op
+function as the argument. Here are two different kinds of no-op
+function:
+
+ - Function: identity ARG
+ This function returns ARG and has no side effects.
+
+ - Function: ignore &rest ARGS
+ This function ignores any arguments and returns `nil'.
+
+\1f
+File: lispref.info, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions
+
+Mapping Functions
+=================
+
+ A "mapping function" applies a given function to each element of a
+list or other collection. XEmacs Lisp has three such functions;
+`mapcar' and `mapconcat', which scan a list, are described here. For
+the third mapping function, `mapatoms', see *Note Creating Symbols::.
+
+ - Function: mapcar FUNCTION SEQUENCE
+ `mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
+ returns a list of the results.
+
+ The argument SEQUENCE may be a list, a vector, or a string. The
+ result is always a list. The length of the result is the same as
+ the length of SEQUENCE.
+
+ For example:
+
+ (mapcar 'car '((a b) (c d) (e f)))
+ => (a c e)
+ (mapcar '1+ [1 2 3])
+ => (2 3 4)
+ (mapcar 'char-to-string "abc")
+ => ("a" "b" "c")
+
+ ;; Call each function in `my-hooks'.
+ (mapcar 'funcall my-hooks)
+
+ (defun mapcar* (f &rest args)
+ "Apply FUNCTION to successive cars of all ARGS.
+ Return the list of results."
+ ;; If no list is exhausted,
+ (if (not (memq 'nil args))
+ ;; apply function to CARs.
+ (cons (apply f (mapcar 'car args))
+ (apply 'mapcar* f
+ ;; Recurse for rest of elements.
+ (mapcar 'cdr args)))))
+
+ (mapcar* 'cons '(a b c) '(1 2 3 4))
+ => ((a . 1) (b . 2) (c . 3))
+
+ - Function: mapconcat FUNCTION SEQUENCE SEPARATOR
+ `mapconcat' applies FUNCTION to each element of SEQUENCE: the
+ results, which must be strings, are concatenated. Between each
+ pair of result strings, `mapconcat' inserts the string SEPARATOR.
+ Usually SEPARATOR contains a space or comma or other suitable
+ punctuation.
+
+ The argument FUNCTION must be a function that can take one
+ argument and return a string.
+
+ (mapconcat 'symbol-name
+ '(The cat in the hat)
+ " ")
+ => "The cat in the hat"
+
+ (mapconcat (function (lambda (x) (format "%c" (1+ x))))
+ "HAL-8000"
+ "")
+ => "IBM.9111"
+
+\1f
+File: lispref.info, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions
+
+Anonymous Functions
+===================
+
+ In Lisp, a function is a list that starts with `lambda', a byte-code
+function compiled from such a list, or alternatively a primitive
+subr-object; names are "extra". Although usually functions are defined
+with `defun' and given names at the same time, it is occasionally more
+concise to use an explicit lambda expression--an anonymous function.
+Such a list is valid wherever a function name is.
+
+ Any method of creating such a list makes a valid function. Even
+this:
+
+ (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
+ => (lambda (x) (+ 12 x))
+
+This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
+it the value (*not* the function definition!) of `silly'.
+
+ Here is how we might call this function:
+
+ (funcall silly 1)
+ => 13
+
+(It does *not* work to write `(silly 1)', because this function is not
+the *function definition* of `silly'. We have not given `silly' any
+function definition, just a value as a variable.)
+
+ Most of the time, anonymous functions are constants that appear in
+your program. For example, you might want to pass one as an argument
+to the function `mapcar', which applies any given function to each
+element of a list. Here we pass an anonymous function that multiplies
+a number by two:
+
+ (defun double-each (list)
+ (mapcar '(lambda (x) (* 2 x)) list))
+ => double-each
+ (double-each '(2 11))
+ => (4 22)
+
+In such cases, we usually use the special form `function' instead of
+simple quotation to quote the anonymous function.
+
+ - Special Form: function FUNCTION-OBJECT
+ This special form returns FUNCTION-OBJECT without evaluating it.
+ In this, it is equivalent to `quote'. However, it serves as a
+ note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended
+ to be used only as a function, and therefore can safely be
+ compiled. Contrast this with `quote', in *Note Quoting::.
+
+ Using `function' instead of `quote' makes a difference inside a
+function or macro that you are going to compile. For example:
+
+ (defun double-each (list)
+ (mapcar (function (lambda (x) (* 2 x))) list))
+ => double-each
+ (double-each '(2 11))
+ => (4 22)
+
+If this definition of `double-each' is compiled, the anonymous function
+is compiled as well. By contrast, in the previous definition where
+ordinary `quote' is used, the argument passed to `mapcar' is the
+precise list shown:
+
+ (lambda (x) (* x 2))
+
+The Lisp compiler cannot assume this list is a function, even though it
+looks like one, since it does not know what `mapcar' does with the
+list. Perhaps `mapcar' will check that the CAR of the third element is
+the symbol `*'! The advantage of `function' is that it tells the
+compiler to go ahead and compile the constant function.
+
+ We sometimes write `function' instead of `quote' when quoting the
+name of a function, but this usage is just a sort of comment.
+
+ (function SYMBOL) == (quote SYMBOL) == 'SYMBOL
+
+ See `documentation' in *Note Accessing Documentation::, for a
+realistic example using `function' and an anonymous function.
+
+\1f
+File: lispref.info, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions
+
+Accessing Function Cell Contents
+================================
+
+ The "function definition" of a symbol is the object stored in the
+function cell of the symbol. The functions described here access, test,
+and set the function cell of symbols.
+
+ See also the function `indirect-function' in *Note Function
+Indirection::.
+
+ - Function: symbol-function SYMBOL
+ This returns the object in the function cell of SYMBOL. If the
+ symbol's function cell is void, a `void-function' error is
+ signaled.
+
+ This function does not check that the returned object is a
+ legitimate function.
+
+ (defun bar (n) (+ n 2))
+ => bar
+ (symbol-function 'bar)
+ => (lambda (n) (+ n 2))
+ (fset 'baz 'bar)
+ => bar
+ (symbol-function 'baz)
+ => bar
+
+ If you have never given a symbol any function definition, we say that
+that symbol's function cell is "void". In other words, the function
+cell does not have any Lisp object in it. If you try to call such a
+symbol as a function, it signals a `void-function' error.
+
+ Note that void is not the same as `nil' or the symbol `void'. The
+symbols `nil' and `void' are Lisp objects, and can be stored into a
+function cell just as any other object can be (and they can be valid
+functions if you define them in turn with `defun'). A void function
+cell contains no object whatsoever.
+
+ You can test the voidness of a symbol's function definition with
+`fboundp'. After you have given a symbol a function definition, you
+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.
+
+ - Function: fmakunbound SYMBOL
+ This function makes SYMBOL's function cell void, so that a
+ subsequent attempt to access this cell will cause a `void-function'
+ error. (See also `makunbound', in *Note Local Variables::.)
+
+ (defun foo (x) x)
+ => x
+ (foo 1)
+ =>1
+ (fmakunbound 'foo)
+ => x
+ (foo 1)
+ error--> Symbol's function definition is void: foo
+
+ - Function: fset SYMBOL OBJECT
+ This function stores OBJECT in the function cell of SYMBOL. The
+ result is OBJECT. Normally OBJECT should be a function or the
+ name of a function, but this is not checked.
+
+ There are three normal uses of this function:
+
+ * Copying one symbol's function definition to another. (In
+ other words, making an alternate name for a function.)
+
+ * 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.
+
+ * In constructs for defining or altering functions. If `defun'
+ were not a primitive, it could be written in Lisp (as a
+ macro) using `fset'.
+
+ Here are examples of the first two uses:
+
+ ;; Give `first' the same definition `car' has.
+ (fset 'first (symbol-function 'car))
+ => #<subr car>
+ (first '(1 2 3))
+ => 1
+
+ ;; Make the symbol `car' the function definition of `xfirst'.
+ (fset 'xfirst 'car)
+ => car
+ (xfirst '(1 2 3))
+ => 1
+ (symbol-function 'xfirst)
+ => car
+ (symbol-function (symbol-function 'xfirst))
+ => #<subr car>
+
+ ;; Define a named keyboard macro.
+ (fset 'kill-two-lines "\^u2\^k")
+ => "\^u2\^k"
+
+ See also the related functions `define-function' and `defalias',
+ in *Note Defining Functions::.
+
+ When writing a function that extends a previously defined function,
+the following idiom is sometimes used:
+
+ (fset 'old-foo (symbol-function 'foo))
+ (defun foo ()
+ "Just like old-foo, except more so."
+ (old-foo)
+ (more-so))
+
+This does not work properly if `foo' has been defined to autoload. In
+such a case, when `foo' calls `old-foo', Lisp attempts to define
+`old-foo' by loading a file. Since this presumably defines `foo'
+rather than `old-foo', it does not produce the proper results. The
+only way to avoid this problem is to make sure the file is loaded
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros
+
+Macros and Byte Compilation
+===========================
+
+ You might ask why we take the trouble to compute an expansion for a
+macro and then evaluate the expansion. Why not have the macro body
+produce the desired results directly? The reason has to do with
+compilation.
+
+ When a macro call appears in a Lisp program being compiled, the Lisp
+compiler calls the macro definition just as the interpreter would, and
+receives an expansion. But instead of evaluating this expansion, it
+compiles the expansion as if it had appeared directly in the program.
+As a result, the compiled code produces the value and side effects
+intended for the macro, but executes at full compiled speed. This would
+not work if the macro body computed the value and side effects
+itself--they would be computed at compile time, which is not useful.
+
+ In order for compilation of macro calls to work, the macros must be
+defined in Lisp when the calls to them are compiled. The compiler has a
+special feature to help you do this: if a file being compiled contains a
+`defmacro' form, the macro is defined temporarily for the rest of the
+compilation of that file. To use this feature, you must define the
+macro in the same file where it is used and before its first use.
+
+ Byte-compiling a file executes any `require' calls at top-level in
+the file. This is in case the file needs the required packages for
+proper compilation. One way to ensure that necessary macro definitions
+are available during compilation is to require the files that define
+them (*note Named Features::.). To avoid loading the macro definition
+files when someone *runs* the compiled program, write
+`eval-when-compile' around the `require' calls (*note Eval During
+Compile::.).
+
+\1f
+File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
+
+Defining Macros
+===============
+
+ A Lisp macro is a list whose CAR is `macro'. Its CDR should be a
+function; expansion of the macro works by applying the function (with
+`apply') to the list of unevaluated argument-expressions from the macro
+call.
+
+ It is possible to use an anonymous Lisp macro just like an anonymous
+function, but this is never done, because it does not make sense to pass
+an anonymous macro to functionals such as `mapcar'. In practice, all
+Lisp macros have names, and they are usually defined with the special
+form `defmacro'.
+
+ - Special Form: defmacro NAME ARGUMENT-LIST BODY-FORMS...
+ `defmacro' defines the symbol NAME as a macro that looks like this:
+
+ (macro lambda ARGUMENT-LIST . BODY-FORMS)
+
+ This macro object is stored in the function cell of NAME. The
+ value returned by evaluating the `defmacro' form is NAME, but
+ usually we ignore this value.
+
+ The shape and meaning of ARGUMENT-LIST is the same as in a
+ function, and the keywords `&rest' and `&optional' may be used
+ (*note Argument List::.). Macros may have a documentation string,
+ but any `interactive' declaration is ignored since macros cannot be
+ called interactively.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
+
+Backquote
+=========
+
+ Macros often need to construct large list structures from a mixture
+of constants and nonconstant parts. To make this easier, use the macro
+``' (often called "backquote").
+
+ Backquote allows you to quote a list, but selectively evaluate
+elements of that list. In the simplest case, it is identical to the
+special form `quote' (*note Quoting::.). For example, these two forms
+yield identical results:
+
+ `(a list of (+ 2 3) elements)
+ => (a list of (+ 2 3) elements)
+ '(a list of (+ 2 3) elements)
+ => (a list of (+ 2 3) elements)
+
+ The special marker `,' inside of the argument to backquote indicates
+a value that isn't constant. Backquote evaluates the argument of `,'
+and puts the value in the list structure:
+
+ (list 'a 'list 'of (+ 2 3) 'elements)
+ => (a list of 5 elements)
+ `(a list of ,(+ 2 3) elements)
+ => (a list of 5 elements)
+
+ You can also "splice" an evaluated value into the resulting list,
+using the special marker `,@'. The elements of the spliced list become
+elements at the same level as the other elements of the resulting list.
+The equivalent code without using ``' is often unreadable. Here are
+some examples:
+
+ (setq some-list '(2 3))
+ => (2 3)
+ (cons 1 (append some-list '(4) some-list))
+ => (1 2 3 4 2 3)
+ `(1 ,@some-list 4 ,@some-list)
+ => (1 2 3 4 2 3)
+
+ (setq list '(hack foo bar))
+ => (hack foo bar)
+ (cons 'use
+ (cons 'the
+ (cons 'words (append (cdr list) '(as elements)))))
+ => (use the words foo bar as elements)
+ `(use the words ,@(cdr list) as elements)
+ => (use the words foo bar as elements)
+
+ In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
+ version 19.29), ``' used a different syntax which required an
+ extra level of parentheses around the entire backquote construct.
+ Likewise, each `,' or `,@' substitution required an extra level of
+ parentheses surrounding both the `,' or `,@' and the following
+ expression. The old syntax required whitespace between the ``',
+ `,' or `,@' and the following expression.
+
+ This syntax is still accepted, but no longer recommended except for
+ compatibility with old Emacs versions.
+
+\1f
+File: lispref.info, Node: Problems with Macros, Prev: Backquote, Up: Macros
+
+Common Problems Using Macros
+============================
+
+ The basic facts of macro expansion have counterintuitive
+consequences. This section describes some important consequences that
+can lead to trouble, and rules to follow to avoid trouble.
+
+* Menu:
+
+* Argument Evaluation:: The expansion should evaluate each macro arg once.
+* Surprising Local Vars:: Local variable bindings in the expansion
+ require special care.
+* Eval During Expansion:: Don't evaluate them; put them in the expansion.
+* Repeated Expansion:: Avoid depending on how many times expansion is done.
+
+\1f
+File: lispref.info, Node: Argument Evaluation, Next: Surprising Local Vars, Up: Problems with Macros
+
+Evaluating Macro Arguments Repeatedly
+-------------------------------------
+
+ When defining a macro you must pay attention to the number of times
+the arguments will be evaluated when the expansion is executed. The
+following macro (used to facilitate iteration) illustrates the problem.
+This macro allows us to write a simple "for" loop such as one might
+find in Pascal.
+
+ (defmacro for (var from init to final do &rest body)
+ "Execute a simple \"for\" loop.
+ For example, (for i from 1 to 10 do (print i))."
+ (list 'let (list (list var init))
+ (cons 'while (cons (list '<= var final)
+ (append body (list (list 'inc var)))))))
+ => for
+ (for i from 1 to 3 do
+ (setq square (* i i))
+ (princ (format "\n%d %d" i square)))
+ ==>
+
+ (let ((i 1))
+ (while (<= i 3)
+ (setq square (* i i))
+ (princ (format "%d %d" i square))
+ (inc i)))
+
+
+ -|1 1
+ -|2 4
+ -|3 9
+ => nil
+
+(The arguments `from', `to', and `do' in this macro are "syntactic
+sugar"; they are entirely ignored. The idea is that you will write
+noise words (such as `from', `to', and `do') in those positions in the
+macro call.)
+
+ Here's an equivalent definition simplified through use of backquote:
+
+ (defmacro for (var from init to final do &rest body)
+ "Execute a simple \"for\" loop.
+ For example, (for i from 1 to 10 do (print i))."
+ `(let ((,var ,init))
+ (while (<= ,var ,final)
+ ,@body
+ (inc ,var))))
+
+ Both forms of this definition (with backquote and without) suffer
+from the defect that FINAL is evaluated on every iteration. If FINAL
+is a constant, this is not a problem. If it is a more complex form,
+say `(long-complex-calculation x)', this can slow down the execution
+significantly. If FINAL has side effects, executing it more than once
+is probably incorrect.
+
+ A well-designed macro definition takes steps to avoid this problem by
+producing an expansion that evaluates the argument expressions exactly
+once unless repeated evaluation is part of the intended purpose of the
+macro. Here is a correct expansion for the `for' macro:
+
+ (let ((i 1)
+ (max 3))
+ (while (<= i max)
+ (setq square (* i i))
+ (princ (format "%d %d" i square))
+ (inc i)))
+
+ Here is a macro definition that creates this expansion:
+
+ (defmacro for (var from init to final do &rest body)
+ "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+ `(let ((,var ,init)
+ (max ,final))
+ (while (<= ,var max)
+ ,@body
+ (inc ,var))))
+
+ Unfortunately, this introduces another problem. Proceed to the
+following node.
+
+\1f
+File: lispref.info, Node: Surprising Local Vars, Next: Eval During Expansion, Prev: Argument Evaluation, Up: Problems with Macros
+
+Local Variables in Macro Expansions
+-----------------------------------
+
+ In the previous section, the definition of `for' was fixed as
+follows to make the expansion evaluate the macro arguments the proper
+number of times:
+
+ (defmacro for (var from init to final do &rest body)
+ "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+
+ `(let ((,var ,init)
+ (max ,final))
+ (while (<= ,var max)
+ ,@body
+ (inc ,var))))
+
+ The new definition of `for' has a new problem: it introduces a local
+variable named `max' which the user does not expect. This causes
+trouble in examples such as the following:
+
+ (let ((max 0))
+ (for x from 0 to 10 do
+ (let ((this (frob x)))
+ (if (< max this)
+ (setq max this)))))
+
+The references to `max' inside the body of the `for', which are
+supposed to refer to the user's binding of `max', really access the
+binding made by `for'.
+
+ The way to correct this is to use an uninterned symbol instead of
+`max' (*note Creating Symbols::.). The uninterned symbol can be bound
+and referred to just like any other symbol, but since it is created by
+`for', we know that it cannot already appear in the user's program.
+Since it is not interned, there is no way the user can put it into the
+program later. It will never appear anywhere except where put by
+`for'. Here is a definition of `for' that works this way:
+
+ (defmacro for (var from init to final do &rest body)
+ "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+ (let ((tempvar (make-symbol "max")))
+ `(let ((,var ,init)
+ (,tempvar ,final))
+ (while (<= ,var ,tempvar)
+ ,@body
+ (inc ,var)))))
+
+This creates an uninterned symbol named `max' and puts it in the
+expansion instead of the usual interned symbol `max' that appears in
+expressions ordinarily.
+
+\1f
+File: lispref.info, Node: Eval During Expansion, Next: Repeated Expansion, Prev: Surprising Local Vars, Up: Problems with Macros
+
+Evaluating Macro Arguments in Expansion
+---------------------------------------
+
+ Another problem can happen if you evaluate any of the macro argument
+expressions during the computation of the expansion, such as by calling
+`eval' (*note Eval::.). If the argument is supposed to refer to the
+user's variables, you may have trouble if the user happens to use a
+variable with the same name as one of the macro arguments. Inside the
+macro body, the macro argument binding is the most local binding of this
+variable, so any references inside the form being evaluated do refer to
+it. Here is an example:
+
+ (defmacro foo (a)
+ (list 'setq (eval a) t))
+ => foo
+ (setq x 'b)
+ (foo x) ==> (setq b t)
+ => t ; and `b' has been set.
+ ;; but
+ (setq a 'c)
+ (foo a) ==> (setq a t)
+ => t ; but this set `a', not `c'.
+
+ It makes a difference whether the user's variable is named `a' or
+`x', because `a' conflicts with the macro argument variable `a'.
+
+ Another reason not to call `eval' in a macro definition is that it
+probably won't do what you intend in a compiled program. The
+byte-compiler runs macro definitions while compiling the program, when
+the program's own computations (which you might have wished to access
+with `eval') don't occur and its local variable bindings don't exist.
+
+ The safe way to work with the run-time value of an expression is to
+put the expression into the macro expansion, so that its value is
+computed as part of executing the expansion.
+
+\1f
+File: lispref.info, Node: Repeated Expansion, Prev: Eval During Expansion, Up: Problems with Macros
+
+How Many Times is the Macro Expanded?
+-------------------------------------
+
+ Occasionally problems result from the fact that a macro call is
+expanded each time it is evaluated in an interpreted function, but is
+expanded only once (during compilation) for a compiled function. If the
+macro definition has side effects, they will work differently depending
+on how many times the macro is expanded.
+
+ In particular, constructing objects is a kind of side effect. If the
+macro is called once, then the objects are constructed only once. In
+other words, the same structure of objects is used each time the macro
+call is executed. In interpreted operation, the macro is reexpanded
+each time, producing a fresh collection of objects each time. Usually
+this does not matter--the objects have the same contents whether they
+are shared or not. But if the surrounding program does side effects on
+the objects, it makes a difference whether they are shared. Here is an
+example:
+
+ (defmacro empty-object ()
+ (list 'quote (cons nil nil)))
+
+ (defun initialize (condition)
+ (let ((object (empty-object)))
+ (if condition
+ (setcar object condition))
+ object))
+
+If `initialize' is interpreted, a new list `(nil)' is constructed each
+time `initialize' is called. Thus, no side effect survives between
+calls. If `initialize' is compiled, then the macro `empty-object' is
+expanded during compilation, producing a single "constant" `(nil)' that
+is reused and altered each time `initialize' is called.
+
+ One way to avoid pathological cases like this is to think of
+`empty-object' as a funny kind of constant, not as a memory allocation
+construct. You wouldn't use `setcar' on a constant such as `'(nil)',
+so naturally you won't use it on `(empty-object)' either.
+
+\1f
+File: lispref.info, Node: Customization, Up: Top
+
+Writing Customization Definitions
+*********************************
+
+ This chapter describes how to declare user options for customization,
+and also customization groups for classifying them. We use the term
+"customization item" to include both kinds of customization
+definitions--as well as face definitions.
+
+* Menu:
+
+* Common Keywords::
+* Group Definitions::
+* Variable Definitions::
+* Customization Types::
+
+\1f
+File: lispref.info, Node: Common Keywords, Next: Group Definitions, Up: Customization
+
+Common Keywords for All Kinds of Items
+======================================
+
+ All kinds of customization declarations (for variables and groups,
+and for faces) accept keyword arguments for specifying various
+information. This section describes some keywords that apply to all
+kinds.
+
+ All of these keywords, except `:tag', can be used more than once in
+a given item. Each use of the keyword has an independent effect. The
+keyword `:tag' is an exception because any given item can only display
+one name.
+
+`:tag NAME'
+ Use NAME, a string, instead of the item's name, to label the item
+ in customization menus and buffers.
+
+`:group GROUP'
+ Put this customization item in group GROUP. When you use `:group'
+ in a `defgroup', it makes the new group a subgroup of GROUP.
+
+ If you use this keyword more than once, you can put a single item
+ into more than one group. Displaying any of those groups will
+ show this item. Be careful not to overdo this!
+
+`:link LINK-DATA'
+ Include an external link after the documentation string for this
+ item. This is a sentence containing an active field which
+ references some other documentation.
+
+ There are three alternatives you can use for LINK-DATA:
+
+ `(custom-manual INFO-NODE)'
+ Link to an Info node; INFO-NODE is a string which specifies
+ the node name, as in `"(emacs)Top"'. The link appears as
+ `[manual]' in the customization buffer.
+
+ `(info-link INFO-NODE)'
+ Like `custom-manual' except that the link appears in the
+ customization buffer with the Info node name.
+
+ `(url-link URL)'
+ Link to a web page; URL is a string which specifies the URL.
+ The link appears in the customization buffer as URL.
+
+ You can specify the text to use in the customization buffer by
+ adding `:tag NAME' after the first element of the LINK-DATA; for
+ example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
+ Emacs manual which appears in the buffer as `foo'.
+
+ An item can have more than one external link; however, most items
+ have none at all.
+
+`:load FILE'
+ Load file FILE (a string) before displaying this customization
+ item. Loading is done with `load-library', and only if the file is
+ not already loaded.
+
+`:require FEATURE'
+ Require feature FEATURE (a symbol) when installing a value for
+ this item (an option or a face) that was saved using the
+ customization feature. This is done by calling `require'.
+
+ The most common reason to use `:require' is when a variable enables
+ a feature such as a minor mode, and just setting the variable
+ won't have any effect unless the code which implements the mode is
+ loaded.
+
+\1f
+File: lispref.info, Node: Group Definitions, Next: Variable Definitions, Prev: Common Keywords, Up: Customization
+
+Defining Custom Groups
+======================
+
+ Each Emacs Lisp package should have one main customization group
+which contains all the options, faces and other groups in the package.
+If the package has a small number of options and faces, use just one
+group and put everything in it. When there are more than twelve or so
+options and faces, then you should structure them into subgroups, and
+put the subgroups under the package's main customization group. It is
+OK to put some of the options and faces in the package's main group
+alongside the subgroups.
+
+ The package's main or only group should be a member of one or more of
+the standard customization groups. (To display the full list of them,
+use `M-x customize'.) Choose one or more of them (but not too many),
+and add your group to each of them using the `:group' keyword.
+
+ The way to declare new customization groups is with `defgroup'.
+
+ - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
+ Declare GROUP as a customization group containing MEMBERS. Do not
+ quote the symbol GROUP. The argument DOC specifies the
+ documentation string for the group.
+
+ The argument MEMBERS is a list specifying an initial set of
+ customization items to be members of the group. However, most
+ often MEMBERS is `nil', and you specify the group's members by
+ using the `:group' keyword when defining those members.
+
+ If you want to specify group members through MEMBERS, each element
+ should have the form `(NAME WIDGET)'. Here NAME is a symbol, and
+ WIDGET is a widget type for editing that symbol. Useful widgets
+ are `custom-variable' for a variable, `custom-face' for a face,
+ and `custom-group' for a group.
+
+ In addition to the common keywords (*note Common Keywords::.), you
+ can use this keyword in `defgroup':
+
+ `:prefix PREFIX'
+ If the name of an item in the group starts with PREFIX, then
+ the tag for that item is constructed (by default) by omitting
+ PREFIX.
+
+ One group can have any number of prefixes.
+
+\1f
+File: lispref.info, Node: Variable Definitions, Next: Customization Types, Prev: Group Definitions, Up: Customization
+
+Defining Customization Variables
+================================
+
+ Use `defcustom' to declare user-editable variables.
+
+ - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]...
+ Declare OPTION as a customizable user option variable. Do not
+ quote OPTION. The argument DOC specifies the documentation string
+ for the variable.
+
+ If OPTION is void, `defcustom' initializes it to DEFAULT. DEFAULT
+ should be an expression to compute the value; be careful in
+ writing it, because it can be evaluated on more than one occasion.
+
+ The following additional keywords are defined:
+
+ `:type TYPE'
+ Use TYPE as the data type for this option. It specifies which
+ values are legitimate, and how to display the value. *Note
+ Customization Types::, for more information.
+
+ `:options LIST'
+ Specify LIST as the list of reasonable values for use in this
+ option.
+
+ Currently this is meaningful only when the type is `hook'.
+ In that case, the elements of LIST should be functions that
+ are useful as elements of the hook value. The user is not
+ restricted to using only these functions, but they are
+ offered as convenient alternatives.
+
+ `:version VERSION'
+ This option specifies that the variable was first introduced,
+ or its default value was changed, in Emacs version VERSION.
+ The value VERSION must be a string. For example,
+
+ (defcustom foo-max 34
+ "*Maximum number of foo's allowed."
+ :type 'integer
+ :group 'foo
+ :version "20.3")
+
+ `:set SETFUNCTION'
+ Specify SETFUNCTION as the way to change the value of this
+ option. The function SETFUNCTION should take two arguments,
+ a symbol and the new value, and should do whatever is
+ necessary to update the value properly for this option (which
+ may not mean simply setting the option as a Lisp variable).
+ The default for SETFUNCTION is `set-default'.
+
+ `:get GETFUNCTION'
+ Specify GETFUNCTION as the way to extract the value of this
+ option. The function GETFUNCTION should take one argument, a
+ symbol, and should return the "current value" for that symbol
+ (which need not be the symbol's Lisp value). The default is
+ `default-value'.
+
+ `:initialize FUNCTION'
+ FUNCTION should be a function used to initialize the variable
+ when the `defcustom' is evaluated. It should take two
+ arguments, the symbol and value. Here are some predefined
+ functions meant for use in this way:
+
+ `custom-initialize-set'
+ Use the variable's `:set' function to initialize the
+ variable, but do not reinitialize it if it is already
+ non-void. This is the default `:initialize' function.
+
+ `custom-initialize-default'
+ Like `custom-initialize-set', but use the function
+ `set-default' to set the variable, instead of the
+ variable's `:set' function. This is the usual choice
+ for a variable whose `:set' function enables or disables
+ a minor mode; with this choice, defining the variable
+ will not call the minor mode function, but customizing
+ the variable will do so.
+
+ `custom-initialize-reset'
+ Always use the `:set' function to initialize the
+ variable. If the variable is already non-void, reset it
+ by calling the `:set' function using the current value
+ (returned by the `:get' method).
+
+ `custom-initialize-changed'
+ Use the `:set' function to initialize the variable, if
+ it is already set or has been customized; otherwise,
+ just use `set-default'.
+
+ The `:require' option is useful for an option that turns on the
+operation of a certain feature. Assuming that the package is coded to
+check the value of the option, you still need to arrange for the package
+to be loaded. You can do that with `:require'. *Note Common
+Keywords::. Here is an example, from the library `paren.el':
+
+ (defcustom show-paren-mode nil
+ "Toggle Show Paren mode...."
+ :set (lambda (symbol value)
+ (show-paren-mode (or value 0)))
+ :initialize 'custom-initialize-default
+ :type 'boolean
+ :group 'paren-showing
+ :require 'paren)
+
+ Internally, `defcustom' uses the symbol property `standard-value' to
+record the expression for the default value, and `saved-value' to
+record the value saved by the user with the customization buffer. The
+`saved-value' property is actually a list whose car is an expression
+which evaluates to the value.
+
+\1f
+File: lispref.info, Node: Customization Types, Prev: Variable Definitions, Up: Customization
+
+Customization Types
+===================
+
+ When you define a user option with `defcustom', you must specify its
+"customization type". That is a Lisp object which describes (1) which
+values are legitimate and (2) how to display the value in the
+customization buffer for editing.
+
+ You specify the customization type in `defcustom' with the `:type'
+keyword. The argument of `:type' is evaluated; since types that vary
+at run time are rarely useful, normally you use a quoted constant. For
+example:
+
+ (defcustom diff-command "diff"
+ "*The command to use to run diff."
+ :type '(string)
+ :group 'diff)
+
+ In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections. After this symbol come a number of arguments, depending on
+the symbol. Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (*note Type Keywords::.).
+
+ Some of the type symbols do not use any arguments; those are called
+"simple types". For a simple type, if you do not use any keyword-value
+pairs, you can omit the parentheses around the type symbol. For
+example just `string' as a customization type is equivalent to
+`(string)'.
+
+* Menu:
+
+* Simple Types::
+* Composite Types::
+* Splicing into Lists::
+* Type Keywords::
+
+\1f
+File: lispref.info, Node: Simple Types, Next: Composite Types, Up: Customization Types
+
+Simple Types
+------------
+
+ This section describes all the simple customization types.
+
+`sexp'
+ The value may be any Lisp object that can be printed and read
+ back. You can use `sexp' as a fall-back for any option, if you
+ don't want to take the time to work out a more specific type to
+ use.
+
+`integer'
+ The value must be an integer, and is represented textually in the
+ customization buffer.
+
+`number'
+ The value must be a number, and is represented textually in the
+ customization buffer.
+
+`string'
+ The value must be a string, and the customization buffer shows
+ just the contents, with no delimiting `"' characters and no
+ quoting with `\'.
+
+`regexp'
+ Like `string' except that the string must be a valid regular
+ expression.
+
+`character'
+ The value must be a character code. A character code is actually
+ an integer, but this type shows the value by inserting the
+ character in the buffer, rather than by showing the number.
+
+`file'
+ The value must be a file name, and you can do completion with
+ `M-<TAB>'.
+
+`(file :must-match t)'
+ The value must be a file name for an existing file, and you can do
+ completion with `M-<TAB>'.
+
+`directory'
+ The value must be a directory name, and you can do completion with
+ `M-<TAB>'.
+
+`symbol'
+ The value must be a symbol. It appears in the customization
+ buffer as the name of the symbol.
+
+`function'
+ The value must be either a lambda expression or a function name.
+ When it is a function name, you can do completion with `M-<TAB>'.
+
+`variable'
+ The value must be a variable name, and you can do completion with
+ `M-<TAB>'.
+
+`face'
+ The value must be a symbol which is a face name.
+
+`boolean'
+ The value is boolean--either `nil' or `t'. Note that by using
+ `choice' and `const' together (see the next section), you can
+ specify that the value must be `nil' or `t', but also specify the
+ text to describe each value in a way that fits the specific
+ meaning of the alternative.
+
+\1f
+File: lispref.info, Node: Composite Types, Next: Splicing into Lists, Prev: Simple Types, Up: Customization Types
+
+Composite Types
+---------------
+
+ When none of the simple types is appropriate, you can use composite
+types, which build new types from other types. Here are several ways of
+doing that:
+
+`(restricted-sexp :match-alternatives CRITERIA)'
+ The value may be any Lisp object that satisfies one of CRITERIA.
+ CRITERIA should be a list, and each elements should be one of
+ these possibilities:
+
+ * A predicate--that is, a function of one argument that returns
+ non-`nil' if the argument fits a certain type. This means
+ that objects of that type are acceptable.
+
+ * A quoted constant--that is, `'OBJECT'. This means that
+ OBJECT itself is an acceptable value.
+
+ For example,
+
+ (restricted-sexp :match-alternatives (integerp 't 'nil))
+
+ allows integers, `t' and `nil' as legitimate values.
+
+ The customization buffer shows all legitimate values using their
+ read syntax, and the user edits them textually.
+
+`(cons CAR-TYPE CDR-TYPE)'
+ The value must be a cons cell, its CAR must fit CAR-TYPE, and its
+ CDR must fit CDR-TYPE. For example, `(cons string symbol)' is a
+ customization type which matches values such as `("foo" . foo)'.
+
+ In the customization buffer, the CAR and the CDR are displayed and
+ edited separately, each according to the type that you specify for
+ it.
+
+`(list ELEMENT-TYPES...)'
+ The value must be a list with exactly as many elements as the
+ ELEMENT-TYPES you have specified; and each element must fit the
+ corresponding ELEMENT-TYPE.
+
+ For example, `(list integer string function)' describes a list of
+ three elements; the first element must be an integer, the second a
+ string, and the third a function.
+
+ In the customization buffer, the each element is displayed and
+ edited separately, according to the type specified for it.
+
+`(vector ELEMENT-TYPES...)'
+ Like `list' except that the value must be a vector instead of a
+ list. The elements work the same as in `list'.
+
+`(choice ALTERNATIVE-TYPES...)'
+ The value must fit at least one of ALTERNATIVE-TYPES. For
+ example, `(choice integer string)' allows either an integer or a
+ string.
+
+ In the customization buffer, the user selects one of the
+ alternatives using a menu, and can then edit the value in the
+ usual way for that alternative.
+
+ Normally the strings in this menu are determined automatically
+ from the choices; however, you can specify different strings for
+ the menu by including the `:tag' keyword in the alternatives. For
+ example, if an integer stands for a number of spaces, while a
+ string is text to use verbatim, you might write the customization
+ type this way,
+
+ (choice (integer :tag "Number of spaces")
+ (string :tag "Literal text"))
+
+ so that the menu offers `Number of spaces' and `Literal Text'.
+
+ In any alternative for which `nil' is not a valid value, other than
+ a `const', you should specify a valid default for that alternative
+ using the `:value' keyword. *Note Type Keywords::.
+
+`(const VALUE)'
+ The value must be VALUE--nothing else is allowed.
+
+ The main use of `const' is inside of `choice'. For example,
+ `(choice integer (const nil))' allows either an integer or `nil'.
+
+ `:tag' is often used with `const', inside of `choice'. For
+ example,
+
+ (choice (const :tag "Yes" t)
+ (const :tag "No" nil)
+ (const :tag "Ask" foo))
+
+`(function-item FUNCTION)'
+ Like `const', but used for values which are functions. This
+ displays the documentation string as well as the function name.
+ The documentation string is either the one you specify with
+ `:doc', or FUNCTION's own documentation string.
+
+`(variable-item VARIABLE)'
+ Like `const', but used for values which are variable names. This
+ displays the documentation string as well as the variable name.
+ The documentation string is either the one you specify with
+ `:doc', or VARIABLE's own documentation string.
+
+`(set ELEMENTS...)'
+ The value must be a list and each element of the list must be one
+ of the ELEMENTS specified. This appears in the customization
+ buffer as a checklist.
+
+`(repeat ELEMENT-TYPE)'
+ The value must be a list and each element of the list must fit the
+ type ELEMENT-TYPE. This appears in the customization buffer as a
+ list of elements, with `[INS]' and `[DEL]' buttons for adding more
+ elements or removing elements.
+
+\1f
+File: lispref.info, Node: Splicing into Lists, Next: Type Keywords, Prev: Composite Types, Up: Customization Types
+
+Splicing into Lists
+-------------------
+
+ The `:inline' feature lets you splice a variable number of elements
+into the middle of a list or vector. You use it in a `set', `choice'
+or `repeat' type which appears among the element-types of a `list' or
+`vector'.
+
+ Normally, each of the element-types in a `list' or `vector'
+describes one and only one element of the list or vector. Thus, if an
+element-type is a `repeat', that specifies a list of unspecified length
+which appears as one element.
+
+ But when the element-type uses `:inline', the value it matches is
+merged directly into the containing sequence. For example, if it
+matches a list with three elements, those become three elements of the
+overall sequence. This is analogous to using `,@' in the backquote
+construct.
+
+ For example, to specify a list whose first element must be `t' and
+whose remaining arguments should be zero or more of `foo' and `bar',
+use this customization type:
+
+ (list (const t) (set :inline t foo bar))
+
+This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
+bar)'.
+
+ When the element-type is a `choice', you use `:inline' not in the
+`choice' itself, but in (some of) the alternatives of the `choice'.
+For example, to match a list which must start with a file name,
+followed either by the symbol `t' or two strings, use this
+customization type:
+
+ (list file
+ (choice (const t)
+ (list :inline t string string)))
+
+If the user chooses the first alternative in the choice, then the
+overall list has two elements and the second element is `t'. If the
+user chooses the second alternative, then the overall list has three
+elements and the second and third must be strings.
+
+\1f
+File: lispref.info, Node: Type Keywords, Prev: Splicing into Lists, Up: Customization Types
+
+Type Keywords
+-------------
+
+ You can specify keyword-argument pairs in a customization type after
+the type name symbol. Here are the keywords you can use, and their
+meanings:
+
+`:value DEFAULT'
+ This is used for a type that appears as an alternative inside of
+ `choice'; it specifies the default value to use, at first, if and
+ when the user selects this alternative with the menu in the
+ customization buffer.
+
+ Of course, if the actual value of the option fits this
+ alternative, it will appear showing the actual value, not DEFAULT.
+
+ If `nil' is not a valid value for the alternative, then it is
+ essential to specify a valid default with `:value'.
+
+`:format FORMAT-STRING'
+ This string will be inserted in the buffer to represent the value
+ corresponding to the type. The following `%' escapes are available
+ for use in FORMAT-STRING:
+
+ `%[BUTTON%]'
+ Display the text BUTTON marked as a button. The `:action'
+ attribute specifies what the button will do if the user
+ invokes it; its value is a function which takes two
+ arguments--the widget which the button appears in, and the
+ event.
+
+ There is no way to specify two different buttons with
+ different actions.
+
+ `%{SAMPLE%}'
+ Show SAMPLE in a special face specified by `:sample-face'.
+
+ `%v'
+ Substitute the item's value. How the value is represented
+ depends on the kind of item, and (for variables) on the
+ customization type.
+
+ `%d'
+ Substitute the item's documentation string.
+
+ `%h'
+ Like `%d', but if the documentation string is more than one
+ line, add an active field to control whether to show all of
+ it or just the first line.
+
+ `%t'
+ Substitute the tag here. You specify the tag with the `:tag'
+ keyword.
+
+ `%%'
+ Display a literal `%'.
+
+`:action ACTION'
+ Perform ACTION if the user clicks on a button.
+
+`:button-face FACE'
+ Use the face FACE (a face name or a list of face names) for button
+ text displayed with `%[...%]'.
+
+`:button-prefix PREFIX'
+`:button-suffix SUFFIX'
+ These specify the text to display before and after a button. Each
+ can be:
+
+ `nil'
+ No text is inserted.
+
+ a string
+ The string is inserted literally.
+
+ a symbol
+ The symbol's value is used.
+
+`:tag TAG'
+ Use TAG (a string) as the tag for the value (or part of the value)
+ that corresponds to this type.
+
+`:doc DOC'
+ Use DOC as the documentation string for this value (or part of the
+ value) that corresponds to this type. In order for this to work,
+ you must specify a value for `:format', and use `%d' or `%h' in
+ that value.
+
+ The usual reason to specify a documentation string for a type is to
+ provide more information about the meanings of alternatives inside
+ a `:choice' type or the parts of some other composite type.
+
+`:help-echo MOTION-DOC'
+ When you move to this item with `widget-forward' or
+ `widget-backward', it will display the string MOTION-DOC in the
+ echo area.
+
+`:match FUNCTION'
+ Specify how to decide whether a value matches the type. The
+ corresponding value, FUNCTION, should be a function that accepts
+ two arguments, a widget and a value; it should return non-`nil' if
+ the value is acceptable.
+
+\1f
+File: lispref.info, Node: Loading, Next: Byte Compilation, Prev: Macros, Up: Top
+
+Loading
+*******
+
+ Loading a file of Lisp code means bringing its contents into the Lisp
+environment in the form of Lisp objects. XEmacs finds and opens the
+file, reads the text, evaluates each form, and then closes the file.
+
+ The load functions evaluate all the expressions in a file just as
+the `eval-current-buffer' function evaluates all the expressions in a
+buffer. The difference is that the load functions read and evaluate
+the text in the file as found on disk, not the text in an Emacs buffer.
+
+ The loaded file must contain Lisp expressions, either as source code
+or as byte-compiled code. Each form in the file is called a "top-level
+form". There is no special format for the forms in a loadable file;
+any form in a file may equally well be typed directly into a buffer and
+evaluated there. (Indeed, most code is tested this way.) Most often,
+the forms are function definitions and variable definitions.
+
+ A file containing Lisp code is often called a "library". Thus, the
+"Rmail library" is a file containing code for Rmail mode. Similarly, a
+"Lisp library directory" is a directory of files containing Lisp code.
+
+* Menu:
+
+* How Programs Do Loading:: The `load' function and others.
+* Autoload:: Setting up a function to autoload.
+* Repeated Loading:: Precautions about loading a file twice.
+* Named Features:: Loading a library if it isn't already loaded.
+* Unloading:: How to "unload" a library that was loaded.
+* Hooks for Loading:: Providing code to be run when
+ particular libraries are loaded.
+
+\1f
+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|writeable|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::.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, Up: Loading
+
+Autoload
+========
+
+ The "autoload" facility allows you to make a function or macro known
+in Lisp, but put off loading the file that defines it. The first call
+to the function automatically reads the proper file to install the real
+definition and other associated code, then runs the real definition as
+if it had been loaded all along.
+
+ There are two ways to set up an autoloaded function: by calling
+`autoload', and by writing a special "magic" comment in the source
+before the real definition. `autoload' is the low-level primitive for
+autoloading; any Lisp program can call `autoload' at any time. Magic
+comments do nothing on their own; they serve as a guide for the command
+`update-file-autoloads', which constructs calls to `autoload' and
+arranges to execute them when Emacs is built. Magic comments are the
+most convenient way to make a function autoload, but only for packages
+installed along with Emacs.
+
+ - Function: autoload FUNCTION FILENAME &optional DOCSTRING INTERACTIVE
+ TYPE
+ This function defines the function (or macro) named FUNCTION so as
+ to load automatically from FILENAME. The string FILENAME
+ 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.
+
+ If INTERACTIVE is non-`nil', then the function can be called
+ interactively. This lets completion in `M-x' work without loading
+ the function's real definition. The complete interactive
+ specification need not be given here; it's not needed unless the
+ user actually calls FUNCTION, and when that happens, it's time to
+ load the real definition.
+
+ You can autoload macros and keymaps as well as ordinary functions.
+ Specify TYPE as `macro' if FUNCTION is really a macro. Specify
+ TYPE as `keymap' if FUNCTION is really a keymap. Various parts of
+ Emacs need to know this information without loading the real
+ definition.
+
+ An autoloaded keymap loads automatically during key lookup when a
+ prefix key's binding is the symbol FUNCTION. Autoloading does not
+ occur for other kinds of access to the keymap. In particular, it
+ does not happen when a Lisp program gets the keymap from the value
+ of a variable and calls `define-key'; not even if the variable
+ name is the same symbol FUNCTION.
+
+ If FUNCTION already has a non-void function definition that is not
+ an autoload object, `autoload' does nothing and returns `nil'. If
+ the function cell of FUNCTION is void, or is already an autoload
+ object, then it is defined as an autoload object like this:
+
+ (autoload FILENAME DOCSTRING INTERACTIVE TYPE)
+
+ For example,
+
+ (symbol-function 'run-prolog)
+ => (autoload "prolog" 169681 t nil)
+
+ In this case, `"prolog"' is the name of the file to load, 169681
+ refers to the documentation string in the `DOC' file (*note
+ Documentation Basics::.), `t' means the function is interactive,
+ and `nil' that it is not a macro or a keymap.
+
+ The autoloaded file usually contains other definitions and may
+require or provide one or more features. If the file is not completely
+loaded (due to an error in the evaluation of its contents), any function
+definitions or `provide' calls that occurred during the load are
+undone. This is to ensure that the next attempt to call any function
+autoloading from this file will try again to load the file. If not for
+this, then some of the functions in the file might appear defined, but
+they might fail to work properly for the lack of certain subroutines
+defined later in the file and not loaded successfully.
+
+ XEmacs as distributed comes with many autoloaded functions. The
+calls to `autoload' are in the file `loaddefs.el'. There is a
+convenient way of updating them automatically.
+
+ If the autoloaded file fails to define the desired Lisp function or
+macro, then an error is signaled with data `"Autoloading failed to
+define function FUNCTION-NAME"'.
+
+ A magic autoload comment looks like `;;;###autoload', on a line by
+itself, just before the real definition of the function in its
+autoloadable source file. The command `M-x update-file-autoloads'
+writes a corresponding `autoload' call into `loaddefs.el'. Building
+Emacs loads `loaddefs.el' and thus calls `autoload'. `M-x
+update-directory-autoloads' is even more powerful; it updates autoloads
+for all files in the current directory.
+
+ The same magic comment can copy any kind of form into `loaddefs.el'.
+If the form following the magic comment is not a function definition,
+it is copied verbatim. You can also use a magic comment to execute a
+form at build time *without* executing it when the file itself is
+loaded. To do this, write the form "on the same line" as the magic
+comment. Since it is in a comment, it does nothing when you load the
+source file; but `update-file-autoloads' copies it to `loaddefs.el',
+where it is executed while building Emacs.
+
+ The following example shows how `doctor' is prepared for autoloading
+with a magic comment:
+
+ ;;;###autoload
+ (defun doctor ()
+ "Switch to *doctor* buffer and start giving psychotherapy."
+ (interactive)
+ (switch-to-buffer "*doctor*")
+ (doctor-mode))
+
+Here's what that produces in `loaddefs.el':
+
+ (autoload 'doctor "doctor"
+ "\
+ Switch to *doctor* buffer and start giving psychotherapy."
+ t)
+
+The backslash and newline immediately following the double-quote are a
+convention used only in the preloaded Lisp files such as `loaddefs.el';
+they tell `make-docfile' to put the documentation string in the `DOC'
+file. *Note Building XEmacs::.
+
+\1f
+File: lispref.info, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading
+
+Repeated Loading
+================
+
+ You may load one file more than once in an Emacs session. For
+example, after you have rewritten and reinstalled a function definition
+by editing it in a buffer, you may wish to return to the original
+version; you can do this by reloading the file it came from.
+
+ When you load or reload files, bear in mind that the `load' and
+`load-library' functions automatically load a byte-compiled file rather
+than a non-compiled file of similar name. If you rewrite a file that
+you intend to save and reinstall, remember to byte-compile it if
+necessary; otherwise you may find yourself inadvertently reloading the
+older, byte-compiled file instead of your newer, non-compiled file!
+
+ When writing the forms in a Lisp library file, keep in mind that the
+file might be loaded more than once. For example, the choice of
+`defvar' vs. `defconst' for defining a variable depends on whether it
+is desirable to reinitialize the variable if the library is reloaded:
+`defconst' does so, and `defvar' does not. (*Note Defining
+Variables::.)
+
+ The simplest way to add an element to an alist is like this:
+
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist))
+
+But this would add multiple elements if the library is reloaded. To
+avoid the problem, write this:
+
+ (or (assq 'leif-mode minor-mode-alist)
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist)))
+
+ To add an element to a list just once, use `add-to-list' (*note
+Setting Variables::.).
+
+ Occasionally you will want to test explicitly whether a library has
+already been loaded. Here's one way to test, in a library, whether it
+has been loaded before:
+
+ (defvar foo-was-loaded)
+
+ (if (not (boundp 'foo-was-loaded))
+ EXECUTE-FIRST-TIME-ONLY)
+
+ (setq foo-was-loaded t)
+
+If the library uses `provide' to provide a named feature, you can use
+`featurep' to test whether the library has been loaded. *Note Named
+Features::.
+
+\1f
+File: lispref.info, Node: Named Features, Next: Unloading, Prev: Repeated Loading, Up: Loading
+
+Features
+========
+
+ `provide' and `require' are an alternative to `autoload' for loading
+files automatically. They work in terms of named "features".
+Autoloading is triggered by calling a specific function, but a feature
+is loaded the first time another program asks for it by name.
+
+ A feature name is a symbol that stands for a collection of functions,
+variables, etc. The file that defines them should "provide" the
+feature. Another program that uses them may ensure they are defined by
+"requiring" the feature. This loads the file of definitions if it
+hasn't been loaded already.
+
+ To require the presence of a feature, call `require' with the
+feature name as argument. `require' looks in the global variable
+`features' to see whether the desired feature has been provided
+already. If not, it loads the feature from the appropriate file. This
+file should call `provide' at the top level to add the feature to
+`features'; if it fails to do so, `require' signals an error.
+
+ Features are normally named after the files that provide them, so
+that `require' need not be given the file name.
+
+ For example, in `emacs/lisp/prolog.el', the definition for
+`run-prolog' includes the following code:
+
+ (defun run-prolog ()
+ "Run an inferior Prolog process, input and output via buffer *prolog*."
+ (interactive)
+ (require 'comint)
+ (switch-to-buffer (make-comint "prolog" prolog-program-name))
+ (inferior-prolog-mode))
+
+The expression `(require 'comint)' loads the file `comint.el' if it has
+not yet been loaded. This ensures that `make-comint' is defined.
+
+ The `comint.el' file contains the following top-level expression:
+
+ (provide 'comint)
+
+This adds `comint' to the global `features' list, so that `(require
+'comint)' will henceforth know that nothing needs to be done.
+
+ When `require' is used at top level in a file, it takes effect when
+you byte-compile that file (*note Byte Compilation::.) as well as when
+you load it. This is in case the required package contains macros that
+the byte compiler must know about.
+
+ Although top-level calls to `require' are evaluated during byte
+compilation, `provide' calls are not. Therefore, you can ensure that a
+file of definitions is loaded before it is byte-compiled by including a
+`provide' followed by a `require' for the same feature, as in the
+following example.
+
+ (provide 'my-feature) ; Ignored by byte compiler,
+ ; evaluated by `load'.
+ (require 'my-feature) ; Evaluated by byte compiler.
+
+The compiler ignores the `provide', then processes the `require' by
+loading the file in question. Loading the file does execute the
+`provide' call, so the subsequent `require' call does nothing while
+loading.
+
+ - Function: provide FEATURE
+ This function announces that FEATURE is now loaded, or being
+ loaded, into the current XEmacs session. This means that the
+ facilities associated with FEATURE are or will be available for
+ other Lisp programs.
+
+ The direct effect of calling `provide' is to add FEATURE to the
+ front of the list `features' if it is not already in the list.
+ The argument FEATURE must be a symbol. `provide' returns FEATURE.
+
+ features
+ => (bar bish)
+
+ (provide 'foo)
+ => foo
+ features
+ => (foo bar bish)
+
+ When a file is loaded to satisfy an autoload, and it stops due to
+ an error in the evaluating its contents, any function definitions
+ or `provide' calls that occurred during the load are undone.
+ *Note Autoload::.
+
+ - Function: require FEATURE &optional FILENAME
+ This function checks whether FEATURE is present in the current
+ XEmacs session (using `(featurep FEATURE)'; see below). If it is
+ not, then `require' loads FILENAME with `load'. If FILENAME is
+ not supplied, then the name of the symbol FEATURE is used as the
+ file name to load.
+
+ If loading the file fails to provide FEATURE, `require' signals an
+ error, `Required feature FEATURE was not provided'.
+
+ - Function: featurep FEXP
+ This function returns `t' if feature FEXP is present in this
+ Emacs. Use this to conditionalize execution of lisp code based on
+ the presence or absence of emacs or environment extensions.
+
+ FEXP can be a symbol, a number, or a list.
+
+ If FEXP is a symbol, it is looked up in the `features' variable,
+ 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
+ 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.
+
+ If FEXP is a list whose car is the symbol `and', the function
+ returns `t' if all the features in its cdr are present, `nil'
+ otherwise.
+
+ If FEXP is a list whose car is the symbol `or', the function
+ returns `t' if any the features in its cdr are present, `nil'
+ otherwise.
+
+ If FEXP is a list whose car is the symbol `not', the function
+ returns `t' if the feature is not present, `nil' otherwise.
+
+ Examples:
+
+ (featurep 'xemacs)
+ => ; t on XEmacs.
+
+ (featurep '(and xemacs gnus))
+ => ; t on XEmacs with Gnus loaded.
+
+ (featurep '(or tty-frames (and emacs 19.30)))
+ => ; t if this Emacs supports TTY frames.
+
+ (featurep '(or (and xemacs 19.15) (and emacs 19.34)))
+ => ; t on XEmacs 19.15 and later, or on
+ ; FSF Emacs 19.34 and later.
+
+ *Please note:* The advanced arguments of this function (anything
+ other than a symbol) are not yet supported by FSF Emacs. If you
+ feel they are useful for supporting multiple Emacs variants, lobby
+ Richard Stallman at `<bug-gnu-emacs@prep.ai.mit.edu>'.
+
+ - Variable: features
+ The value of this variable is a list of symbols that are the
+ features loaded in the current XEmacs session. Each symbol was
+ put in this list with a call to `provide'. The order of the
+ elements in the `features' list is not significant.
+
+\1f
+File: lispref.info, Node: Unloading, Next: Hooks for Loading, Prev: Named Features, Up: Loading
+
+Unloading
+=========
+
+ You can discard the functions and variables loaded by a library to
+reclaim memory for other Lisp objects. To do this, use the function
+`unload-feature':
+
+ - Command: unload-feature FEATURE &optional FORCE
+ This command unloads the library that provided feature FEATURE.
+ It undefines all functions, macros, and variables defined in that
+ library with `defconst', `defvar', `defun', `defmacro',
+ `defsubst', `definf-function' and `defalias'. It then restores
+ any autoloads formerly associated with those symbols. (Loading
+ saves these in the `autoload' property of the symbol.)
+
+ Ordinarily, `unload-feature' refuses to unload a library on which
+ other loaded libraries depend. (A library A depends on library B
+ if A contains a `require' for B.) If the optional argument FORCE
+ is non-`nil', dependencies are ignored and you can unload any
+ library.
+
+ The `unload-feature' function is written in Lisp; its actions are
+based on the variable `load-history'.
+
+ - Variable: load-history
+ This variable's value is an alist connecting library names with the
+ names of functions and variables they define, the features they
+ provide, and the features they require.
+
+ Each element is a list and describes one library. The CAR of the
+ list is the name of the library, as a string. The rest of the
+ list is composed of these kinds of objects:
+
+ * Symbols that were defined by this library.
+
+ * Lists of the form `(require . FEATURE)' indicating features
+ that were required.
+
+ * Lists of the form `(provide . FEATURE)' indicating features
+ that were provided.
+
+ The value of `load-history' may have one element whose CAR is
+ `nil'. This element describes definitions made with `eval-buffer'
+ on a buffer that is not visiting a file.
+
+ The command `eval-region' updates `load-history', but does so by
+adding the symbols defined to the element for the file being visited,
+rather than replacing that element.
+
+\1f
+File: lispref.info, Node: Hooks for Loading, Prev: Unloading, Up: Loading
+
+Hooks for Loading
+=================
+
+ - Variable: after-load-alist
+ An alist of expressions to evaluate if and when particular
+ libraries are loaded. Each element looks like this:
+
+ (FILENAME FORMS...)
+
+ When `load' is run and the file-name argument is FILENAME, the
+ FORMS in the corresponding element are executed at the end of
+ loading.
+
+ FILENAME must match exactly! Normally FILENAME is the name of a
+ library, with no directory specified, since that is how `load' is
+ normally called. An error in FORMS does not undo the load, but
+ does prevent execution of the rest of the FORMS.
+
+
+\1f
+File: lispref.info, Node: Byte Compilation, Next: Debugging, Prev: Loading, Up: Top
+
+Byte Compilation
+****************
+
+ XEmacs Lisp has a "compiler" that translates functions written in
+Lisp into a special representation called "byte-code" that can be
+executed more efficiently. The compiler replaces Lisp function
+definitions with byte-code. When a byte-coded function is called, its
+definition is evaluated by the "byte-code interpreter".
+
+ Because the byte-compiled code is evaluated by the byte-code
+interpreter, instead of being executed directly by the machine's
+hardware (as true compiled code is), byte-code is completely
+transportable from machine to machine without recompilation. It is not,
+however, as fast as true compiled code.
+
+ In general, any version of Emacs can run byte-compiled code produced
+by recent earlier versions of Emacs, but the reverse is not true. In
+particular, if you compile a program with XEmacs 20, the compiled code
+may not run in earlier versions.
+
+ The first time a compiled-function object is executed, the byte-code
+instructions are validated and the byte-code is further optimized. An
+`invalid-byte-code' error is signaled if the byte-code is invalid, for
+example if it contains invalid opcodes. This usually means a bug in
+the byte compiler.
+
+ *Note Compilation Errors::, for how to investigate errors occurring
+in byte compilation.
+
+* Menu:
+
+* Speed of Byte-Code:: An example of speedup from byte compilation.
+* Compilation Functions:: Byte compilation functions.
+* Docs and Compilation:: Dynamic loading of documentation strings.
+* Dynamic Loading:: Dynamic loading of individual functions.
+* Eval During Compile:: Code to be evaluated when you compile.
+* Compiled-Function Objects:: The data type used for byte-compiled functions.
+* Disassembly:: Disassembling byte-code; how to read byte-code.
+
+\1f
+File: lispref.info, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation
+
+Performance of Byte-Compiled Code
+=================================
+
+ A byte-compiled function is not as efficient as a primitive function
+written in C, but runs much faster than the version written in Lisp.
+Here is an example:
+
+ (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
+
+ (silly-loop 5000000)
+ => ("Mon Sep 14 15:51:49 1998"
+ "Mon Sep 14 15:52:07 1998") ; 18 seconds
+
+ (byte-compile 'silly-loop)
+ => #<compiled-function
+ (n)
+ "...(23)"
+ [current-time-string t1 n 0]
+ 2
+ "Return time before and after N iterations of a loop.">
+
+ (silly-loop 5000000)
+ => ("Mon Sep 14 15:53:43 1998"
+ "Mon Sep 14 15:53:49 1998") ; 6 seconds
+
+ In this example, the interpreted code required 18 seconds to run,
+whereas the byte-compiled code required 6 seconds. These results are
+representative, but actual results will vary greatly.
+
+\1f
+File: lispref.info, Node: Compilation Functions, Next: Docs and Compilation, Prev: Speed of Byte-Code, Up: Byte Compilation
+
+The Compilation Functions
+=========================
+
+ You can byte-compile an individual function or macro definition with
+the `byte-compile' function. You can compile a whole file with
+`byte-compile-file', or several files with `byte-recompile-directory'
+or `batch-byte-compile'.
+
+ When you run the byte compiler, you may get warnings in a buffer
+called `*Compile-Log*'. These report things in your program that
+suggest a problem but are not necessarily erroneous.
+
+ Be careful when byte-compiling code that uses macros. Macro calls
+are expanded when they are compiled, so the macros must already be
+defined for proper compilation. For more details, see *Note Compiling
+Macros::.
+
+ Normally, compiling a file does not evaluate the file's contents or
+load the file. But it does execute any `require' calls at top level in
+the file. One way to ensure that necessary macro definitions are
+available during compilation is to `require' the file that defines them
+(*note Named Features::.). To avoid loading the macro definition files
+when someone *runs* the compiled program, write `eval-when-compile'
+around the `require' calls (*note Eval During Compile::.).
+
+ - Function: byte-compile SYMBOL
+ This function byte-compiles the function definition of SYMBOL,
+ replacing the previous definition with the compiled one. The
+ function definition of SYMBOL must be the actual code for the
+ function; i.e., the compiler does not follow indirection to
+ another symbol. `byte-compile' returns the new, compiled
+ definition of SYMBOL.
+
+ If SYMBOL's definition is a compiled-function object,
+ `byte-compile' does nothing and returns `nil'. Lisp records only
+ one function definition for any symbol, and if that is already
+ compiled, non-compiled code is not available anywhere. So there
+ is no way to "compile the same definition again."
+
+ (defun factorial (integer)
+ "Compute factorial of INTEGER."
+ (if (= 1 integer) 1
+ (* integer (factorial (1- integer)))))
+ => factorial
+
+ (byte-compile 'factorial)
+ => #<compiled-function
+ (integer)
+ "...(21)"
+ [integer 1 factorial]
+ 3
+ "Compute factorial of INTEGER.">
+
+ The result is a compiled-function object. The string it contains
+ is the actual byte-code; each character in it is an instruction or
+ an operand of an instruction. The vector contains all the
+ constants, variable names and function names used by the function,
+ except for certain primitives that are coded as special
+ instructions.
+
+ - Command: compile-defun &optional ARG
+ This command reads the defun containing point, compiles it, and
+ evaluates the result. If you use this on a defun that is actually
+ a function definition, the effect is to install a compiled version
+ of that function.
+
+ If ARG is non-`nil', the result is inserted in the current buffer
+ after the form; otherwise, it is printed in the minibuffer.
+
+ - Command: byte-compile-file FILENAME &optional LOAD
+ This function compiles a file of Lisp code named FILENAME into a
+ file of byte-code. The output file's name is made by appending
+ `c' to the end of FILENAME.
+
+ If `load' is non-`nil', the file is loaded after having been
+ compiled.
+
+ Compilation works by reading the input file one form at a time.
+ If it is a definition of a function or macro, the compiled
+ function or macro definition is written out. Other forms are
+ batched together, then each batch is compiled, and written so that
+ its compiled code will be executed when the file is read. All
+ comments are discarded when the input file is read.
+
+ This command returns `t'. When called interactively, it prompts
+ for the file name.
+
+ % ls -l push*
+ -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
+
+ (byte-compile-file "~/emacs/push.el")
+ => t
+
+ % ls -l push*
+ -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
+ -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
+
+ - Command: byte-recompile-directory DIRECTORY &optional FLAG
+ 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.
+
+ 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.
+
+ The return value of this command is unpredictable.
+
+ - Function: batch-byte-compile
+ This function runs `byte-compile-file' on files specified on the
+ command line. This function must be used only in a batch
+ execution of Emacs, as it kills Emacs on completion. An error in
+ one file does not prevent processing of subsequent files. (The
+ file that gets the error will not, of course, produce any compiled
+ code.)
+
+ % emacs -batch -f batch-byte-compile *.el
+
+ - Function: batch-byte-recompile-directory
+ This function is similar to `batch-byte-compile' but runs the
+ command `byte-recompile-directory' on the files remaining on the
+ command line.
+
+ - Variable: byte-recompile-directory-ignore-errors-p
+ If non-`nil', this specifies that `byte-recompile-directory' will
+ continue compiling even when an error occurs in a file. This is
+ normally `nil', but is bound to `t' by
+ `batch-byte-recompile-directory'.
+
+ - Function: byte-code INSTRUCTIONS CONSTANTS STACK-SIZE
+ 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.
+
+ In newer Emacs versions (19 and up), byte code is usually executed
+ as part of a compiled-function object, and only rarely due to an
+ explicit call to `byte-code'. A byte-compiled function was once
+ actually defined with a body that calls `byte-code', but in recent
+ versions of Emacs `byte-code' is only used to run isolated
+ fragments of lisp code without an associated argument list.
+
+\1f
+File: lispref.info, Node: Docs and Compilation, Next: Dynamic Loading, Prev: Compilation Functions, Up: Byte Compilation
+
+Documentation Strings and Compilation
+=====================================
+
+ Functions and variables loaded from a byte-compiled file access their
+documentation strings dynamically from the file whenever needed. This
+saves space within Emacs, and makes loading faster because the
+documentation strings themselves need not be processed while loading the
+file. Actual access to the documentation strings becomes slower as a
+result, but normally not enough to bother users.
+
+ Dynamic access to documentation strings does have drawbacks:
+
+ * If you delete or move the compiled file after loading it, Emacs
+ can no longer access the documentation strings for the functions
+ and variables in the file.
+
+ * If you alter the compiled file (such as by compiling a new
+ version), then further access to documentation strings in this
+ file will give nonsense results.
+
+ If your site installs Emacs following the usual procedures, these
+problems will never normally occur. Installing a new version uses a new
+directory with a different name; as long as the old version remains
+installed, its files will remain unmodified in the places where they are
+expected to be.
+
+ However, if you have built Emacs yourself and use it from the
+directory where you built it, you will experience this problem
+occasionally if you edit and recompile Lisp files. When it happens, you
+can cure the problem by reloading the file after recompiling it.
+
+ Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs
+19.28 do not support the dynamic docstrings feature, and so will not be
+able to load bytecode created by more recent Emacs versions. You can
+turn off the dynamic docstring feature by setting
+`byte-compile-dynamic-docstrings' to `nil'. Once this is done, you can
+compile files that will load into older Emacs versions. You can do
+this globally, or for one source file by specifying a file-local
+binding for the variable. Here's one way to do that:
+
+ -*-byte-compile-dynamic-docstrings: nil;-*-
+
+ - Variable: byte-compile-dynamic-docstrings
+ If this is non-`nil', the byte compiler generates compiled files
+ that are set up for dynamic loading of documentation strings.
+
+ The dynamic documentation string feature writes compiled files that
+use a special Lisp reader construct, `#@COUNT'. This construct skips
+the next COUNT characters. It also uses the `#$' construct, which
+stands for "the name of this file, as a string." It is best not to use
+these constructs in Lisp source files.
+
+\1f
+File: lispref.info, Node: Dynamic Loading, Next: Eval During Compile, Prev: Docs and Compilation, Up: Byte Compilation
+
+Dynamic Loading of Individual Functions
+=======================================
+
+ When you compile a file, you can optionally enable the "dynamic
+function loading" feature (also known as "lazy loading"). With dynamic
+function loading, loading the file doesn't fully read the function
+definitions in the file. Instead, each function definition contains a
+place-holder which refers to the file. The first time each function is
+called, it reads the full definition from the file, to replace the
+place-holder.
+
+ The advantage of dynamic function loading is that loading the file
+becomes much faster. This is a good thing for a file which contains
+many separate commands, provided that using one of them does not imply
+you will soon (or ever) use the rest. A specialized mode which provides
+many keyboard commands often has that usage pattern: a user may invoke
+the mode, but use only a few of the commands it provides.
+
+ The dynamic loading feature has certain disadvantages:
+
+ * If you delete or move the compiled file after loading it, Emacs
+ can no longer load the remaining function definitions not already
+ loaded.
+
+ * If you alter the compiled file (such as by compiling a new
+ version), then trying to load any function not already loaded will
+ get nonsense results.
+
+ If you compile a new version of the file, the best thing to do is
+immediately load the new compiled file. That will prevent any future
+problems.
+
+ The byte compiler uses the dynamic function loading feature if the
+variable `byte-compile-dynamic' is non-`nil' at compilation time. Do
+not set this variable globally, since dynamic loading is desirable only
+for certain files. Instead, enable the feature for specific source
+files with file-local variable bindings, like this:
+
+ -*-byte-compile-dynamic: t;-*-
+
+ - Variable: byte-compile-dynamic
+ If this is non-`nil', the byte compiler generates compiled files
+ that are set up for dynamic function loading.
+
+ - Function: fetch-bytecode FUNCTION
+ This immediately finishes loading the definition of FUNCTION from
+ its byte-compiled file, if it is not fully loaded already. The
+ argument FUNCTION may be a compiled-function object or a function
+ name.
+
+\1f
+File: lispref.info, Node: Eval During Compile, Next: Compiled-Function Objects, Prev: Dynamic Loading, Up: Byte Compilation
+
+Evaluation During Compilation
+=============================
+
+ These features permit you to write code to be evaluated during
+compilation of a program.
+
+ - Special Form: eval-and-compile BODY
+ This form marks BODY to be evaluated both when you compile the
+ containing code and when you run it (whether compiled or not).
+
+ You can get a similar result by putting BODY in a separate file
+ and referring to that file with `require'. Using `require' is
+ preferable if there is a substantial amount of code to be executed
+ in this way.
+
+ - Special Form: eval-when-compile BODY
+ This form marks BODY to be evaluated at compile time and not when
+ the compiled program is loaded. The result of evaluation by the
+ compiler becomes a constant which appears in the compiled program.
+ When the program is interpreted, not compiled at all, BODY is
+ evaluated normally.
+
+ At top level, this is analogous to the Common Lisp idiom
+ `(eval-when (compile eval) ...)'. Elsewhere, the Common Lisp `#.'
+ reader macro (but not when interpreting) is closer to what
+ `eval-when-compile' does.
+
+\1f
+File: lispref.info, Node: Compiled-Function Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation
+
+Compiled-Function Objects
+=========================
+
+ Byte-compiled functions have a special data type: they are
+"compiled-function objects". The evaluator handles this data type
+specially when it appears as a function to be called.
+
+ The printed representation for a compiled-function object normally
+begins with `#<compiled-function' and ends with `>'. However, if the
+variable `print-readably' is non-`nil', the object is printed beginning
+with `#[' and ending with `]'. This representation can be read
+directly by the Lisp reader, and is used in byte-compiled files (those
+ending in `.elc').
+
+ In Emacs version 18, there was no compiled-function object data type;
+compiled functions used the function `byte-code' to run the byte code.
+
+ A compiled-function object has a number of different attributes.
+They are:
+
+ARGLIST
+ The list of argument symbols.
+
+INSTRUCTIONS
+ The string containing the byte-code instructions.
+
+CONSTANTS
+ The vector of Lisp objects referenced by the byte code. These
+ include symbols used as function names and variable names.
+
+STACK-SIZE
+ The maximum stack size this function needs.
+
+DOC-STRING
+ The documentation string (if any); otherwise, `nil'. The value may
+ be a number or a list, in case the documentation string is stored
+ in a file. Use the function `documentation' to get the real
+ documentation string (*note Accessing Documentation::.).
+
+INTERACTIVE
+ The interactive spec (if any). This can be a string or a Lisp
+ expression. It is `nil' for a function that isn't interactive.
+
+DOMAIN
+ The domain (if any). This is only meaningful if I18N3
+ (message-translation) support was compiled into XEmacs. This is a
+ string defining which domain to find the translation for the
+ documentation string and interactive prompt. *Note Domain
+ Specification::.
+
+ Here's an example of a compiled-function object, in printed
+representation. It is the definition of the command `backward-sexp'.
+
+ (symbol-function 'backward-sexp)
+ => #<compiled-function
+ (&optional arg)
+ "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
+
+ The primitive way to create a compiled-function object is with
+`make-byte-code':
+
+ - Function: make-byte-code ARGLIST INSTRUCTIONS CONSTANTS STACK-SIZE
+ &optional DOC-STRING INTERACTIVE
+ This function constructs and returns a compiled-function object
+ with the specified attributes.
+
+ *Please note:* Unlike all other Emacs-lisp functions, calling this
+ with five arguments is *not* the same as calling it with six
+ arguments, the last of which is `nil'. If the INTERACTIVE arg is
+ specified as `nil', then that means that this function was defined
+ with `(interactive)'. If the arg is not specified, then that means
+ the function is not interactive. This is terrible behavior which
+ is retained for compatibility with old `.elc' files which expected
+ these semantics.
+
+ You should not try to come up with the elements for a
+compiled-function object yourself, because if they are inconsistent,
+XEmacs may crash when you call the function. Always leave it to the
+byte compiler to create these objects; it makes the elements consistent
+(we hope).
+
+ The following primitives are provided for accessing the elements of
+a compiled-function object.
+
+ - Function: compiled-function-arglist FUNCTION
+ This function returns the argument list of compiled-function object
+ FUNCTION.
+
+ - Function: compiled-function-instructions FUNCTION
+ This function returns a string describing the byte-code
+ instructions of compiled-function object FUNCTION.
+
+ - Function: compiled-function-constants FUNCTION
+ This function returns the vector of Lisp objects referenced by
+ compiled-function object FUNCTION.
+
+ - Function: compiled-function-stack-size FUNCTION
+ This function returns the maximum stack size needed by
+ compiled-function object FUNCTION.
+
+ - Function: compiled-function-doc-string FUNCTION
+ This function returns the doc string of compiled-function object
+ FUNCTION, if available.
+
+ - Function: compiled-function-interactive FUNCTION
+ This function returns the interactive spec of compiled-function
+ object FUNCTION, if any. The return value is `nil' or a
+ two-element list, the first element of which is the symbol
+ `interactive' and the second element is the interactive spec (a
+ string or Lisp form).
+
+ - Function: compiled-function-domain FUNCTION
+ This function returns the domain of compiled-function object
+ FUNCTION, if any. The result will be a string or `nil'. *Note
+ Domain Specification::.
+
+\1f
+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
+
+\1f
+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::.
+
+\1f
+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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger
+
+Entering the Debugger on an Error
+---------------------------------
+
+ The most important time to enter the debugger is when a Lisp error
+happens. This allows you to investigate the immediate causes of the
+error.
+
+ However, entry to the debugger is not a normal consequence of an
+error. Many commands frequently get Lisp errors when invoked in
+inappropriate contexts (such as `C-f' at the end of the buffer) and
+during ordinary editing it would be very unpleasant to enter the
+debugger each time this happens. If you want errors to enter the
+debugger, set the variable `debug-on-error' to non-`nil'.
+
+ - User Option: debug-on-error
+ This variable determines whether the debugger is called when an
+ error is signaled and not handled. If `debug-on-error' is `t', all
+ errors call the debugger. If it is `nil', none call the debugger.
+
+ The value can also be a list of error conditions that should call
+ the debugger. For example, if you set it to the list
+ `(void-variable)', then only errors about a variable that has no
+ value invoke the debugger.
+
+ When this variable is non-`nil', Emacs does not catch errors that
+ happen in process filter functions and sentinels. Therefore, these
+ errors also can invoke the debugger. *Note Processes::.
+
+ - User Option: debug-ignored-errors
+ This variable specifies certain kinds of errors that should not
+ enter the debugger. Its value is a list of error condition
+ symbols and/or regular expressions. If the error has any of those
+ condition symbols, or if the error message matches any of the
+ regular expressions, then that error does not enter the debugger,
+ regardless of the value of `debug-on-error'.
+
+ The normal value of this variable lists several errors that happen
+ often during editing but rarely result from bugs in Lisp programs.
+
+ To debug an error that happens during loading of the `.emacs' file,
+use the option `-debug-init', which binds `debug-on-error' to `t' while
+`.emacs' is loaded and inhibits use of `condition-case' to catch init
+file errors.
+
+ If your `.emacs' file sets `debug-on-error', the effect may not last
+past the end of loading `.emacs'. (This is an undesirable byproduct of
+the code that implements the `-debug-init' command line option.) The
+best way to make `.emacs' set `debug-on-error' permanently is with
+`after-init-hook', like this:
+
+ (add-hook 'after-init-hook
+ '(lambda () (setq debug-on-error t)))
+
+ - User Option: debug-on-signal
+ This variable is similar to `debug-on-error' but breaks whenever
+ an error is signalled, regardless of whether it would be handled.
+
+\1f
+File: lispref.info, Node: Infinite Loops, Next: Function Debugging, Prev: Error Debugging, Up: Debugger
+
+Debugging Infinite Loops
+------------------------
+
+ When a program loops infinitely and fails to return, your first
+problem is to stop the loop. On most operating systems, you can do this
+with `C-g', which causes quit.
+
+ Ordinary quitting gives no information about why the program was
+looping. To get more information, you can set the variable
+`debug-on-quit' to non-`nil'. Quitting with `C-g' is not considered an
+error, and `debug-on-error' has no effect on the handling of `C-g'.
+Likewise, `debug-on-quit' has no effect on errors.
+
+ Once you have the debugger running in the middle of the infinite
+loop, you can proceed from the debugger using the stepping commands.
+If you step through the entire loop, you will probably get enough
+information to solve the problem.
+
+ - User Option: debug-on-quit
+ This variable determines whether the debugger is called when `quit'
+ is signaled and not handled. If `debug-on-quit' is non-`nil',
+ then the debugger is called whenever you quit (that is, type
+ `C-g'). If `debug-on-quit' is `nil', then the debugger is not
+ called when you quit. *Note Quitting::.
+
+\1f
+File: lispref.info, Node: Function Debugging, Next: Explicit Debug, Prev: Infinite Loops, Up: Debugger
+
+Entering the Debugger on a Function Call
+----------------------------------------
+
+ To investigate a problem that happens in the middle of a program, one
+useful technique is to enter the debugger whenever a certain function is
+called. You can do this to the function in which the problem occurs,
+and then step through the function, or you can do this to a function
+called shortly before the problem, step quickly over the call to that
+function, and then step through its caller.
+
+ - Command: debug-on-entry FUNCTION-NAME
+ This function requests FUNCTION-NAME to invoke the debugger each
+ time it is called. It works by inserting the form `(debug
+ 'debug)' into the function definition as the first form.
+
+ Any function defined as Lisp code may be set to break on entry,
+ regardless of whether it is interpreted code or compiled code. If
+ the function is a command, it will enter the debugger when called
+ from Lisp and when called interactively (after the reading of the
+ arguments). You can't debug primitive functions (i.e., those
+ written in C) this way.
+
+ When `debug-on-entry' is called interactively, it prompts for
+ FUNCTION-NAME in the minibuffer.
+
+ If the function is already set up to invoke the debugger on entry,
+ `debug-on-entry' does nothing.
+
+ *Please note:* if you redefine a function after using
+ `debug-on-entry' on it, the code to enter the debugger is lost.
+
+ `debug-on-entry' returns FUNCTION-NAME.
+
+ (defun fact (n)
+ (if (zerop n) 1
+ (* n (fact (1- n)))))
+ => fact
+ (debug-on-entry 'fact)
+ => fact
+ (fact 3)
+
+ ------ Buffer: *Backtrace* ------
+ Entering:
+ * fact(3)
+ eval-region(4870 4878 t)
+ byte-code("...")
+ eval-last-sexp(nil)
+ (let ...)
+ eval-insert-last-sexp(nil)
+ * call-interactively(eval-insert-last-sexp)
+ ------ Buffer: *Backtrace* ------
+
+ (symbol-function 'fact)
+ => (lambda (n)
+ (debug (quote debug))
+ (if (zerop n) 1 (* n (fact (1- n)))))
+
+ - Command: cancel-debug-on-entry 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
+ empty string, it cancels debugging for all functions.
+
+ If `cancel-debug-on-entry' is called more than once on the same
+ function, the second call does nothing. `cancel-debug-on-entry'
+ returns FUNCTION-NAME.
+
+\1f
+File: lispref.info, Node: Explicit Debug, Next: Using Debugger, Prev: Function Debugging, Up: Debugger
+
+Explicit Entry to the Debugger
+------------------------------
+
+ You can cause the debugger to be called at a certain point in your
+program by writing the expression `(debug)' at that point. To do this,
+visit the source file, insert the text `(debug)' at the proper place,
+and type `C-M-x'. Be sure to undo this insertion before you save the
+file!
+
+ The place where you insert `(debug)' must be a place where an
+additional form can be evaluated and its value ignored. (If the value
+of `(debug)' isn't ignored, it will alter the execution of the
+program!) The most common suitable places are inside a `progn' or an
+implicit `progn' (*note Sequencing::.).
+
+\1f
+File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
+
+Using the Debugger
+------------------
+
+ When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named `*Backtrace*' in another
+window. The backtrace buffer contains one line for each level of Lisp
+function execution currently going on. At the beginning of this buffer
+is a message describing the reason that the debugger was invoked (such
+as the error message and associated data, if it was invoked due to an
+error).
+
+ The backtrace buffer is read-only and uses a special major mode,
+Debugger mode, in which letters are defined as debugger commands. The
+usual XEmacs editing commands are available; thus, you can switch
+windows to examine the buffer that was being edited at the time of the
+error, switch buffers, visit files, or do any other sort of editing.
+However, the debugger is a recursive editing level (*note Recursive
+Editing::.) and it is wise to go back to the backtrace buffer and exit
+the debugger (with the `q' command) when you are finished with it.
+Exiting the debugger gets out of the recursive edit and kills the
+backtrace buffer.
+
+ The backtrace buffer shows you the functions that are executing and
+their argument values. It also allows you to specify a stack frame by
+moving point to the line describing that frame. (A stack frame is the
+place where the Lisp interpreter records information about a particular
+invocation of a function.) The frame whose line point is on is
+considered the "current frame". Some of the debugger commands operate
+on the current frame.
+
+ The debugger itself must be run byte-compiled, since it makes
+assumptions about how many stack frames are used for the debugger
+itself. These assumptions are false if the debugger is running
+interpreted.
+
+\1f
+File: lispref.info, Node: Debugger Commands, Next: Invoking the Debugger, Prev: Using Debugger, Up: Debugger
+
+Debugger Commands
+-----------------
+
+ Inside the debugger (in Debugger mode), these special commands are
+available in addition to the usual cursor motion commands. (Keep in
+mind that all the usual facilities of XEmacs, such as switching windows
+or buffers, are still available.)
+
+ The most important use of debugger commands is for stepping through
+code, so that you can see how control flows. The debugger can step
+through the control structures of an interpreted function, but cannot do
+so in a byte-compiled function. If you would like to step through a
+byte-compiled function, replace it with an interpreted definition of the
+same function. (To do this, visit the source file for the function and
+type `C-M-x' on its definition.)
+
+ Here is a list of Debugger mode commands:
+
+`c'
+ Exit the debugger and continue execution. This resumes execution
+ of the program as if the debugger had never been entered (aside
+ from the effect of any variables or data structures you may have
+ changed while inside the debugger).
+
+ Continuing when an error or quit was signalled will cause the
+ normal action of the signalling to take place. If you do not want
+ this to happen, but instead want the program execution to continue
+ as if the call to `signal' did not occur, use the `r' command.
+
+`d'
+ Continue execution, but enter the debugger the next time any Lisp
+ function is called. This allows you to step through the
+ subexpressions of an expression, seeing what values the
+ subexpressions compute, and what else they do.
+
+ The stack frame made for the function call which enters the
+ debugger in this way will be flagged automatically so that the
+ debugger will be called again when the frame is exited. You can
+ use the `u' command to cancel this flag.
+
+`b'
+ Flag the current frame so that the debugger will be entered when
+ the frame is exited. Frames flagged in this way are marked with
+ stars in the backtrace buffer.
+
+`u'
+ Don't enter the debugger when the current frame is exited. This
+ cancels a `b' command on that frame.
+
+`e'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the echo area. The debugger alters certain important
+ variables, and the current buffer, as part of its operation; `e'
+ temporarily restores their outside-the-debugger values so you can
+ examine them. This makes the debugger more transparent. By
+ contrast, `M-:' does nothing special in the debugger; it shows you
+ the variable values within the debugger.
+
+`q'
+ Terminate the program being debugged; return to top-level XEmacs
+ command execution.
+
+ If the debugger was entered due to a `C-g' but you really want to
+ quit, and not debug, use the `q' command.
+
+`r'
+ Return a value from the debugger. The value is computed by
+ reading an expression with the minibuffer and evaluating it.
+
+ The `r' command is useful when the debugger was invoked due to exit
+ from a Lisp call frame (as requested with `b'); then the value
+ specified in the `r' command is used as the value of that frame.
+ It is also useful if you call `debug' and use its return value.
+
+ If the debugger was entered at the beginning of a function call,
+ `r' has the same effect as `c', and the specified return value
+ does not matter.
+
+ If the debugger was entered through a call to `signal' (i.e. as a
+ result of an error or quit), then returning a value will cause the
+ call to `signal' itself to return, rather than throwing to
+ top-level or invoking a handler, as is normal. This allows you to
+ correct an error (e.g. the type of an argument was wrong) or
+ continue from a `debug-on-quit' as if it never happened.
+
+ Note that some errors (e.g. any error signalled using the `error'
+ function, and many errors signalled from a primitive function) are
+ not continuable. If you return a value from them and continue
+ execution, then the error will immediately be signalled again.
+ Other errors (e.g. wrong-type-argument errors) will be continually
+ resignalled until the problem is corrected.
+
+\1f
+File: lispref.info, Node: Invoking the Debugger, Next: Internals of Debugger, Prev: Debugger Commands, Up: Debugger
+
+Invoking the Debugger
+---------------------
+
+ Here we describe fully the function used to invoke the debugger.
+
+ - Function: debug &rest DEBUGGER-ARGS
+ This function enters the debugger. It switches buffers to a buffer
+ named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
+ recursive entry to the debugger, etc.), and fills it with
+ information about the stack of Lisp function calls. It then
+ enters a recursive edit, showing the backtrace buffer in Debugger
+ mode.
+
+ The Debugger mode `c' and `r' commands exit the recursive edit;
+ then `debug' switches back to the previous buffer and returns to
+ whatever called `debug'. This is the only way the function
+ `debug' can return to its caller.
+
+ If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
+ if it is not one of the special values in the table below), then
+ `debug' displays the rest of its arguments at the top of the
+ `*Backtrace*' buffer. This mechanism is used to display a message
+ to the user.
+
+ However, if the first argument passed to `debug' is one of the
+ following special values, then it has special significance.
+ Normally, these values are passed to `debug' only by the internals
+ of XEmacs and the debugger, and not by programmers calling `debug'.
+
+ The special values are:
+
+ `lambda'
+ A first argument of `lambda' means `debug' was called because
+ of entry to a function when `debug-on-next-call' was
+ non-`nil'. The debugger displays `Entering:' as a line of
+ text at the top of the buffer.
+
+ `debug'
+ `debug' as first argument indicates a call to `debug' because
+ of entry to a function that was set to debug on entry. The
+ debugger displays `Entering:', just as in the `lambda' case.
+ It also marks the stack frame for that function so that it
+ will invoke the debugger when exited.
+
+ `t'
+ When the first argument is `t', this indicates a call to
+ `debug' due to evaluation of a list form when
+ `debug-on-next-call' is non-`nil'. The debugger displays the
+ following as the top line in the buffer:
+
+ Beginning evaluation of function call form:
+
+ `exit'
+ When the first argument is `exit', it indicates the exit of a
+ stack frame previously marked to invoke the debugger on exit.
+ The second argument given to `debug' in this case is the
+ value being returned from the frame. The debugger displays
+ `Return value:' on the top line of the buffer, followed by
+ the value being returned.
+
+ `error'
+ When the first argument is `error', the debugger indicates
+ that it is being entered because an error or `quit' was
+ signaled and not handled, by displaying `Signaling:' followed
+ by the error signaled and any arguments to `signal'. For
+ example,
+
+ (let ((debug-on-error t))
+ (/ 1 0))
+
+ ------ Buffer: *Backtrace* ------
+ Signaling: (arith-error)
+ /(1 0)
+ ...
+ ------ Buffer: *Backtrace* ------
+
+ If an error was signaled, presumably the variable
+ `debug-on-error' is non-`nil'. If `quit' was signaled, then
+ presumably the variable `debug-on-quit' is non-`nil'.
+
+ `nil'
+ Use `nil' as the first of the DEBUGGER-ARGS when you want to
+ enter the debugger explicitly. The rest of the DEBUGGER-ARGS
+ are printed on the top line of the buffer. You can use this
+ feature to display messages--for example, to remind yourself
+ of the conditions under which `debug' is called.
+
+\1f
+File: lispref.info, Node: Internals of Debugger, Prev: Invoking the Debugger, Up: Debugger
+
+Internals of the Debugger
+-------------------------
+
+ This section describes functions and variables used internally by the
+debugger.
+
+ - Variable: debugger
+ The value of this variable is the function to call to invoke the
+ debugger. Its value must be a function of any number of arguments
+ (or, more typically, the name of a function). Presumably this
+ function will enter some kind of debugger. The default value of
+ the variable is `debug'.
+
+ The first argument that Lisp hands to the function indicates why it
+ was called. The convention for arguments is detailed in the
+ description of `debug'.
+
+ - Command: backtrace &optional STREAM DETAILED
+ This function prints a trace of Lisp function calls currently
+ active. This is the function used by `debug' to fill up the
+ `*Backtrace*' buffer. It is written in C, since it must have
+ access to the stack to determine which function calls are active.
+ The return value is always `nil'.
+
+ The backtrace is normally printed to `standard-output', but this
+ can be changed by specifying a value for STREAM. If DETAILED is
+ non-`nil', the backtrace also shows places where currently active
+ variable bindings, catches, condition-cases, and unwind-protects
+ were made as well as function calls.
+
+ In the following example, a Lisp expression calls `backtrace'
+ explicitly. This prints the backtrace to the stream
+ `standard-output': in this case, to the buffer `backtrace-output'.
+ Each line of the backtrace represents one function call. The
+ line shows the values of the function's arguments if they are all
+ known. If they are still being computed, the line says so. The
+ arguments of special forms are elided.
+
+ (with-output-to-temp-buffer "backtrace-output"
+ (let ((var 1))
+ (save-excursion
+ (setq var (eval '(progn
+ (1+ var)
+ (list 'testing (backtrace))))))))
+
+ => nil
+
+ ----------- Buffer: backtrace-output ------------
+ backtrace()
+ (list ...computing arguments...)
+ (progn ...)
+ eval((progn (1+ var) (list (quote testing) (backtrace))))
+ (setq ...)
+ (save-excursion ...)
+ (let ...)
+ (with-output-to-temp-buffer ...)
+ eval-region(1973 2142 #<buffer *scratch*>)
+ byte-code("... for eval-print-last-sexp ...")
+ eval-print-last-sexp(nil)
+ * call-interactively(eval-print-last-sexp)
+ ----------- Buffer: backtrace-output ------------
+
+ The character `*' indicates a frame whose debug-on-exit flag is
+ set.
+
+ - Variable: debug-on-next-call
+ If this variable is non-`nil', it says to call the debugger before
+ the next `eval', `apply' or `funcall'. Entering the debugger sets
+ `debug-on-next-call' to `nil'.
+
+ The `d' command in the debugger works by setting this variable.
+
+ - Function: backtrace-debug LEVEL FLAG
+ This function sets the debug-on-exit flag of the stack frame LEVEL
+ levels down the stack, giving it the value FLAG. If FLAG is
+ non-`nil', this will cause the debugger to be entered when that
+ frame later exits. Even a nonlocal exit through that frame will
+ enter the debugger.
+
+ This function is used only by the debugger.
+
+ - Variable: command-debug-status
+ This variable records the debugging status of the current
+ interactive command. Each time a command is called interactively,
+ this variable is bound to `nil'. The debugger can set this
+ variable to leave information for future debugger invocations
+ during the same command.
+
+ The advantage, for the debugger, of using this variable rather than
+ another global variable is that the data will never carry over to a
+ subsequent command invocation.
+
+ - Function: backtrace-frame FRAME-NUMBER
+ The function `backtrace-frame' is intended for use in Lisp
+ debuggers. It returns information about what computation is
+ happening in the stack frame FRAME-NUMBER levels down.
+
+ If that frame has not evaluated the arguments yet (or is a special
+ form), the value is `(nil FUNCTION ARG-FORMS...)'.
+
+ If that frame has evaluated its arguments and called its function
+ already, the value is `(t FUNCTION ARG-VALUES...)'.
+
+ In the return value, FUNCTION is whatever was supplied as the CAR
+ of the evaluated list, or a `lambda' expression in the case of a
+ macro call. If the function has a `&rest' argument, that is
+ represented as the tail of the list ARG-VALUES.
+
+ If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.
+
+\1f
+File: lispref.info, Node: Syntax Errors, Next: Compilation Errors, Prev: Debugger, Up: Debugging
+
+Debugging Invalid Lisp Syntax
+=============================
+
+ The Lisp reader reports invalid syntax, but cannot say where the real
+problem is. For example, the error "End of file during parsing" in
+evaluating an expression indicates an excess of open parentheses (or
+square brackets). The reader detects this imbalance at the end of the
+file, but it cannot figure out where the close parenthesis should have
+been. Likewise, "Invalid read syntax: ")"" indicates an excess close
+parenthesis or missing open parenthesis, but does not say where the
+missing parenthesis belongs. How, then, to find what to change?
+
+ If the problem is not simply an imbalance of parentheses, a useful
+technique is to try `C-M-e' at the beginning of each defun, and see if
+it goes to the place where that defun appears to end. If it does not,
+there is a problem in that defun.
+
+ However, unmatched parentheses are the most common syntax errors in
+Lisp, and we can give further advice for those cases.
+
+* Menu:
+
+* Excess Open:: How to find a spurious open paren or missing close.
+* Excess Close:: How to find a spurious close paren or missing open.
+
+\1f
+File: lispref.info, Node: Excess Open, Next: Excess Close, Up: Syntax Errors
+
+Excess Open Parentheses
+-----------------------
+
+ The first step is to find the defun that is unbalanced. If there is
+an excess open parenthesis, the way to do this is to insert a close
+parenthesis at the end of the file and type `C-M-b' (`backward-sexp').
+This will move you to the beginning of the defun that is unbalanced.
+(Then type `C-<SPC> C-_ C-u C-<SPC>' to set the mark there, undo the
+insertion of the close parenthesis, and finally return to the mark.)
+
+ The next step is to determine precisely what is wrong. There is no
+way to be sure of this except to study the program, but often the
+existing indentation is a clue to where the parentheses should have
+been. The easiest way to use this clue is to reindent with `C-M-q' and
+see what moves.
+
+ Before you do this, make sure the defun has enough close parentheses.
+Otherwise, `C-M-q' will get an error, or will reindent all the rest of
+the file until the end. So move to the end of the defun and insert a
+close parenthesis there. Don't use `C-M-e' to move there, since that
+too will fail to work until the defun is balanced.
+
+ Now you can go to the beginning of the defun and type `C-M-q'.
+Usually all the lines from a certain point to the end of the function
+will shift to the right. There is probably a missing close parenthesis,
+or a superfluous open parenthesis, near that point. (However, don't
+assume this is true; study the code to make sure.) Once you have found
+the discrepancy, undo the `C-M-q' with `C-_', since the old indentation
+is probably appropriate to the intended parentheses.
+
+ After you think you have fixed the problem, use `C-M-q' again. If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, `C-M-q' should not change
+anything.
+
+\1f
+File: lispref.info, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors
+
+Excess Close Parentheses
+------------------------
+
+ To deal with an excess close parenthesis, first insert an open
+parenthesis at the beginning of the file, back up over it, and type
+`C-M-f' to find the end of the unbalanced defun. (Then type `C-<SPC>
+C-_ C-u C-<SPC>' to set the mark there, undo the insertion of the open
+parenthesis, and finally return to the mark.)
+
+ Then find the actual matching close parenthesis by typing `C-M-f' at
+the beginning of the defun. This will leave you somewhere short of the
+place where the defun ought to end. It is possible that you will find
+a spurious close parenthesis in that vicinity.
+
+ If you don't see a problem at that point, the next thing to do is to
+type `C-M-q' at the beginning of the defun. A range of lines will
+probably shift left; if so, the missing open parenthesis or spurious
+close parenthesis is probably near the first of those lines. (However,
+don't assume this is true; study the code to make sure.) Once you have
+found the discrepancy, undo the `C-M-q' with `C-_', since the old
+indentation is probably appropriate to the intended parentheses.
+
+ After you think you have fixed the problem, use `C-M-q' again. If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, `C-M-q' should not change
+anything.
+
+\1f
+File: lispref.info, Node: Compilation Errors, Next: Edebug, Prev: Syntax Errors, Up: Debugging
+
+Debugging Problems in Compilation
+=================================
+
+ When an error happens during byte compilation, it is normally due to
+invalid syntax in the program you are compiling. The compiler prints a
+suitable error message in the `*Compile-Log*' buffer, and then stops.
+The message may state a function name in which the error was found, or
+it may not. Either way, here is how to find out where in the file the
+error occurred.
+
+ What you should do is switch to the buffer ` *Compiler Input*'.
+(Note that the buffer name starts with a space, so it does not show up
+in `M-x list-buffers'.) This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read.
+
+ If the error was due to invalid Lisp syntax, point shows exactly
+where the invalid syntax was *detected*. The cause of the error is not
+necessarily near by! Use the techniques in the previous section to find
+the error.
+
+ If the error was detected while compiling a form that had been read
+successfully, then point is located at the end of the form. In this
+case, this technique can't localize the error precisely, but can still
+show you which function to check.
+
+\1f
+File: lispref.info, Node: Edebug, Prev: Compilation Errors, Up: Top
+
+Edebug
+======
+
+ Edebug is a source-level debugger for XEmacs Lisp programs that
+provides the following features:
+
+ * Step through evaluation, stopping before and after each expression.
+
+ * Set conditional or unconditional breakpoints, install embedded
+ breakpoints, or a global break event.
+
+ * Trace slow or fast stopping briefly at each stop point, or each
+ breakpoint.
+
+ * Display expression results and evaluate expressions as if outside
+ of Edebug. Interface with the custom printing package for
+ printing circular structures.
+
+ * Automatically reevaluate a list of expressions and display their
+ results each time Edebug updates the display.
+
+ * Output trace info on function enter and exit.
+
+ * Errors stop before the source causing the error.
+
+ * Display backtrace without Edebug calls.
+
+ * Allow specification of argument evaluation for macros and defining
+ forms.
+
+ * Provide rudimentary coverage testing and display of frequency
+ counts.
+
+ The first three sections should tell you enough about Edebug to
+enable you to use it.
+
+* Menu:
+
+* Using Edebug:: Introduction to use of Edebug.
+* Instrumenting:: You must first instrument code.
+* Edebug Execution Modes:: Execution modes, stopping more or less often.
+* Jumping:: Commands to jump to a specified place.
+* Edebug Misc:: Miscellaneous commands.
+* Breakpoints:: Setting breakpoints to make the program stop.
+* Trapping Errors:: trapping errors with Edebug.
+* Edebug Views:: Views inside and outside of Edebug.
+* Edebug Eval:: Evaluating expressions within Edebug.
+* Eval List:: Automatic expression evaluation.
+* Reading in Edebug:: Customization of reading.
+* Printing in Edebug:: Customization of printing.
+* Tracing:: How to produce tracing output.
+* Coverage Testing:: How to test evaluation coverage.
+* The Outside Context:: Data that Edebug saves and restores.
+* Instrumenting Macro Calls:: Specifying how to handle macro calls.
+* Edebug Options:: Option variables for customizing Edebug.
+
+\1f
+File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug
+
+Using Edebug
+------------
+
+ To debug an XEmacs Lisp program with Edebug, you must first
+"instrument" the Lisp code that you want to debug. If you want to just
+try it now, load `edebug.el', move point into a definition and do `C-u
+C-M-x' (`eval-defun' with a prefix argument). See *Note
+Instrumenting:: for alternative ways to instrument code.
+
+ Once a function is instrumented, any call to the function activates
+Edebug. Activating Edebug may stop execution and let you step through
+the function, or it may update the display and continue execution while
+checking for debugging commands, depending on the selected Edebug
+execution mode. The initial execution mode is `step', by default,
+which does stop execution. *Note Edebug Execution Modes::.
+
+ Within Edebug, you normally view an XEmacs buffer showing the source
+of the Lisp function you are debugging. This is referred to as the
+"source code buffer"--but note that it is not always the same buffer
+depending on which function is currently being executed.
+
+ An arrow at the left margin indicates the line where the function is
+executing. Point initially shows where within the line the function is
+executing, but you can move point yourself.
+
+ If you instrument the definition of `fac' (shown below) and then
+execute `(fac 3)', here is what you normally see. Point is at the
+open-parenthesis before `if'.
+
+ (defun fac (n)
+ =>-!-(if (< 0 n)
+ (* n (fac (1- n)))
+ 1))
+
+ The places within a function where Edebug can stop execution are
+called "stop points". These occur both before and after each
+subexpression that is a list, and also after each variable reference.
+Here we show with periods the stop points found in the function `fac':
+
+ (defun fac (n)
+ .(if .(< 0 n.).
+ .(* n. .(fac (1- n.).).).
+ 1).)
+
+ While the source code buffer is selected, the special commands of
+Edebug are available in it, in addition to the commands of XEmacs Lisp
+mode. (The buffer is temporarily made read-only, however.) For
+example, you can type the Edebug command <SPC> to execute until the
+next stop point. If you type <SPC> once after entry to `fac', here is
+the display you will see:
+
+ (defun fac (n)
+ =>(if -!-(< 0 n)
+ (* n (fac (1- n)))
+ 1))
+
+ When Edebug stops execution after an expression, it displays the
+expression's value in the echo area.
+
+ Other frequently used commands are `b' to set a breakpoint at a stop
+point, `g' to execute until a breakpoint is reached, and `q' to exit to
+the top-level command loop. Type `?' to display a list of all Edebug
+commands.
+
+\1f
+File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug
+
+Instrumenting for Edebug
+------------------------
+
+ In order to use Edebug to debug Lisp code, you must first
+"instrument" the code. Instrumenting a form inserts additional code
+into it which invokes Edebug at the proper places. Furthermore, if
+Edebug detects a syntax error while instrumenting, point is left at the
+erroneous code and an `invalid-read-syntax' error is signaled.
+
+ Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is
+redefined so that when invoked with a prefix argument on a definition,
+it instruments the definition before evaluating it. (The source code
+itself is not modified.) If the variable `edebug-all-defs' is
+non-`nil', that inverts the meaning of the prefix argument: then
+`C-M-x' instruments the definition *unless* it has a prefix argument.
+The default value of `edebug-all-defs' is `nil'. The command `M-x
+edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
+
+ If `edebug-all-defs' is non-`nil', then the commands `eval-region',
+`eval-current-buffer', and `eval-buffer' also instrument any
+definitions they evaluate. Similarly, `edebug-all-forms' controls
+whether `eval-region' should instrument *any* form, even non-defining
+forms. This doesn't apply to loading or evaluations in the minibuffer.
+The command `M-x edebug-all-forms' toggles this option.
+
+ Another command, `M-x edebug-eval-top-level-form', is available to
+instrument any top-level form regardless of the value of
+`edebug-all-defs' or `edebug-all-forms'.
+
+ Just before Edebug instruments any code, it calls any functions in
+the variable `edebug-setup-hook' and resets its value 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. For example,
+`my-specs.el' may be loaded automatically when you use `my-package'
+with Edebug by including the following code in `my-package.el'.
+
+ (add-hook 'edebug-setup-hook
+ (function (lambda () (require 'my-specs))))
+
+ While Edebug is active, the command `I' (`edebug-instrument-callee')
+instruments the definition of the function or macro called by the list
+form after point, if is not already instrumented. If the location of
+the definition is not known to Edebug, this command cannot be used.
+After loading Edebug, `eval-region' records the position of every
+definition it evaluates, even if not instrumenting it. Also see the
+command `i' (*Note Jumping::) which steps into the callee.
+
+ Edebug knows how to instrument all the standard special forms, an
+interactive form with an expression argument, anonymous lambda
+expressions, and other defining forms. (Specifications for macros
+defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.)
+Edebug cannot know what a user-defined macro will do with the arguments
+of a macro call so you must tell it. See *Note Instrumenting Macro
+Calls:: for the details.
+
+ Note that a couple ways remain to evaluate expressions without
+instrumenting them. Loading a file via the `load' subroutine does not
+instrument expressions for Edebug. Evaluations in the minibuffer via
+`eval-expression' (`M-ESC') are not instrumented.
+
+ To remove instrumentation from a definition, simply reevaluate it
+with one of the non-instrumenting commands, or reload the file.
+
+ See *Note Edebug Eval:: for other evaluation functions available
+inside of Edebug.
+
+\1f
+File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
+
+Edebug Execution Modes
+----------------------
+
+ Edebug supports several execution modes for running the program you
+are debugging. We call these alternatives "Edebug execution modes"; do
+not confuse them with major or minor modes. The current Edebug
+execution mode determines how Edebug displays the progress of the
+evaluation, whether it stops at each stop point, or continues to the
+next breakpoint, for example.
+
+ Normally, you specify the Edebug execution mode by typing a command
+to continue the program in a certain mode. Here is a table of these
+commands. All except for `S' resume execution of the program, at least
+for a certain distance.
+
+`S'
+ Stop: don't execute any more of the program for now, just wait for
+ more Edebug commands (`edebug-stop').
+
+`<SPC>'
+ Step: stop at the next stop point encountered (`edebug-step-mode').
+
+`n'
+ Next: stop at the next stop point encountered after an expression
+ (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note
+ Edebug Misc::.
+
+`t'
+ Trace: pause one second at each Edebug stop point
+ (`edebug-trace-mode').
+
+`T'
+ Rapid trace: update at each stop point, but don't actually pause
+ (`edebug-Trace-fast-mode').
+
+`g'
+ Go: run until the next breakpoint (`edebug-go-mode'). *Note
+ Breakpoints::.
+
+`c'
+ Continue: pause for one second at each breakpoint, but don't stop
+ (`edebug-continue-mode').
+
+`C'
+ Rapid continue: update at each breakpoint, but don't actually pause
+ (`edebug-Continue-fast-mode').
+
+`G'
+ Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You
+ can still stop the program by hitting any key.
+
+ In general, the execution modes earlier in the above list run the
+program more slowly or stop sooner.
+
+ When you enter a new Edebug level, the initial execution mode comes
+from the value of the variable `edebug-initial-mode'. By default, this
+specifies `step' mode. Note that you may reenter the same Edebug level
+several times if, for example, an instrumented function is called
+several times from one command.
+
+ While executing or tracing, you can interrupt the execution by typing
+any Edebug command. Edebug stops the program at the next stop point and
+then executes the command that you typed. For example, typing `t'
+during execution switches to trace mode at the next stop point. You can
+use `S' to stop execution without doing anything else.
+
+ If your function happens to read input, a character you hit
+intending to interrupt execution may be read by the function instead.
+You can avoid such unintended results by paying attention to when your
+program wants input.
+
+ Keyboard macros containing Edebug commands do not work; when you exit
+from Edebug, to resume the program, whether you are defining or
+executing a keyboard macro is forgotten. Also, defining or executing a
+keyboard macro outside of Edebug does not affect the command loop inside
+Edebug. This is usually an advantage. But see
+`edebug-continue-kbd-macro'.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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 <RET>'
+ 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.
+
+\1f
+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.
+
+\1f
+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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug
+
+Trapping Errors
+---------------
+
+ An error may be signaled by subroutines or XEmacs Lisp code. If a
+signal is not handled by a `condition-case', this indicates an
+unrecognized situation has occurred. If Edebug is not active when an
+unhandled error is signaled, `debug' is run normally (if
+`debug-on-error' is non-`nil'). But while Edebug is active,
+`debug-on-error' and `debug-on-quit' are bound to `edebug-on-error' and
+`edebug-on-quit', which are both `t' by default. Actually, if
+`debug-on-error' already has a non-`nil' value, that value is still
+used.
+
+ It is best to change the values of `edebug-on-error' or
+`edebug-on-quit' when Edebug is not active since their values won't be
+used until the next time Edebug is invoked at a deeper command level.
+If you only change `debug-on-error' or `debug-on-quit' while Edebug is
+active, these changes will be forgotten when Edebug becomes inactive.
+Furthermore, during Edebug's recursive edit, these variables are bound
+to the values they had outside of Edebug.
+
+ Edebug shows you the last stop point that it knew about before the
+error was signaled. This may be the location of a call to a function
+which was not instrumented, within which the error actually occurred.
+For an unbound variable error, the last known stop point might be quite
+distant from the offending variable. If the cause of the error is not
+obvious at first, note that you can also get a full backtrace inside of
+Edebug (see *Note Edebug Misc::).
+
+ Edebug can also trap signals even if they are handled. If
+`debug-on-error' is a list of signal names, Edebug will stop when any
+of these errors are signaled. Edebug shows you the last known stop
+point just as for unhandled errors. After you continue execution, the
+error is signaled again (but without being caught by Edebug). Edebug
+can only trap errors that are handled if they are signaled in Lisp code
+(not subroutines) since it does so by temporarily replacing the
+`signal' function.
+
+\1f
+File: lispref.info, Node: Edebug Views, Next: Edebug Eval, Prev: Trapping Errors, Up: Edebug
+
+Edebug Views
+------------
+
+ The following Edebug commands let you view aspects of the buffer and
+window status that obtained before entry to Edebug.
+
+`v'
+ View the outside window configuration (`edebug-view-outside').
+
+`p'
+ Temporarily display the outside current buffer with point at its
+ outside position (`edebug-bounce-point'). If prefix arg is
+ supplied, sit for that many seconds instead.
+
+`w'
+ Move point back to the current stop point (`edebug-where') in the
+ source code buffer. Also, if you use this command in another
+ window displaying the same buffer, this window will be used
+ instead to display the buffer in the future.
+
+`W'
+ Toggle the `edebug-save-windows' variable which indicates whether
+ the outside window configuration is saved and restored
+ (`edebug-toggle-save-windows'). Also, each time it is toggled on,
+ make the outside window configuration the same as the current
+ window configuration.
+
+ With a prefix argument, `edebug-toggle-save-windows' only toggles
+ saving and restoring of the selected window. To specify a window
+ that is not displaying the source code buffer, you must use
+ `C-xXW' from the global keymap.
+
+ You can view the outside window configuration with `v' or just
+bounce to the current point in the current buffer with `p', even if it
+is not normally displayed. After moving point, you may wish to pop
+back to the stop point with `w' from a source code buffer.
+
+ By using `W' twice, Edebug again saves and restores the outside
+window configuration, but to the current configuration. This is a
+convenient way to, for example, add another buffer to be displayed
+whenever Edebug is active. However, the automatic redisplay of
+`*edebug*' and `*edebug-trace*' may conflict with the buffers you wish
+to see unless you have enough windows open.
+
+\1f
+File: lispref.info, Node: Edebug Eval, Next: Eval List, Prev: Edebug Views, Up: Edebug
+
+Evaluation
+----------
+
+ While within Edebug, you can evaluate expressions "as if" Edebug were
+not running. Edebug tries to be invisible to the expression's
+evaluation and printing. Evaluation of expressions that cause side
+effects will work as expected except for things that Edebug explicitly
+saves and restores. See *Note The Outside Context:: for details on this
+process. Also see *Note Reading in Edebug:: and *Note Printing in
+Edebug:: for topics related to evaluation.
+
+`e EXP <RET>'
+ Evaluate expression EXP in the context outside of Edebug
+ (`edebug-eval-expression'). In other words, Edebug tries to avoid
+ altering the effect of EXP.
+
+`M-<ESC> EXP <RET>'
+ Evaluate expression EXP in the context of Edebug itself.
+
+`C-x C-e'
+ Evaluate the expression before point, in the context outside of
+ Edebug (`edebug-eval-last-sexp').
+
+ Edebug supports evaluation of expressions containing references to
+lexically bound symbols created by the following constructs in `cl.el'
+(version 2.03 or later): `lexical-let', `macrolet', and
+`symbol-macrolet'.
+
+\1f
+File: lispref.info, Node: Eval List, Next: Reading in Edebug, Prev: Edebug Eval, Up: Edebug
+
+Evaluation List Buffer
+----------------------
+
+ You can use the "evaluation list buffer", called `*edebug*', to
+evaluate expressions interactively. You can also set up the
+"evaluation list" of expressions to be evaluated automatically each
+time Edebug updates the display.
+
+`E'
+ Switch to the evaluation list buffer `*edebug*'
+ (`edebug-visit-eval-list').
+
+ In the `*edebug*' buffer you can use the commands of Lisp
+Interaction as well as these special commands:
+
+`LFD'
+ Evaluate the expression before point, in the outside context, and
+ insert the value in the buffer (`edebug-eval-print-last-sexp').
+
+`C-x C-e'
+ Evaluate the expression before point, in the context outside of
+ Edebug (`edebug-eval-last-sexp').
+
+`C-c C-u'
+ Build a new evaluation list from the first expression of each
+ group, reevaluate and redisplay (`edebug-update-eval-list').
+ Groups are separated by comment lines.
+
+`C-c C-d'
+ Delete the evaluation list group that point is in
+ (`edebug-delete-eval-item').
+
+`C-c C-w'
+ Switch back to the source code buffer at the current stop point
+ (`edebug-where').
+
+ You can evaluate expressions in the evaluation list window with
+`LFD' or `C-x C-e', just as you would in `*scratch*'; but they are
+evaluated in the context outside of Edebug.
+
+ The expressions you enter interactively (and their results) are lost
+when you continue execution unless you add them to the evaluation list
+with `C-c C-u'. This command builds a new list from the first
+expression of each "evaluation list group". Groups are separated by
+comment lines. Be careful not to add expressions that execute
+instrumented code otherwise an infinite loop will result.
+
+ When the evaluation list is redisplayed, each expression is displayed
+followed by the result of evaluating it, and a comment line. If an
+error occurs during an evaluation, the error message is displayed in a
+string as if it were the result. Therefore expressions that, for
+example, use variables not currently valid do not interrupt your
+debugging.
+
+ Here is an example of what the evaluation list window looks like
+after several expressions have been added to it:
+
+ (current-buffer)
+ #<buffer *scratch*>
+ ;---------------------------------------------------------------
+ (selected-window)
+ #<window 16 on *scratch*>
+ ;---------------------------------------------------------------
+ (point)
+ 196
+ ;---------------------------------------------------------------
+ bad-var
+ "Symbol's value as variable is void: bad-var"
+ ;---------------------------------------------------------------
+ (recursion-depth)
+ 0
+ ;---------------------------------------------------------------
+ this-command
+ eval-last-sexp
+ ;---------------------------------------------------------------
+
+ To delete a group, move point into it and type `C-c C-d', or simply
+delete the text for the group and update the evaluation list with `C-c
+C-u'. When you add a new group, be sure it is separated from its
+neighbors by a comment line.
+
+ After selecting `*edebug*', you can return to the source code buffer
+with `C-c C-w'. The `*edebug*' buffer is killed when you continue
+execution, and recreated next time it is needed.
+
+\1f
+File: lispref.info, Node: Reading in Edebug, Next: Printing in Edebug, Prev: Eval List, Up: Edebug
+
+Reading in Edebug
+-----------------
+
+ To instrument a form, Edebug first reads the whole form. Edebug
+replaces the standard Lisp Reader with its own reader that remembers the
+positions of expressions. This reader is used by the Edebug
+replacements for `eval-region', `eval-defun', `eval-buffer', and
+`eval-current-buffer'.
+
+ Another package, `cl-read.el', replaces the standard reader with one
+that understands Common Lisp reader macros. If you use that package,
+Edebug will automatically load `edebug-cl-read.el' to provide
+corresponding reader macros that remember positions of expressions. If
+you define new reader macros, you will have to define similar reader
+macros for Edebug.
+
+\1f
+File: lispref.info, Node: Printing in Edebug, Next: Tracing, Prev: Reading in Edebug, Up: Edebug
+
+Printing in Edebug
+------------------
+
+ If the result of an expression in your program contains a circular
+reference, you may get an error when Edebug attempts to print it. You
+can set `print-length' to a non-zero value to limit the print length of
+lists (the number of cdrs), and in Emacs 19, set `print-level' to a
+non-zero value to limit the print depth of lists. But you can print
+such circular structures and structures that share elements more
+informatively by using the `cust-print' package.
+
+ To load `cust-print' and activate custom printing only for Edebug,
+simply use the command `M-x edebug-install-custom-print'. To restore
+the standard print functions, use `M-x edebug-uninstall-custom-print'.
+You can also activate custom printing for printing in any Lisp code;
+see the package for details.
+
+ Here is an example of code that creates a circular structure:
+
+ (progn
+ (edebug-install-custom-print)
+ (setq a '(x y))
+ (setcar a a))
+
+ Edebug will print the result of the `setcar' as `Result: #1=(#1#
+y)'. The `#1=' notation names the structure that follows it, and the
+`#1#' notation references the previously named structure. This
+notation is used for any shared elements of lists or vectors.
+
+ Independent of whether `cust-print' is active, while printing
+results Edebug binds `print-length', `print-level', and `print-circle'
+to `edebug-print-length' (`50'), `edebug-print-level' (`50'), and
+`edebug-print-circle' (`t') respectively, if these values are
+non-`nil'. Also, `print-readably' is bound to `nil' since some objects
+simply cannot be printed readably.
+
+\1f
+File: lispref.info, Node: Tracing, Next: Coverage Testing, Prev: Printing in Edebug, Up: Edebug
+
+Tracing
+-------
+
+ In addition to automatic stepping through source code, which is also
+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
+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
+the function. The number of `:'s is computed from the recursion depth.
+The balanced braces in the trace buffer can be used to find the
+matching beginning or end of function calls. These displays may be
+customized by replacing the functions `edebug-print-trace-before' and
+`edebug-print-trace-after', which take an arbitrary message string to
+print.
+
+ The macro `edebug-tracing' provides tracing similar to function
+enter and exit tracing, but for arbitrary expressions. This macro
+should be explicitly inserted by you around expressions you wish to
+trace the execution of. The first argument is a message string
+(evaluated), and the rest are expressions to evaluate. The result of
+the last expression is returned.
+
+ Finally, you can insert arbitrary strings into the trace buffer with
+explicit calls to `edebug-trace'. The arguments of this function are
+the same as for `message', but a newline is always inserted after each
+string printed in this way.
+
+ `edebug-tracing' and `edebug-trace' insert lines in the trace buffer
+even if Edebug is not active. Every time the trace buffer is added to,
+the window is scrolled to show the last lines inserted. (There may be
+some display problems if you use tracing along with the evaluation
+list.)
+
+\1f
+File: lispref.info, Node: Coverage Testing, Next: The Outside Context, Prev: Tracing, Up: Edebug
+
+Coverage Testing
+----------------
+
+ Edebug provides a rudimentary coverage tester and display of
+execution frequency. Frequency counts are always accumulated, both
+before and after evaluation of each instrumented expression, even if
+the execution mode is `Go-nonstop'. Coverage testing is only done if
+the option `edebug-test-coverage' is non-`nil' because this is
+relatively expensive. Both data sets are displayed by `M-x
+edebug-display-freq-count'.
+
+ - Command: edebug-display-freq-count
+ Display the frequency count data for each line of the current
+ definition. The frequency counts are inserted as comment lines
+ after each line, and you can undo all insertions with one `undo'
+ command. The counts are inserted starting under the `(' before an
+ expression or the `)' after an expression, or on the last char of
+ a symbol. The counts are only displayed when they differ from
+ previous counts on the same line.
+
+ If coverage is being tested, whenever all known results of an
+ expression are `eq', the char `=' will be appended after the count
+ for that expression. Note that this is always the case for an
+ expression only evaluated once.
+
+ To clear the frequency count and coverage data for a definition,
+ reinstrument it.
+
+
+ For example, after evaluating `(fac 5)' with an embedded breakpoint,
+and setting `edebug-test-coverage' to `t', when the breakpoint is
+reached, the frequency data is looks like this:
+
+ (defun fac (n)
+ (if (= n 0) (edebug))
+ ;#6 1 0 =5
+ (if (< 0 n)
+ ;#5 =
+ (* n (fac (1- n)))
+ ;# 5 0
+ 1))
+ ;# 0
+
+ The comment lines show that `fac' has been called 6 times. The
+first `if' statement has returned 5 times with the same result each
+time, and the same is true for the condition on the second `if'. The
+recursive call of `fac' has not returned at all.
+
+\1f
+File: lispref.info, Node: The Outside Context, Next: Instrumenting Macro Calls, Prev: Coverage Testing, Up: Edebug
+
+The Outside Context
+-------------------
+
+ Edebug tries to be transparent to the program you are debugging. In
+addition, most evaluations you do within Edebug (see *Note Edebug
+Eval::) occur in the same outside context which is temporarily restored
+for the evaluation. But Edebug is not completely successful and this
+section explains precisely how it fails. Edebug operation unavoidably
+alters some data in XEmacs, and this can interfere with debugging
+certain programs. Also notice that Edebug's protection against change
+of outside data means that any side effects *intended* by the user in
+the course of debugging will be defeated.
+
+* Menu:
+
+* Checking Whether to Stop:: When Edebug decides what to do.
+* Edebug Display Update:: When Edebug updates the display.
+* Edebug Recursive Edit:: When Edebug stops execution.
+
+\1f
+File: lispref.info, Node: Checking Whether to Stop, Next: Edebug Display Update, Up: The Outside Context
+
+Checking Whether to Stop
+........................
+
+ Whenever Edebug is entered just to think about whether to take some
+action, it needs to save and restore certain data.
+
+ * `max-lisp-eval-depth' and `max-specpdl-size' are both incremented
+ one time to reduce Edebug's impact on the stack. You could,
+ however, still run out of stack space when using Edebug.
+
+ * The state of keyboard macro execution is saved and restored. While
+ Edebug is active, `executing-macro' is bound to
+ `edebug-continue-kbd-macro'.
+
+\1f
+File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context
+
+Edebug Display Update
+.....................
+
+ When Edebug needs to display something (e.g., in trace mode), it
+saves the current window configuration from "outside" Edebug. When you
+exit Edebug (by continuing the program), it restores the previous window
+configuration.
+
+ XEmacs redisplays only when it pauses. Usually, when you continue
+execution, the program comes back into Edebug at a breakpoint or after
+stepping without pausing or reading input in between. In such cases,
+XEmacs never gets a chance to redisplay the "outside" configuration.
+What you see is the same window configuration as the last time Edebug
+was active, with no interruption.
+
+ Entry to Edebug for displaying something also saves and restores the
+following data, but some of these are deliberately not restored if an
+error or quit signal occurs.
+
+ * Which buffer is current, and where point and mark are in the
+ current buffer are saved and restored.
+
+ * The Edebug Display Update, is saved and restored if
+ `edebug-save-windows' is non-`nil'. It is not restored on error
+ or quit, but the outside selected window *is* reselected even on
+ error or quit in case a `save-excursion' is active. If the value
+ of `edebug-save-windows' is a list, only the listed windows are
+ saved and restored.
+
+ The window start and horizontal scrolling of the source code
+ buffer are not restored, however, so that the display remains
+ coherent.
+
+ * The value of point in each displayed buffer is saved and restored
+ if `edebug-save-displayed-buffer-points' is non-`nil'.
+
+ * The variables `overlay-arrow-position' and `overlay-arrow-string'
+ are saved and restored. So you can safely invoke Edebug from the
+ recursive edit elsewhere in the same buffer.
+
+ * `cursor-in-echo-area' is locally bound to `nil' so that the cursor
+ shows up in the window.
+
+\1f
+File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context
+
+Edebug Recursive Edit
+.....................
+
+ When Edebug is entered and actually reads commands from the user, it
+saves (and later restores) these additional data:
+
+ * The current match data, for whichever buffer was current.
+
+ * `last-command', `this-command', `last-command-char',
+ `last-input-char', `last-input-event', `last-command-event',
+ `last-event-frame', `last-nonmenu-event', and `track-mouse' .
+ Commands used within Edebug do not affect these variables outside
+ of Edebug.
+
+ The key sequence returned by `this-command-keys' is changed by
+ executing commands within Edebug and there is no way to reset the
+ key sequence from Lisp.
+
+ For Emacs 18, Edebug cannot save and restore the value of
+ `unread-command-char'. Entering Edebug while this variable has a
+ nontrivial value can interfere with execution of the program you
+ are debugging.
+
+ * Complex commands executed while in Edebug are added to the variable
+ `command-history'. In rare cases this can alter execution.
+
+ * Within Edebug, the recursion depth appears one deeper than the
+ recursion depth outside Edebug. This is not true of the
+ automatically updated evaluation list window.
+
+ * `standard-output' and `standard-input' are bound to `nil' by the
+ `recursive-edit', but Edebug temporarily restores them during
+ evaluations.
+
+ * The state of keyboard macro definition is saved and restored.
+ While Edebug is active, `defining-kbd-macro' is bound to
+ `edebug-continue-kbd-macro'.
+
+\1f
+File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug
+
+Instrumenting Macro Calls
+-------------------------
+
+ When Edebug instruments an expression that calls a Lisp macro, it
+needs additional advice to do the job properly. This is because there
+is no way to tell which subexpressions of the macro call may be
+evaluated. (Evaluation may occur explicitly in the macro body, or when
+the resulting expansion is evaluated, or any time later.) You must
+explain the format of macro call arguments by using `def-edebug-spec' to
+define an "Edebug specification" for each macro.
+
+ - Macro: def-edebug-spec MACRO SPECIFICATION
+ Specify which expressions of a call to macro MACRO are forms to be
+ evaluated. For simple macros, the SPECIFICATION often looks very
+ similar to the formal argument list of the macro definition, but
+ specifications are much more general than macro arguments.
+
+ The MACRO argument may actually be any symbol, not just a macro
+ name.
+
+ Unless you are using Emacs 19 or XEmacs, this macro is only defined
+ in Edebug, so you may want to use the following which is
+ equivalent: `(put 'MACRO 'edebug-form-spec 'SPECIFICATION)'
+
+ Here is a simple example that defines the specification for the
+`for' macro described in the XEmacs Lisp Reference Manual, followed by
+an alternative, equivalent specification.
+
+ (def-edebug-spec for
+ (symbolp "from" form "to" form "do" &rest form))
+
+ (def-edebug-spec for
+ (symbolp ['from form] ['to form] ['do body]))
+
+ Here is a table of the possibilities for SPECIFICATION and how each
+directs processing of arguments.
+
+*`t'
+ All arguments are instrumented for evaluation.
+
+*`0'
+ None of the arguments is instrumented.
+
+*a symbol
+ The symbol must have an Edebug specification which is used instead.
+ This indirection is repeated until another kind of specification is
+ found. This allows you to inherit the specification for another
+ macro.
+
+*a list
+ The elements of the list describe the types of the arguments of a
+ calling form. The possible elements of a specification list are
+ described in the following sections.
+
+* Menu:
+
+* Specification List:: How to specify complex patterns of evaluation.
+* Backtracking:: What Edebug does when matching fails.
+* Debugging Backquote:: Debugging Backquote
+* Specification Examples:: To help understand specifications.
+
+\1f
+File: lispref.info, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls
+
+Specification List
+..................
+
+ A "specification list" is required for an Edebug specification if
+some arguments of a macro call are evaluated while others are not. Some
+elements in a specification list match one or more arguments, but others
+modify the processing of all following elements. The latter, called
+"keyword specifications", are symbols beginning with ``&'' (e.g.
+`&optional').
+
+ A specification list may contain sublists which match arguments that
+are themselves lists, or it may contain vectors used for grouping.
+Sublists and groups thus subdivide the specification list into a
+hierarchy of levels. Keyword specifications only apply to the
+remainder of the sublist or group they are contained in and there is an
+implicit grouping around a keyword specification and all following
+elements in the sublist or group.
+
+ If a specification list fails at some level, then backtracking may
+be invoked to find some alternative at a higher level, or if no
+alternatives remain, an error will be signaled. See *Note
+Backtracking:: for more details.
+
+ Edebug specifications provide at least the power of regular
+expression matching. Some context-free constructs are also supported:
+the matching of sublists with balanced parentheses, recursive
+processing of forms, and recursion via indirect specifications.
+
+ Each element of a specification list may be one of the following,
+with the corresponding type of argument:
+
+`sexp'
+ A single unevaluated expression.
+
+`form'
+ A single evaluated expression, which is instrumented.
+
+`place'
+ A place as in the Common Lisp `setf' place argument. It will be
+ instrumented just like a form, but the macro is expected to strip
+ the instrumentation. Two functions, `edebug-unwrap' and
+ `edebug-unwrap*', are provided to strip the instrumentation one
+ level or recursively at all levels.
+
+`body'
+ Short for `&rest form'. See `&rest' below.
+
+`function-form'
+ A function form: either a quoted function symbol, a quoted lambda
+ expression, or a form (that should evaluate to a function symbol
+ or lambda expression). This is useful when function arguments
+ might be quoted with `quote' rather than `function' since the body
+ of a lambda expression will be instrumented either way.
+
+`lambda-expr'
+ An unquoted anonymous lambda expression.
+
+`&optional'
+ All following elements in the specification list are optional; as
+ soon as one does not match, Edebug stops matching at this level.
+
+ To make just a few elements optional followed by non-optional
+ elements, use `[&optional SPECS...]'. To specify that several
+ elements should all succeed together, use `&optional [SPECS...]'.
+ See the `defun' example below.
+
+`&rest'
+ All following elements in the specification list are repeated zero
+ or more times. All the elements need not match in the last
+ repetition, however.
+
+ To repeat only a few elements, use `[&rest SPECS...]'. To specify
+ all elements must match on every repetition, use `&rest
+ [SPECS...]'.
+
+`&or'
+ Each of the following elements in the specification list is an
+ alternative, processed left to right until one matches. One of the
+ alternatives must match otherwise the `&or' specification fails.
+
+ Each list element following `&or' is a single alternative even if
+ it is a keyword specification. (This breaks the implicit grouping
+ rule.) To group two or more list elements as a single
+ alternative, enclose them in `[...]'.
+
+`¬'
+ Each of the following elements is matched as alternatives as if by
+ using `&or', but if any of them match, the specification fails.
+ If none of them match, nothing is matched, but the `¬'
+ specification succeeds.
+
+`&define'
+ Indicates that the specification is for a defining form. The
+ defining form itself is not instrumented (i.e. Edebug does not
+ stop before and after the defining form), but forms inside it
+ typically will be instrumented. The `&define' keyword should be
+ the first element in a list specification.
+
+ Additional specifications that may only appear after `&define' are
+ described here. See the `defun' example below.
+
+ `name'
+ The argument, a symbol, is the name of the defining form.
+ But a defining form need not be named at all, in which case a
+ unique name will be created for it.
+
+ The `name' specification may be used more than once in the
+ specification and each subsequent use will append the
+ corresponding symbol argument to the previous name with ``@''
+ between them. This is useful for generating unique but
+ meaningful names for definitions such as `defadvice' and
+ `defmethod'.
+
+ `:name'
+ The element following `:name' should be a symbol; it is used
+ as an additional name component for the definition. This is
+ useful to add a unique, static component to the name of the
+ definition. It may be used more than once. No argument is
+ matched.
+
+ `arg'
+ The argument, a symbol, is the name of an argument of the
+ defining form. However, lambda list keywords (symbols
+ starting with ``&'') are not allowed. See `lambda-list' and
+ the example below.
+
+ `lambda-list'
+ This matches the whole argument list of an XEmacs Lisp lambda
+ expression, which is a list of symbols and the keywords
+ `&optional' and `&rest'
+
+ `def-body'
+ The argument is the body of code in a definition. This is
+ like `body', described above, but a definition body must be
+ instrumented with a different Edebug call that looks up
+ information associated with the definition. Use `def-body'
+ for the highest level list of forms within the definition.
+
+ `def-form'
+ The argument is a single, highest-level form in a definition.
+ This is like `def-body', except use this to match a single
+ form rather than a list of forms. As a special case,
+ `def-form' also means that tracing information is not output
+ when the form is executed. See the `interactive' example
+ below.
+
+`nil'
+ This is successful when there are no more arguments to match at the
+ current argument list level; otherwise it fails. See sublist
+ specifications and the backquote example below.
+
+`gate'
+ No argument is matched but backtracking through the gate is
+ disabled while matching the remainder of the specifications at
+ this level. This is primarily used to generate more specific
+ syntax error messages. See *Note Backtracking:: for more details.
+ Also see the `let' example below.
+
+`OTHER-SYMBOL'
+ Any other symbol in a specification list may be a predicate or an
+ indirect specification.
+
+ If the symbol has an Edebug specification, this "indirect
+ specification" should be either a list specification that is used
+ in place of the symbol, or a function that is called to process the
+ arguments. The specification may be defined with `def-edebug-spec'
+ just as for macros. See the `defun' example below.
+
+ Otherwise, the symbol should be a predicate. The predicate is
+ called with the argument and the specification fails if the
+ predicate fails. The argument is not instrumented.
+
+ Predicates that may be used include: `symbolp', `integerp',
+ `stringp', `vectorp', `atom' (which matches a number, string,
+ symbol, or vector), `keywordp', and `lambda-list-keywordp'. The
+ last two, defined in `edebug.el', test whether the argument is a
+ symbol starting with ``:'' and ``&'' respectively.
+
+`[ELEMENTS...]'
+ Rather than matching a vector argument, a vector treats the
+ ELEMENTS as a single "group specification".
+
+`"STRING"'
+ The argument should be a symbol named STRING. This specification
+ is equivalent to the quoted symbol, `'SYMBOL', where the name of
+ SYMBOL is the STRING, but the string form is preferred.
+
+`'SYMBOL or (quote SYMBOL)'
+ The argument should be the symbol SYMBOL. But use a string
+ specification instead.
+
+`(vector ELEMENTS...)'
+ The argument should be a vector whose elements must match the
+ ELEMENTS in the specification. See the backquote example below.
+
+`(ELEMENTS...)'
+ Any other list is a "sublist specification" and the argument must
+ be a list whose elements match the specification ELEMENTS.
+
+ A sublist specification may be a dotted list and the corresponding
+ list argument may then be a dotted list. Alternatively, the last
+ cdr of a dotted list specification may be another sublist
+ specification (via a grouping or an indirect specification, e.g.
+ `(spec . [(more specs...)])') whose elements match the non-dotted
+ list arguments. This is useful in recursive specifications such
+ as in the backquote example below. Also see the description of a
+ `nil' specification above for terminating such recursion.
+
+ Note that a sublist specification of the form `(specs . nil)'
+ means the same as `(specs)', and `(specs .
+ (sublist-elements...))' means the same as `(specs
+ sublist-elements...)'.
+
+\1f
+File: lispref.info, Node: Backtracking, Next: Debugging Backquote, Prev: Specification List, Up: Instrumenting Macro Calls
+
+Backtracking
+............
+
+ If a specification fails to match at some point, this does not
+necessarily mean a syntax error will be signaled; instead,
+"backtracking" will take place until all alternatives have been
+exhausted. Eventually every element of the argument list must be
+matched by some element in the specification, and every required element
+in the specification must match some argument.
+
+ Backtracking is disabled for the remainder of a sublist or group when
+certain conditions occur, described below. Backtracking is reenabled
+when a new alternative is established by `&optional', `&rest', or
+`&or'. It is also reenabled initially when processing a sublist or
+group specification or an indirect specification.
+
+ You might want to disable backtracking to commit to some alternative
+so that Edebug can provide a more specific syntax error message.
+Normally, if no alternative matches, Edebug reports that none matched,
+but if one alternative is committed to, Edebug can report how it failed
+to match.
+
+ First, backtracking is disabled while matching any of the form
+specifications (i.e. `form', `body', `def-form', and `def-body').
+These specifications will match any form so any error must be in the
+form itself rather than at a higher level.
+
+ Second, backtracking is disabled after successfully matching a quoted
+symbol or string specification, since this usually indicates a
+recognized construct. If you have a set of alternative constructs that
+all begin with the same symbol, you can usually work around this
+constraint by factoring the symbol out of the alternatives, e.g.,
+`["foo" &or [first case] [second case] ...]'.
+
+ Third, backtracking may be explicitly disabled by using the `gate'
+specification. This is useful when you know that no higher
+alternatives may apply.
+
+\1f
+File: lispref.info, Node: Debugging Backquote, Next: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls
+
+Debugging Backquote
+...................
+
+ Backquote (``') is a macro that results in an expression that may or
+may not be evaluated. It is often used to simplify the definition of a
+macro to return an expression that is evaluated, but Edebug does not
+know when this is the case. However, the forms inside unquotes (`,' and
+`,@') are evaluated and Edebug instruments them.
+
+ Nested backquotes are supported by Edebug, but there is a limit on
+the support of quotes inside of backquotes. Quoted forms (with `'')
+are not normally evaluated, but if the quoted form appears immediately
+within `,' and `,@' forms, Edebug treats this as a backquoted form at
+the next higher level (even if there is not a next higher level - this
+is difficult to fix).
+
+ If the backquoted forms happen to be code intended to be evaluated,
+you can have Edebug instrument them by using `edebug-`' instead of the
+regular ``'. Unquoted forms can always appear inside `edebug-`'
+anywhere a form is normally allowed. But `(, FORM)' may be used in two
+other places specially recognized by Edebug: wherever a predicate
+specification would match, and at the head of a list form in place of a
+function name or lambda expression. The FORM inside a spliced unquote,
+`(,@ FORM)', will be wrapped, but the unquote form itself will not be
+wrapped since this would interfere with the splicing.
+
+ There is one other complication with using `edebug-`'. If the
+`edebug-`' call is in a macro and the macro may be called from code
+that is also instrumented, and if unquoted forms contain any macro
+arguments bound to instrumented forms, then you should modify the
+specification for the macro as follows: the specifications for those
+arguments must use `def-form' instead of `form'. (This is to
+reestablish the Edebugging context for those external forms.)
+
+ For example, the `for' macro (*note Problems with Macros: ()Problems
+with Macros.) is shown here but with `edebug-`' substituted for regular
+``'.
+
+ (defmacro inc (var)
+ (list 'setq var (list '1+ var)))
+
+ (defmacro for (var from init to final do &rest body)
+ (let ((tempvar (make-symbol "max")))
+ (edebug-` (let (((, var) (, init))
+ ((, tempvar) (, final)))
+ (while (<= (, var) (, tempvar))
+ (, body)
+ (inc (, var)))))))
+
+ Here is the corresponding modified Edebug specification and some code
+that calls the macro:
+
+ (def-edebug-spec for
+ (symbolp "from" def-form "to" def-form "do" &rest def-form))
+
+ (let ((n 5))
+ (for i from n to (* n (+ n 1)) do
+ (message "%s" i)))
+
+ After instrumenting the `for' macro and the macro call, Edebug first
+steps to the beginning of the macro call, then into the macro body,
+then through each of the unquoted expressions in the backquote showing
+the expressions that will be embedded in the backquote form. Then when
+the macro expansion is evaluated, Edebug will step through the `let'
+form and each time it gets to an unquoted form, it will jump back to an
+argument of the macro call to step through that expression. Finally
+stepping will continue after the macro call. Even more convoluted
+execution paths may result when using anonymous functions.
+
+ When the result of an expression is an instrumented expression, it is
+difficult to see the expression inside the instrumentation. So you may
+want to set the option `edebug-unwrap-results' to a non-`nil' value
+while debugging such expressions, but it would slow Edebug down to
+always do this.
+
+\1f
+File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls
+
+Specification Examples
+......................
+
+ Here we provide several examples of Edebug specifications to show
+many of its capabilities.
+
+ A `let' special form has a sequence of bindings and a body. Each of
+the bindings is either a symbol or a sublist with a symbol and optional
+value. In the specification below, notice the `gate' inside of the
+sublist to prevent backtracking.
+
+ (def-edebug-spec let
+ ((&rest
+ &or symbolp (gate symbolp &optional form))
+ body))
+
+ Edebug uses the following specifications for `defun' and `defmacro'
+and the associated argument list and `interactive' specifications. It
+is necessary to handle the expression argument of an interactive form
+specially since it is actually evaluated outside of the function body.
+
+ (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec
+ (def-edebug-spec defun
+ (&define name lambda-list
+ [&optional stringp] ; Match the doc string, if present.
+ [&optional ("interactive" interactive)]
+ def-body))
+
+ (def-edebug-spec lambda-list
+ (([&rest arg]
+ [&optional ["&optional" arg &rest arg]]
+ &optional ["&rest" arg]
+ )))
+
+ (def-edebug-spec interactive
+ (&optional &or stringp def-form)) ; Notice: `def-form'
+
+ The specification for backquote below illustrates how to match
+dotted lists and use `nil' to terminate recursion. It also illustrates
+how components of a vector may be matched. (The actual specification
+provided by Edebug does not support dotted lists because doing so
+causes very deep recursion that could fail.)
+
+ (def-edebug-spec ` (backquote-form)) ;; alias just for clarity
+
+ (def-edebug-spec backquote-form
+ (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
+ (backquote-form . [&or nil backquote-form])
+ (vector &rest backquote-form)
+ sexp))
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
+
+Input Streams
+=============
+
+ Most of the Lisp functions for reading text take an "input stream"
+as an argument. The input stream specifies where or how to get the
+characters of the text to be read. Here are the possible types of input
+stream:
+
+BUFFER
+ The input characters are read from BUFFER, starting with the
+ character directly after point. Point advances as characters are
+ read.
+
+MARKER
+ The input characters are read from the buffer that MARKER is in,
+ starting with the character directly after the marker. The marker
+ position advances as characters are read. The value of point in
+ the buffer has no effect when the stream is a marker.
+
+STRING
+ The input characters are taken from STRING, starting at the first
+ character in the string and using as many characters as required.
+
+FUNCTION
+ The input characters are generated by FUNCTION, one character per
+ call. Normally FUNCTION is called with no arguments, and should
+ return a character.
+
+ Occasionally FUNCTION is called with one argument (always a
+ character). When that happens, FUNCTION should save the argument
+ and arrange to return it on the next call. This is called
+ "unreading" the character; it happens when the Lisp reader reads
+ one character too many and wants to "put it back where it came
+ from".
+
+`t'
+ `t' used as a stream means that the input is read from the
+ minibuffer. In fact, the minibuffer is invoked once and the text
+ given by the user is made into a string that is then used as the
+ input stream.
+
+`nil'
+ `nil' supplied as an input stream means to use the value of
+ `standard-input' instead; that value is the "default input
+ stream", and must be a non-`nil' input stream.
+
+SYMBOL
+ A symbol as input stream is equivalent to the symbol's function
+ definition (if any).
+
+ Here is an example of reading from a stream that is a buffer, showing
+where point is located before and after:
+
+ ---------- Buffer: foo ----------
+ This-!- is the contents of foo.
+ ---------- Buffer: foo ----------
+
+ (read (get-buffer "foo"))
+ => is
+ (read (get-buffer "foo"))
+ => the
+
+ ---------- Buffer: foo ----------
+ This is the-!- contents of foo.
+ ---------- Buffer: foo ----------
+
+Note that the first read skips a space. Reading skips any amount of
+whitespace preceding the significant text.
+
+ In Emacs 18, reading a symbol discarded the delimiter terminating the
+symbol. Thus, point would end up at the beginning of `contents' rather
+than after `the'. The Emacs 19 behavior is superior because it
+correctly handles input such as `bar(foo)', where the open-parenthesis
+that ends one object is needed as the beginning of another object.
+
+ Here is an example of reading from a stream that is a marker,
+initially positioned at the beginning of the buffer shown. The value
+read is the symbol `This'.
+
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ ---------- Buffer: foo ----------
+
+ (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
+ => #<marker at 1 in foo>
+ (read m)
+ => This
+ m
+ => #<marker at 5 in foo> ;; Before the first space.
+
+ Here we read from the contents of a string:
+
+ (read "(When in) the course")
+ => (When in)
+
+ The following example reads from the minibuffer. The prompt is:
+`Lisp expression: '. (That is always the prompt used when you read
+from the stream `t'.) The user's input is shown following the prompt.
+
+ (read t)
+ => 23
+ ---------- Buffer: Minibuffer ----------
+ Lisp expression: 23 <RET>
+ ---------- Buffer: Minibuffer ----------
+
+ Finally, here is an example of a stream that is a function, named
+`useless-stream'. Before we use the stream, we initialize the variable
+`useless-list' to a list of characters. Then each call to the function
+`useless-stream' obtains the next character in the list or unreads a
+character by adding it to the front of the list.
+
+ (setq useless-list (append "XY()" nil))
+ => (88 89 40 41)
+
+ (defun useless-stream (&optional unread)
+ (if unread
+ (setq useless-list (cons unread useless-list))
+ (prog1 (car useless-list)
+ (setq useless-list (cdr useless-list)))))
+ => useless-stream
+
+Now we read using the stream thus constructed:
+
+ (read 'useless-stream)
+ => XY
+
+ useless-list
+ => (40 41)
+
+Note that the open and close parentheses remains in the list. The Lisp
+reader encountered the open parenthesis, decided that it ended the
+input, and unread it. Another attempt to read from the stream at this
+point would read `()' and return `nil'.
+
+\1f
+File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print
+
+Input Functions
+===============
+
+ This section describes the Lisp functions and variables that pertain
+to reading.
+
+ In the functions below, STREAM stands for an input stream (see the
+previous section). If STREAM is `nil' or omitted, it defaults to the
+value of `standard-input'.
+
+ An `end-of-file' error is signaled if reading encounters an
+unterminated list, vector, or string.
+
+ - Function: read &optional STREAM
+ This function reads one textual Lisp expression from STREAM,
+ returning it as a Lisp object. This is the basic Lisp input
+ function.
+
+ - Function: read-from-string STRING &optional START END
+ This function reads the first textual Lisp expression from the
+ text in STRING. It returns a cons cell whose CAR is that
+ expression, and whose CDR is an integer giving the position of the
+ next remaining character in the string (i.e., the first one not
+ read).
+
+ If START is supplied, then reading begins at index START in the
+ string (where the first character is at index 0). If END is also
+ supplied, then reading stops just before that index, as if the rest
+ of the string were not there.
+
+ For example:
+
+ (read-from-string "(setq x 55) (setq y 5)")
+ => ((setq x 55) . 11)
+ (read-from-string "\"A short string\"")
+ => ("A short string" . 16)
+
+ ;; Read starting at the first character.
+ (read-from-string "(list 112)" 0)
+ => ((list 112) . 10)
+ ;; Read starting at the second character.
+ (read-from-string "(list 112)" 1)
+ => (list . 5)
+ ;; Read starting at the seventh character,
+ ;; and stopping at the ninth.
+ (read-from-string "(list 112)" 6 8)
+ => (11 . 8)
+
+ - Variable: standard-input
+ This variable holds the default input stream--the stream that
+ `read' uses when the STREAM argument is `nil'.
+
+\1f
+File: lispref.info, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print
+
+Output Streams
+==============
+
+ An output stream specifies what to do with the characters produced
+by printing. Most print functions accept an output stream as an
+optional argument. Here are the possible types of output stream:
+
+BUFFER
+ The output characters are inserted into BUFFER at point. Point
+ advances as characters are inserted.
+
+MARKER
+ The output characters are inserted into the buffer that MARKER
+ points into, at the marker position. The marker position advances
+ as characters are inserted. The value of point in the buffer has
+ no effect on printing when the stream is a marker.
+
+FUNCTION
+ The output characters are passed to FUNCTION, which is responsible
+ for storing them away. It is called with a single character as
+ argument, as many times as there are characters to be output, and
+ is free to do anything at all with the characters it receives.
+
+`t'
+ The output characters are displayed in the echo area.
+
+`nil'
+ `nil' specified as an output stream means to the value of
+ `standard-output' instead; that value is the "default output
+ stream", and must be a non-`nil' output stream.
+
+SYMBOL
+ A symbol as output stream is equivalent to the symbol's function
+ definition (if any).
+
+ Many of the valid output streams are also valid as input streams.
+The difference between input and output streams is therefore mostly one
+of how you use a Lisp object, not a distinction of types of object.
+
+ Here is an example of a buffer used as an output stream. Point is
+initially located as shown immediately before the `h' in `the'. At the
+end, point is located directly before that same `h'.
+
+ ---------- Buffer: foo ----------
+ This is t-!-he contents of foo.
+ ---------- Buffer: foo ----------
+
+ (print "This is the output" (get-buffer "foo"))
+ => "This is the output"
+
+ ---------- Buffer: foo ----------
+ This is t
+ "This is the output"
+ -!-he contents of foo.
+ ---------- Buffer: foo ----------
+
+ Now we show a use of a marker as an output stream. Initially, the
+marker is in buffer `foo', between the `t' and the `h' in the word
+`the'. At the end, the marker has advanced over the inserted text so
+that it remains positioned before the same `h'. Note that the location
+of point, shown in the usual fashion, has no effect.
+
+ ---------- Buffer: foo ----------
+ "This is the -!-output"
+ ---------- Buffer: foo ----------
+
+ m
+ => #<marker at 11 in foo>
+
+ (print "More output for foo." m)
+ => "More output for foo."
+
+ ---------- Buffer: foo ----------
+ "This is t
+ "More output for foo."
+ he -!-output"
+ ---------- Buffer: foo ----------
+
+ m
+ => #<marker at 35 in foo>
+
+ The following example shows output to the echo area:
+
+ (print "Echo Area output" t)
+ => "Echo Area output"
+ ---------- Echo Area ----------
+ "Echo Area output"
+ ---------- Echo Area ----------
+
+ Finally, we show the use of a function as an output stream. The
+function `eat-output' takes each character that it is given and conses
+it onto the front of the list `last-output' (*note Building Lists::.).
+At the end, the list contains all the characters output, but in reverse
+order.
+
+ (setq last-output nil)
+ => nil
+
+ (defun eat-output (c)
+ (setq last-output (cons c last-output)))
+ => eat-output
+
+ (print "This is the output" 'eat-output)
+ => "This is the output"
+
+ last-output
+ => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
+ ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
+
+Now we can put the output in the proper order by reversing the list:
+
+ (concat (nreverse last-output))
+ => "
+ \"This is the output\"
+ "
+
+Calling `concat' converts the list to a string so you can see its
+contents more clearly.
+
+\1f
+File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print
+
+Output Functions
+================
+
+ This section describes the Lisp functions for printing Lisp objects.
+
+ Some of the XEmacs printing functions add quoting characters to the
+output when necessary so that it can be read properly. The quoting
+characters used are `"' and `\'; they distinguish strings from symbols,
+and prevent punctuation characters in strings and symbols from being
+taken as delimiters when reading. *Note Printed Representation::, for
+full details. You specify quoting or no quoting by the choice of
+printing function.
+
+ If the text is to be read back into Lisp, then it is best to print
+with quoting characters to avoid ambiguity. Likewise, if the purpose is
+to describe a Lisp object clearly for a Lisp programmer. However, if
+the purpose of the output is to look nice for humans, then it is better
+to print without quoting.
+
+ Printing a self-referent Lisp object requires an infinite amount of
+text. In certain cases, trying to produce this text leads to a stack
+overflow. XEmacs detects such recursion and prints `#LEVEL' instead of
+recursively printing an object already being printed. For example,
+here `#0' indicates a recursive reference to the object at level 0 of
+the current print operation:
+
+ (setq foo (list nil))
+ => (nil)
+ (setcar foo foo)
+ => (#0)
+
+ In the functions below, STREAM stands for an output stream. (See
+the previous section for a description of output streams.) If STREAM
+is `nil' or omitted, it defaults to the value of `standard-output'.
+
+ - Function: print OBJECT &optional STREAM
+ The `print' function is a convenient way of printing. It outputs
+ the printed representation of OBJECT to STREAM, printing in
+ addition one newline before OBJECT and another after it. Quoting
+ characters are used. `print' returns OBJECT. For example:
+
+ (progn (print 'The\ cat\ in)
+ (print "the hat")
+ (print " came back"))
+ -|
+ -| The\ cat\ in
+ -|
+ -| "the hat"
+ -|
+ -| " came back"
+ -|
+ => " came back"
+
+ - Function: prin1 OBJECT &optional STREAM
+ This function outputs the printed representation of OBJECT to
+ STREAM. It does not print newlines to separate output as `print'
+ does, but it does use quoting characters just like `print'. It
+ returns OBJECT.
+
+ (progn (prin1 'The\ cat\ in)
+ (prin1 "the hat")
+ (prin1 " came back"))
+ -| The\ cat\ in"the hat"" came back"
+ => " came back"
+
+ - Function: princ OBJECT &optional STREAM
+ This function outputs the printed representation of OBJECT to
+ STREAM. It returns OBJECT.
+
+ This function is intended to produce output that is readable by
+ people, not by `read', so it doesn't insert quoting characters and
+ doesn't put double-quotes around the contents of strings. It does
+ not add any spacing between calls.
+
+ (progn
+ (princ 'The\ cat)
+ (princ " in the \"hat\""))
+ -| The cat in the "hat"
+ => " in the \"hat\""
+
+ - Function: terpri &optional STREAM
+ This function outputs a newline to STREAM. The name stands for
+ "terminate print".
+
+ - Function: write-char CHARACTER &optional STREAM
+ This function outputs CHARACTER to STREAM. It returns CHARACTER.
+
+ - Function: prin1-to-string OBJECT &optional NOESCAPE
+ This function returns a string containing the text that `prin1'
+ would have printed for the same argument.
+
+ (prin1-to-string 'foo)
+ => "foo"
+ (prin1-to-string (mark-marker))
+ => "#<marker at 2773 in strings.texi>"
+
+ If NOESCAPE is non-`nil', that inhibits use of quoting characters
+ in the output. (This argument is supported in Emacs versions 19
+ and later.)
+
+ (prin1-to-string "foo")
+ => "\"foo\""
+ (prin1-to-string "foo" t)
+ => "foo"
+
+ See `format', in *Note String Conversion::, for other ways to
+ obtain the printed representation of a Lisp object as a string.
+
+\1f
+File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print
+
+Variables Affecting Output
+==========================
+
+ - Variable: standard-output
+ The value of this variable is the default output stream--the stream
+ that print functions use when the STREAM argument is `nil'.
+
+ - Variable: print-escape-newlines
+ If this variable is non-`nil', then newline characters in strings
+ are printed as `\n' and formfeeds are printed as `\f'. Normally
+ these characters are printed as actual newlines and formfeeds.
+
+ This variable affects the print functions `prin1' and `print', as
+ well as everything that uses them. It does not affect `princ'.
+ Here is an example using `prin1':
+
+ (prin1 "a\nb")
+ -| "a
+ -| b"
+ => "a
+ b"
+
+ (let ((print-escape-newlines t))
+ (prin1 "a\nb"))
+ -| "a\nb"
+ => "a
+ b"
+
+ In the second expression, the local binding of
+ `print-escape-newlines' is in effect during the call to `prin1',
+ but not during the printing of the result.
+
+ - Variable: print-readably
+ If non-`nil', then all objects will be printed in a readable form.
+ If an object has no readable representation, then an error is
+ signalled. When `print-readably' is true, compiled-function
+ objects will be written in `#[...]' form instead of in
+ `#<compiled-function [...]>' form, and two-element lists of the
+ form `(quote object)' will be written as the equivalent `'object'.
+ Do not *set* this variable; bind it instead.
+
+ - Variable: print-length
+ The value of this variable is the maximum number of elements of a
+ list that will be printed. If a list being printed has more than
+ this many elements, it is abbreviated with an ellipsis.
+
+ If the value is `nil' (the default), then there is no limit.
+
+ (setq print-length 2)
+ => 2
+ (print '(1 2 3 4 5))
+ -| (1 2 ...)
+ => (1 2 ...)
+
+ - Variable: print-level
+ The value of this variable is the maximum depth of nesting of
+ parentheses and brackets when printed. Any list or vector at a
+ depth exceeding this limit is abbreviated with an ellipsis. A
+ value of `nil' (which is the default) means no limit.
+
+ This variable exists in version 19 and later versions.
+
+ - Variable: print-string-length
+ The value of this variable is the maximum number of characters of
+ a string that will be printed. If a string being printed has more
+ than this many characters, it is abbreviated with an ellipsis.
+
+ - Variable: print-gensym
+ If non-`nil', then uninterned symbols will be printed specially.
+ Uninterned symbols are those which are not present in `obarray',
+ that is, those which were made with `make-symbol' or by calling
+ `intern' with a second argument.
+
+ When `print-gensym' is true, such symbols will be preceded by
+ `#:', which causes the reader to create a new symbol instead of
+ interning and returning an existing one. Beware: The `#:' syntax
+ creates a new symbol each time it is seen, so if you print an
+ object which contains two pointers to the same uninterned symbol,
+ `read' will not duplicate that structure.
+
+ Also, since XEmacs has no real notion of packages, there is no way
+ for the printer to distinguish between symbols interned in no
+ obarray, and symbols interned in an alternate obarray.
+
+ - Variable: float-output-format
+ This variable holds the format descriptor string that Lisp uses to
+ print floats. This is a `%'-spec like those accepted by `printf'
+ in C, but with some restrictions. It must start with the two
+ characters `%.'. After that comes an integer precision
+ specification, and then a letter which controls the format. The
+ letters allowed are `e', `f' and `g'.
+
+ * Use `e' for exponential notation `DIG.DIGITSeEXPT'.
+
+ * Use `f' for decimal point notation `DIGITS.DIGITS'.
+
+ * Use `g' to choose the shorter of those two formats for the
+ number at hand.
+
+ The precision in any of these cases is the number of digits
+ 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'.
+
+ Regardless of the value of `float-output-format', a floating point
+ number will never be printed in such a way that it is ambiguous
+ with an integer; that is, a floating-point number will always be
+ printed with a decimal point and/or an exponent, even if the
+ digits following the decimal point are all zero. This is to
+ preserve read-equivalence.
+
+\1f
+File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top
+
+Minibuffers
+***********
+
+ A "minibuffer" is a special buffer that XEmacs commands use to read
+arguments more complicated than the single numeric prefix argument.
+These arguments include file names, buffer names, and command names (as
+in `M-x'). The minibuffer is displayed on the bottom line of the
+frame, in the same place as the echo area, but only while it is in use
+for reading an argument.
+
+* Menu:
+
+* Intro to Minibuffers:: Basic information about minibuffers.
+* Text from Minibuffer:: How to read a straight text string.
+* Object from Minibuffer:: How to read a Lisp object or expression.
+* Minibuffer History:: Recording previous minibuffer inputs
+ so the user can reuse them.
+* Completion:: How to invoke and customize completion.
+* Yes-or-No Queries:: Asking a question with a simple answer.
+* Multiple Queries:: Asking a series of similar questions.
+* Minibuffer Misc:: Various customization hooks and variables.
+
+\1f
+File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
+
+Introduction to Minibuffers
+===========================
+
+ In most ways, a minibuffer is a normal XEmacs buffer. Most
+operations *within* a buffer, such as editing commands, work normally
+in a minibuffer. However, many operations for managing buffers do not
+apply to minibuffers. The name of a minibuffer always has the form
+` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
+displayed only in special windows used only for minibuffers; these
+windows always appear at the bottom of a frame. (Sometime frames have
+no minibuffer window, and sometimes a special kind of frame contains
+nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
+
+ The minibuffer's window is normally a single line. You can resize it
+temporarily with the window sizing commands; it reverts to its normal
+size when the minibuffer is exited. You can resize it permanently by
+using the window sizing commands in the frame's other window, when the
+minibuffer is not active. If the frame contains just a minibuffer, you
+can change the minibuffer's size by changing the frame's size.
+
+ If a command uses a minibuffer while there is an active minibuffer,
+this is called a "recursive minibuffer". The first minibuffer is named
+` *Minibuf-0*'. Recursive minibuffers are named by incrementing the
+number at the end of the name. (The names begin with a space so that
+they won't show up in normal buffer lists.) Of several recursive
+minibuffers, the innermost (or most recently entered) is the active
+minibuffer. We usually call this "the" minibuffer. You can permit or
+forbid recursive minibuffers by setting the variable
+`enable-recursive-minibuffers'.
+
+ Like other buffers, a minibuffer may use any of several local keymaps
+(*note Keymaps::.); these contain various exit commands and in some
+cases completion commands (*note Completion::.).
+
+ * `minibuffer-local-map' is for ordinary input (no completion).
+
+ * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
+ like <RET>. This is used mainly for Mocklisp compatibility.
+
+ * `minibuffer-local-completion-map' is for permissive completion.
+
+ * `minibuffer-local-must-match-map' is for strict completion and for
+ cautious completion.
+
+\1f
+File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
+
+Reading Text Strings with the Minibuffer
+========================================
+
+ Most often, the minibuffer is used to read text as a string. It can
+also be used to read a Lisp object in textual form. The most basic
+primitive for minibuffer input is `read-from-minibuffer'; it can do
+either one.
+
+ In most cases, you should not call minibuffer input functions in the
+middle of a Lisp function. Instead, do all minibuffer input as part of
+reading the arguments for a command, in the `interactive' spec. *Note
+Defining Commands::.
+
+ - Function: read-from-minibuffer PROMPT-STRING &optional
+ INITIAL-CONTENTS KEYMAP READ HIST
+ This function is the most general way to get input through the
+ minibuffer. By default, it accepts arbitrary text and returns it
+ as a string; however, if READ is non-`nil', then it uses `read' to
+ convert the text into a Lisp object (*note Input Functions::.).
+
+ The first thing this function does is to activate a minibuffer and
+ display it with PROMPT-STRING as the prompt. This value must be a
+ string.
+
+ Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer'
+ inserts it into the minibuffer, leaving point at the end. The
+ minibuffer appears with this text as its contents.
+
+ The value of INITIAL-CONTENTS may also be a cons cell of the form
+ `(STRING . POSITION)'. This means to insert STRING in the
+ minibuffer but put point POSITION characters from the beginning,
+ rather than at the end.
+
+ If KEYMAP is non-`nil', that keymap is the local keymap to use in
+ the minibuffer. If KEYMAP is omitted or `nil', the value of
+ `minibuffer-local-map' is used as the keymap. Specifying a keymap
+ is the most important way to customize the minibuffer for various
+ applications such as completion.
+
+ The argument HIST specifies which history list variable to use for
+ saving the input and for history commands used in the minibuffer.
+ It defaults to `minibuffer-history'. *Note Minibuffer History::.
+
+ When the user types a command to exit the minibuffer,
+ `read-from-minibuffer' uses the text in the minibuffer to produce
+ its return value. Normally it simply makes a string containing
+ that text. However, if READ is non-`nil', `read-from-minibuffer'
+ reads the text and returns the resulting Lisp object, unevaluated.
+ (*Note Input Functions::, for information about reading.)
+
+ - Function: read-string PROMPT &optional INITIAL
+ This function reads a string from the minibuffer and returns it.
+ The arguments PROMPT and INITIAL are used as in
+ `read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
+
+ This is a simplified interface to the `read-from-minibuffer'
+ function:
+
+ (read-string PROMPT INITIAL)
+ ==
+ (read-from-minibuffer PROMPT INITIAL nil nil nil)
+
+ - Variable: minibuffer-local-map
+ This is the default local keymap for reading from the minibuffer.
+ By default, it makes the following bindings:
+
+ <LFD>
+ `exit-minibuffer'
+
+ <RET>
+ `exit-minibuffer'
+
+ `C-g'
+ `abort-recursive-edit'
+
+ `M-n'
+ `next-history-element'
+
+ `M-p'
+ `previous-history-element'
+
+ `M-r'
+ `next-matching-history-element'
+
+ `M-s'
+ `previous-matching-history-element'
+
+ - Function: read-no-blanks-input PROMPT &optional INITIAL
+ This function reads a string from the minibuffer, but does not
+ allow whitespace characters as part of the input: instead, those
+ characters terminate the input. The arguments PROMPT and INITIAL
+ are used as in `read-from-minibuffer'.
+
+ This is a simplified interface to the `read-from-minibuffer'
+ function, and passes the value of the `minibuffer-local-ns-map'
+ keymap as the KEYMAP argument for that function. Since the keymap
+ `minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
+ to put a space into the string, by quoting it.
+
+ (read-no-blanks-input PROMPT INITIAL)
+ ==
+ (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)
+
+ - Variable: minibuffer-local-ns-map
+ This built-in variable is the keymap used as the minibuffer local
+ keymap in the function `read-no-blanks-input'. By default, it
+ makes the following bindings, in addition to those of
+ `minibuffer-local-map':
+
+ <SPC>
+ `exit-minibuffer'
+
+ <TAB>
+ `exit-minibuffer'
+
+ `?'
+ `self-insert-and-exit'
+
+\1f
+File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
+
+Reading Lisp Objects with the Minibuffer
+========================================
+
+ This section describes functions for reading Lisp objects with the
+minibuffer.
+
+ - Function: read-minibuffer PROMPT &optional INITIAL
+ This function reads a Lisp object in the minibuffer and returns it,
+ without evaluating it. The arguments PROMPT and INITIAL are used
+ as in `read-from-minibuffer'.
+
+ This is a simplified interface to the `read-from-minibuffer'
+ function:
+
+ (read-minibuffer PROMPT INITIAL)
+ ==
+ (read-from-minibuffer PROMPT INITIAL nil t)
+
+ Here is an example in which we supply the string `"(testing)"' as
+ initial input:
+
+ (read-minibuffer
+ "Enter an expression: " (format "%s" '(testing)))
+
+ ;; Here is how the minibuffer is displayed:
+
+ ---------- Buffer: Minibuffer ----------
+ Enter an expression: (testing)-!-
+ ---------- Buffer: Minibuffer ----------
+
+ The user can type <RET> immediately to use the initial input as a
+ default, or can edit the input.
+
+ - Function: eval-minibuffer PROMPT &optional INITIAL
+ This function reads a Lisp expression in the minibuffer, evaluates
+ it, then returns the result. The arguments PROMPT and INITIAL are
+ used as in `read-from-minibuffer'.
+
+ This function simply evaluates the result of a call to
+ `read-minibuffer':
+
+ (eval-minibuffer PROMPT INITIAL)
+ ==
+ (eval (read-minibuffer PROMPT INITIAL))
+
+ - Function: edit-and-eval-command PROMPT FORM
+ This function reads a Lisp expression in the minibuffer, and then
+ evaluates it. The difference between this command and
+ `eval-minibuffer' is that here the initial FORM is not optional
+ 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 (`"')
+ appear in the initial text. *Note Output Functions::.
+
+ The first thing `edit-and-eval-command' does is to activate the
+ minibuffer with PROMPT as the prompt. Then it inserts the printed
+ representation of FORM in the minibuffer, and lets the user edit.
+ When the user exits the minibuffer, the edited text is read with
+ `read' and then evaluated. The resulting value becomes the value
+ of `edit-and-eval-command'.
+
+ In the following example, we offer the user an expression with
+ initial text which is a valid form already:
+
+ (edit-and-eval-command "Please edit: " '(forward-word 1))
+
+ ;; After evaluation of the preceding expression,
+ ;; the following appears in the minibuffer:
+
+ ---------- Buffer: Minibuffer ----------
+ Please edit: (forward-word 1)-!-
+ ---------- Buffer: Minibuffer ----------
+
+ Typing <RET> right away would exit the minibuffer and evaluate the
+ expression, thus moving point forward one word.
+ `edit-and-eval-command' returns `t' in this example.
+
+\1f
+File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
+
+Minibuffer History
+==================
+
+ A "minibuffer history list" records previous minibuffer inputs so
+the user can reuse them conveniently. A history list is actually a
+symbol, not a list; it is a variable whose value is a list of strings
+(previous inputs), most recent first.
+
+ There are many separate history lists, used for different kinds of
+inputs. It's the Lisp programmer's job to specify the right history
+list for each use of the minibuffer.
+
+ The basic minibuffer input functions `read-from-minibuffer' and
+`completing-read' both accept an optional argument named HIST which is
+how you specify the history list. Here are the possible values:
+
+VARIABLE
+ Use VARIABLE (a symbol) as the history list.
+
+(VARIABLE . STARTPOS)
+ Use VARIABLE (a symbol) as the history list, and assume that the
+ initial history position is STARTPOS (an integer, counting from
+ zero which specifies the most recent element of the history).
+
+ If you specify STARTPOS, then you should also specify that element
+ of the history as the initial minibuffer contents, for consistency.
+
+ If you don't specify HIST, then the default history list
+`minibuffer-history' is used. For other standard history lists, see
+below. You can also create your own history list variable; just
+initialize it to `nil' before the first use.
+
+ Both `read-from-minibuffer' and `completing-read' add new elements
+to the history list automatically, and provide commands to allow the
+user to reuse items on the list. The only thing your program needs to
+do to use a history list is to initialize it and to pass its name to
+the input functions when you wish. But it is safe to modify the list
+by hand when the minibuffer input functions are not using it.
+
+ - Variable: minibuffer-history
+ The default history list for minibuffer history input.
+
+ - Variable: query-replace-history
+ A history list for arguments to `query-replace' (and similar
+ arguments to other commands).
+
+ - Variable: file-name-history
+ A history list for file name arguments.
+
+ - Variable: regexp-history
+ A history list for regular expression arguments.
+
+ - Variable: extended-command-history
+ A history list for arguments that are names of extended commands.
+
+ - Variable: shell-command-history
+ A history list for arguments that are shell commands.
+
+ - Variable: read-expression-history
+ A history list for arguments that are Lisp expressions to evaluate.
+
+ - Variable: Info-minibuffer-history
+ A history list for Info mode's minibuffer.
+
+ - Variable: Manual-page-minibuffer-history
+ A history list for `manual-entry'.
+
+ There are many other minibuffer history lists, defined by various
+libraries. An `M-x apropos' search for `history' should prove fruitful
+in discovering them.
+
+\1f
+File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
+
+Completion
+==========
+
+ "Completion" is a feature that fills in the rest of a name starting
+from an abbreviation for it. Completion works by comparing the user's
+input against a list of valid names and determining how much of the
+name is determined uniquely by what the user has typed. For example,
+when you type `C-x b' (`switch-to-buffer') and then type the first few
+letters of the name of the buffer to which you wish to switch, and then
+type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
+can.
+
+ Standard XEmacs commands offer completion for names of symbols,
+files, buffers, and processes; with the functions in this section, you
+can implement completion for other kinds of names.
+
+ The `try-completion' function is the basic primitive for completion:
+it returns the longest determined completion of a given initial string,
+with a given set of strings to match against.
+
+ The function `completing-read' provides a higher-level interface for
+completion. A call to `completing-read' specifies how to determine the
+list of valid names. The function then activates the minibuffer with a
+local keymap that binds a few keys to commands useful for completion.
+Other functions provide convenient simple interfaces for reading
+certain kinds of names with completion.
+
+* Menu:
+
+* Basic Completion:: Low-level functions for completing strings.
+ (These are too low level to use the minibuffer.)
+* Minibuffer Completion:: Invoking the minibuffer with completion.
+* Completion Commands:: Minibuffer commands that do completion.
+* High-Level Completion:: Convenient special cases of completion
+ (reading buffer name, file name, etc.)
+* Reading File Names:: Using completion to read file names.
+* Programmed Completion:: Finding the completions for a given file name.
+
+\1f
+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 parameters to this function are the same as to
+ `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.
+
+\1f
+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
+ 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.
+
+ The user can exit with null input by typing <RET> with an empty
+ minibuffer. Then `completing-read' returns `nil'. This is how
+ the user requests whatever default the command uses for the value
+ being read. The user can return using <RET> in this way regardless
+ of the value of REQUIRE-MATCH.
+
+ The function `completing-read' works by calling `read-minibuffer'.
+ 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 `<DEL> <DEL> b <RET>', `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::.
+
+\1f
+File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
+
+Minibuffer Commands That Do Completion
+--------------------------------------
+
+ This section describes the keymaps, commands and user options used in
+the minibuffer to do completion.
+
+ - Variable: minibuffer-local-completion-map
+ `completing-read' uses this value as the local keymap when an
+ exact match of one of the completions is not required. By
+ default, this keymap makes the following bindings:
+
+ `?'
+ `minibuffer-completion-help'
+
+ <SPC>
+ `minibuffer-complete-word'
+
+ <TAB>
+ `minibuffer-complete'
+
+ with other characters bound as in `minibuffer-local-map' (*note
+ Text from Minibuffer::.).
+
+ - Variable: minibuffer-local-must-match-map
+ `completing-read' uses this value as the local keymap when an
+ exact match of one of the completions is required. Therefore, no
+ keys are bound to `exit-minibuffer', the command that exits the
+ minibuffer unconditionally. By default, this keymap makes the
+ following bindings:
+
+ `?'
+ `minibuffer-completion-help'
+
+ <SPC>
+ `minibuffer-complete-word'
+
+ <TAB>
+ `minibuffer-complete'
+
+ <LFD>
+ `minibuffer-complete-and-exit'
+
+ <RET>
+ `minibuffer-complete-and-exit'
+
+ with other characters bound as in `minibuffer-local-map'.
+
+ - Variable: minibuffer-completion-table
+ The value of this variable is the alist or obarray used for
+ completion in the minibuffer. This is the global variable that
+ contains what `completing-read' passes to `try-completion'. It is
+ used by minibuffer completion commands such as
+ `minibuffer-complete-word'.
+
+ - Variable: minibuffer-completion-predicate
+ This variable's value is the predicate that `completing-read'
+ passes to `try-completion'. The variable is also used by the other
+ minibuffer completion functions.
+
+ - Command: minibuffer-complete-word
+ This function completes the minibuffer contents by at most a single
+ word. Even if the minibuffer contents have only one completion,
+ `minibuffer-complete-word' does not add any characters beyond the
+ first character that is not a word constituent. *Note Syntax
+ Tables::.
+
+ - Command: minibuffer-complete
+ This function completes the minibuffer contents as far as possible.
+
+ - Command: minibuffer-complete-and-exit
+ This function completes the minibuffer contents, and exits if
+ confirmation is not required, i.e., if
+ `minibuffer-completion-confirm' is non-`nil'. If confirmation
+ *is* required, it is given by repeating this command
+ immediately--the command is programmed to work without confirmation
+ when run twice in succession.
+
+ - Variable: minibuffer-completion-confirm
+ When the value of this variable is non-`nil', XEmacs asks for
+ confirmation of a completion before exiting the minibuffer. The
+ function `minibuffer-complete-and-exit' checks the value of this
+ variable before it exits.
+
+ - Command: minibuffer-completion-help
+ This function creates a list of the possible completions of the
+ current minibuffer contents. It works by calling `all-completions'
+ using the value of the variable `minibuffer-completion-table' as
+ the COLLECTION argument, and the value of
+ `minibuffer-completion-predicate' as the PREDICATE argument. The
+ list of completions is displayed as text in a buffer named
+ `*Completions*'.
+
+ - Function: display-completion-list COMPLETIONS
+ This function displays COMPLETIONS to the stream in
+ `standard-output', usually a buffer. (*Note Read and Print::, for
+ more information about streams.) The argument COMPLETIONS is
+ normally a list of completions just returned by `all-completions',
+ but it does not have to be. Each element may be a symbol or a
+ string, either of which is simply printed, or a list of two
+ strings, which is printed as if the strings were concatenated.
+
+ This function is called by `minibuffer-completion-help'. The most
+ common way to use it is together with
+ `with-output-to-temp-buffer', like this:
+
+ (with-output-to-temp-buffer "*Completions*"
+ (display-completion-list
+ (all-completions (buffer-string) my-alist)))
+
+ - User Option: completion-auto-help
+ If this variable is non-`nil', the completion commands
+ automatically display a list of possible completions whenever
+ nothing can be completed because the next character is not
+ uniquely determined.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
+
+High-Level Completion Functions
+--------------------------------
+
+ This section describes the higher-level convenient functions for
+reading certain sorts of names with completion.
+
+ In most cases, you should not call these functions in the middle of a
+Lisp function. When possible, do all minibuffer input as part of
+reading the arguments for a command, in the `interactive' spec. *Note
+Defining Commands::.
+
+ - Function: read-buffer PROMPT &optional DEFAULT EXISTING
+ This function reads the name of a buffer and returns it as a
+ string. The argument DEFAULT is the default name to use, the
+ value to return if the user exits with an empty minibuffer. If
+ non-`nil', it should be a string or a buffer. It is mentioned in
+ the prompt, but is not inserted in the minibuffer as initial input.
+
+ If EXISTING is non-`nil', then the name specified must be that of
+ an existing buffer. The usual commands to exit the minibuffer do
+ not exit if the text is not valid, and <RET> does completion to
+ attempt to find a valid name. (However, DEFAULT is not checked
+ for validity; it is returned, whatever it is, if the user exits
+ with the minibuffer empty.)
+
+ In the following example, the user enters `minibuffer.t', and then
+ types <RET>. The argument EXISTING is `t', and the only buffer
+ name starting with the given input is `minibuffer.texi', so that
+ name is the value.
+
+ (read-buffer "Buffer name? " "foo" t)
+ ;; After evaluation of the preceding expression,
+ ;; the following prompt appears,
+ ;; with an empty minibuffer:
+
+ ---------- Buffer: Minibuffer ----------
+ Buffer name? (default foo) -!-
+ ---------- Buffer: Minibuffer ----------
+
+ ;; The user types `minibuffer.t <RET>'.
+ => "minibuffer.texi"
+
+ - Function: read-command PROMPT
+ This function reads the name of a command and returns it as a Lisp
+ symbol. The argument PROMPT is used as in `read-from-minibuffer'.
+ Recall that a command is anything for which `commandp' returns
+ `t', and a command name is a symbol for which `commandp' returns
+ `t'. *Note Interactive Call::.
+
+ (read-command "Command name? ")
+
+ ;; After evaluation of the preceding expression,
+ ;; the following prompt appears with an empty minibuffer:
+
+ ---------- Buffer: Minibuffer ----------
+ Command name?
+ ---------- Buffer: Minibuffer ----------
+
+ If the user types `forward-c <RET>', then this function returns
+ `forward-char'.
+
+ The `read-command' function is a simplified interface to the
+ function `completing-read'. It uses the variable `obarray' so as
+ to complete in the set of extant Lisp symbols, and it uses the
+ `commandp' predicate so as to accept only command names:
+
+ (read-command PROMPT)
+ ==
+ (intern (completing-read PROMPT obarray
+ 'commandp t nil))
+
+ - Function: read-variable PROMPT
+ This function reads the name of a user variable and returns it as a
+ symbol.
+
+ (read-variable "Variable name? ")
+
+ ;; After evaluation of the preceding expression,
+ ;; the following prompt appears,
+ ;; with an empty minibuffer:
+
+ ---------- Buffer: Minibuffer ----------
+ Variable name? -!-
+ ---------- Buffer: Minibuffer ----------
+
+ If the user then types `fill-p <RET>', `read-variable' returns
+ `fill-prefix'.
+
+ This function is similar to `read-command', but uses the predicate
+ `user-variable-p' instead of `commandp':
+
+ (read-variable PROMPT)
+ ==
+ (intern
+ (completing-read PROMPT obarray
+ 'user-variable-p t nil))
+
+\1f
+File: lispref.info, Node: Reading File Names, Next: Programmed Completion, Prev: High-Level Completion, Up: Completion
+
+Reading File Names
+------------------
+
+ Here is another high-level completion function, designed for reading
+a file name. It provides special features including automatic insertion
+of the default directory.
+
+ - Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
+ INITIAL
+ This function reads a file name in the minibuffer, prompting with
+ PROMPT and providing completion. If DEFAULT is non-`nil', then
+ the function returns DEFAULT if the user just types <RET>.
+ DEFAULT is not checked for validity; it is returned, whatever it
+ is, if the user exits with the minibuffer empty.
+
+ If EXISTING is non-`nil', then the user must specify the name of
+ an existing file; <RET> performs completion to make the name valid
+ if possible, and then refuses to exit if it is not valid. If the
+ value of EXISTING is neither `nil' nor `t', then <RET> also
+ requires confirmation after completion. If EXISTING is `nil',
+ then the name of a nonexistent file is acceptable.
+
+ The argument DIRECTORY specifies the directory to use for
+ completion of relative file names. If `insert-default-directory'
+ is non-`nil', DIRECTORY is also inserted in the minibuffer as
+ initial input. It defaults to the current buffer's value of
+ `default-directory'.
+
+ If you specify INITIAL, that is an initial file name to insert in
+ the buffer (after with DIRECTORY, if that is inserted). In this
+ case, point goes at the beginning of INITIAL. The default for
+ INITIAL is `nil'--don't insert any file name. To see what INITIAL
+ does, try the command `C-x C-v'.
+
+ Here is an example:
+
+ (read-file-name "The file is ")
+
+ ;; After evaluation of the preceding expression,
+ ;; the following appears in the minibuffer:
+
+ ---------- Buffer: Minibuffer ----------
+ The file is /gp/gnu/elisp/-!-
+ ---------- Buffer: Minibuffer ----------
+
+ Typing `manual <TAB>' results in the following:
+
+ ---------- Buffer: Minibuffer ----------
+ The file is /gp/gnu/elisp/manual.texi-!-
+ ---------- Buffer: Minibuffer ----------
+
+ If the user types <RET>, `read-file-name' returns the file name as
+ the string `"/gp/gnu/elisp/manual.texi"'.
+
+ - User Option: insert-default-directory
+ This variable is used by `read-file-name'. Its value controls
+ whether `read-file-name' starts by placing the name of the default
+ directory in the minibuffer, plus the initial file name if any.
+ If the value of this variable is `nil', then `read-file-name' does
+ not place any initial input in the minibuffer (unless you specify
+ initial input with the INITIAL argument). In that case, the
+ default directory is still used for completion of relative file
+ names, but is not displayed.
+
+ For example:
+
+ ;; Here the minibuffer starts out with the default directory.
+ (let ((insert-default-directory t))
+ (read-file-name "The file is "))
+
+ ---------- Buffer: Minibuffer ----------
+ The file is ~lewis/manual/-!-
+ ---------- Buffer: Minibuffer ----------
+
+ ;; Here the minibuffer is empty and only the prompt
+ ;; appears on its line.
+ (let ((insert-default-directory nil))
+ (read-file-name "The file is "))
+
+ ---------- Buffer: Minibuffer ----------
+ The file is -!-
+ ---------- Buffer: Minibuffer ----------
+
+\1f
+File: lispref.info, Node: Programmed Completion, Prev: Reading File Names, Up: Completion
+
+Programmed Completion
+---------------------
+
+ Sometimes it is not possible to create an alist or an obarray
+containing all the intended possible completions. In such a case, you
+can supply your own function to compute the completion of a given
+string. This is called "programmed completion".
+
+ To use this feature, pass a symbol with a function definition as the
+COLLECTION argument to `completing-read'. The function
+`completing-read' arranges to pass your completion function along to
+`try-completion' and `all-completions', which will then let your
+function do all the work.
+
+ The completion function should accept three arguments:
+
+ * The string to be completed.
+
+ * The predicate function to filter possible matches, or `nil' if
+ none. Your function should call the predicate for each possible
+ match, and ignore the possible match if the predicate returns
+ `nil'.
+
+ * A flag specifying the type of operation.
+
+ There are three flag values for three operations:
+
+ * `nil' specifies `try-completion'. The completion function should
+ return the completion of the specified string, or `t' if the
+ string is an exact match already, or `nil' if the string matches no
+ possibility.
+
+ * `t' specifies `all-completions'. The completion function should
+ return a list of all possible completions of the specified string.
+
+ * `lambda' specifies a test for an exact match. The completion
+ function should return `t' if the specified string is an exact
+ match for some possibility; `nil' otherwise.
+
+ It would be consistent and clean for completion functions to allow
+lambda expressions (lists that are functions) as well as function
+symbols as COLLECTION, but this is impossible. Lists as completion
+tables are already assigned another meaning--as alists. It would be
+unreliable to fail to handle an alist normally because it is also a
+possible function. So you must arrange for any function you wish to
+use for completion to be encapsulated in a symbol.
+
+ Emacs uses programmed completion when completing file names. *Note
+File Name Completion::.
+
+\1f
+File: lispref.info, Node: Yes-or-No Queries, Next: Multiple Queries, Prev: Completion, Up: Minibuffers
+
+Yes-or-No Queries
+=================
+
+ This section describes functions used to ask the user a yes-or-no
+question. The function `y-or-n-p' can be answered with a single
+character; it is useful for questions where an inadvertent wrong answer
+will not have serious consequences. `yes-or-no-p' is suitable for more
+momentous questions, since it requires three or four characters to
+answer. Variations of these functions can be used to ask a yes-or-no
+question using a dialog box, or optionally using one.
+
+ If either of these functions is called in a command that was invoked
+using the mouse, then it uses a dialog box or pop-up menu to ask the
+question. Otherwise, it uses keyboard input.
+
+ Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
+does not; but it seems best to describe them together.
+
+ - Function: y-or-n-p PROMPT
+ This function asks the user a question, expecting input in the echo
+ area. It returns `t' if the user types `y', `nil' if the user
+ types `n'. This function also accepts <SPC> to mean yes and <DEL>
+ to mean no. It accepts `C-]' to mean "quit", like `C-g', because
+ the question might look like a minibuffer and for that reason the
+ user might try to use `C-]' to get out. The answer is a single
+ character, with no <RET> needed to terminate it. Upper and lower
+ case are equivalent.
+
+ "Asking the question" means printing PROMPT in the echo area,
+ followed by the string `(y or n) '. If the input is not one of
+ the expected answers (`y', `n', `<SPC>', `<DEL>', or something
+ that quits), the function responds `Please answer y or n.', and
+ repeats the request.
+
+ This function does not actually use the minibuffer, since it does
+ not allow editing of the answer. It actually uses the echo area
+ (*note The Echo Area::.), which uses the same screen space as the
+ minibuffer. The cursor moves to the echo area while the question
+ is being asked.
+
+ The answers and their meanings, even `y' and `n', are not
+ hardwired. The keymap `query-replace-map' specifies them. *Note
+ Search and Replace::.
+
+ In the following example, the user first types `q', which is
+ invalid. At the next prompt the user types `y'.
+
+ (y-or-n-p "Do you need a lift? ")
+
+ ;; After evaluation of the preceding expression,
+ ;; the following prompt appears in the echo area:
+
+ ---------- Echo area ----------
+ Do you need a lift? (y or n)
+ ---------- Echo area ----------
+
+ ;; If the user then types `q', the following appears:
+ ---------- Echo area ----------
+ Please answer y or n. Do you need a lift? (y or n)
+ ---------- Echo area ----------
+
+ ;; When the user types a valid answer,
+ ;; it is displayed after the question:
+ ---------- Echo area ----------
+ Do you need a lift? (y or n) y
+ ---------- Echo area ----------
+
+ We show successive lines of echo area messages, but only one
+ actually appears on the screen at a time.
+
+ - Function: yes-or-no-p PROMPT
+ This function asks the user a question, expecting input in the
+ minibuffer. It returns `t' if the user enters `yes', `nil' if the
+ user types `no'. The user must type <RET> to finalize the
+ response. Upper and lower case are equivalent.
+
+ `yes-or-no-p' starts by displaying PROMPT in the echo area,
+ followed by `(yes or no) '. The user must type one of the
+ expected responses; otherwise, the function responds `Please answer
+ yes or no.', waits about two seconds and repeats the request.
+
+ `yes-or-no-p' requires more work from the user than `y-or-n-p' and
+ is appropriate for more crucial decisions.
+
+ Here is an example:
+
+ (yes-or-no-p "Do you really want to remove everything? ")
+
+ ;; After evaluation of the preceding expression,
+ ;; the following prompt appears,
+ ;; with an empty minibuffer:
+
+ ---------- Buffer: minibuffer ----------
+ Do you really want to remove everything? (yes or no)
+ ---------- Buffer: minibuffer ----------
+
+ If the user first types `y <RET>', which is invalid because this
+ function demands the entire word `yes', it responds by displaying
+ these prompts, with a brief pause between them:
+
+ ---------- Buffer: minibuffer ----------
+ Please answer yes or no.
+ Do you really want to remove everything? (yes or no)
+ ---------- Buffer: minibuffer ----------
+
+ - Function: yes-or-no-p-dialog-box PROMPT
+ This function asks the user a "y or n" question with a popup dialog
+ box. It returns `t' if the answer is "yes". PROMPT is the string
+ to display to ask the question.
+
+ The following functions ask a question either in the minibuffer or a
+dialog box, depending on whether the last user event (which presumably
+invoked this command) was a keyboard or mouse event. When XEmacs is
+running on a window system, the functions `y-or-n-p' and `yes-or-no-p'
+are replaced with the following functions, so that menu items bring up
+dialog boxes instead of minibuffer questions.
+
+ - Function: y-or-n-p-maybe-dialog-box PROMPT
+ This function asks user a "y or n" question, using either a dialog
+ box or the minibuffer, as appropriate.
+
+ - Function: yes-or-no-p-maybe-dialog-box PROMPT
+ This function asks user a "yes or no" question, using either a
+ dialog box or the minibuffer, as appropriate.
+
+\1f
+File: lispref.info, Node: Multiple Queries, Next: Minibuffer Misc, Prev: Yes-or-No Queries, Up: Minibuffers
+
+Asking Multiple Y-or-N Questions
+================================
+
+ When you have a series of similar questions to ask, such as "Do you
+want to save this buffer" for each buffer in turn, you should use
+`map-y-or-n-p' to ask the collection of questions, rather than asking
+each question individually. This gives the user certain convenient
+facilities such as the ability to answer the whole series at once.
+
+ - Function: map-y-or-n-p PROMPTER ACTOR LIST &optional HELP
+ ACTION-ALIST
+ This function, new in Emacs 19, asks the user a series of
+ questions, reading a single-character answer in the echo area for
+ each one.
+
+ The value of LIST specifies the objects to ask questions about.
+ It should be either a list of objects or a generator function. If
+ it is a function, it should expect no arguments, and should return
+ either the next object to ask about, or `nil' meaning stop asking
+ questions.
+
+ The argument PROMPTER specifies how to ask each question. If
+ PROMPTER is a string, the question text is computed like this:
+
+ (format PROMPTER OBJECT)
+
+ where OBJECT is the next object to ask about (as obtained from
+ LIST).
+
+ If not a string, PROMPTER should be a function of one argument
+ (the next object to ask about) and should return the question
+ text. If the value is a string, that is the question to ask the
+ user. The function can also return `t' meaning do act on this
+ object (and don't ask the user), or `nil' meaning ignore this
+ object (and don't ask the user).
+
+ The argument ACTOR says how to act on the answers that the user
+ gives. It should be a function of one argument, and it is called
+ with each object that the user says yes for. Its argument is
+ always an object obtained from LIST.
+
+ If the argument HELP is given, it should be a list of this form:
+
+ (SINGULAR PLURAL ACTION)
+
+ where SINGULAR is a string containing a singular noun that
+ describes the objects conceptually being acted on, PLURAL is the
+ corresponding plural noun, and ACTION is a transitive verb
+ describing what ACTOR does.
+
+ If you don't specify HELP, the default is `("object" "objects"
+ "act on")'.
+
+ Each time a question is asked, the user may enter `y', `Y', or
+ <SPC> to act on that object; `n', `N', or <DEL> to skip that
+ object; `!' to act on all following objects; <ESC> or `q' to exit
+ (skip all following objects); `.' (period) to act on the current
+ object and then exit; or `C-h' to get help. These are the same
+ answers that `query-replace' accepts. The keymap
+ `query-replace-map' defines their meaning for `map-y-or-n-p' as
+ well as for `query-replace'; see *Note Search and Replace::.
+
+ You can use ACTION-ALIST to specify additional possible answers
+ and what they mean. It is an alist of elements of the form `(CHAR
+ FUNCTION HELP)', each of which defines one additional answer. In
+ this element, CHAR is a character (the answer); FUNCTION is a
+ function of one argument (an object from LIST); HELP is a string.
+
+ When the user responds with CHAR, `map-y-or-n-p' calls FUNCTION.
+ If it returns non-`nil', the object is considered "acted upon",
+ and `map-y-or-n-p' advances to the next object in LIST. If it
+ returns `nil', the prompt is repeated for the same object.
+
+ If `map-y-or-n-p' is called in a command that was invoked using the
+ mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
+ Info::.) is either `nil' or a list--then it uses a dialog box or
+ pop-up menu to ask the question. In this case, it does not use
+ keyboard input or the echo area. You can force use of the mouse
+ or use of keyboard input by binding `last-nonmenu-event' to a
+ suitable value around the call.
+
+ The return value of `map-y-or-n-p' is the number of objects acted
+ on.
+
+\1f
+File: lispref.info, Node: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
+
+Minibuffer Miscellany
+=====================
+
+ This section describes some basic functions and variables related to
+minibuffers.
+
+ - Command: exit-minibuffer
+ This command exits the active minibuffer. It is normally bound to
+ keys in minibuffer local keymaps.
+
+ - Command: self-insert-and-exit
+ This command exits the active minibuffer after inserting the last
+ character typed on the keyboard (found in `last-command-char';
+ *note Command Loop Info::.).
+
+ - Command: previous-history-element N
+ This command replaces the minibuffer contents with the value of the
+ Nth previous (older) history element.
+
+ - Command: next-history-element N
+ This command replaces the minibuffer contents with the value of the
+ Nth more recent history element.
+
+ - Command: previous-matching-history-element PATTERN
+ This command replaces the minibuffer contents with the value of the
+ previous (older) history element that matches PATTERN (a regular
+ expression).
+
+ - Command: next-matching-history-element PATTERN
+ This command replaces the minibuffer contents with the value of
+ the next (newer) history element that matches PATTERN (a regular
+ expression).
+
+ - Function: minibuffer-prompt
+ This function returns the prompt string of the currently active
+ minibuffer. If no minibuffer is active, it returns `nil'.
+
+ - Function: minibuffer-prompt-width
+ This function returns the display width of the prompt string of the
+ currently active minibuffer. If no minibuffer is active, it
+ returns 0.
+
+ - Variable: minibuffer-setup-hook
+ This is a normal hook that is run whenever the minibuffer is
+ entered. *Note Hooks::.
+
+ - Variable: minibuffer-exit-hook
+ This is a normal hook that is run whenever the minibuffer is
+ exited. *Note Hooks::.
+
+ - Variable: minibuffer-help-form
+ The current value of this variable is used to rebind `help-form'
+ locally inside the minibuffer (*note Help Functions::.).
+
+ - Function: active-minibuffer-window
+ This function returns the currently active minibuffer window, or
+ `nil' if none is currently active.
+
+ - Function: minibuffer-window &optional FRAME
+ This function returns the minibuffer window used for frame FRAME.
+ If FRAME is `nil', that stands for the current frame. Note that
+ the minibuffer window used by a frame need not be part of that
+ frame--a frame that has no minibuffer of its own necessarily uses
+ some other frame's minibuffer window.
+
+ - Function: window-minibuffer-p WINDOW
+ This function returns non-`nil' if WINDOW is a minibuffer window.
+
+ It is not correct to determine whether a given window is a
+minibuffer by comparing it with the result of `(minibuffer-window)',
+because there can be more than one minibuffer window if there is more
+than one frame.
+
+ - Function: minibuffer-window-active-p WINDOW
+ This function returns non-`nil' if WINDOW, assumed to be a
+ minibuffer window, is currently active.
+
+ - Variable: minibuffer-scroll-window
+ If the value of this variable is non-`nil', it should be a window
+ object. When the function `scroll-other-window' is called in the
+ minibuffer, it scrolls this window.
+
+ Finally, some functions and variables deal with recursive minibuffers
+(*note Recursive Editing::.):
+
+ - Function: minibuffer-depth
+ This function returns the current depth of activations of the
+ minibuffer, a nonnegative integer. If no minibuffers are active,
+ it returns zero.
+
+ - User Option: enable-recursive-minibuffers
+ If this variable is non-`nil', you can invoke commands (such as
+ `find-file') that use minibuffers even while in the minibuffer
+ window. Such invocation produces a recursive editing level for a
+ new minibuffer. The outer-level minibuffer is invisible while you
+ are editing the inner one.
+
+ This variable only affects invoking the minibuffer while the
+ minibuffer window is selected. If you switch windows while in the
+ minibuffer, you can always invoke minibuffer commands while some
+ other window is selected.
+
+ In FSF Emacs 19, if a command name has a property
+`enable-recursive-minibuffers' that is non-`nil', then the command can
+use the minibuffer to read arguments even if it is invoked from the
+minibuffer. The minibuffer command `next-matching-history-element'
+(normally `M-s' in the minibuffer) uses this feature.
+
+ This is not implemented in XEmacs because it is a kludge. If you
+want to explicitly set the value of `enable-recursive-minibuffers' in
+this fashion, just use an evaluated interactive spec and bind
+`enable-recursive-minibuffers' while reading from the minibuffer. See
+the definition of `next-matching-history-element' in
+`lisp/prim/minibuf.el'.
+
+\1f
+File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top
+
+Command Loop
+************
+
+ When you run XEmacs, it enters the "editor command loop" almost
+immediately. This loop reads events, executes their definitions, and
+displays the results. In this chapter, we describe how these things
+are done, and the subroutines that allow Lisp programs to do them.
+
+* Menu:
+
+* Command Overview:: How the command loop reads commands.
+* Defining Commands:: Specifying how a function should read arguments.
+* Interactive Call:: Calling a command, so that it will read arguments.
+* Command Loop Info:: Variables set by the command loop for you to examine.
+* Events:: What input looks like when you read it.
+* Reading Input:: How to read input events from the keyboard or mouse.
+* Waiting:: Waiting for user input or elapsed time.
+* Quitting:: How `C-g' works. How to catch or defer quitting.
+* Prefix Command Arguments:: How the commands to set prefix args work.
+* Recursive Editing:: Entering a recursive edit,
+ and why you usually shouldn't.
+* Disabling Commands:: How the command loop handles disabled commands.
+* Command History:: How the command history is set up, and how accessed.
+* Keyboard Macros:: How keyboard macros are implemented.
+
+\1f
+File: lispref.info, Node: Command Overview, Next: Defining Commands, Up: Command Loop
+
+Command Loop Overview
+=====================
+
+ The command loop in XEmacs is a standard event loop, reading events
+one at a time with `next-event' and handling them with
+`dispatch-event'. An event is typically a single user action, such as
+a keypress, mouse movement, or menu selection; but they can also be
+notifications from the window system, informing XEmacs that (for
+example) part of its window was just uncovered and needs to be redrawn.
+*Note Events::. Pending events are held in a first-in, first-out list
+called the "event queue": events are read from the head of the list,
+and newly arriving events are added to the tail. In this way, events
+are always processed in the order in which they arrive.
+
+ `dispatch-event' does most of the work of handling user actions.
+The first thing it must do is put the events together into a key
+sequence, which is a sequence of events that translates into a command.
+It does this by consulting the active keymaps, which specify what the
+valid key sequences are and how to translate them into commands. *Note
+Key Lookup::, for information on how this is done. The result of the
+translation should be a keyboard macro or an interactively callable
+function. If the key is `M-x', then it reads the name of another
+command, which it then calls. This is done by the command
+`execute-extended-command' (*note Interactive Call::.).
+
+ To execute a command requires first reading the arguments for it.
+This is done by calling `command-execute' (*note Interactive Call::.).
+For commands written in Lisp, the `interactive' specification says how
+to read the arguments. This may use the prefix argument (*note Prefix
+Command Arguments::.) or may read with prompting in the minibuffer
+(*note Minibuffers::.). For example, the command `find-file' has an
+`interactive' specification which says to read a file name using the
+minibuffer. The command's function body does not use the minibuffer;
+if you call this command from Lisp code as a function, you must supply
+the file name string as an ordinary Lisp function argument.
+
+ If the command is a string or vector (i.e., a keyboard macro) then
+`execute-kbd-macro' is used to execute it. You can call this function
+yourself (*note Keyboard Macros::.).
+
+ To terminate the execution of a running command, type `C-g'. This
+character causes "quitting" (*note Quitting::.).
+
+ - Variable: pre-command-hook
+ The editor command loop runs this normal hook before each command.
+ At that time, `this-command' contains the command that is about to
+ run, and `last-command' describes the previous command. *Note
+ Hooks::.
+
+ - Variable: post-command-hook
+ The editor command loop runs this normal hook after each command.
+ (In FSF Emacs, it is also run when the command loop is entered, or
+ reentered after an error or quit.) At that time, `this-command'
+ describes the command that just ran, and `last-command' describes
+ the command before that. *Note Hooks::.
+
+ Quitting is suppressed while running `pre-command-hook' and
+`post-command-hook'. If an error happens while executing one of these
+hooks, it terminates execution of the hook, but that is all it does.
+
+\1f
+File: lispref.info, Node: Defining Commands, Next: Interactive Call, Prev: Command Overview, Up: Command Loop
+
+Defining Commands
+=================
+
+ A Lisp function becomes a command when its body contains, at top
+level, a form that calls the special form `interactive'. This form
+does nothing when actually executed, but its presence serves as a flag
+to indicate that interactive calling is permitted. Its argument
+controls the reading of arguments for an interactive call.
+
+* Menu:
+
+* Using Interactive:: General rules for `interactive'.
+* Interactive Codes:: The standard letter-codes for reading arguments
+ in various ways.
+* Interactive Examples:: Examples of how to read interactive arguments.
+
+\1f
+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.
+
+\1f
+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. <TAB>, <SPC>, and <RET> 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
+ <LFD> or <RET>. (`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
+ <LFD> or <RET>. 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.
+
+\1f
+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
+
+\1f
+File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
+
+Interactive Call
+================
+
+ After the command loop has translated a key sequence into a
+definition, it invokes that definition using the function
+`command-execute'. If the definition is a function that is a command,
+`command-execute' calls `call-interactively', which reads the arguments
+and calls the command. You can also call these functions yourself.
+
+ - Function: commandp OBJECT
+ Returns `t' if OBJECT is suitable for calling interactively; that
+ is, if OBJECT is a command. Otherwise, returns `nil'.
+
+ The interactively callable objects include strings and vectors
+ (treated as keyboard macros), lambda expressions that contain a
+ top-level call to `interactive', compiled-function objects made
+ from such lambda expressions, autoload objects that are declared
+ as interactive (non-`nil' fourth argument to `autoload'), and some
+ of the primitive functions.
+
+ A symbol is `commandp' if its function definition is `commandp'.
+
+ Keys and keymaps are not commands. Rather, they are used to look
+ up commands (*note Keymaps::.).
+
+ See `documentation' in *Note Accessing Documentation::, for a
+ realistic example of using `commandp'.
+
+ - Function: call-interactively COMMAND &optional RECORD-FLAG
+ This function calls the interactively callable function COMMAND,
+ reading arguments according to its interactive calling
+ specifications. An error is signaled if COMMAND is not a function
+ or if it cannot be called interactively (i.e., is not a command).
+ Note that keyboard macros (strings and vectors) are not accepted,
+ even though they are considered commands, because they are not
+ functions.
+
+ If RECORD-FLAG is the symbol `lambda', the interactive calling
+ arguments for `command' are read and returned as a list, but the
+ function is not called on them.
+
+ If RECORD-FLAG is `t', then this command and its arguments are
+ unconditionally added to the list `command-history'. Otherwise,
+ the command is added only if it uses the minibuffer to read an
+ argument. *Note Command History::.
+
+ - Function: command-execute COMMAND &optional RECORD-FLAG
+ This function executes COMMAND as an editing command. The
+ argument COMMAND must satisfy the `commandp' predicate; i.e., it
+ must be an interactively callable function or a keyboard macro.
+
+ A string or vector as COMMAND is executed with
+ `execute-kbd-macro'. A function is passed to
+ `call-interactively', along with the optional RECORD-FLAG.
+
+ A symbol is handled by using its function definition in its place.
+ A symbol with an `autoload' definition counts as a command if it
+ was declared to stand for an interactively callable function.
+ Such a definition is handled by loading the specified library and
+ then rechecking the definition of the symbol.
+
+ - Command: execute-extended-command PREFIX-ARGUMENT
+ This function reads a command name from the minibuffer using
+ `completing-read' (*note Completion::.). Then it uses
+ `command-execute' to call the specified command. Whatever that
+ command returns becomes the value of `execute-extended-command'.
+
+ If the command asks for a prefix argument, it receives the value
+ PREFIX-ARGUMENT. If `execute-extended-command' is called
+ interactively, the current raw prefix argument is used for
+ PREFIX-ARGUMENT, and thus passed on to whatever command is run.
+
+ `execute-extended-command' is the normal definition of `M-x', so
+ it uses the string `M-x ' as a prompt. (It would be better to
+ take the prompt from the events used to invoke
+ `execute-extended-command', but that is painful to implement.) A
+ description of the value of the prefix argument, if any, also
+ becomes part of the prompt.
+
+ (execute-extended-command 1)
+ ---------- Buffer: Minibuffer ----------
+ 1 M-x forward-word RET
+ ---------- Buffer: Minibuffer ----------
+ => t
+
+ - Function: interactive-p
+ This function returns `t' if the containing function (the one that
+ called `interactive-p') was called interactively, with the function
+ `call-interactively'. (It makes no difference whether
+ `call-interactively' was called from Lisp or directly from the
+ editor command loop.) If the containing function was called by
+ Lisp evaluation (or with `apply' or `funcall'), then it was not
+ called interactively.
+
+ The most common use of `interactive-p' is for deciding whether to
+ print an informative message. As a special exception,
+ `interactive-p' returns `nil' whenever a keyboard macro is being
+ run. This is to suppress the informative messages and speed
+ execution of the macro.
+
+ For example:
+
+ (defun foo ()
+ (interactive)
+ (and (interactive-p)
+ (message "foo")))
+ => foo
+
+ (defun bar ()
+ (interactive)
+ (setq foobar (list (foo) (interactive-p))))
+ => bar
+
+ ;; Type `M-x foo'.
+ -| foo
+
+ ;; Type `M-x bar'.
+ ;; This does not print anything.
+
+ foobar
+ => (nil t)
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
+
+Information from the Command Loop
+=================================
+
+ The editor command loop sets several Lisp variables to keep status
+records for itself and for commands that are run.
+
+ - Variable: last-command
+ This variable records the name of the previous command executed by
+ the command loop (the one before the current command). Normally
+ the value is a symbol with a function definition, but this is not
+ guaranteed.
+
+ The value is copied from `this-command' when a command returns to
+ the command loop, except when the command specifies a prefix
+ argument for the following command.
+
+ - Variable: this-command
+ This variable records the name of the command now being executed by
+ the editor command loop. Like `last-command', it is normally a
+ symbol with a function definition.
+
+ The command loop sets this variable just before running a command,
+ and copies its value into `last-command' when the command finishes
+ (unless the command specifies a prefix argument for the following
+ command).
+
+ Some commands set this variable during their execution, as a flag
+ for whatever command runs next. In particular, the functions for
+ killing text set `this-command' to `kill-region' so that any kill
+ commands immediately following will know to append the killed text
+ to the previous kill.
+
+ If you do not want a particular command to be recognized as the
+previous command in the case where it got an error, you must code that
+command to prevent this. One way is to set `this-command' to `t' at the
+beginning of the command, and set `this-command' back to its proper
+value at the end, like this:
+
+ (defun foo (args...)
+ (interactive ...)
+ (let ((old-this-command this-command))
+ (setq this-command t)
+ ...do the work...
+ (setq this-command old-this-command)))
+
+ - Function: this-command-keys
+ This function returns a vector containing the key and mouse events
+ that invoked the present command, plus any previous commands that
+ generated the prefix argument for this command. (Note: this is not
+ the same as in FSF Emacs, which can return a string.) *Note
+ Events::.
+
+ This function copies the vector and the events; it is safe to keep
+ and modify them.
+
+ (this-command-keys)
+ ;; Now use `C-u C-x C-e' to evaluate that.
+ => [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
+
+ - Variable: last-command-event
+ This variable is set to the last input event that was read by the
+ command loop as part of a command. The principal use of this
+ variable is in `self-insert-command', which uses it to decide which
+ character to insert.
+
+ 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-command-char' in FSF
+ Emacs.
+
+ last-command-event
+ ;; Now type `C-u C-x C-e'.
+ => #<keypress-event control-E>
+
+ - Variable: last-command-char
+ If the value of `last-command-event' is a keyboard event, then this
+ is the nearest character equivalent to it (or `nil' if there is no
+ character equivalent). `last-command-char' is the character that
+ `self-insert-command' will insert in the buffer. Remember that
+ there is *not* a one-to-one mapping between keyboard events and
+ XEmacs characters: many keyboard events have no corresponding
+ character, and when the Mule feature is available, most characters
+ can not be input on standard keyboards, except possibly with help
+ from an input method. 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 variable exists for compatibility with Emacs version 18.
+
+ last-command-char
+ ;; Now use `C-u C-x C-e' to evaluate that.
+ => ?\^E
+
+
+ - Variable: current-mouse-event
+ This variable holds the mouse-button event which invoked this
+ command, or `nil'. This is what `(interactive "e")' returns.
+
+ - Variable: echo-keystrokes
+ This variable determines how much time should elapse before command
+ characters echo. Its value must be an integer, which specifies the
+ number of seconds to wait before echoing. If the user types a
+ prefix key (say `C-x') and then delays this many seconds before
+ continuing, the key `C-x' is echoed in the echo area. Any
+ subsequent characters in the same command will be echoed as well.
+
+ If the value is zero, then command input is not echoed.
+
+\1f
+File: lispref.info, Node: Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop
+
+Events
+======
+
+ The XEmacs command loop reads a sequence of "events" that represent
+keyboard or mouse activity. Unlike in Emacs 18 and in FSF Emacs,
+events are a primitive Lisp type that must be manipulated using their
+own accessor and settor primitives. This section describes the
+representation and meaning of input events in detail.
+
+ A key sequence that starts with a mouse event is read using the
+keymaps of the buffer in the window that the mouse was in, not the
+current buffer. This does not imply that clicking in a window selects
+that window or its buffer--that is entirely under the control of the
+command binding of the key sequence.
+
+ For information about how exactly the XEmacs command loop works,
+*Note Reading Input::.
+
+ - Function: eventp OBJECT
+ This function returns non-`nil' if EVENT is an input event.
+
+* Menu:
+
+* Event Types:: Events come in different types.
+* Event Contents:: What the contents of each event type are.
+* Event Predicates:: Querying whether an event is of a
+ particular type.
+* Accessing Mouse Event Positions::
+ Determining where a mouse event occurred,
+ and over what.
+* Accessing Other Event Info:: Accessing non-positional event info.
+* Working With Events:: Creating, copying, and destroying events.
+* Converting Events:: Converting between events, keys, and
+ characters.
+
+\1f
+File: lispref.info, Node: Event Types, Next: Event Contents, Up: Events
+
+Event Types
+-----------
+
+ Events represent keyboard or mouse activity or status changes of
+various sorts, such as process input being available or a timeout being
+triggered. The different event types are as follows:
+
+key-press event
+ A key was pressed. Note that modifier keys such as "control",
+ "shift", and "alt" do not generate events; instead, they are
+ tracked internally by XEmacs, and non-modifier key presses
+ generate events that specify both the key pressed and the
+ modifiers that were held down at the time.
+
+button-press event
+button-release event
+ A button was pressed or released. Along with the button that was
+ pressed or released, button events specify the modifier keys that
+ were held down at the time and the position of the pointer at the
+ time.
+
+motion event
+ The pointer was moved. Along with the position of the pointer,
+ these events also specify the modifier keys that were held down at
+ the time.
+
+misc-user event
+ A menu item was selected, the scrollbar was used, or a drag or a
+ drop occurred.
+
+process event
+ Input is available on a process.
+
+timeout event
+ A timeout has triggered.
+
+magic event
+ Some window-system-specific action (such as a frame being resized
+ or a portion of a frame needing to be redrawn) has occurred. The
+ contents of this event are not accessible at the E-Lisp level, but
+ `dispatch-event' knows what to do with an event of this type.
+
+eval event
+ This is a special kind of event specifying that a particular
+ function needs to be called when this event is dispatched. An
+ event of this type is sometimes placed in the event queue when a
+ magic event is processed. This kind of event should generally
+ just be passed off to `dispatch-event'. *Note Dispatching an
+ Event::.
+
+\1f
+File: lispref.info, Node: Event Contents, Next: Event Predicates, Prev: Event Types, Up: Events
+
+Contents of the Different Types of Events
+-----------------------------------------
+
+ Every event, no matter what type it is, contains a timestamp (which
+is typically an offset in milliseconds from when the X server was
+started) indicating when the event occurred. In addition, many events
+contain a "channel", which specifies which frame the event occurred on,
+and/or a value indicating which modifier keys (shift, control, etc.)
+were held down at the time of the event.
+
+ The contents of each event are as follows:
+
+key-press event
+
+ channel
+
+ timestamp
+
+ key
+ Which key was pressed. This is an integer (in the printing
+ ASCII range: >32 and <127) or a symbol such as `left' or
+ `right'. Note that many physical keys are actually treated
+ as two separate keys, depending on whether the shift key is
+ pressed; for example, the "a" key is treated as either "a" or
+ "A" depending on the state of the shift key, and the "1" key
+ is similarly treated as either "1" or "!" on most keyboards.
+ In such cases, the shift key does not show up in the modifier
+ list. For other keys, such as `backspace', the shift key
+ shows up as a regular modifier.
+
+ modifiers
+ Which modifier keys were pressed. As mentioned above, the
+ shift key is not treated as a modifier for many keys and will
+ not show up in this list in such cases.
+
+button-press event
+button-release event
+
+ channel
+
+ timestamp
+
+ button
+ What button went down or up. Buttons are numbered starting
+ at 1.
+
+ modifiers
+ Which modifier keys were pressed. The special business
+ mentioned above for the shift key does *not* apply to mouse
+ events.
+
+ x
+ y
+ The position of the pointer (in pixels) at the time of the
+ event.
+
+pointer-motion event
+
+ channel
+
+ timestamp
+
+ x
+ y
+ The position of the pointer (in pixels) after it moved.
+
+ modifiers
+ Which modifier keys were pressed. The special business
+ mentioned above for the shift key does *not* apply to mouse
+ events.
+
+misc-user event
+
+ timestamp
+
+ function
+ The E-Lisp function to call for this event. This is normally
+ either `eval' or `call-interactively'.
+
+ object
+ The object to pass to the function. This is normally the
+ callback that was specified in the menu description.
+
+ button
+ What button went down or up. Buttons are numbered starting
+ at 1.
+
+ modifiers
+ Which modifier keys were pressed. The special business
+ mentioned above for the shift key does *not* apply to mouse
+ events.
+
+ x
+ y
+ The position of the pointer (in pixels) at the time of the
+ event.
+
+process_event
+
+ timestamp
+
+ process
+ The Emacs "process" object in question.
+
+timeout event
+
+ timestamp
+
+ function
+ The E-Lisp function to call for this timeout. It is called
+ with one argument, the event.
+
+ object
+ Some Lisp object associated with this timeout, to make it
+ easier to tell them apart. The function and object for this
+ event were specified when the timeout was set.
+
+magic event
+
+ timestamp
+ (The rest of the information in this event is not user-accessible.)
+
+eval event
+
+ timestamp
+
+ function
+ An E-Lisp function to call when this event is dispatched.
+
+ object
+ The object to pass to the function. The function and object
+ are set when the event is created.
+
+ - Function: event-type EVENT
+ Return the type of EVENT.
+
+ This will be a symbol; one of
+
+ `key-press'
+ A key was pressed.
+
+ `button-press'
+ A mouse button was pressed.
+
+ `button-release'
+ A mouse button was released.
+
+ `motion'
+ The mouse moved.
+
+ `misc-user'
+ Some other user action happened; typically, this is a menu
+ selection, scrollbar action, or drag and drop action.
+
+ `process'
+ Input is available from a subprocess.
+
+ `timeout'
+ A timeout has expired.
+
+ `eval'
+ This causes a specified action to occur when dispatched.
+
+ `magic'
+ Some window-system-specific event has occurred.
+
+\1f
+File: lispref.info, Node: Event Predicates, Next: Accessing Mouse Event Positions, Prev: Event Contents, Up: Events
+
+Event Predicates
+----------------
+
+ The following predicates return whether an object is an event of a
+particular type.
+
+ - Function: key-press-event-p OBJECT
+ This is true if OBJECT is a key-press event.
+
+ - Function: button-event-p OBJECT OBJECT
+ This is true if OBJECT is a mouse button-press or button-release
+ event.
+
+ - Function: button-press-event-p OBJECT
+ This is true if OBJECT is a mouse button-press event.
+
+ - Function: button-release-event-p OBJECT
+ This is true if OBJECT is a mouse button-release event.
+
+ - Function: motion-event-p OBJECT
+ This is true if OBJECT is a mouse motion event.
+
+ - Function: mouse-event-p OBJECT
+ This is true if OBJECT is a mouse button-press, button-release or
+ motion event.
+
+ - Function: eval-event-p OBJECT
+ This is true if OBJECT is an eval event.
+
+ - Function: misc-user-event-p OBJECT
+ This is true if OBJECT is a misc-user event.
+
+ - Function: process-event-p OBJECT
+ This is true if OBJECT is a process event.
+
+ - Function: timeout-event-p OBJECT
+ This is true if OBJECT is a timeout event.
+
+ - Function: event-live-p OBJECT
+ This is true if OBJECT is any event that has not been deallocated.
+
+\1f
+File: lispref.info, Node: Accessing Mouse Event Positions, Next: Accessing Other Event Info, Prev: Event Predicates, Up: Events
+
+Accessing the Position of a Mouse Event
+---------------------------------------
+
+ Unlike other events, mouse events (i.e. motion, button-press,
+button-release, and drag or drop type misc-user events) occur in a
+particular location on the screen. Many primitives are provided for
+determining exactly where the event occurred and what is under that
+location.
+
+* Menu:
+
+* Frame-Level Event Position Info::
+* Window-Level Event Position Info::
+* Event Text Position Info::
+* Event Glyph Position Info::
+* Event Toolbar Position Info::
+* Other Event Position Info::
+
+\1f
+File: lispref.info, Node: Frame-Level Event Position Info, Next: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
+
+Frame-Level Event Position Info
+...............................
+
+ The following functions return frame-level information about where a
+mouse event occurred.
+
+ - Function: event-frame EVENT
+ This function returns the "channel" or frame that the given mouse
+ motion, button press, button release, or misc-user event occurred
+ in. This will be `nil' for non-mouse events.
+
+ - Function: event-x-pixel EVENT
+ This function returns the X position in pixels of the given mouse
+ event. The value returned is relative to the frame the event
+ occurred in. This will signal an error if the event is not a
+ mouse event.
+
+ - Function: event-y-pixel EVENT
+ This function returns the Y position in pixels of the given mouse
+ event. The value returned is relative to the frame the event
+ occurred in. This will signal an error if the event is not a
+ mouse event.
+
+\1f
+File: lispref.info, Node: Window-Level Event Position Info, Next: Event Text Position Info, Prev: Frame-Level Event Position Info, Up: Accessing Mouse Event Positions
+
+Window-Level Event Position Info
+................................
+
+ The following functions return window-level information about where
+a mouse event occurred.
+
+ - Function: event-window EVENT
+ Given a mouse motion, button press, button release, or misc-user
+ event, compute and return the window on which that event occurred.
+ This may be `nil' if the event occurred in the border or over a
+ toolbar. The modeline is considered to be within the window it
+ describes.
+
+ - Function: event-buffer EVENT
+ Given a mouse motion, button press, button release, or misc-user
+ event, compute and return the buffer of the window on which that
+ event occurred. This may be `nil' if the event occurred in the
+ border or over a toolbar. The modeline is considered to be within
+ the window it describes. This is equivalent to calling
+ `event-window' and then calling `window-buffer' on the result if
+ it is a window.
+
+ - Function: event-window-x-pixel EVENT
+ This function returns the X position in pixels of the given mouse
+ event. The value returned is relative to the window the event
+ occurred in. This will signal an error if the event is not a
+ mouse-motion, button-press, button-release, or misc-user event.
+
+ - Function: event-window-y-pixel EVENT
+ This function returns the Y position in pixels of the given mouse
+ event. The value returned is relative to the window the event
+ occurred in. This will signal an error if the event is not a
+ mouse-motion, button-press, button-release, or misc-user event.
+
+\1f
+File: lispref.info, Node: Event Text Position Info, Next: Event Glyph Position Info, Prev: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
+
+Event Text Position Info
+........................
+
+ The following functions return information about the text (including
+the modeline) that a mouse event occurred over or near.
+
+ - Function: event-over-text-area-p EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event, this function returns `t' if the event is over the text
+ area of a window. Otherwise, `nil' is returned. The modeline is
+ not considered to be part of the text area.
+
+ - Function: event-over-modeline-p EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event, this function returns `t' if the event is over the modeline
+ of a window. Otherwise, `nil' is returned.
+
+ - Function: event-x EVENT
+ This function returns the X position of the given mouse-motion,
+ button-press, button-release, or misc-user event in characters.
+ This is relative to the window the event occurred over.
+
+ - Function: event-y EVENT
+ This function returns the Y position of the given mouse-motion,
+ button-press, button-release, or misc-user event in characters.
+ This is relative to the window the event occurred over.
+
+ - Function: event-point EVENT
+ This function returns the character position of the given
+ mouse-motion, button-press, button-release, or misc-user event.
+ If the event did not occur over a window, or did not occur over
+ text, then this returns `nil'. Otherwise, it returns an index
+ into the buffer visible in the event's window.
+
+ - Function: event-closest-point EVENT
+ This function returns the character position of the given
+ mouse-motion, button-press, button-release, or misc-user event.
+ If the event did not occur over a window or over text, it returns
+ the closest point to the location of the event. If the Y pixel
+ position overlaps a window and the X pixel position is to the left
+ of that window, the closest point is the beginning of the line
+ containing the Y position. If the Y pixel position overlaps a
+ window and the X pixel position is to the right of that window,
+ the closest point is the end of the line containing the Y
+ position. If the Y pixel position is above a window, 0 is
+ returned. If it is below a window, the value of `(window-end)' is
+ returned.
+
+\1f
+File: lispref.info, Node: Event Glyph Position Info, Next: Event Toolbar Position Info, Prev: Event Text Position Info, Up: Accessing Mouse Event Positions
+
+Event Glyph Position Info
+.........................
+
+ The following functions return information about the glyph (if any)
+that a mouse event occurred over.
+
+ - Function: event-over-glyph-p EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event, this function returns `t' if the event is over a glyph.
+ Otherwise, `nil' is returned.
+
+ - Function: event-glyph-extent EVENT
+ If the given mouse-motion, button-press, button-release, or
+ misc-user event happened on top of a glyph, this returns its
+ extent; else `nil' is returned.
+
+ - Function: event-glyph-x-pixel EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event over a glyph, this function returns the X position of the
+ pointer relative to the upper left of the glyph. If the event is
+ not over a glyph, it returns `nil'.
+
+ - Function: event-glyph-y-pixel EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event over a glyph, this function returns the Y position of the
+ pointer relative to the upper left of the glyph. If the event is
+ not over a glyph, it returns `nil'.
+
+\1f
+File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Position Info, Prev: Event Glyph Position Info, Up: Accessing Mouse Event Positions
+
+Event Toolbar Position Info
+...........................
+
+ - Function: event-over-toolbar-p EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event, this function returns `t' if the event is over a toolbar.
+ Otherwise, `nil' is returned.
+
+ - Function: event-toolbar-button EVENT
+ If the given mouse-motion, button-press, button-release, or
+ misc-user event happened on top of a toolbar button, this function
+ returns the button. Otherwise, `nil' is returned.
+
+\1f
+File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Position Info, Up: Accessing Mouse Event Positions
+
+Other Event Position Info
+.........................
+
+ - Function: event-over-border-p EVENT
+ Given a mouse-motion, button-press, button-release, or misc-user
+ event, this function returns `t' if the event is over an internal
+ toolbar. Otherwise, `nil' is returned.
+
+\1f
+File: lispref.info, Node: Accessing Other Event Info, Next: Working With Events, Prev: Accessing Mouse Event Positions, Up: Events
+
+Accessing the Other Contents of Events
+--------------------------------------
+
+ The following functions allow access to the contents of events other
+than the position info described in the previous section.
+
+ - Function: event-timestamp EVENT
+ This function returns the timestamp of the given event object.
+
+ - Function: event-device EVENT
+ This function returns the device that the given event occurred on.
+
+ - Function: event-key EVENT
+ This function returns the Keysym of the given key-press event.
+ This will be the ASCII code of a printing character, or a symbol.
+
+ - Function: event-button EVENT
+ This function returns the button-number of the given button-press
+ or button-release event.
+
+ - Function: event-modifiers EVENT
+ This function returns a list of symbols, the names of the modifier
+ keys which were down when the given mouse or keyboard event was
+ produced.
+
+ - Function: event-modifier-bits EVENT
+ This function returns a number representing the modifier keys
+ which were down when the given mouse or keyboard event was
+ produced.
+
+ - Function: event-function EVENT
+ This function returns the callback function of the given timeout,
+ misc-user, or eval event.
+
+ - Function: event-object EVENT
+ This function returns the callback function argument of the given
+ timeout, misc-user, or eval event.
+
+ - Function: event-process EVENT
+ This function returns the process of the given process event.
+
+\1f
+File: lispref.info, Node: Working With Events, Next: Converting Events, Prev: Accessing Other Event Info, Up: Events
+
+Working With Events
+-------------------
+
+ XEmacs provides primitives for creating, copying, and destroying
+event objects. Many functions that return events take an event object
+as an argument and fill in the fields of this event; or they make accept
+either an event object or `nil', creating the event object first in the
+latter case.
+
+ - Function: make-event &optional TYPE PLIST
+ This function creates a new event structure. If no arguments are
+ specified, the created event will be empty. To specify the event
+ type, use the TYPE argument. The allowed types are `empty',
+ `key-press', `button-press', `button-release', `motion', or
+ `misc-user'.
+
+ PLIST is a property list, the properties being compatible to those
+ returned by `event-properties'. For events other than `empty', it
+ is mandatory to specify certain properties. For `empty' events,
+ PLIST must be `nil'. The list is "canonicalized", which means
+ that if a property keyword is present more than once, only the
+ first instance is taken into account. Specifying an unknown or
+ illegal property signals an error.
+
+ The following properties are allowed:
+
+ `channel'
+ The event channel. This is a frame or a console. For mouse
+ events (of type `button-press', `button-release' and
+ `motion'), this must be a frame. For key-press events, it
+ must be a console. If channel is unspecified by PLIST, it
+ will be set to the selected frame or selected console, as
+ appropriate.
+
+ `key'
+ The event key. This is either a symbol or a character. It
+ is allowed (and required) only for key-press events.
+
+ `button'
+ The event button. This an integer, either 1, 2 or 3. It is
+ allowed only for button-press and button-release events.
+
+ `modifiers'
+ The event modifiers. This is a list of modifier symbols. It
+ is allowed for key-press, button-press, button-release and
+ motion events.
+
+ `x'
+ The event X coordinate. This is an integer. It is relative
+ to the channel's root window, and is allowed for
+ button-press, button-release and motion events.
+
+ `y'
+ The event Y coordinate. This is an integer. It is relative
+ to the channel's root window, and is allowed for
+ button-press, button-release and motion events. This means
+ that, for instance, to access the toolbar, the `y' property
+ will have to be negative.
+
+ `timestamp'
+ The event timestamp, a non-negative integer. Allowed for all
+ types of events.
+
+ *WARNING*: the event object returned by this function may be a
+ reused one; see the function `deallocate-event'.
+
+ The events created by `make-event' can be used as non-interactive
+ arguments to the functions with an `(interactive "e")'
+ specification.
+
+ Here are some basic examples of usage:
+
+ ;; Create an empty event.
+ (make-event)
+ => #<empty-event>
+
+ ;; Try creating a key-press event.
+ (make-event 'key-press)
+ error--> Undefined key for keypress event
+
+ ;; Creating a key-press event, try 2
+ (make-event 'key-press '(key home))
+ => #<keypress-event home>
+
+ ;; Create a key-press event of dubious fame.
+ (make-event 'key-press '(key escape modifiers (meta alt control shift)))
+ => #<keypress-event control-meta-alt-shift-escape>
+
+ ;; Create a M-button1 event at coordinates defined by variables
+ ;; X and Y.
+ (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
+ => #<buttondown-event meta-button1>
+
+ ;; Create a similar button-release event.
+ (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
+ => #<buttonup-event meta-button1up>
+
+ ;; Create a mouse-motion event.
+ (make-event 'motion '(x 20 y 30))
+ => #<motion-event 20, 30>
+
+ (event-properties (make-event 'motion '(x 20 y 30)))
+ => (channel #<x-frame "emacs" 0x8e2> x 20 y 30
+ modifiers nil timestamp 0)
+
+ In conjunction with `event-properties', you can use `make-event'
+ to create modified copies of existing events. For instance, the
+ following code will return an `equal' copy of EVENT:
+
+ (make-event (event-type EVENT)
+ (event-properties EVENT))
+
+ Note, however, that you cannot use `make-event' as the generic
+ replacement for `copy-event', because it does not allow creating
+ all of the event types.
+
+ To create a modified copy of an event, you can use the
+ canonicalization feature of PLIST. The following example creates
+ a copy of EVENT, but with `modifiers' reset to `nil'.
+
+ (make-event (event-type EVENT)
+ (append '(modifiers nil)
+ (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.
+
+ - Function: deallocate-event EVENT
+ This function allows the given event structure to be reused. You
+ *MUST NOT* use this event object after calling this function with
+ 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.
+
+\1f
+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 <Tab>, not the distinct character
+ <Control-I>.
+
+ 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 <control> and
+ <meta>, and will ignore the <shift> modifier on those characters
+ which have no shifted ASCII equivalent (<Control-Shift-A> for
+ example, will be mapped to the same ASCII code as <Control-A>).
+
+ If ALLOW-META is non-`nil', then the <Meta> modifier will be
+ represented by turning on the high bit of the byte returned;
+ otherwise, `nil' will be returned for events containing the <Meta>
+ 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; <M-x> and <oslash> 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.
+
+\1f
+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.
+
+\1f
+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 ----------
+
+ => [#<keypress-event control-X> #<keypress-event control-F>]
+
+ 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.
+
+\1f
+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)
+ => #<keypress-event right>
+
+ - 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.
+
+\1f
+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).
+
+\1f
+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
+
+\1f
+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)
+ -| #<keypress-event 1>
+ -| #<keypress-event control-E>
+ => #<keypress-event 1>
+
+ - 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
+
+\1f
+File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
+
+Waiting for Elapsed Time or Input
+=================================
+
+ The wait functions are designed to wait for a certain amount of time
+to pass or until there is input. For example, you may wish to pause in
+the middle of a computation to allow the user time to view the display.
+`sit-for' pauses and updates the screen, and returns immediately if
+input comes in, while `sleep-for' pauses without updating the screen.
+
+ Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
+two arguments to specify the time (one integer and one float value),
+instead of a single argument that can be either an integer or a float.
+
+ - Function: sit-for SECONDS &optional NODISP
+ This function performs redisplay (provided there is no pending
+ input from the user), then waits SECONDS seconds, or until input is
+ available. The result is `t' if `sit-for' waited the full time
+ with no input arriving (see `input-pending-p' in *Note Peeking and
+ Discarding::). Otherwise, the value is `nil'.
+
+ The argument SECONDS need not be an integer. If it is a floating
+ point number, `sit-for' waits for a fractional number of seconds.
+
+ Redisplay is normally preempted if input arrives, and does not
+ happen at all if input is available before it starts. (You can
+ force screen updating in such a case by using `force-redisplay'.
+ *Note Refresh Screen::.) If there is no input pending, you can
+ force an update with no delay by using `(sit-for 0)'.
+
+ If NODISP is non-`nil', then `sit-for' does not redisplay, but it
+ still returns as soon as input is available (or when the timeout
+ elapses).
+
+ The usual purpose of `sit-for' is to give the user time to read
+ text that you display.
+
+ - Function: sleep-for SECONDS
+ This function simply pauses for SECONDS seconds without updating
+ the display. This function pays no attention to available input.
+ It returns `nil'.
+
+ The argument SECONDS need not be an integer. If it is a floating
+ point number, `sleep-for' waits for a fractional number of seconds.
+
+ Use `sleep-for' when you wish to guarantee a delay.
+
+ *Note Time of Day::, for functions to get the current time.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop
+
+Quitting
+========
+
+ Typing `C-g' while a Lisp function is running causes XEmacs to
+"quit" whatever it is doing. This means that control returns to the
+innermost active command loop.
+
+ Typing `C-g' while the command loop is waiting for keyboard input
+does not cause a quit; it acts as an ordinary input character. In the
+simplest case, you cannot tell the difference, because `C-g' normally
+runs the command `keyboard-quit', whose effect is to quit. However,
+when `C-g' follows a prefix key, the result is an undefined key. The
+effect is to cancel the prefix key as well as any prefix argument.
+
+ In the minibuffer, `C-g' has a different definition: it aborts out
+of the minibuffer. This means, in effect, that it exits the minibuffer
+and then quits. (Simply quitting would return to the command loop
+*within* the minibuffer.) The reason why `C-g' does not quit directly
+when the command reader is reading input is so that its meaning can be
+redefined in the minibuffer in this way. `C-g' following a prefix key
+is not redefined in the minibuffer, and it has its normal effect of
+canceling the prefix key and prefix argument. This too would not be
+possible if `C-g' always quit directly.
+
+ When `C-g' does directly quit, it does so by setting the variable
+`quit-flag' to `t'. XEmacs checks this variable at appropriate times
+and quits if it is not `nil'. Setting `quit-flag' non-`nil' in any way
+thus causes a quit.
+
+ At the level of C code, quitting cannot happen just anywhere; only
+at the special places that check `quit-flag'. The reason for this is
+that quitting at other places might leave an inconsistency in XEmacs's
+internal state. Because quitting is delayed until a safe place,
+quitting cannot make XEmacs crash.
+
+ Certain functions such as `read-key-sequence' or `read-quoted-char'
+prevent quitting entirely even though they wait for input. Instead of
+quitting, `C-g' serves as the requested input. In the case of
+`read-key-sequence', this serves to bring about the special behavior of
+`C-g' in the command loop. In the case of `read-quoted-char', this is
+so that `C-q' can be used to quote a `C-g'.
+
+ You can prevent quitting for a portion of a Lisp function by binding
+the variable `inhibit-quit' to a non-`nil' value. Then, although `C-g'
+still sets `quit-flag' to `t' as usual, the usual result of this--a
+quit--is prevented. Eventually, `inhibit-quit' will become `nil'
+again, such as when its binding is unwound at the end of a `let' form.
+At that time, if `quit-flag' is still non-`nil', the requested quit
+happens immediately. This behavior is ideal when you wish to make sure
+that quitting does not happen within a "critical section" of the
+program.
+
+ In some functions (such as `read-quoted-char'), `C-g' is handled in
+a special way that does not involve quitting. This is done by reading
+the input with `inhibit-quit' bound to `t', and setting `quit-flag' to
+`nil' before `inhibit-quit' becomes `nil' again. This excerpt from the
+definition of `read-quoted-char' shows how this is done; it also shows
+that normal quitting is permitted after the first character of input.
+
+ (defun read-quoted-char (&optional prompt)
+ "...DOCUMENTATION..."
+ (let ((count 0) (code 0) char)
+ (while (< count 3)
+ (let ((inhibit-quit (zerop count))
+ (help-form nil))
+ (and prompt (message "%s-" prompt))
+ (setq char (read-char))
+ (if inhibit-quit (setq quit-flag nil)))
+ ...)
+ (logand 255 code)))
+
+ - Variable: quit-flag
+ If this variable is non-`nil', then XEmacs quits immediately,
+ unless `inhibit-quit' is non-`nil'. Typing `C-g' ordinarily sets
+ `quit-flag' non-`nil', regardless of `inhibit-quit'.
+
+ - Variable: inhibit-quit
+ This variable determines whether XEmacs should quit when
+ `quit-flag' is set to a value other than `nil'. If `inhibit-quit'
+ is non-`nil', then `quit-flag' has no special effect.
+
+ - Command: keyboard-quit
+ This function signals the `quit' condition with `(signal 'quit
+ nil)'. This is the same thing that quitting does. (See `signal'
+ in *Note Errors::.)
+
+ You can specify a character other than `C-g' to use for quitting.
+See the function `set-input-mode' in *Note Terminal Input::.
+
+\1f
+File: lispref.info, Node: Prefix Command Arguments, Next: Recursive Editing, Prev: Quitting, Up: Command Loop
+
+Prefix Command Arguments
+========================
+
+ Most XEmacs commands can use a "prefix argument", a number specified
+before the command itself. (Don't confuse prefix arguments with prefix
+keys.) The prefix argument is at all times represented by a value,
+which may be `nil', meaning there is currently no prefix argument.
+Each command may use the prefix argument or ignore it.
+
+ There are two representations of the prefix argument: "raw" and
+"numeric". The editor command loop uses the raw representation
+internally, and so do the Lisp variables that store the information, but
+commands can request either representation.
+
+ Here are the possible values of a raw prefix argument:
+
+ * `nil', meaning there is no prefix argument. Its numeric value is
+ 1, but numerous commands make a distinction between `nil' and the
+ integer 1.
+
+ * An integer, which stands for itself.
+
+ * A list of one element, which is an integer. This form of prefix
+ argument results from one or a succession of `C-u''s with no
+ digits. The numeric value is the integer in the list, but some
+ commands make a distinction between such a list and an integer
+ alone.
+
+ * The symbol `-'. This indicates that `M--' or `C-u -' was typed,
+ without following digits. The equivalent numeric value is -1, but
+ some commands make a distinction between the integer -1 and the
+ symbol `-'.
+
+ We illustrate these possibilities by calling the following function
+with various prefixes:
+
+ (defun display-prefix (arg)
+ "Display the value of the raw prefix arg."
+ (interactive "P")
+ (message "%s" arg))
+
+Here are the results of calling `display-prefix' with various raw
+prefix arguments:
+
+ M-x display-prefix -| nil
+
+ C-u M-x display-prefix -| (4)
+
+ C-u C-u M-x display-prefix -| (16)
+
+ C-u 3 M-x display-prefix -| 3
+
+ M-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.)
+
+ C-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.)
+
+ C-u - M-x display-prefix -| -
+
+ M-- M-x display-prefix -| - ; (Same as `C-u -'.)
+
+ C-- M-x display-prefix -| - ; (Same as `C-u -'.)
+
+ C-u - 7 M-x display-prefix -| -7
+
+ M-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.)
+
+ C-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.)
+
+ XEmacs uses two variables to store the prefix argument: `prefix-arg'
+and `current-prefix-arg'. Commands such as `universal-argument' that
+set up prefix arguments for other commands store them in `prefix-arg'.
+In contrast, `current-prefix-arg' conveys the prefix argument to the
+current command, so setting it has no effect on the prefix arguments
+for future commands.
+
+ Normally, commands specify which representation to use for the prefix
+argument, either numeric or raw, in the `interactive' declaration.
+(*Note Using Interactive::.) Alternatively, functions may look at the
+value of the prefix argument directly in the variable
+`current-prefix-arg', but this is less clean.
+
+ - Function: prefix-numeric-value ARG
+ This function returns the numeric meaning of a valid raw prefix
+ argument value, ARG. 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
+ returned.
+
+ - Variable: current-prefix-arg
+ This variable holds the raw prefix argument for the *current*
+ command. Commands may examine it directly, but the usual way to
+ access it is with `(interactive "P")'.
+
+ - Variable: prefix-arg
+ The value of this variable is the raw prefix argument for the
+ *next* editing command. Commands that specify prefix arguments for
+ the following command work by setting this variable.
+
+ Do not call the functions `universal-argument', `digit-argument', or
+`negative-argument' unless you intend to let the user enter the prefix
+argument for the *next* command.
+
+ - Command: universal-argument
+ This command reads input and specifies a prefix argument for the
+ following command. Don't call this command yourself unless you
+ know what you are doing.
+
+ - Command: digit-argument ARG
+ This command adds to the prefix argument for the following
+ command. The argument ARG is the raw prefix argument as it was
+ before this command; it is used to compute the updated prefix
+ argument. Don't call this command yourself unless you know what
+ you are doing.
+
+ - Command: negative-argument ARG
+ This command adds to the numeric argument for the next command.
+ The argument ARG is the raw prefix argument as it was before this
+ command; its value is negated to form the new prefix argument.
+ Don't call this command yourself unless you know what you are
+ doing.
+
+\1f
+File: lispref.info, Node: Recursive Editing, Next: Disabling Commands, Prev: Prefix Command Arguments, Up: Command Loop
+
+Recursive Editing
+=================
+
+ The XEmacs command loop is entered automatically when XEmacs starts
+up. This top-level invocation of the command loop never exits; it keeps
+running as long as XEmacs does. Lisp programs can also invoke the
+command loop. Since this makes more than one activation of the command
+loop, we call it "recursive editing". A recursive editing level has
+the effect of suspending whatever command invoked it and permitting the
+user to do arbitrary editing before resuming that command.
+
+ The commands available during recursive editing are the same ones
+available in the top-level editing loop and defined in the keymaps.
+Only a few special commands exit the recursive editing level; the others
+return to the recursive editing level when they finish. (The special
+commands for exiting are always available, but they do nothing when
+recursive editing is not in progress.)
+
+ All command loops, including recursive ones, set up all-purpose error
+handlers so that an error in a command run from the command loop will
+not exit the loop.
+
+ Minibuffer input is a special kind of recursive editing. It has a
+few special wrinkles, such as enabling display of the minibuffer and the
+minibuffer window, but fewer than you might suppose. Certain keys
+behave differently in the minibuffer, but that is only because of the
+minibuffer's local map; if you switch windows, you get the usual XEmacs
+commands.
+
+ To invoke a recursive editing level, call the function
+`recursive-edit'. This function contains the command loop; it also
+contains a call to `catch' with tag `exit', which makes it possible to
+exit the recursive editing level by throwing to `exit' (*note Catch and
+Throw::.). If you throw a value other than `t', then `recursive-edit'
+returns normally to the function that called it. The command `C-M-c'
+(`exit-recursive-edit') does this. Throwing a `t' value causes
+`recursive-edit' to quit, so that control returns to the command loop
+one level up. This is called "aborting", and is done by `C-]'
+(`abort-recursive-edit').
+
+ Most applications should not use recursive editing, except as part of
+using the minibuffer. Usually it is more convenient for the user if you
+change the major mode of the current buffer temporarily to a special
+major mode, which should have a command to go back to the previous mode.
+(The `e' command in Rmail uses this technique.) Or, if you wish to
+give the user different text to edit "recursively", create and select a
+new buffer in a special mode. In this mode, define a command to
+complete the processing and go back to the previous buffer. (The `m'
+command in Rmail does this.)
+
+ Recursive edits are useful in debugging. You can insert a call to
+`debug' into a function definition as a sort of breakpoint, so that you
+can look around when the function gets there. `debug' invokes a
+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
+ 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
+ recursive editing level.
+
+ In the following example, the function `simple-rec' first advances
+ point one word, then enters a recursive edit, printing out a
+ message in the echo area. The user can then do any editing
+ desired, and then type `C-M-c' to exit and continue executing
+ `simple-rec'.
+
+ (defun simple-rec ()
+ (forward-word 1)
+ (message "Recursive edit in progress")
+ (recursive-edit)
+ (forward-word 1))
+ => simple-rec
+ (simple-rec)
+ => nil
+
+ - Command: exit-recursive-edit
+ This function exits from the innermost recursive edit (including
+ minibuffer input). Its definition is effectively `(throw 'exit
+ nil)'.
+
+ - Command: abort-recursive-edit
+ This function aborts the command that requested the innermost
+ recursive edit (including minibuffer input), by signaling `quit'
+ after exiting the recursive edit. Its definition is effectively
+ `(throw 'exit t)'. *Note Quitting::.
+
+ - Command: top-level
+ This function exits all recursive editing levels; it does not
+ return a value, as it jumps completely out of any computation
+ directly back to the main command loop.
+
+ - Function: recursion-depth
+ This function returns the current depth of recursive edits. When
+ no recursive edit is active, it returns 0.
+
+\1f
+File: lispref.info, Node: Disabling Commands, Next: Command History, Prev: Recursive Editing, Up: Command Loop
+
+Disabling Commands
+==================
+
+ "Disabling a command" marks the command as requiring user
+confirmation before it can be executed. Disabling is used for commands
+which might be confusing to beginning users, to prevent them from using
+the commands by accident.
+
+ The low-level mechanism for disabling a command is to put a
+non-`nil' `disabled' property on the Lisp symbol for the command.
+These properties are normally set up by the user's `.emacs' file with
+Lisp expressions such as this:
+
+ (put 'upcase-region 'disabled t)
+
+For a few commands, these properties are present by default and may be
+removed by the `.emacs' file.
+
+ If the value of the `disabled' property is a string, the message
+saying the command is disabled includes that string. For example:
+
+ (put 'delete-region 'disabled
+ "Text deleted this way cannot be yanked back!\n")
+
+ *Note Disabling: (xemacs)Disabling, for the details on what happens
+when a disabled command is invoked interactively. Disabling a command
+has no effect on calling it as a function from Lisp programs.
+
+ - Command: enable-command COMMAND
+ Allow COMMAND to be executed without special confirmation from now
+ on, and (if the user confirms) alter the user's `.emacs' file so
+ that this will apply to future sessions.
+
+ - Command: disable-command COMMAND
+ Require special confirmation to execute COMMAND from now on, and
+ (if the user confirms) alter the user's `.emacs' file so that this
+ will apply to future sessions.
+
+ - Variable: disabled-command-hook
+ This normal hook is run instead of a disabled command, when the
+ user invokes the disabled command interactively. The hook
+ functions can use `this-command-keys' to determine what the user
+ typed to run the command, and thus find the command itself. *Note
+ Hooks::.
+
+ By default, `disabled-command-hook' contains a function that asks
+ the user whether to proceed.
+
+\1f
+File: lispref.info, Node: Command History, Next: Keyboard Macros, Prev: Disabling Commands, Up: Command Loop
+
+Command History
+===============
+
+ The command loop keeps a history of the complex commands that have
+been executed, to make it convenient to repeat these commands. A
+"complex command" is one for which the interactive argument reading
+uses the minibuffer. This includes any `M-x' command, any `M-:'
+command, and any command whose `interactive' specification reads an
+argument from the minibuffer. Explicit use of the minibuffer during
+the execution of the command itself does not cause the command to be
+considered complex.
+
+ - Variable: command-history
+ This variable's value is a list of recent complex commands, each
+ represented as a form to evaluate. It continues to accumulate all
+ complex commands for the duration of the editing session, but all
+ but the first (most recent) thirty elements are deleted when a
+ garbage collection takes place (*note Garbage Collection::.).
+
+ command-history
+ => ((switch-to-buffer "chistory.texi")
+ (describe-key "^X^[")
+ (visit-tags-table "~/emacs/src/")
+ (find-tag "repeat-complex-command"))
+
+ This history list is actually a special case of minibuffer history
+(*note Minibuffer History::.), with one special twist: the elements are
+expressions rather than strings.
+
+ There are a number of commands devoted to the editing and recall of
+previous commands. The commands `repeat-complex-command', and
+`list-command-history' are described in the user manual (*note
+Repetition: (xemacs)Repetition.). Within the minibuffer, the history
+commands used are the same ones available in any minibuffer.
+
+\1f
+File: lispref.info, Node: Keyboard Macros, Prev: Command History, Up: Command Loop
+
+Keyboard Macros
+===============
+
+ A "keyboard macro" is a canned sequence of input events that can be
+considered a command and made the definition of a key. The Lisp
+representation of a keyboard macro is a string or vector containing the
+events. Don't confuse keyboard macros with Lisp macros (*note
+Macros::.).
+
+ - Function: execute-kbd-macro MACRO &optional COUNT
+ This function executes MACRO as a sequence of events. If MACRO is
+ a string or vector, then the events in it are executed exactly as
+ if they had been input by the user. The sequence is *not*
+ expected to be a single key sequence; normally a keyboard macro
+ definition consists of several key sequences concatenated.
+
+ If MACRO is a symbol, then its function definition is used in
+ place of MACRO. If that is another symbol, this process repeats.
+ Eventually the result should be a string or vector. If the result
+ is not a symbol, string, or vector, an error is signaled.
+
+ The argument COUNT is a repeat count; MACRO is executed that many
+ times. If COUNT is omitted or `nil', MACRO is executed once. If
+ it is 0, MACRO is executed over and over until it encounters an
+ error or a failing search.
+
+ - Variable: executing-macro
+ This variable contains the string or vector that defines the
+ keyboard macro that is currently executing. It is `nil' if no
+ macro is currently executing. A command can test this variable to
+ behave differently when run from an executing macro. Do not set
+ this variable yourself.
+
+ - Variable: defining-kbd-macro
+ This variable indicates whether a keyboard macro is being defined.
+ A command can test this variable to behave differently while a
+ macro is being defined. The commands `start-kbd-macro' and
+ `end-kbd-macro' set this variable--do not set it yourself.
+
+ - Variable: last-kbd-macro
+ This variable is the definition of the most recently defined
+ keyboard macro. Its value is a string or vector, or `nil'.
+
+ The commands are described in the user's manual (*note Keyboard
+Macros: (xemacs)Keyboard Macros.).
+
+\1f
+File: lispref.info, Node: Keymaps, Next: Menus, Prev: Command Loop, Up: Top
+
+Keymaps
+*******
+
+ The bindings between input events and commands are recorded in data
+structures called "keymaps". Each binding in a keymap associates (or
+"binds") an individual event type either with another keymap or with a
+command. When an event is bound to a keymap, that keymap is used to
+look up the next input event; this continues until a command is found.
+The whole process is called "key lookup".
+
+* Menu:
+
+* Keymap Terminology:: Definitions of terms pertaining to keymaps.
+* Format of Keymaps:: What a keymap looks like as a Lisp object.
+* Creating Keymaps:: Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+ of another keymap.
+* Key Sequences:: How to specify key sequences.
+* Prefix Keys:: Defining a key with a keymap as its definition.
+* Active Keymaps:: Each buffer has a local keymap
+ to override the standard (global) bindings.
+ A minor mode can also override them.
+* Key Lookup:: How extracting elements from keymaps works.
+* Functions for Key Lookup:: How to request key lookup.
+* Changing Key Bindings:: Redefining a key in a keymap.
+* Key Binding Commands:: Interactive interfaces for redefining keys.
+* Scanning Keymaps:: Looking through all keymaps, for printing help.
+* Other Keymap Functions:: Miscellaneous keymap functions.
+
+\1f
+File: lispref.info, Node: Keymap Terminology, Next: Format of Keymaps, Up: Keymaps
+
+Keymap Terminology
+==================
+
+ A "keymap" is a table mapping event types to definitions (which can
+be any Lisp objects, though only certain types are meaningful for
+execution by the command loop). Given an event (or an event type) and a
+keymap, XEmacs can get the event's definition. Events mapped in keymaps
+include keypresses, button presses, and button releases (*note
+Events::.).
+
+ A sequence of input events that form a unit is called a "key
+sequence", or "key" for short. A sequence of one event is always a key
+sequence, and so are some multi-event sequences.
+
+ A keymap determines a binding or definition for any key sequence. If
+the key sequence is a single event, its binding is the definition of the
+event in the keymap. The binding of a key sequence of more than one
+event is found by an iterative process: the binding of the first event
+is found, and must be a keymap; then the second event's binding is found
+in that keymap, and so on until all the events in the key sequence are
+used up.
+
+ If the binding of a key sequence is a keymap, we call the key
+sequence a "prefix key". Otherwise, we call it a "complete key"
+(because no more events can be added to it). If the binding is `nil',
+we call the key "undefined". Examples of prefix keys are `C-c', `C-x',
+and `C-x 4'. Examples of defined complete keys are `X', <RET>, and
+`C-x 4 C-f'. Examples of undefined complete keys are `C-x C-g', and
+`C-c 3'. *Note Prefix Keys::, for more details.
+
+ The rule for finding the binding of a key sequence assumes that the
+intermediate bindings (found for the events before the last) are all
+keymaps; if this is not so, the sequence of events does not form a
+unit--it is not really a key sequence. In other words, removing one or
+more events from the end of any valid key must always yield a prefix
+key. For example, `C-f C-n' is not a key; `C-f' is not a prefix key,
+so a longer sequence starting with `C-f' cannot be a key.
+
+ Note that the set of possible multi-event key sequences depends on
+the bindings for prefix keys; therefore, it can be different for
+different keymaps, and can change when bindings are changed. However,
+a one-event sequence is always a key sequence, because it does not
+depend on any prefix keys for its well-formedness.
+
+ At any time, several primary keymaps are "active"--that is, in use
+for finding key bindings. These are the "global map", which is shared
+by all buffers; the "local keymap", which is usually associated with a
+specific major mode; and zero or more "minor mode keymaps", which
+belong to currently enabled minor modes. (Not all minor modes have
+keymaps.) The local keymap bindings shadow (i.e., take precedence
+over) the corresponding global bindings. The minor mode keymaps shadow
+both local and global keymaps. *Note Active Keymaps::, for details.
+
+\1f
+File: lispref.info, Node: Format of Keymaps, Next: Creating Keymaps, Prev: Keymap Terminology, Up: Keymaps
+
+Format of Keymaps
+=================
+
+ A keymap is a primitive type that associates events with their
+bindings. Note that this is different from Emacs 18 and FSF Emacs,
+where keymaps are lists.
+
+ - Function: keymapp OBJECT
+ This function returns `t' if OBJECT is a keymap, `nil' otherwise.
+
+\1f
+File: lispref.info, Node: Creating Keymaps, Next: Inheritance and Keymaps, Prev: Format of Keymaps, Up: Keymaps
+
+Creating Keymaps
+================
+
+ Here we describe the functions for creating keymaps.
+
+ - Function: make-keymap &optional NAME
+ This function constructs and returns a new keymap object. All
+ entries in it are `nil', meaning "command undefined".
+
+ Optional argument NAME specifies a name to assign to the keymap,
+ as in `set-keymap-name'. This name is only a debugging
+ convenience; it is not used except when printing the keymap.
+
+ - Function: make-sparse-keymap &optional NAME
+ This function constructs and returns a new keymap object. All
+ 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
+ distinction is not great.
+
+ Optional argument NAME specifies a name to assign to the keymap,
+ as in `set-keymap-name'. This name is only a debugging
+ convenience; it is not used except when printing the keymap.
+
+ - Function: set-keymap-name KEYMAP NEW-NAME
+ This function assigns a "name" to a keymap. The name is only a
+ debugging convenience; it is not used except when printing the
+ keymap.
+
+ - Function: keymap-name KEYMAP
+ This function returns the "name" of a keymap, as assigned using
+ `set-keymap-name'.
+
+ - Function: copy-keymap KEYMAP
+ This function returns a copy of KEYMAP. Any keymaps that appear
+ directly as bindings in KEYMAP are also copied recursively, and so
+ on to any number of levels. However, recursive copying does not
+ take place when the definition of a character is a symbol whose
+ function definition is a keymap; the same symbol appears in the
+ new copy.
+
+ (setq map (copy-keymap (current-local-map)))
+ => #<keymap 3 entries 0x21f80>
+
+ (eq map (current-local-map))
+ => nil
+
+\1f
+File: lispref.info, Node: Inheritance and Keymaps, Next: Key Sequences, Prev: Creating Keymaps, Up: Keymaps
+
+Inheritance and Keymaps
+=======================
+
+ A keymap can inherit the bindings of other keymaps. The other
+keymaps are called the keymap's "parents", and are set with
+`set-keymap-parents'. When searching for a binding for a key sequence
+in a particular keymap, that keymap itself will first be searched;
+then, if no binding was found in the map and it has parents, the first
+parent keymap will be searched; then that keymap's parent will be
+searched, and so on, until either a binding for the key sequence is
+found, or a keymap without a parent is encountered. At this point, the
+search will continue with the next parent of the most recently
+encountered keymap that has another parent, etc. Essentially, a
+depth-first search of all the ancestors of the keymap is conducted.
+
+ `(current-global-map)' is the default parent of all keymaps.
+
+ - Function: set-keymap-parents KEYMAP PARENTS
+ This function sets the parent keymaps of KEYMAP to the list
+ PARENTS.
+
+ If you change the bindings in one of the keymaps in PARENTS using
+ `define-key' or other key-binding functions, these changes are
+ visible in KEYMAP unless shadowed by bindings in that map or in
+ earlier-searched ancestors. The converse is not true: if you use
+ `define-key' to change KEYMAP, that affects the bindings in that
+ map, but has no effect on any of the keymaps in PARENTS.
+
+ - Function: keymap-parents KEYMAP
+ This function returns the list of parent keymaps of KEYMAP, or
+ `nil' if KEYMAP has no parents.
+
+ As an alternative to specifying a parent, you can also specify a
+"default binding" that is used whenever a key is not otherwise bound in
+the keymap. This is useful for terminal emulators, for example, which
+may want to trap all keystrokes and pass them on in some modified
+format. Note that if you specify a default binding for a keymap,
+neither the keymap's parents nor the current global map are searched for
+key bindings.
+
+ - Function: set-keymap-default-binding KEYMAP COMMAND
+ This function sets the default binding of KEYMAP to COMMAND, or
+ `nil' if no default is desired.
+
+ - Function: keymap-default-binding KEYMAP
+ This function returns the default binding of KEYMAP, or `nil' if
+ it has none.
+
+\1f
+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 <CONTROL> and <META>). 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 (<CONTROL>,
+<META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>). 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 <SHIFT> 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 <SHIFT> 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 <SHIFT>,
+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'.
+
+\1f
+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 <META>
+ 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 <ESC> 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.
+
+\1f
+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)
+ => #<keymap global-map 639 entries 0x221>
+
+ - 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)
+ => #<keymap lisp-interaction-mode-map 5 entries 0x558>
+ (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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps
+
+Key Lookup
+==========
+
+ "Key lookup" is the process of finding the binding of a key sequence
+from a given keymap. Actual execution of the binding is not part of
+key lookup.
+
+ Key lookup uses just the event type of each event in the key
+sequence; the rest of the event is ignored. In fact, a key sequence
+used for key lookup may designate mouse events with just their types
+(symbols) instead of with entire mouse events (lists). *Note Events::.
+Such a pseudo-key-sequence is insufficient for `command-execute', but
+it is sufficient for looking up or rebinding a key.
+
+ When the key sequence consists of multiple events, key lookup
+processes the events sequentially: the binding of the first event is
+found, and must be a keymap; then the second event's binding is found in
+that keymap, and so on until all the events in the key sequence are used
+up. (The binding thus found for the last event may or may not be a
+keymap.) Thus, the process of key lookup is defined in terms of a
+simpler process for looking up a single event in a keymap. How that is
+done depends on the type of object associated with the event in that
+keymap.
+
+ Let's use the term "keymap entry" to describe the value found by
+looking up an event type in a keymap. (This doesn't include the item
+string and other extra elements in menu key bindings because
+`lookup-key' and other key lookup functions don't include them in the
+returned value.) While any Lisp object may be stored in a keymap as a
+keymap entry, not all make sense for key lookup. Here is a list of the
+meaningful kinds of keymap entries:
+
+`nil'
+ `nil' means that the events used so far in the lookup form an
+ undefined key. When a keymap fails to mention an event type at
+ all, and has no default binding, that is equivalent to a binding
+ of `nil' for that event type.
+
+KEYMAP
+ The events used so far in the lookup form a prefix key. The next
+ event of the key sequence is looked up in KEYMAP.
+
+COMMAND
+ The events used so far in the lookup form a complete key, and
+ COMMAND is its binding. *Note What Is a Function::.
+
+ARRAY
+ The array (either a string or a vector) is a keyboard macro. The
+ events used so far in the lookup form a complete key, and the
+ array is its binding. See *Note Keyboard Macros::, for more
+ information. (Note that you cannot use a shortened form of a key
+ sequence here, such as `(control y)'; you must use the full form
+ `[(control y)]'. *Note Key Sequences::.)
+
+LIST
+ The meaning of a list depends on the types of the elements of the
+ list.
+
+ * If the CAR of LIST is `lambda', then the list is a lambda
+ expression. This is presumed to be a command, and is treated
+ as such (see above).
+
+ * If the CAR of LIST is a keymap and the CDR is an event type,
+ then this is an "indirect entry":
+
+ (OTHERMAP . OTHERTYPE)
+
+ When key lookup encounters an indirect entry, it looks up
+ instead the binding of OTHERTYPE in OTHERMAP and uses that.
+
+ This feature permits you to define one key as an alias for
+ another key. For example, an entry whose CAR is the keymap
+ called `esc-map' and whose CDR is 32 (the code for <SPC>)
+ means, "Use the global binding of `Meta-<SPC>', whatever that
+ may be."
+
+SYMBOL
+ The function definition of SYMBOL is used in place of SYMBOL. If
+ that too is a symbol, then this process is repeated, any number of
+ times. Ultimately this should lead to an object that is a keymap,
+ a command or a keyboard macro. A list is allowed if it is a
+ keymap or a command, but indirect entries are not understood when
+ found via symbols.
+
+ Note that keymaps and keyboard macros (strings and vectors) are not
+ valid functions, so a symbol with a keymap, string, or vector as
+ its function definition is invalid as a function. It is, however,
+ valid as a key binding. If the definition is a keyboard macro,
+ then the symbol is also valid as an argument to `command-execute'
+ (*note Interactive Call::.).
+
+ The symbol `undefined' is worth special mention: it means to treat
+ the key as undefined. Strictly speaking, the key is defined, and
+ its binding is the command `undefined'; but that command does the
+ same thing that is done automatically for an undefined key: it
+ rings the bell (by calling `ding') but does not signal an error.
+
+ `undefined' is used in local keymaps to override a global key
+ binding and make the key "undefined" locally. A local binding of
+ `nil' would fail to do this because it would not override the
+ global binding.
+
+ANYTHING ELSE
+ If any other type of object is found, the events used so far in the
+ lookup form a complete key, and the object is its binding, but the
+ binding is not executable as a command.
+
+ In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or `nil'.
+
+\1f
+File: lispref.info, Node: Functions for Key Lookup, Next: Changing Key Bindings, Prev: Key Lookup, Up: Keymaps
+
+Functions for Key Lookup
+========================
+
+ Here are the functions and variables pertaining to key lookup.
+
+ - Function: lookup-key KEYMAP KEY &optional ACCEPT-DEFAULTS
+ This function returns the definition of KEY in KEYMAP. If the
+ string or vector KEY is not a valid key sequence according to the
+ prefix keys specified in KEYMAP (which means it is "too long" and
+ has extra events at the end), then the value is a number, the
+ number of events at the front of KEY that compose a complete key.
+
+ If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
+ default bindings as well as bindings for the specific events in
+ KEY. Otherwise, `lookup-key' reports only bindings for the
+ specific sequence KEY, ignoring default bindings except when you
+ explicitly ask about them.
+
+ All the other functions described in this chapter that look up
+ keys use `lookup-key'.
+
+ (lookup-key (current-global-map) "\C-x\C-f")
+ => find-file
+ (lookup-key (current-global-map) "\C-x\C-f12345")
+ => 2
+
+ If KEY begins with the character whose value is contained in
+ `meta-prefix-char', that character is implicitly removed and the
+ <META> modifier added to the key. Thus, the first example below is
+ handled by conversion into the second example.
+
+ (lookup-key (current-global-map) "\ef")
+ => forward-word
+ (lookup-key (current-global-map) "\M-f")
+ => forward-word
+
+ Unlike `read-key-sequence', this function does not modify the
+ specified events in ways that discard information (*note Key
+ Sequence Input::.). In particular, it does not convert letters to
+ lower case.
+
+ - Command: undefined
+ Used in keymaps to undefine keys. If a key sequence is defined to
+ this, invoking this key sequence causes a "key undefined" error,
+ just as if the key sequence had no binding.
+
+ - Function: key-binding KEY &optional ACCEPT-DEFAULTS
+ This function returns the binding for KEY in the current keymaps,
+ trying all the active keymaps. The result is `nil' if KEY is
+ undefined in the keymaps.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ (key-binding "\C-x\C-f")
+ => find-file
+ (key-binding '(control home))
+ => beginning-of-buffer
+ (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
+ 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
+ global keymap, or `nil' if it is undefined there.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ - Function: minor-mode-key-binding KEY &optional ACCEPT-DEFAULTS
+ This function returns a list of all the active minor mode bindings
+ of KEY. More precisely, it returns an alist of pairs `(MODENAME .
+ BINDING)', where MODENAME is the variable that enables the minor
+ mode, and BINDING is KEY's binding in that mode. If KEY has no
+ minor-mode bindings, the value is `nil'.
+
+ If the first binding is not a prefix command, all subsequent
+ bindings from other minor modes are omitted, since they would be
+ completely shadowed. Similarly, the list omits non-prefix
+ bindings that follow prefix bindings.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ - Variable: meta-prefix-char
+ This variable is the meta-prefix character code. It is used when
+ translating a two-character sequence to a meta character so it can
+ be looked up in a keymap. For useful results, the value should be
+ a prefix event (*note Prefix Keys::.). The default value is
+ `?\^[' (integer 27), which is the ASCII character usually produced
+ by the <ESC> key.
+
+ As long as the value of `meta-prefix-char' remains `?\^[', key
+ lookup translates `<ESC> b' into `M-b', which is normally defined
+ as the `backward-word' command. However, if you set
+ `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
+ equivalent ASCII code `24', then XEmacs will translate `C-x b'
+ (whose standard binding is the `switch-to-buffer' command) into
+ `M-b'.
+
+ meta-prefix-char ; The default value.
+ => ?\^[ ; Under XEmacs 20.
+ => 27 ; Under XEmacs 19.
+
+ (key-binding "\eb")
+ => backward-word
+
+ ?\C-x ; The print representation
+ ; of a character.
+ => ?\^X ; Under XEmacs 20.
+ => 24 ; Under XEmacs 19.
+
+ (setq meta-prefix-char 24)
+ => 24
+
+ (key-binding "\C-xb")
+ => backward-word ; Now, typing `C-x b' is
+ ; like typing `M-b'.
+
+ (setq meta-prefix-char ?\e) ; Avoid confusion!
+ ; Restore the default value!
+ => ?\^[ ; Under XEmacs 20.
+ => 27 ; Under XEmacs 19.
+
+\1f
+File: lispref.info, Node: Changing Key Bindings, Next: Key Binding Commands, Prev: Functions for Key Lookup, Up: Keymaps
+
+Changing Key Bindings
+=====================
+
+ The way to rebind a key is to change its entry in a keymap. If you
+change a binding in the global keymap, the change is effective in all
+buffers (though it has no direct effect in buffers that shadow the
+global binding with a local one). If you change the current buffer's
+local map, that usually affects all buffers using the same major mode.
+The `global-set-key' and `local-set-key' functions are convenient
+interfaces for these operations (*note Key Binding Commands::.). You
+can also use `define-key', a more general function; then you must
+specify explicitly the map to change.
+
+ The way to specify the key sequence that you want to rebind is
+described above (*note Key Sequences::.).
+
+ For the functions below, an error is signaled if KEYMAP is not a
+keymap or if KEY is not a string or vector representing a key sequence.
+You can use event types (symbols) as shorthand for events that are
+lists.
+
+ - Function: define-key KEYMAP KEY BINDING
+ This function sets the binding for KEY in KEYMAP. (If KEY is more
+ than one event long, the change is actually made in another keymap
+ reached from KEYMAP.) The argument BINDING can be any Lisp
+ object, but only certain types are meaningful. (For a list of
+ meaningful types, see *Note Key Lookup::.) The value returned by
+ `define-key' is BINDING.
+
+ Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
+ or undefined; otherwise an error is signaled.
+
+ If some prefix of KEY is undefined, then `define-key' defines it
+ as a prefix key so that the rest of KEY may be defined as
+ specified.
+
+ Here is an example that creates a sparse keymap and makes a number of
+bindings in it:
+
+ (setq map (make-sparse-keymap))
+ => #<keymap 0 entries 0xbee>
+
+ (define-key map "\C-f" 'forward-char)
+ => forward-char
+
+ map
+ => #<keymap 1 entry 0xbee>
+ (describe-bindings-internal map)
+ => ; (Inserted in buffer)
+ C-f forward-char
+
+ ;; Build sparse submap for `C-x' and bind `f' in that.
+ (define-key map "\C-xf" 'forward-word)
+ => forward-word
+
+ map
+ => #<keymap 2 entries 0xbee>
+ (describe-bindings-internal map)
+ => ; (Inserted in buffer)
+ C-f forward-char
+ C-x << Prefix Command >>
+
+ C-x f forward-word
+
+ ;; Bind `C-p' to the `ctl-x-map'.
+ (define-key map "\C-p" ctl-x-map)
+ ;; `ctl-x-map'
+ => #<keymap Control-X-prefix 77 entries 0x3bf>
+
+ ;; Bind `C-f' to `foo' in the `ctl-x-map'.
+ (define-key map "\C-p\C-f" 'foo)
+ => foo
+
+ map
+ => #<keymap 3 entries 0xbee>
+ (describe-bindings-internal map)
+ => ; (Inserted in buffer)
+ C-f forward-char
+ C-p << Prefix command Control-X-prefix >>
+ C-x << Prefix Command >>
+
+ C-p tab indent-rigidly
+ C-p $ set-selective-display
+ C-p ' expand-abbrev
+ C-p ( start-kbd-macro
+ C-p ) end-kbd-macro
+ ...
+ C-p C-x exchange-point-and-mark
+ C-p C-z suspend-or-iconify-emacs
+ C-p M-escape repeat-complex-command
+ C-p M-C-[ repeat-complex-command
+
+ C-x f forward-word
+
+ C-p 4 . find-tag-other-window
+ ...
+ C-p 4 C-o display-buffer
+
+ C-p 5 0 delete-frame
+ ...
+ C-p 5 C-f find-file-other-frame
+
+ ...
+
+ C-p a i g inverse-add-global-abbrev
+ C-p a i l inverse-add-mode-abbrev
+
+Note that storing a new binding for `C-p C-f' actually works by
+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
+ 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'.
+
+ For example, this redefines `C-x C-f', if you do it in an XEmacs
+ with standard bindings:
+
+ (substitute-key-definition
+ '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.
+ Thus, you can change one map under the control of the bindings in
+ another. For example,
+
+ (substitute-key-definition
+ 'delete-backward-char 'my-funny-delete
+ my-map global-map)
+
+ puts the special deletion command in `my-map' for whichever keys
+ are globally bound to the standard deletion command.
+
+
+ - Function: suppress-keymap KEYMAP &optional NODIGITS
+ This function changes the contents of the full keymap KEYMAP by
+ making all the printing characters undefined. More precisely, it
+ binds them to the command `undefined'. This makes ordinary
+ insertion of text impossible. `suppress-keymap' returns `nil'.
+
+ If NODIGITS is `nil', then `suppress-keymap' defines digits to run
+ `digit-argument', and `-' to run `negative-argument'. Otherwise
+ it makes them undefined like the rest of the printing characters.
+
+ The `suppress-keymap' function does not make it impossible to
+ modify a buffer, as it does not suppress commands such as `yank'
+ and `quoted-insert'. To prevent any modification of a buffer, make
+ it read-only (*note Read Only Buffers::.).
+
+ Since this function modifies KEYMAP, you would normally use it on
+ a newly created keymap. Operating on an existing keymap that is
+ used for some other purpose is likely to cause trouble; for
+ example, suppressing `global-map' would make it impossible to use
+ most of XEmacs.
+
+ Most often, `suppress-keymap' is used to initialize local keymaps
+ of modes such as Rmail and Dired where insertion of text is not
+ desirable and the buffer is read-only. Here is an example taken
+ from the file `emacs/lisp/dired.el', showing how the local keymap
+ for Dired mode is set up:
+
+ ...
+ (setq dired-mode-map (make-keymap))
+ (suppress-keymap dired-mode-map)
+ (define-key dired-mode-map "r" 'dired-rename-file)
+ (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+ (define-key dired-mode-map "d" 'dired-flag-file-deleted)
+ (define-key dired-mode-map "v" 'dired-view-file)
+ (define-key dired-mode-map "e" 'dired-find-file)
+ (define-key dired-mode-map "f" 'dired-find-file)
+ ...
+
+\1f
+File: lispref.info, Node: Key Binding Commands, Next: Scanning Keymaps, Prev: Changing Key Bindings, Up: Keymaps
+
+Commands for Binding Keys
+=========================
+
+ This section describes some convenient interactive interfaces for
+changing key bindings. They work by calling `define-key'.
+
+ People often use `global-set-key' in their `.emacs' file for simple
+customization. For example,
+
+ (global-set-key "\C-x\C-\\" 'next-line)
+
+or
+
+ (global-set-key [(control ?x) (control ?\\)] 'next-line)
+
+or
+
+ (global-set-key [?\C-x ?\C-\\] 'next-line)
+
+redefines `C-x C-\' to move down a line.
+
+ (global-set-key [(meta button1)] 'mouse-set-point)
+
+redefines the first (leftmost) mouse button, typed with the Meta key, to
+set point where you click.
+
+ - Command: global-set-key KEY DEFINITION
+ This function sets the binding of KEY in the current global map to
+ DEFINITION.
+
+ (global-set-key KEY DEFINITION)
+ ==
+ (define-key (current-global-map) KEY DEFINITION)
+
+ - Command: global-unset-key KEY
+ This function removes the binding of KEY from the current global
+ map.
+
+ One use of this function is in preparation for defining a longer
+ key that uses KEY as a prefix--which would not be allowed if KEY
+ has a non-prefix binding. For example:
+
+ (global-unset-key "\C-l")
+ => nil
+
+ (global-set-key "\C-l\C-l" 'redraw-display)
+ => nil
+
+ This function is implemented simply using `define-key':
+
+ (global-unset-key KEY)
+ ==
+ (define-key (current-global-map) KEY nil)
+
+ - Command: local-set-key KEY DEFINITION
+ This function sets the binding of KEY in the current local keymap
+ to DEFINITION.
+
+ (local-set-key KEY DEFINITION)
+ ==
+ (define-key (current-local-map) KEY DEFINITION)
+
+ - Command: local-unset-key KEY
+ This function removes the binding of KEY from the current local
+ map.
+
+ (local-unset-key KEY)
+ ==
+ (define-key (current-local-map) KEY nil)
+
+\1f
+File: lispref.info, Node: Scanning Keymaps, Next: Other Keymap Functions, Prev: Key Binding Commands, Up: Keymaps
+
+Scanning Keymaps
+================
+
+ This section describes functions used to scan all the current
+keymaps, or all keys within a keymap, for the sake of printing help
+information.
+
+ - Function: accessible-keymaps KEYMAP &optional PREFIX
+ This function returns a list of all the keymaps that can be
+ accessed (via prefix keys) from KEYMAP. The value is an
+ association list with elements of the form `(KEY . MAP)', where
+ KEY is a prefix key whose definition in KEYMAP is MAP.
+
+ The elements of the alist are ordered so that the KEY increases in
+ length. The first element is always `([] . KEYMAP)', because the
+ specified keymap is accessible from itself with a prefix of no
+ events.
+
+ If PREFIX is given, it should be a prefix key sequence; then
+ `accessible-keymaps' includes only the submaps whose prefixes start
+ with PREFIX. These elements look just as they do in the value of
+ `(accessible-keymaps)'; the only difference is that some elements
+ are omitted.
+
+ In the example below, the returned alist indicates that the key
+ `C-x', which is displayed as `[(control x)]', is a prefix key
+ whose definition is the keymap `#<keymap ((control x) #<keymap
+ emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
+ notation for the keymap's name indicates that this is an internal
+ submap of `emacs-lisp-mode-map'. This is because
+ `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
+ its parent, and `lisp-interaction-mode-map' defines no key
+ sequences beginning with `C-x'.)
+
+ (current-local-map)
+ => #<keymap lisp-interaction-mode-map 5 entries 0x558>
+ (accessible-keymaps (current-local-map))
+ =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
+ ([(control x)] .
+ #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
+ 1 entry 0x8a2>))
+
+ The following example shows the results of calling
+ `accessible-keymaps' on a large, complex keymap. Notice how some
+ keymaps were given explicit names using `set-keymap-name'; those
+ submaps without explicit names are given descriptive names
+ indicating their relationship to their enclosing keymap.
+
+ (accessible-keymaps (current-global-map))
+ => (([] . #<keymap global-map 639 entries 0x221>)
+ ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
+ ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
+ ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
+ ([(meta escape)] .
+ #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+ 3 entries 0x3e0>)
+ ([(meta control \[)] .
+ #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+ 3 entries 0x3e0>)
+ ([f1] . #<keymap help-map 33 entries 0x4ec>)
+ ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
+ ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
+ ([(control x) \6] . #<keymap 13 entries 0x4d2>)
+ ([(control x) a] .
+ #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+ 8 entries 0x3ef>)
+ ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
+ ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
+ ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
+ ([(control x) a i] .
+ #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+ 8 entries 0x3ef>)
+ 2 entries 0x3f5>))
+
+ - Function: map-keymap FUNCTION KEYMAP &optional SORT-FIRST
+ 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
+ inserts new elements into the keymap, it may or may not be called
+ with them later. No element of the keymap will ever be passed to
+ the function more than once.
+
+ The function will not be called on elements of this keymap's
+ parents (*note Inheritance and Keymaps::.) or upon keymaps which
+ are contained within this keymap (multi-character definitions).
+ It will be called on <META> characters since they are not really
+ two-character sequences.
+
+ If the optional third argument SORT-FIRST is non-`nil', then the
+ elements of the keymap will be passed to the mapper function in a
+ canonical order. Otherwise, they will be passed in hash (that is,
+ random) order, which is faster.
+
+ - Function: keymap-fullness KEYMAP
+ This function returns the number of bindings in the keymap.
+
+ - Function: where-is-internal DEFINITION &optional KEYMAPS FIRSTONLY
+ NOINDIRECT EVENT-OR-KEYS
+ This function returns a list of key sequences (of any length) that
+ are bound to DEFINITION in a set of keymaps.
+
+ The argument DEFINITION can be any object; it is compared with all
+ keymap entries using `eq'.
+
+ KEYMAPS can be either a keymap (meaning search in that keymap and
+ the current global keymap) or a list of keymaps (meaning search in
+ 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
+ `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).
+
+ If FIRSTONLY is non-`nil', then the value is a single vector
+ representing the first key sequence found, rather than a list of
+ all possible key sequences.
+
+ If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
+ indirect keymap bindings. This makes it possible to search for an
+ indirect definition itself.
+
+ This function is used by `where-is' (*note Help: (emacs)Help.).
+
+ (where-is-internal 'describe-function)
+ => ([(control h) d] [(control h) f] [f1 d] [f1 f])
+
+ - Function: describe-bindings-internal MAP &optional ALL SHADOW PREFIX
+ MOUSE-ONLY-P
+ This function inserts (into the current buffer) a list of all
+ defined keys and their definitions in MAP. Optional second
+ argument ALL says whether to include even "uninteresting"
+ definitions, i.e. symbols with a non-`nil' `suppress-keymap'
+ property. Third argument SHADOW is a list of keymaps whose
+ bindings shadow those of map; if a binding is present in any
+ shadowing map, it is not printed. Fourth argument PREFIX, if
+ non-`nil', should be a key sequence; only bindings which start
+ with that key sequence will be printed. Fifth argument
+ MOUSE-ONLY-P says to only print bindings for mouse clicks.
+
+ `describe-bindings-internal' is used to implement the help command
+`describe-bindings'.
+
+ - Command: describe-bindings 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.
+
+ When several characters with consecutive ASCII codes have the same
+ definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In
+ this instance, you need to know the ASCII codes to understand
+ which characters this means. For example, in the default global
+ map, the characters `<SPC> .. ~' are described by a single line.
+ <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
+ them include all the normal printing characters, (e.g., letters,
+ 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.
+
+\1f
+File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps
+
+Other Keymap Functions
+======================
+
+ - Function: set-keymap-prompt KEYMAP NEW-PROMPT
+ This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
+ `nil' if no prompt is desired. The prompt is shown in the
+ echo-area when reading a key-sequence to be looked-up in this
+ keymap.
+
+ - Function: keymap-prompt KEYMAP &optional USE-INHERITED
+ This function returns the "prompt" of the given keymap. If
+ USE-INHERITED is non-`nil', any parent keymaps will also be
+ searched for a prompt.
+
+\1f
+File: lispref.info, Node: Menus, Next: Dialog Boxes, Prev: Keymaps, Up: Top
+
+Menus
+*****
+
+* Menu:
+
+* Menu Format:: Format of a menu description.
+* Menubar Format:: How to specify a menubar.
+* Menubar:: Functions for controlling the menubar.
+* Modifying Menus:: Modifying a menu description.
+* Pop-Up Menus:: Functions for specifying pop-up menus.
+* Menu Filters:: Filter functions for the default menubar.
+* Menu Accelerators:: Using and controlling menu accelerator keys
+* Buffers Menu:: The menu that displays the list of buffers.
+
+\1f
+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 ]
+ )
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top
+
+GNU GENERAL PUBLIC LICENSE
+**************************
+
+ Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+ 675 Mass Ave, Cambridge, MA 02139, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+Preamble
+========
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License applies to any program or other work which contains a
+ notice placed by the copyright holder saying it may be distributed
+ under the terms of this General Public License. The "Program",
+ below, refers to any such program or work, and a "work based on
+ the Program" means either the Program or any derivative work under
+ copyright law: that is to say, a work containing the Program or a
+ portion of it, either verbatim or with modifications and/or
+ translated into another language. (Hereinafter, translation is
+ included without limitation in the term "modification".) Each
+ licensee is addressed as "you".
+
+ Activities other than copying, distribution and modification are
+ not covered by this License; they are outside its scope. The act
+ of running the Program is not restricted, and the output from the
+ Program is covered only if its contents constitute a work based on
+ the Program (independent of having been made by running the
+ Program). Whether that is true depends on what the Program does.
+
+ 1. You may copy and distribute verbatim copies of the Program's
+ source code as you receive it, in any medium, provided that you
+ conspicuously and appropriately publish on each copy an appropriate
+ copyright notice and disclaimer of warranty; keep intact all the
+ notices that refer to this License and to the absence of any
+ warranty; and give any other recipients of the Program a copy of
+ this License along with the Program.
+
+ You may charge a fee for the physical act of transferring a copy,
+ and you may at your option offer warranty protection in exchange
+ for a fee.
+
+ 2. You may modify your copy or copies of the Program or any portion
+ of it, thus forming a work based on the Program, and copy and
+ distribute such modifications or work under the terms of Section 1
+ above, provided that you also meet all of these conditions:
+
+ a. You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b. You must cause any work that you distribute or publish, that
+ in whole or in part contains or is derived from the Program
+ or any part thereof, to be licensed as a whole at no charge
+ to all third parties under the terms of this License.
+
+ c. If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display
+ an announcement including an appropriate copyright notice and
+ a notice that there is no warranty (or else, saying that you
+ provide a warranty) and that users may redistribute the
+ program under these conditions, and telling the user how to
+ view a copy of this License. (Exception: if the Program
+ itself is interactive but does not normally print such an
+ announcement, your work based on the Program is not required
+ to print an announcement.)
+
+ These requirements apply to the modified work as a whole. If
+ identifiable sections of that work are not derived from the
+ Program, and can be reasonably considered independent and separate
+ works in themselves, then this License, and its terms, do not
+ apply to those sections when you distribute them as separate
+ works. But when you distribute the same sections as part of a
+ whole which is a work based on the Program, the distribution of
+ the whole must be on the terms of this License, whose permissions
+ for other licensees extend to the entire whole, and thus to each
+ and every part regardless of who wrote it.
+
+ Thus, it is not the intent of this section to claim rights or
+ contest your rights to work written entirely by you; rather, the
+ intent is to exercise the right to control the distribution of
+ derivative or collective works based on the Program.
+
+ In addition, mere aggregation of another work not based on the
+ Program with the Program (or with a work based on the Program) on
+ a volume of a storage or distribution medium does not bring the
+ other work under the scope of this License.
+
+ 3. You may copy and distribute the Program (or a work based on it,
+ under Section 2) in object code or executable form under the terms
+ of Sections 1 and 2 above provided that you also do one of the
+ following:
+
+ a. Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of
+ Sections 1 and 2 above on a medium customarily used for
+ software interchange; or,
+
+ b. Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your
+ cost of physically performing source distribution, a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a
+ medium customarily used for software interchange; or,
+
+ c. Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with
+ such an offer, in accord with Subsection b above.)
+
+ The source code for a work means the preferred form of the work for
+ making modifications to it. For an executable work, complete
+ source code means all the source code for all modules it contains,
+ plus any associated interface definition files, plus the scripts
+ used to control compilation and installation of the executable.
+ However, as a special exception, the source code distributed need
+ not include anything that is normally distributed (in either
+ source or binary form) with the major components (compiler,
+ kernel, and so on) of the operating system on which the executable
+ runs, unless that component itself accompanies the executable.
+
+ If distribution of executable or object code is made by offering
+ access to copy from a designated place, then offering equivalent
+ access to copy the source code from the same place counts as
+ distribution of the source code, even though third parties are not
+ compelled to copy the source along with the object code.
+
+ 4. You may not copy, modify, sublicense, or distribute the Program
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense or distribute the Program is
+ void, and will automatically terminate your rights under this
+ License. However, parties who have received copies, or rights,
+ from you under this License will not have their licenses
+ terminated so long as such parties remain in full compliance.
+
+ 5. You are not required to accept this License, since you have not
+ signed it. However, nothing else grants you permission to modify
+ or distribute the Program or its derivative works. These actions
+ are prohibited by law if you do not accept this License.
+ Therefore, by modifying or distributing the Program (or any work
+ based on the Program), you indicate your acceptance of this
+ License to do so, and all its terms and conditions for copying,
+ distributing or modifying the Program or works based on it.
+
+ 6. Each time you redistribute the Program (or any work based on the
+ Program), the recipient automatically receives a license from the
+ original licensor to copy, distribute or modify the Program
+ subject to these terms and conditions. You may not impose any
+ further restrictions on the recipients' exercise of the rights
+ granted herein. You are not responsible for enforcing compliance
+ by third parties to this License.
+
+ 7. If, as a consequence of a court judgment or allegation of patent
+ infringement or for any other reason (not limited to patent
+ issues), conditions are imposed on you (whether by court order,
+ agreement or otherwise) that contradict the conditions of this
+ License, they do not excuse you from the conditions of this
+ License. If you cannot distribute so as to satisfy simultaneously
+ your obligations under this License and any other pertinent
+ obligations, then as a consequence you may not distribute the
+ Program at all. For example, if a patent license would not permit
+ royalty-free redistribution of the Program by all those who
+ receive copies directly or indirectly through you, then the only
+ way you could satisfy both it and this License would be to refrain
+ entirely from distribution of the Program.
+
+ If any portion of this section is held invalid or unenforceable
+ under any particular circumstance, the balance of the section is
+ intended to apply and the section as a whole is intended to apply
+ in other circumstances.
+
+ It is not the purpose of this section to induce you to infringe any
+ patents or other property right claims or to contest validity of
+ any such claims; this section has the sole purpose of protecting
+ the integrity of the free software distribution system, which is
+ implemented by public license practices. Many people have made
+ generous contributions to the wide range of software distributed
+ through that system in reliance on consistent application of that
+ system; it is up to the author/donor to decide if he or she is
+ willing to distribute software through any other system and a
+ licensee cannot impose that choice.
+
+ This section is intended to make thoroughly clear what is believed
+ to be a consequence of the rest of this License.
+
+ 8. If the distribution and/or use of the Program is restricted in
+ certain countries either by patents or by copyrighted interfaces,
+ the original copyright holder who places the Program under this
+ License may add an explicit geographical distribution limitation
+ excluding those countries, so that distribution is permitted only
+ in or among countries not thus excluded. In such case, this
+ License incorporates the limitation as if written in the body of
+ this License.
+
+ 9. The Free Software Foundation may publish revised and/or new
+ versions of the General Public License from time to time. Such
+ new versions will be similar in spirit to the present version, but
+ may differ in detail to address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+ Program specifies a version number of this License which applies
+ to it and "any later version", you have the option of following
+ the terms and conditions either of that version or of any later
+ version published by the Free Software Foundation. If the Program
+ does not specify a version number of this License, you may choose
+ any version ever published by the Free Software Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+ programs whose distribution conditions are different, write to the
+ author to ask for permission. For software which is copyrighted
+ by the Free Software Foundation, write to the Free Software
+ Foundation; we sometimes make exceptions for this. Our decision
+ will be guided by the two goals of preserving the free status of
+ all derivatives of our free software and of promoting the sharing
+ and reuse of software generally.
+
+ NO WARRANTY
+
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+ WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+ LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+ HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+ WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+ NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
+ QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+ PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+ SERVICING, REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+ WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+ MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+ LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+ INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+ INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+ DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+ OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+ OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+=============================================
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+ ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
+ Copyright (C) 19YY NAME OF AUTHOR
+
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version 2
+ of the License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+ Also add information on how to contact you by electronic and paper
+mail.
+
+ If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+ type `show w'. This is free software, and you are welcome
+ to redistribute it under certain conditions; type `show c'
+ for details.
+
+ The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+ You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright
+ interest in the program `Gnomovision'
+ (which makes passes at compilers) written
+ by James Hacker.
+
+ SIGNATURE OF TY COON, 1 April 1989
+ Ty Coon, President of Vice
+
+ This General Public License does not permit incorporating your
+program into proprietary programs. If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library. If this is what you want to do, use the
+GNU Library General Public License instead of this License.
+
+\1f
+File: lispref.info, Node: Introduction, Next: Lisp Data Types, Prev: Copying, Up: Top
+
+Introduction
+************
+
+ Most of the XEmacs text editor is written in the programming
+language called XEmacs Lisp. You can write new code in XEmacs Lisp and
+install it as an extension to the editor. However, XEmacs Lisp is more
+than a mere "extension language"; it is a full computer programming
+language in its own right. You can use it as you would any other
+programming language.
+
+ Because XEmacs Lisp is designed for use in an editor, it has special
+features for scanning and parsing text as well as features for handling
+files, buffers, displays, subprocesses, and so on. XEmacs Lisp is
+closely integrated with the editing facilities; thus, editing commands
+are functions that can also conveniently be called from Lisp programs,
+and parameters for customization are ordinary Lisp variables.
+
+ This manual describes XEmacs Lisp, presuming considerable familiarity
+with the use of XEmacs for editing. (See `The XEmacs Reference
+Manual', for this basic information.) Generally speaking, the earlier
+chapters describe features of XEmacs Lisp that have counterparts in many
+programming languages, and later chapters describe features that are
+peculiar to XEmacs Lisp or relate specifically to editing.
+
+ This is edition 3.3.
+
+* Menu:
+
+* Caveats:: Flaws and a request for help.
+* Lisp History:: XEmacs Lisp is descended from Maclisp.
+* Conventions:: How the manual is formatted.
+* Acknowledgements:: The authors, editors, and sponsors of this manual.
+
+\1f
+File: lispref.info, Node: Caveats, Next: Lisp History, Up: Introduction
+
+Caveats
+=======
+
+ This manual has gone through numerous drafts. It is nearly complete
+but not flawless. There are a few topics that are not covered, either
+because we consider them secondary (such as most of the individual
+modes) or because they are yet to be written. Because we are not able
+to deal with them completely, we have left out several parts
+intentionally. This includes most information about usage on VMS.
+
+ The manual should be fully correct in what it does cover, and it is
+therefore open to criticism on anything it says--from specific examples
+and descriptive text, to the ordering of chapters and sections. If
+something is confusing, or you find that you have to look at the sources
+or experiment to learn something not covered in the manual, then perhaps
+the manual should be fixed. Please let us know.
+
+ As you use this manual, we ask that you send corrections as soon as
+you find them. If you think of a simple, real life example for a
+function or group of functions, please make an effort to write it up
+and send it in. Please reference any comments to the node name and
+function or variable name, as appropriate. Also state the number of
+the edition which you are criticizing.
+
+ This manual was originally written for FSF Emacs 19 and was updated
+by Ben Wing (wing@666.com) for Lucid Emacs 19.10 and later for XEmacs
+19.12, 19.13, 19.14, and 20.0. It was further updated by the XEmacs
+Development Team for 19.15 and 20.1. Please send comments and
+corrections relating to XEmacs-specific portions of this manual to
+ xemacs@xemacs.org
+
+ or post to the newsgroup
+ comp.emacs.xemacs
+
+ --Ben Wing
+
+\1f
+File: lispref.info, Node: Lisp History, Next: Conventions, Prev: Caveats, Up: Introduction
+
+Lisp History
+============
+
+ Lisp (LISt Processing language) was first developed in the late
+1950's at the Massachusetts Institute of Technology for research in
+artificial intelligence. The great power of the Lisp language makes it
+superior for other purposes as well, such as writing editing commands.
+
+ Dozens of Lisp implementations have been built over the years, each
+with its own idiosyncrasies. Many of them were inspired by Maclisp,
+which was written in the 1960's at MIT's Project MAC. Eventually the
+implementors of the descendants of Maclisp came together and developed a
+standard for Lisp systems, called Common Lisp.
+
+ XEmacs Lisp is largely inspired by Maclisp, and a little by Common
+Lisp. If you know Common Lisp, you will notice many similarities.
+However, many of the features of Common Lisp have been omitted or
+simplified in order to reduce the memory requirements of XEmacs.
+Sometimes the simplifications are so drastic that a Common Lisp user
+might be very confused. We will occasionally point out how XEmacs Lisp
+differs from Common Lisp. If you don't know Common Lisp, don't worry
+about it; this manual is self-contained.
+
+\1f
+File: lispref.info, Node: Conventions, Next: Acknowledgements, Prev: Lisp History, Up: Introduction
+
+Conventions
+===========
+
+ This section explains the notational conventions that are used in
+this manual. You may want to skip this section and refer back to it
+later.
+
+* Menu:
+
+* Some Terms:: Explanation of terms we use in this manual.
+* nil and t:: How the symbols `nil' and `t' are used.
+* Evaluation Notation:: The format we use for examples of evaluation.
+* Printing Notation:: The format we use for examples that print output.
+* Error Messages:: The format we use for examples of errors.
+* Buffer Text Notation:: The format we use for buffer contents in examples.
+* Format of Descriptions:: Notation for describing functions, variables, etc.
+
+\1f
+File: lispref.info, Node: Some Terms, Next: nil and t, Up: Conventions
+
+Some Terms
+----------
+
+ Throughout this manual, the phrases "the Lisp reader" and "the Lisp
+printer" are used to refer to those routines in Lisp that convert
+textual representations of Lisp objects into actual Lisp objects, and
+vice versa. *Note Printed Representation::, for more details. You, the
+person reading this manual, are thought of as "the programmer" and are
+addressed as "you". "The user" is the person who uses Lisp programs,
+including those you write.
+
+ Examples of Lisp code appear in this font or form: `(list 1 2 3)'.
+Names that represent arguments or metasyntactic variables appear in
+this font or form: FIRST-NUMBER.
+
+\1f
+File: lispref.info, Node: nil and t, Next: Evaluation Notation, Prev: Some Terms, Up: Conventions
+
+`nil' and `t'
+-------------
+
+ In Lisp, the symbol `nil' has three separate meanings: it is a
+symbol with the name `nil'; it is the logical truth value FALSE; and it
+is the empty list--the list of zero elements. When used as a variable,
+`nil' always has the value `nil'.
+
+ As far as the Lisp reader is concerned, `()' and `nil' are
+identical: they stand for the same object, the symbol `nil'. The
+different ways of writing the symbol are intended entirely for human
+readers. After the Lisp reader has read either `()' or `nil', there is
+no way to determine which representation was actually written by the
+programmer.
+
+ In this manual, we use `()' when we wish to emphasize that it means
+the empty list, and we use `nil' when we wish to emphasize that it
+means the truth value FALSE. That is a good convention to use in Lisp
+programs also.
+
+ (cons 'foo ()) ; Emphasize the empty list
+ (not nil) ; Emphasize the truth value FALSE
+
+ In contexts where a truth value is expected, any non-`nil' value is
+considered to be TRUE. However, `t' is the preferred way to represent
+the truth value TRUE. When you need to choose a value which represents
+TRUE, and there is no other basis for choosing, use `t'. The symbol
+`t' always has value `t'.
+
+ In XEmacs Lisp, `nil' and `t' are special symbols that always
+evaluate to themselves. This is so that you do not need to quote them
+to use them as constants in a program. An attempt to change their
+values results in a `setting-constant' error. *Note Accessing
+Variables::.
+
+\1f
+File: lispref.info, Node: Evaluation Notation, Next: Printing Notation, Prev: nil and t, Up: Conventions
+
+Evaluation Notation
+-------------------
+
+ A Lisp expression that you can evaluate is called a "form".
+Evaluating a form always produces a result, which is a Lisp object. In
+the examples in this manual, this is indicated with `=>':
+
+ (car '(1 2))
+ => 1
+
+You can read this as "`(car '(1 2))' evaluates to 1".
+
+ When a form is a macro call, it expands into a new form for Lisp to
+evaluate. We show the result of the expansion with `==>'. We may or
+may not show the actual result of the evaluation of the expanded form.
+
+ (news-cadr '(a b c))
+ ==> (car (cdr '(a b c)))
+ => b
+
+ Sometimes to help describe one form we show another form that
+produces identical results. The exact equivalence of two forms is
+indicated with `=='.
+
+ (cons 'a nil) == (list 'a)
+
+\1f
+File: lispref.info, Node: Printing Notation, Next: Error Messages, Prev: Evaluation Notation, Up: Conventions
+
+Printing Notation
+-----------------
+
+ Many of the examples in this manual print text when they are
+evaluated. If you execute example code in a Lisp Interaction buffer
+(such as the buffer `*scratch*'), the printed text is inserted into the
+buffer. If you execute the example by other means (such as by
+evaluating the function `eval-region'), the printed text is displayed
+in the echo area. You should be aware that text displayed in the echo
+area is truncated to a single line.
+
+ Examples in this manual indicate printed text with `-|',
+irrespective of where that text goes. The value returned by evaluating
+the form (here `bar') follows on a separate line.
+
+ (progn (print 'foo) (print 'bar))
+ -| foo
+ -| bar
+ => bar
+
+\1f
+File: lispref.info, Node: Error Messages, Next: Buffer Text Notation, Prev: Printing Notation, Up: Conventions
+
+Error Messages
+--------------
+
+ Some examples signal errors. This normally displays an error message
+in the echo area. We show the error message on a line starting with
+`error-->'. Note that `error-->' itself does not appear in the echo
+area.
+
+ (+ 23 'x)
+ error--> Wrong type argument: integer-or-marker-p, x
+
+\1f
+File: lispref.info, Node: Buffer Text Notation, Next: Format of Descriptions, Prev: Error Messages, Up: Conventions
+
+Buffer Text Notation
+--------------------
+
+ Some examples show modifications to text in a buffer, with "before"
+and "after" versions of the text. These examples show the contents of
+the buffer in question between two lines of dashes containing the buffer
+name. In addition, `-!-' indicates the location of point. (The symbol
+for point, of course, is not part of the text in the buffer; it
+indicates the place *between* two characters where point is located.)
+
+ ---------- Buffer: foo ----------
+ This is the -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ => nil
+ ---------- Buffer: foo ----------
+ This is the changed -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+\1f
+File: lispref.info, Node: Format of Descriptions, Prev: Buffer Text Notation, Up: Conventions
+
+Format of Descriptions
+----------------------
+
+ Functions, variables, macros, commands, user options, and special
+forms are described in this manual in a uniform format. The first line
+of a description contains the name of the item followed by its
+arguments, if any. The category--function, variable, or
+whatever--appears at the beginning of the line. The description
+follows on succeeding lines, sometimes with examples.
+
+* Menu:
+
+* A Sample Function Description:: A description of an imaginary
+ function, `foo'.
+* A Sample Variable Description:: A description of an imaginary
+ variable,
+ `electric-future-map'.
+
+\1f
+File: lispref.info, Node: A Sample Function Description, Next: A Sample Variable Description, Up: Format of Descriptions
+
+A Sample Function Description
+.............................
+
+ In a function description, the name of the function being described
+appears first. It is followed on the same line by a list of parameters.
+The names used for the parameters are also used in the body of the
+description.
+
+ The appearance of the keyword `&optional' in the parameter list
+indicates that the arguments for subsequent parameters may be omitted
+(omitted parameters default to `nil'). Do not write `&optional' when
+you call the function.
+
+ The keyword `&rest' (which will always be followed by a single
+parameter) indicates that any number of arguments can follow. The value
+of the single following parameter will be a list of all these arguments.
+Do not write `&rest' when you call the function.
+
+ Here is a description of an imaginary function `foo':
+
+ - Function: foo INTEGER1 &optional INTEGER2 &rest INTEGERS
+ The function `foo' subtracts INTEGER1 from INTEGER2, then adds all
+ the rest of the arguments to the result. If INTEGER2 is not
+ supplied, then the number 19 is used by default.
+
+ (foo 1 5 3 9)
+ => 16
+ (foo 5)
+ => 14
+
+ More generally,
+
+ (foo W X Y...)
+ ==
+ (+ (- X W) Y...)
+
+ Any parameter whose name contains the name of a type (e.g., INTEGER,
+INTEGER1 or BUFFER) is expected to be of that type. A plural of a type
+(such as BUFFERS) often means a list of objects of that type.
+Parameters named OBJECT may be of any type. (*Note Lisp Data Types::,
+for a list of XEmacs object types.) Parameters with other sorts of
+names (e.g., NEW-FILE) are discussed specifically in the description of
+the function. In some sections, features common to parameters of
+several functions are described at the beginning.
+
+ *Note Lambda Expressions::, for a more complete description of
+optional and rest arguments.
+
+ Command, macro, and special form descriptions have the same format,
+but the word `Function' is replaced by `Command', `Macro', or `Special
+Form', respectively. Commands are simply functions that may be called
+interactively; macros process their arguments differently from functions
+(the arguments are not evaluated), but are presented the same way.
+
+ Special form descriptions use a more complex notation to specify
+optional and repeated parameters because they can break the argument
+list down into separate arguments in more complicated ways.
+``[OPTIONAL-ARG]'' means that OPTIONAL-ARG is optional and
+`REPEATED-ARGS...' stands for zero or more arguments. Parentheses are
+used when several arguments are grouped into additional levels of list
+structure. Here is an example:
+
+ - Special Form: count-loop (VAR [FROM TO [INC]]) BODY...
+ This imaginary special form implements a loop that executes the
+ BODY forms and then increments the variable VAR on each iteration.
+ On the first iteration, the variable has the value FROM; on
+ subsequent iterations, it is incremented by 1 (or by INC if that
+ is given). The loop exits before executing BODY if VAR equals TO.
+ Here is an example:
+
+ (count-loop (i 0 10)
+ (prin1 i) (princ " ")
+ (prin1 (aref vector i)) (terpri))
+
+ If FROM and TO are omitted, then VAR is bound to `nil' before the
+ loop begins, and the loop exits if VAR is non-`nil' at the
+ beginning of an iteration. Here is an example:
+
+ (count-loop (done)
+ (if (pending)
+ (fixit)
+ (setq done t)))
+
+ In this special form, the arguments FROM and TO are optional, but
+ must both be present or both absent. If they are present, INC may
+ optionally be specified as well. These arguments are grouped with
+ the argument VAR into a list, to distinguish them from BODY, which
+ includes all remaining elements of the form.
+
+\1f
+File: lispref.info, Node: A Sample Variable Description, Prev: A Sample Function Description, Up: Format of Descriptions
+
+A Sample Variable Description
+.............................
+
+ A "variable" is a name that can hold a value. Although any variable
+can be set by the user, certain variables that exist specifically so
+that users can change them are called "user options". Ordinary
+variables and user options are described using a format like that for
+functions except that there are no arguments.
+
+ Here is a description of the imaginary `electric-future-map'
+variable.
+
+ - Variable: electric-future-map
+ The value of this variable is a full keymap used by Electric
+ Command Future mode. The functions in this map allow you to edit
+ commands you have not yet thought about executing.
+
+ User option descriptions have the same format, but `Variable' is
+replaced by `User Option'.
+
+\1f
+File: lispref.info, Node: Acknowledgements, Prev: Conventions, Up: Introduction
+
+Acknowledgements
+================
+
+ This manual was based on the GNU Emacs Lisp Reference Manual, version
+2.4, written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M.
+Stallman and Chris Welty, the volunteers of the GNU manual group, in an
+effort extending over several years. Robert J. Chassell helped to
+review and edit the manual, with the support of the Defense Advanced
+Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt,
+Jr. of Computational Logic, Inc.
+
+ Ben Wing adapted this manual for XEmacs 19.14 and 20.0, and earlier
+for Lucid Emacs 19.10, XEmacs 19.12, and XEmacs 19.13. He is the sole
+author of many of the manual sections, in particular the XEmacs-specific
+sections: events, faces, extents, glyphs, specifiers, toolbar, menubars,
+scrollbars, dialog boxes, devices, consoles, hash tables, range tables,
+char tables, databases, and others. The section on annotations was
+originally written by Chuck Thompson. Corrections to v3.1 and later
+were done by Martin Buchholz, Steve Baur, and Hrvoje Niksic.
+
+ Corrections to the original GNU Emacs Lisp Reference Manual were
+supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David
+Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch,
+David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf
+Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow,
+George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman,
+Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard
+Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner
+Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim,
+Arnold D. Robbins, Raul Rockwell, Per Starback, Shinichirou Sugou, Kimmo
+Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew
+Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
+
+\1f
+File: lispref.info, Node: Lisp Data Types, Next: Numbers, Prev: Introduction, Up: Top
+
+Lisp Data Types
+***************
+
+ A Lisp "object" is a piece of data used and manipulated by Lisp
+programs. For our purposes, a "type" or "data type" is a set of
+possible objects.
+
+ Every object belongs to at least one type. Objects of the same type
+have similar structures and may usually be used in the same contexts.
+Types can overlap, and objects can belong to two or more types.
+Consequently, we can ask whether an object belongs to a particular type,
+but not for "the" type of an object.
+
+ A few fundamental object types are built into XEmacs. These, from
+which all other types are constructed, are called "primitive types".
+Each object belongs to one and only one primitive type. These types
+include "integer", "character" (starting with XEmacs 20.0), "float",
+"cons", "symbol", "string", "vector", "bit-vector", "subr",
+"compiled-function", "hash-table", "range-table", "char-table",
+"weak-list", and several special types, such as "buffer", that are
+related to editing. (*Note Editing Types::.)
+
+ Each primitive type has a corresponding Lisp function that checks
+whether an object is a member of that type.
+
+ Note that Lisp is unlike many other languages in that Lisp objects
+are "self-typing": the primitive type of the object is implicit in the
+object itself. For example, if an object is a vector, nothing can treat
+it as a number; Lisp knows it is a vector, not a number.
+
+ In most languages, the programmer must declare the data type of each
+variable, and the type is known by the compiler but not represented in
+the data. Such type declarations do not exist in XEmacs Lisp. A Lisp
+variable can have any type of value, and it remembers whatever value
+you store in it, type and all.
+
+ This chapter describes the purpose, printed representation, and read
+syntax of each of the standard types in Emacs Lisp. Details on how to
+use these types can be found in later chapters.
+
+* Menu:
+
+* Printed Representation:: How Lisp objects are represented as text.
+* Comments:: Comments and their formatting conventions.
+* Primitive Types:: List of all primitive types in XEmacs.
+* Programming Types:: Types found in all Lisp systems.
+* Editing Types:: Types specific to XEmacs.
+* Window-System Types:: Types specific to windowing systems.
+* Type Predicates:: Tests related to types.
+* Equality Predicates:: Tests of equality between any two objects.
+
+\1f
+File: lispref.info, Node: Printed Representation, Next: Comments, Up: Lisp Data Types
+
+Printed Representation and Read Syntax
+======================================
+
+ The "printed representation" of an object is the format of the
+output generated by the Lisp printer (the function `prin1') for that
+object. The "read syntax" of an object is the format of the input
+accepted by the Lisp reader (the function `read') for that object.
+Most objects have more than one possible read syntax. Some types of
+object have no read syntax; except for these cases, the printed
+representation of an object is also a read syntax for it.
+
+ In other languages, an expression is text; it has no other form. In
+Lisp, an expression is primarily a Lisp object and only secondarily the
+text that is the object's read syntax. Often there is no need to
+emphasize this distinction, but you must keep it in the back of your
+mind, or you will occasionally be very confused.
+
+ Every type has a printed representation. Some types have no read
+syntax, since it may not make sense to enter objects of these types
+directly in a Lisp program. For example, the buffer type does not have
+a read syntax. Objects of these types are printed in "hash notation":
+the characters `#<' followed by a descriptive string (typically the
+type name followed by the name of the object), and closed with a
+matching `>'. Hash notation cannot be read at all, so the Lisp reader
+signals the error `invalid-read-syntax' whenever it encounters `#<'.
+
+ (current-buffer)
+ => #<buffer "objects.texi">
+
+ When you evaluate an expression interactively, the Lisp interpreter
+first reads the textual representation of it, producing a Lisp object,
+and then evaluates that object (*note Evaluation::.). However,
+evaluation and reading are separate activities. Reading returns the
+Lisp object represented by the text that is read; the object may or may
+not be evaluated later. *Note Input Functions::, for a description of
+`read', the basic function for reading objects.
+
+\1f
+File: lispref.info, Node: Comments, Next: Primitive Types, Prev: Printed Representation, Up: Lisp Data Types
+
+Comments
+========
+
+ A "comment" is text that is written in a program only for the sake
+of humans that read the program, and that has no effect on the meaning
+of the program. In Lisp, a semicolon (`;') starts a comment if it is
+not within a string or character constant. The comment continues to
+the end of line. The Lisp reader discards comments; they do not become
+part of the Lisp objects which represent the program within the Lisp
+system.
+
+ The `#@COUNT' construct, which skips the next COUNT characters, is
+useful for program-generated comments containing binary data. The
+XEmacs Lisp byte compiler uses this in its output files (*note Byte
+Compilation::.). It isn't meant for source files, however.
+
+ *Note Comment Tips::, for conventions for formatting comments.
+
+\1f
+File: lispref.info, Node: Primitive Types, Next: Programming Types, Prev: Comments, Up: Lisp Data Types
+
+Primitive Types
+===============
+
+ For reference, here is a list of all the primitive types that may
+exist in XEmacs. Note that some of these types may not exist in some
+XEmacs executables; that depends on the options that XEmacs was
+configured with.
+
+ * bit-vector
+
+ * buffer
+
+ * char-table
+
+ * character
+
+ * charset
+
+ * coding-system
+
+ * cons
+
+ * color-instance
+
+ * compiled-function
+
+ * console
+
+ * database
+
+ * device
+
+ * event
+
+ * extent
+
+ * face
+
+ * float
+
+ * font-instance
+
+ * frame
+
+ * glyph
+
+ * hash-table
+
+ * image-instance
+
+ * integer
+
+ * keymap
+
+ * marker
+
+ * process
+
+ * range-table
+
+ * specifier
+
+ * string
+
+ * subr
+
+ * subwindow
+
+ * symbol
+
+ * toolbar-button
+
+ * tooltalk-message
+
+ * tooltalk-pattern
+
+ * vector
+
+ * weak-list
+
+ * window
+
+ * window-configuration
+
+ * x-resource
+
+ In addition, the following special types are created internally but
+will never be seen by Lisp code. You may encounter them, however, if
+you are debugging XEmacs. The printed representation of these objects
+begins `#<INTERNAL EMACS BUG', which indicates to the Lisp programmer
+that he has found an internal bug in XEmacs if he ever encounters any
+of these objects.
+
+ * char-table-entry
+
+ * command-builder
+
+ * extent-auxiliary
+
+ * extent-info
+
+ * lcrecord-list
+
+ * lstream
+
+ * opaque
+
+ * opaque-list
+
+ * popup-data
+
+ * symbol-value-buffer-local
+
+ * symbol-value-forward
+
+ * symbol-value-lisp-magic
+
+ * symbol-value-varalias
+
+ * toolbar-data
+
+\1f
+File: lispref.info, Node: Programming Types, Next: Editing Types, Prev: Primitive Types, Up: Lisp Data Types
+
+Programming Types
+=================
+
+ There are two general categories of types in XEmacs Lisp: those
+having to do with Lisp programming, and those having to do with
+editing. The former exist in many Lisp implementations, in one form or
+another. The latter are unique to XEmacs Lisp.
+
+* Menu:
+
+* Integer Type:: Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type:: The representation of letters, numbers and
+ control characters.
+* Symbol Type:: A multi-use object that refers to a function,
+ variable, or property list, and has a unique identity.
+* Sequence Type:: Both lists and arrays are classified as sequences.
+* Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
+* Array Type:: Arrays include strings and vectors.
+* String Type:: An (efficient) array of characters.
+* Vector Type:: One-dimensional arrays.
+* Bit Vector Type:: An (efficient) array of bits.
+* Function Type:: A piece of executable code you can call from elsewhere.
+* Macro Type:: A method of expanding an expression into another
+ expression, more fundamental but less pretty.
+* Primitive Function Type:: A function written in C, callable from Lisp.
+* Compiled-Function Type:: A function written in Lisp, then compiled.
+* Autoload Type:: A type used for automatically loading seldom-used
+ functions.
+* Char Table Type:: A mapping from characters to Lisp objects.
+* Hash Table Type:: A fast mapping between Lisp objects.
+* Range Table Type:: A mapping from ranges of integers to Lisp objects.
+* Weak List Type:: A list with special garbage-collection properties.
+
+\1f
+File: lispref.info, Node: Integer Type, Next: Floating Point Type, Up: Programming Types
+
+Integer Type
+------------
+
+ The range of values for integers in XEmacs Lisp is -134217728 to
+134217727 (28 bits; i.e., -2**27 to 2**27 - 1) on most machines. (Some
+machines, in particular 64-bit machines such as the DEC Alpha, may
+provide a wider range.) It is important to note that the XEmacs Lisp
+arithmetic functions do not check for overflow. Thus `(1+ 134217727)'
+is -134217728 on most machines. (However, you *will* get an error if
+you attempt to read an out-of-range number using the Lisp reader.)
+
+ The read syntax for integers is a sequence of (base ten) digits with
+an optional sign at the beginning. (The printed representation produced
+by the Lisp interpreter never has a leading `+'.)
+
+ -1 ; The integer -1.
+ 1 ; The integer 1.
+ +1 ; Also the integer 1.
+ 268435457 ; Causes an error on a 28-bit implementation.
+
+ *Note Numbers::, for more information.
+
+\1f
+File: lispref.info, Node: Floating Point Type, Next: Character Type, Prev: Integer Type, Up: Programming Types
+
+Floating Point Type
+-------------------
+
+ XEmacs supports floating point numbers. The precise range of
+floating point numbers is machine-specific.
+
+ The printed representation for floating point numbers requires either
+a decimal point (with at least one digit following), an exponent, or
+both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
+are five ways of writing a floating point number whose value is 1500.
+They are all equivalent.
+
+ *Note Numbers::, for more information.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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-up-p
+ This function returns `t' if a pop-up menu is up, `nil' otherwise.
+
+ - Variable: popup-menu-titles
+ If true (the default), pop-up menus will have title bars at the
+ top.
+
+ Some machinery is provided that attempts to provide a higher-level
+mechanism onto pop-up menus. This only works if you do not redefine
+the binding for button3.
+
+ - Command: popup-mode-menu
+ This function pops up a menu of global and mode-specific commands.
+ The menu is computed by combining `global-popup-menu' and
+ `mode-popup-menu'. This is the default binding for button3. You
+ should generally not change this binding.
+
+ - Variable: global-popup-menu
+ This holds the global popup menu. This is present in all modes.
+ (This is `nil' by default.)
+
+ - Variable: mode-popup-menu
+ The mode-specific popup menu. Automatically buffer local. This
+ is appended to the default items in `global-popup-menu'.
+
+ - Constant: default-popup-menu
+ This holds the default value of `mode-popup-menu'.
+
+ - Variable: activate-popup-menu-hook
+ Function or functions run before a mode-specific popup menu is made
+ visible. These functions are called with no arguments, and should
+ interrogate and modify the value of `global-popup-menu' or
+ `mode-popup-menu' as desired. Note: this hook is only run if you
+ use `popup-mode-menu' for activating the global and mode-specific
+ commands; if you have your own binding for button3, this hook
+ won't be run.
+
+ The following convenience functions are provided for displaying
+pop-up menus.
+
+ - Function: popup-buffer-menu EVENT
+ This function pops up a copy of the `Buffers' menu (from the
+ menubar) where the mouse is clicked.
+
+ - Function: popup-menubar-menu EVENT
+ This function pops up a copy of menu that also appears in the
+ menubar.
+
+\1f
+File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus
+
+Menu Accelerators
+=================
+
+ Menu accelerators are keyboard shortcuts for accessing the menubar.
+Accelerator keys can be specified for menus as well as for menu items.
+An accelerator key for a menu is used to activate that menu when it
+appears as a submenu of another menu. An accelerator key for a menu
+item is used to activate that item.
+
+* Menu:
+
+* Creating Menu Accelerators:: How to add accelerator keys to a menu.
+* Keyboard Menu Traversal:: How to use and modify the keys which are used
+ to traverse the menu structure.
+* Menu Accelerator Functions:: Functions for working with menu accelerators.
+
+\1f
+File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators
+
+Creating Menu Accelerators
+--------------------------
+
+ Menu accelerators are specified as part of the menubar format using
+the :accelerator tag to specify a key or by placing "%_" in the menu or
+menu item name prior to the letter which is to be used as the
+accelerator key. The advantage of the second method is that the menu
+rendering code then knows to draw an underline under that character,
+which is the canonical way of indicating an accelerator key to a user.
+
+ For example, the command
+
+ (add-submenu nil '("%_Test"
+ ["One" (insert "1") :accelerator ?1 :active t]
+ ["%_Two" (insert "2")]
+ ["%_3" (insert "3")]))
+
+ will add a new menu to the top level menubar. The new menu can be
+reached by pressing "t" while the top level menubar is active. When
+the menu is active, pressing "1" will activate the first item and
+insert the character "1" into the buffer. Pressing "2" will activate
+the second item and insert the character "2" into the buffer. Pressing
+"3" will activate the third item and insert the character "3" into the
+buffer.
+
+ It is possible to activate the top level menubar itself using
+accelerator keys. *Note Menu Accelerator Functions::.
+
+\1f
+File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators
+
+Keyboard Menu Traversal
+-----------------------
+
+ In addition to immediately activating a menu or menu item, the
+keyboard can be used to traverse the menus without activating items.
+The keyboard arrow keys, the return key and the escape key are defined
+to traverse the menus in a way that should be familiar to users of any
+of a certain family of popular PC operating systems.
+
+ This behavior can be changed by modifying the bindings in
+menu-accelerator-map. At this point, the online help is your best bet
+for more information about how to modify the menu traversal keys.
+
+\1f
+File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators
+
+Menu Accelerator Functions
+--------------------------
+
+ - Function: 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.
+
+ - Variable: menu-accelerator-enabled
+ Whether menu accelerator keys can cause the menubar to become
+ active.
+
+ If `menu-force' or `menu-fallback', then menu accelerator keys can
+ be used to activate the top level menu. Once the menubar becomes
+ active, the accelerator keys can be used regardless of the value
+ of this variable.
+
+ `menu-force' is used to indicate that the menu accelerator key
+ takes precedence over bindings in the current keymap(s).
+ `menu-fallback' means that bindings in the current keymap take
+ precedence over menu accelerator keys. Thus a top level menu with
+ an accelerator of "T" would be activated on a keypress of Meta-t
+ if MENU-ACCELERATOR-ENABLED is `menu-force'. However, if
+ MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not
+ activate the menubar and will instead run the function
+ transpose-words, to which it is normally bound.
+
+ The default value is `nil'.
+
+ See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.
+
+ - Variable: menu-accelerator-map
+ Keymap consulted to determine the commands to run in response to
+ keypresses occurring while the menubar is active. *Note Keyboard
+ Menu Traversal::.
+
+ - Variable: menu-accelerator-modifiers
+ A list of modifier keys which must be pressed in addition to a
+ valid menu accelerator in order for the top level menu to be
+ activated in response to a keystroke. The default value of
+ `(meta)' mirrors the usage of the alt key as a menu accelerator in
+ popular PC operating systems.
+
+ The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly
+ the modifiers present in the keypress. The only exception is that
+ the shift modifier is accepted in conjunction with alphabetic keys
+ even if it is not a menu accelerator modifier.
+
+ See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.
+
+ - Variable: menu-accelerator-prefix
+ Prefix key(s) that must be typed before menu accelerators will be
+ activated. Must be a valid key descriptor.
+
+ The default value is `nil'.
+
+ (setq menu-accelerator-prefix ?\C-x)
+ (setq menu-accelerator-modifiers '(meta control))
+ (setq menu-accelerator-enabled 'menu-force)
+ (add-submenu nil '("%_Test"
+ ["One" (insert "1") :accelerator ?1 :active t]
+ ["%_Two" (insert "2")]
+ ["%_3" (insert "3")]))
+
+ will add the menu "Test" to the top level menubar. Pressing C-x
+followed by C-M-T will activate the menubar and display the "Test"
+menu. Pressing C-M-T by itself will not activate the menubar. Neither
+will pressing C-x followed by anything else.
+
+\1f
+File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus
+
+Buffers Menu
+============
+
+ The following options control how the `Buffers' menu is displayed.
+This is a list of all (or a subset of) the buffers currently in
+existence, and is updated dynamically.
+
+ - User Option: buffers-menu-max-size
+ This user option holds the maximum number of entries which may
+ appear on the `Buffers' menu. If this is 10, then only the ten
+ most-recently-selected buffers will be shown. If this is `nil',
+ then all buffers will be shown. Setting this to a large number or
+ `nil' will slow down menu responsiveness.
+
+ - Function: format-buffers-menu-line BUFFER
+ This function returns a string to represent BUFFER in the
+ `Buffers' menu. `nil' means the buffer shouldn't be listed. You
+ can redefine this.
+
+ - User Option: complex-buffers-menu-p
+ If true, the `Buffers' menu will contain several commands, as
+ submenus of each buffer line. If this is false, then there will
+ be only one command: select that buffer.
+
+ - User Option: buffers-menu-switch-to-buffer-function
+ This user option holds the function to call to select a buffer
+ from the `Buffers' menu. `switch-to-buffer' is a good choice, as
+ is `pop-to-buffer'.
+
+\1f
+File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top
+
+Dialog Boxes
+************
+
+* Menu:
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+\1f
+File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes
+
+Dialog Box Format
+=================
+
+ A dialog box description is a list.
+
+ * The first element of the list is a string to display in the dialog
+ box.
+
+ * The rest of the elements are descriptions of the dialog box's
+ buttons. Each one is a vector of three elements:
+ - The first element is the text of the button.
+
+ - The second element is the "callback".
+
+ - The third element is `t' or `nil', whether this button is
+ selectable.
+
+ If the callback of a button 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'.
+
+ One (and only one) of the buttons may be `nil'. This marker means
+that all following buttons should be flushright instead of flushleft.
+
+ The syntax, more precisely:
+
+ form := <something to pass to `eval'>
+ command := <a symbol or string, to pass to `call-interactively'>
+ callback := command | form
+ active-p := <t, nil, or a form to evaluate to decide whether this
+ button should be selectable>
+ name := <string>
+ partition := 'nil'
+ button := '[' name callback active-p ']'
+ dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'
+
+\1f
+File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes
+
+Dialog Box Functions
+====================
+
+ - Function: popup-dialog-box DBOX-DESC
+ This function pops up a dialog box. DBOX-DESC describes how the
+ dialog box will appear (*note Dialog Box Format::.).
+
+ *Note Yes-or-No Queries::, for functions to ask a yes/no question
+using a dialog box.
+
+\1f
+File: lispref.info, Node: Toolbar, Next: Scrollbars, Prev: Dialog Boxes, Up: Top
+
+Toolbar
+*******
+
+* Menu:
+
+* Toolbar Intro:: An introduction.
+* Toolbar Descriptor Format:: How to create a toolbar.
+* Specifying the Toolbar:: Setting a toolbar's contents.
+* Other Toolbar Variables:: Controlling the size of toolbars.
+
+\1f
+File: lispref.info, Node: Toolbar Intro, Next: Toolbar Descriptor Format, Up: Toolbar
+
+Toolbar Intro
+=============
+
+ A "toolbar" is a bar of icons displayed along one edge of a frame.
+You can view a toolbar as a series of menu shortcuts - the most common
+menu options can be accessed with a single click rather than a series
+of clicks and/or drags to select the option from a menu. Consistent
+with this, a help string (called the "help-echo") describing what an
+icon in the toolbar (called a "toolbar button") does, is displayed in
+the minibuffer when the mouse is over the button.
+
+ In XEmacs, a toolbar can be displayed along any of the four edges of
+the frame, and two or more different edges can be displaying toolbars
+simultaneously. The contents, thickness, and visibility of the
+toolbars can be controlled separately, and the values can be
+per-buffer, per-frame, etc., using specifiers (*note Specifiers::.).
+
+ Normally, there is one toolbar displayed in a frame. Usually, this
+is the standard toolbar, but certain modes will override this and
+substitute their own toolbar. In some cases (e.g. the VM package), a
+package will supply its own toolbar along a different edge from the
+standard toolbar, so that both can be visible at once. This standard
+toolbar is usually positioned along the top of the frame, but this can
+be changed using `set-default-toolbar-position'.
+
+ Note that, for each of the toolbar properties (contents, thickness,
+and visibility), there is a separate specifier for each of the four
+toolbar positions (top, bottom, left, and right), and an additional
+specifier for the "default" toolbar, i.e. the toolbar whose position is
+controlled by `set-default-toolbar-position'. The way this works is
+that `set-default-toolbar-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 toolbar, you just change the default
+specifiers, and everything works. A package such as VM that wants to
+put its own toolbar in a different location from the default just sets
+the position-specific specifiers, and if the user sets the default
+toolbar to the same position, it will just not be visible.
+
+\1f
+File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Toolbar Intro, Up: Toolbar
+
+Toolbar Descriptor Format
+=========================
+
+ The contents of a toolbar are specified using a "toolbar descriptor".
+The format of a toolbar descriptor is a list of "toolbar button
+descriptors". Each toolbar 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 toolbar button descriptors may be `nil'
+instead of a vector; this signifies the division between the toolbar
+buttons that are to be displayed flush-left, and the buttons to be
+displayed flush-right.
+
+ The first vector format above specifies a normal toolbar button; the
+others specify blank areas in the toolbar.
+
+ 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
+ toolbar 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
+ toolbar buttons (using `toolbar-buttons-captioned-p'). The
+ function `toolbar-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 toolbar 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
+ toolbar button is activated (i.e. when the mouse is released over
+ the toolbar button, if the press occurred in the toolbar). It can
+ be any form accepted by `call-interactively', since this is how it
+ is invoked.
+
+ * The third element ENABLED-P specifies whether the toolbar 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
+ toolbar button.
+
+ For the other vector formats (specifying blank areas of the toolbar):
+
+ * 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: toolbar-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
+ toolbar button descriptor (typically, the result of this function
+ is assigned to a symbol, which is specified as the first argument
+ of the toolbar button descriptor).
+
+ - Function: check-toolbar-button-syntax BUTTON &optional NOERROR
+ Verify the syntax of entry BUTTON in a toolbar description list.
+ If you want to verify the syntax of a toolbar description list as a
+ whole, use `check-valid-instantiator' with a specifier type of
+ `toolbar'.
+
+\1f
+File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar
+
+Specifying the Toolbar
+======================
+
+ In order to specify the contents of a toolbar, set one of the
+specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
+`left-toolbar', or `right-toolbar'. 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 toolbar
+descriptors, as described above. *Note Specifiers::, for more
+information.
+
+ Most of the time, you will set `default-toolbar', which allows the
+user to choose where the toolbar should go.
+
+ - Specifier: default-toolbar
+ The position of this toolbar is specified in the function
+ `default-toolbar-position'. If the corresponding
+ position-specific toolbar (e.g. `top-toolbar' if
+ `default-toolbar-position' is `top') does not specify a toolbar in
+ a particular domain, then the value of `default-toolbar' in that
+ domain, of any, will be used instead.
+
+ Note that the toolbar 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-toolbar-height',
+`bottom-toolbar-height', `left-toolbar-width', and
+`right-toolbar-width', and the visibility status is controlled by the
+specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
+`left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
+Toolbar Variables::.).
+
+ - Function: set-default-toolbar-position POSITION
+ This function sets the position that the `default-toolbar' 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-toolbar', 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-toolbar-height' or
+ `default-toolbar-width', and from `default-toolbar-visible-p',
+ respectively (*note Other Toolbar Variables::.).
+
+ - Function: default-toolbar-position
+ This function returns the position that the `default-toolbar' will
+ be displayed at.
+
+ You can also explicitly set a toolbar 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
+toolbar. If that does not yield a toolbar descriptor, the
+`default-toolbar' is consulted if `default-toolbar-position' indicates
+this position.
+
+ - Specifier: top-toolbar
+ Specifier for the toolbar at the top of the frame.
+
+ - Specifier: bottom-toolbar
+ Specifier for the toolbar at the bottom of the frame.
+
+ - Specifier: left-toolbar
+ Specifier for the toolbar at the left edge of the frame.
+
+ - Specifier: right-toolbar
+ 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.
+ Toolbar specifiers are the actual objects contained in the toolbar
+ variables described above, and their valid instantiators are
+ toolbar descriptors (*note Toolbar Descriptor Format::.).
+
+\1f
+File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
+
+Other Toolbar Variables
+=======================
+
+ The variables to control the toolbar thickness, visibility status,
+and captioned status are all specifiers. *Note Specifiers::.
+
+ - Specifier: default-toolbar-height
+ This specifies the height of the default toolbar, if it's oriented
+ horizontally. The position of the default toolbar is specified by
+ the function `set-default-toolbar-position'. If the corresponding
+ position-specific toolbar thickness specifier (e.g.
+ `top-toolbar-height' if `default-toolbar-position' is `top') does
+ not specify a thickness in a particular domain (a window or a
+ frame), then the value of `default-toolbar-height' or
+ `default-toolbar-width' (depending on the toolbar orientation) in
+ that domain, if any, will be used instead.
+
+ - Specifier: default-toolbar-width
+ This specifies the width of the default toolbar, if it's oriented
+ vertically. This behaves like `default-toolbar-height'.
+
+ Note that `default-toolbar-height' is only used when
+`default-toolbar-position' is `top' or `bottom', and
+`default-toolbar-width' is only used when `default-toolbar-position' is
+`left' or `right'.
+
+ - Specifier: top-toolbar-height
+ This specifies the height of the top toolbar.
+
+ - Specifier: bottom-toolbar-height
+ This specifies the height of the bottom toolbar.
+
+ - Specifier: left-toolbar-width
+ This specifies the width of the left toolbar.
+
+ - Specifier: right-toolbar-width
+ This specifies the width of the right toolbar.
+
+ Note that all of the position-specific toolbar thickness specifiers
+have a fallback value of zero when they do not correspond to the
+default toolbar. Therefore, you will have to set a non-zero thickness
+value if you want a position-specific toolbar to be displayed.
+
+ - Specifier: default-toolbar-visible-p
+ This specifies whether the default toolbar is visible. The
+ position of the default toolbar is specified by the function
+ `set-default-toolbar-position'. If the corresponding
+ position-specific toolbar visibility specifier (e.g.
+ `top-toolbar-visible-p' if `default-toolbar-position' is `top')
+ does not specify a visible-p value in a particular domain (a
+ window or a frame), then the value of `default-toolbar-visible-p'
+ in that domain, if any, will be used instead.
+
+ - Specifier: top-toolbar-visible-p
+ This specifies whether the top toolbar is visible.
+
+ - Specifier: bottom-toolbar-visible-p
+ This specifies whether the bottom toolbar is visible.
+
+ - Specifier: left-toolbar-visible-p
+ This specifies whether the left toolbar is visible.
+
+ - Specifier: right-toolbar-visible-p
+ This specifies whether the right toolbar is visible.
+
+ `default-toolbar-visible-p' and all of the position-specific toolbar
+visibility specifiers have a fallback value of true.
+
+ Internally, toolbar 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 toolbar thickness or visibility that you will see in that frame.
+The value in the domain of a frame itself specifies the toolbar
+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 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
+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
+expanded to take up the slack.
+
+ - Specifier: toolbar-buttons-captioned-p
+ Whether toolbar buttons are captioned. This affects which glyphs
+ from a toolbar button descriptor are chosen. *Note Toolbar
+ Descriptor Format::.
+
+ You can also reset the toolbar to what it was when XEmacs started up.
+
+ - Constant: initial-toolbar-spec
+ The toolbar descriptor used to initialize `default-toolbar' at
+ startup.
+
+\1f
+File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Toolbar, Up: Top
+
+scrollbars
+**********
+
+ Not yet documented.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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/
+
+\1f
+File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols
+
+CDE dt
+------
+
+ CDE stands for Common Desktop Environment. It is based on the Motif
+widget library. It's drag'n'drop protocol is also an abstraction of the
+Motif protocol (so it might be possible, that XEmacs will also support
+the Motif protocol soon).
+
+ CDE has three different types: file, buffer, and text. XEmacs only
+uses file and buffer drags. The API will disallow full URL drags, only
+file method URLs are passed through.
+
+ Buffer drags are always converted to plain text.
+
+\1f
+File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols
+
+MSWindows OLE
+-------------
+
+ Only allows file drags and drops.
+
+\1f
+File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols
+
+Loose ends
+----------
+
+ The following protocols will be supported soon: Xdnd, Motif, Xde (if
+I get some specs), KDE OffiX (if KDE can find XEmacs windows).
+
+ In particular Xdnd will be one of the protocols that can benefit from
+the XEmacs API, cause it also uses MIME types to encode dragged data.
+
+\1f
+File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop
+
+Drop Interface
+==============
+
+ For each activated low-level protocol, a internal routine will catch
+incoming drops and convert them to a dragdrop-drop type misc-user-event.
+
+ This misc-user-event has its function argument set to
+`dragdrop-drop-dispatch' and the object contains the data of the drop
+(converted to URL/MIME specific data). This function will search the
+variable `experimental-dragdrop-drop-functions' for a function that can
+handle the dropped data.
+
+ To modify the drop behavior, the user can modify the variable
+`experimental-dragdrop-drop-functions'. Each element of this list
+specifies a possible handler for dropped data. The first one that can
+handle the data will return `t' and exit. Another possibility is to set
+a extent-property with the same name. Extents are checked prior to the
+variable.
+
+ The customization group `drag-n-drop' shows all variables of user
+interest.
+
+\1f
+File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop
+
+Drag Interface
+==============
+
+ This describes the drag API (not implemented yet).
+
+\1f
+File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top
+
+Major and Minor Modes
+*********************
+
+ A "mode" is a set of definitions that customize XEmacs and can be
+turned on and off while you edit. There are two varieties of modes:
+"major modes", which are mutually exclusive and used for editing
+particular kinds of text, and "minor modes", which provide features
+that users can enable individually.
+
+ This chapter describes how to write both major and minor modes, how
+to indicate them in the modeline, and how they run hooks supplied by the
+user. For related topics such as keymaps and syntax tables, see *Note
+Keymaps::, and *Note Syntax Tables::.
+
+* Menu:
+
+* Major Modes:: Defining major modes.
+* Minor Modes:: Defining minor modes.
+* Modeline Format:: Customizing the text that appears in the modeline.
+* Hooks:: How to use hooks; how to write code that provides hooks.
+
+\1f
+File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes
+
+Major Modes
+===========
+
+ Major modes specialize XEmacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.
+
+ The least specialized major mode is called "Fundamental mode". This
+mode has no mode-specific definitions or variable settings, so each
+XEmacs command behaves in its default manner, and each option is in its
+default state. All other major modes redefine various keys and options.
+For example, Lisp Interaction mode provides special key bindings for
+<LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
+keys.
+
+ When you need to write several editing commands to help you perform a
+specialized editing task, creating a new major mode is usually a good
+idea. In practice, writing a major mode is easy (in contrast to
+writing a minor mode, which is often difficult).
+
+ If the new mode is similar to an old one, it is often unwise to
+modify the old one to serve two purposes, since it may become harder to
+use and maintain. Instead, copy and rename an existing major mode
+definition and alter the copy--or define a "derived mode" (*note
+Derived Modes::.). For example, Rmail Edit mode, which is in
+`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
+mode except that it provides three additional commands. Its definition
+is distinct from that of Text mode, but was derived from it.
+
+ Rmail Edit mode is an example of a case where one piece of text is
+put temporarily into a different major mode so it can be edited in a
+different way (with ordinary XEmacs commands rather than Rmail). In
+such cases, the temporary major mode usually has a command to switch
+back to the buffer's usual mode (Rmail mode, in this case). You might
+be tempted to present the temporary redefinitions inside a recursive
+edit and restore the usual ones when the user exits; but this is a bad
+idea because it constrains the user's options when it is done in more
+than one buffer: recursive edits must be exited most-recently-entered
+first. Using alternative major modes avoids this limitation. *Note
+Recursive Editing::.
+
+ The standard XEmacs Lisp library directory contains the code for
+several major modes, in files including `text-mode.el', `texinfo.el',
+`lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these
+libraries to see how modes are written. Text mode is perhaps the
+simplest major mode aside from Fundamental mode. Rmail mode is a
+complicated and specialized mode.
+
+* Menu:
+
+* Major Mode Conventions:: Coding conventions for keymaps, etc.
+* Example Major Modes:: Text mode and Lisp modes.
+* Auto Major Mode:: How XEmacs chooses the major mode automatically.
+* Mode Help:: Finding out how to use a mode.
+* Derived Modes:: Defining a new major mode based on another major
+ mode.
+
+\1f
+File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes
+
+Major Mode Conventions
+----------------------
+
+ The code for existing major modes follows various coding conventions,
+including conventions for local keymap and syntax table initialization,
+global names, and hooks. Please follow these conventions when you
+define a new major mode:
+
+ * Define a command whose name ends in `-mode', with no arguments,
+ that switches to the new mode in the current buffer. This command
+ should set up the keymap, syntax table, and local variables in an
+ existing buffer without changing the buffer's text.
+
+ * Write a documentation string for this command that describes the
+ special commands available in this mode. `C-h m'
+ (`describe-mode') in your mode will display this string.
+
+ The documentation string may include the special documentation
+ substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
+ enable the documentation to adapt automatically to the user's own
+ key bindings. *Note Keys in Documentation::.
+
+ * The major mode command should start by calling
+ `kill-all-local-variables'. This is what gets rid of the local
+ variables of the major mode previously in effect.
+
+ * The major mode command should set the variable `major-mode' to the
+ major mode command symbol. This is how `describe-mode' discovers
+ which documentation to print.
+
+ * The major mode command should set the variable `mode-name' to the
+ "pretty" name of the mode, as a string. This appears in the mode
+ line.
+
+ * Since all global names are in the same name space, all the global
+ variables, constants, and functions that are part of the mode
+ should have names that start with the major mode name (or with an
+ abbreviation of it if the name is long). *Note Style Tips::.
+
+ * The major mode should usually have its own keymap, which is used
+ as the local keymap in all buffers in that mode. The major mode
+ function should call `use-local-map' to install this local map.
+ *Note Active Keymaps::, for more information.
+
+ This keymap should be kept in a global variable named
+ `MODENAME-mode-map'. Normally the library that defines the mode
+ sets this variable.
+
+ * The mode may have its own syntax table or may share one with other
+ related modes. If it has its own syntax table, it should store
+ this in a variable named `MODENAME-mode-syntax-table'. *Note
+ Syntax Tables::.
+
+ * The mode may have its own abbrev table or may share one with other
+ related modes. If it has its own abbrev table, it should store
+ this in a variable named `MODENAME-mode-abbrev-table'. *Note
+ Abbrev Tables::.
+
+ * Use `defvar' to set mode-related variables, so that they are not
+ reinitialized if they already have a value. (Such reinitialization
+ could discard customizations made by the user.)
+
+ * To make a buffer-local binding for an Emacs customization
+ variable, use `make-local-variable' in the major mode command, not
+ `make-variable-buffer-local'. The latter function would make the
+ variable local to every buffer in which it is subsequently set,
+ which would affect buffers that do not use this mode. It is
+ undesirable for a mode to have such global effects. *Note
+ Buffer-Local Variables::.
+
+ It's ok to use `make-variable-buffer-local', if you wish, for a
+ variable used only within a single Lisp package.
+
+ * Each major mode should have a "mode hook" named
+ `MODENAME-mode-hook'. The major mode command should run that
+ hook, with `run-hooks', as the very last thing it does. *Note
+ Hooks::.
+
+ * The major mode command may also run the hooks of some more basic
+ modes. For example, `indented-text-mode' runs `text-mode-hook' as
+ well as `indented-text-mode-hook'. It may run these other hooks
+ immediately before the mode's own hook (that is, after everything
+ else), or it may run them earlier.
+
+ * If something special should be done if the user switches a buffer
+ from this mode to any other major mode, the mode can set a local
+ value for `change-major-mode-hook'.
+
+ * If this mode is appropriate only for specially-prepared text, then
+ the major mode command symbol should have a property named
+ `mode-class' with value `special', put on as follows:
+
+ (put 'funny-mode 'mode-class 'special)
+
+ This tells XEmacs that new buffers created while the current
+ buffer has Funny mode should not inherit Funny mode. Modes such
+ as Dired, Rmail, and Buffer List use this feature.
+
+ * If you want to make the new mode the default for files with certain
+ recognizable names, add an element to `auto-mode-alist' to select
+ the mode for those file names. If you define the mode command to
+ autoload, you should add this element in the same file that calls
+ `autoload'. Otherwise, it is sufficient to add the element in the
+ file that contains the mode definition. *Note Auto Major Mode::.
+
+ * In the documentation, you should provide a sample `autoload' form
+ and an example of how to add to `auto-mode-alist', that users can
+ include in their `.emacs' files.
+
+ * The top-level forms in the file defining the mode should be
+ written so that they may be evaluated more than once without
+ adverse consequences. Even if you never load the file more than
+ once, someone else will.
+
+ - Variable: change-major-mode-hook
+ This normal hook is run by `kill-all-local-variables' before it
+ does anything else. This gives major modes a way to arrange for
+ something special to be done if the user switches to a different
+ major mode. For best results, make this variable buffer-local, so
+ that it will disappear after doing its job and will not interfere
+ with the subsequent major mode. *Note Hooks::.
+
+\1f
+File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes
+
+Major Mode Examples
+-------------------
+
+ Text mode is perhaps the simplest mode besides Fundamental mode.
+Here are excerpts from `text-mode.el' that illustrate many of the
+conventions listed above:
+
+ ;; Create mode-specific tables.
+ (defvar text-mode-syntax-table nil
+ "Syntax table used while in text mode.")
+
+ (if text-mode-syntax-table
+ () ; Do not change the table if it is already set up.
+ (setq text-mode-syntax-table (make-syntax-table))
+ (modify-syntax-entry ?\" ". " text-mode-syntax-table)
+ (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
+ (modify-syntax-entry ?' "w " text-mode-syntax-table))
+
+ (defvar text-mode-abbrev-table nil
+ "Abbrev table used while in text mode.")
+ (define-abbrev-table 'text-mode-abbrev-table ())
+
+ (defvar text-mode-map nil) ; Create a mode-specific keymap.
+
+ (if text-mode-map
+ () ; Do not change the keymap if it is already set up.
+ (setq text-mode-map (make-sparse-keymap))
+ (define-key text-mode-map "\t" 'tab-to-tab-stop)
+ (define-key text-mode-map "\es" 'center-line)
+ (define-key text-mode-map "\eS" 'center-paragraph))
+
+ Here is the complete major mode function definition for Text mode:
+
+ (defun text-mode ()
+ "Major mode for editing text intended for humans to read.
+ Special commands: \\{text-mode-map}
+
+ Turning on text-mode runs the hook `text-mode-hook'."
+ (interactive)
+ (kill-all-local-variables)
+
+ (use-local-map text-mode-map) ; This provides the local keymap.
+ (setq mode-name "Text") ; This name goes into the modeline.
+ (setq major-mode 'text-mode) ; This is how `describe-mode'
+ ; finds the doc string to print.
+ (setq local-abbrev-table text-mode-abbrev-table)
+ (set-syntax-table text-mode-syntax-table)
+ (run-hooks 'text-mode-hook)) ; Finally, this permits the user to
+ ; customize the mode with a hook.
+
+ The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+Interaction mode) have more features than Text mode and the code is
+correspondingly more complicated. Here are excerpts from
+`lisp-mode.el' that illustrate how these modes are written.
+
+ ;; Create mode-specific table variables.
+ (defvar lisp-mode-syntax-table nil "")
+ (defvar emacs-lisp-mode-syntax-table nil "")
+ (defvar lisp-mode-abbrev-table nil "")
+
+ (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
+ ; if it is already set.
+ (let ((i 0))
+ (setq emacs-lisp-mode-syntax-table (make-syntax-table))
+
+ ;; Set syntax of chars up to 0 to class of chars that are
+ ;; part of symbol names but not words.
+ ;; (The number 0 is `48' in the ASCII character set.)
+ (while (< i ?0)
+ (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
+ (setq i (1+ i)))
+ ...
+
+ ;; Set the syntax for other characters.
+ (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
+ (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
+ ...
+
+ (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
+ (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
+ ...))
+ ;; Create an abbrev table for lisp-mode.
+ (define-abbrev-table 'lisp-mode-abbrev-table ())
+
+ Much code is shared among the three Lisp modes. The following
+function sets various variables; it is called by each of the major Lisp
+mode functions:
+
+ (defun lisp-mode-variables (lisp-syntax)
+ ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
+ ;; and `t' in the other two Lisp modes.
+ (cond (lisp-syntax
+ (if (not lisp-mode-syntax-table)
+ ;; The Emacs Lisp mode syntax table always exists, but
+ ;; the Lisp Mode syntax table is created the first time a
+ ;; mode that needs it is called. This is to save space.
+
+ (progn (setq lisp-mode-syntax-table
+ (copy-syntax-table emacs-lisp-mode-syntax-table))
+ ;; Change some entries for Lisp mode.
+ (modify-syntax-entry ?\| "\" "
+ lisp-mode-syntax-table)
+ (modify-syntax-entry ?\[ "_ "
+ lisp-mode-syntax-table)
+ (modify-syntax-entry ?\] "_ "
+ lisp-mode-syntax-table)))
+
+ (set-syntax-table lisp-mode-syntax-table)))
+ (setq local-abbrev-table lisp-mode-abbrev-table)
+ ...)
+
+ Functions such as `forward-paragraph' use the value of the
+`paragraph-start' variable. Since Lisp code is different from ordinary
+text, the `paragraph-start' variable needs to be set specially to
+handle Lisp. Also, comments are indented in a special fashion in Lisp
+and the Lisp modes need their own mode-specific
+`comment-indent-function'. The code to set these variables is the rest
+of `lisp-mode-variables'.
+
+ (make-local-variable 'paragraph-start)
+ ;; Having `^' is not clean, but `page-delimiter'
+ ;; has them too, and removing those is a pain.
+ (setq paragraph-start (concat "^$\\|" page-delimiter))
+ ...
+
+ (make-local-variable 'comment-indent-function)
+ (setq comment-indent-function 'lisp-comment-indent))
+
+ Each of the different Lisp modes has a slightly different keymap.
+For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
+Lisp modes do not. However, all Lisp modes have some commands in
+common. The following function adds these common commands to a given
+keymap.
+
+ (defun lisp-mode-commands (map)
+ (define-key map "\e\C-q" 'indent-sexp)
+ (define-key map "\177" 'backward-delete-char-untabify)
+ (define-key map "\t" 'lisp-indent-line))
+
+ Here is an example of using `lisp-mode-commands' to initialize a
+keymap, as part of the code for Emacs Lisp mode. First we declare a
+variable with `defvar' to hold the mode-specific keymap. When this
+`defvar' executes, it sets the variable to `nil' if it was void. Then
+we set up the keymap if the variable is `nil'.
+
+ This code avoids changing the keymap or the variable if it is already
+set up. This lets the user customize the keymap.
+
+ (defvar emacs-lisp-mode-map () "")
+ (if emacs-lisp-mode-map
+ ()
+ (setq emacs-lisp-mode-map (make-sparse-keymap))
+ (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
+ (lisp-mode-commands emacs-lisp-mode-map))
+
+ Finally, here is the complete major mode function definition for
+Emacs Lisp mode.
+
+ (defun emacs-lisp-mode ()
+ "Major mode for editing Lisp code to run in XEmacs.
+ Commands:
+ Delete converts tabs to spaces as it moves back.
+ Blank lines separate paragraphs. Semicolons start comments.
+ \\{emacs-lisp-mode-map}
+
+ Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+ (interactive)
+ (kill-all-local-variables)
+ (use-local-map emacs-lisp-mode-map) ; This provides the local keymap.
+ (set-syntax-table emacs-lisp-mode-syntax-table)
+
+ (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode'
+ ; finds out what to describe.
+ (setq mode-name "Emacs-Lisp") ; This goes into the modeline.
+ (lisp-mode-variables nil) ; This defines various variables.
+ (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a
+ ; hook to customize the mode.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes
+
+How XEmacs Chooses a Major Mode
+-------------------------------
+
+ Based on information in the file name or in the file itself, XEmacs
+automatically selects a major mode for the new buffer when a file is
+visited.
+
+ - Command: fundamental-mode
+ Fundamental mode is a major mode that is not specialized for
+ anything in particular. Other major modes are defined in effect
+ by comparison with this one--their definitions say what to change,
+ starting from Fundamental mode. The `fundamental-mode' function
+ does *not* run any hooks; you're not supposed to customize it.
+ (If you want Emacs to behave differently in Fundamental mode,
+ change the *global* state of Emacs.)
+
+ - Command: normal-mode &optional FIND-FILE
+ This function establishes the proper major mode and local variable
+ bindings for the current buffer. First it calls `set-auto-mode',
+ then it runs `hack-local-variables' to parse, and bind or evaluate
+ as appropriate, any local variables.
+
+ If the FIND-FILE argument to `normal-mode' is non-`nil',
+ `normal-mode' assumes that the `find-file' function is calling it.
+ In this case, it may process a local variables list at the end of
+ the file and in the `-*-' line. The variable
+ `enable-local-variables' controls whether to do so.
+
+ If you run `normal-mode' interactively, the argument FIND-FILE is
+ normally `nil'. In this case, `normal-mode' unconditionally
+ processes any local variables list. *Note Local Variables in
+ Files: (emacs)File variables, for the syntax of the local
+ variables section of a file.
+
+ `normal-mode' uses `condition-case' around the call to the major
+ mode function, so errors are caught and reported as a `File mode
+ specification error', followed by the original error message.
+
+ - User Option: enable-local-variables
+ This variable controls processing of local variables lists in files
+ being visited. A value of `t' means process the local variables
+ lists unconditionally; `nil' means ignore them; anything else means
+ ask the user what to do for each file. The default value is `t'.
+
+ - Variable: ignored-local-variables
+ This variable holds a list of variables that should not be set by
+ a local variables list. Any value specified for one of these
+ variables is ignored.
+
+ In addition to this list, any variable whose name has a non-`nil'
+`risky-local-variable' property is also ignored.
+
+ - User Option: enable-local-eval
+ This variable controls processing of `Eval:' in local variables
+ lists in files being visited. A value of `t' means process them
+ unconditionally; `nil' means ignore them; anything else means ask
+ the user what to do for each file. The default value is `maybe'.
+
+ - Function: set-auto-mode
+ This function selects the major mode that is appropriate for the
+ current buffer. It may base its decision on the value of the `-*-'
+ line, on the visited file name (using `auto-mode-alist'), or on the
+ value of a local variable. However, this function does not look
+ for the `mode:' local variable near the end of a file; the
+ `hack-local-variables' function does that. *Note How Major Modes
+ are Chosen: (emacs)Choosing Modes.
+
+ - User Option: default-major-mode
+ This variable holds the default major mode for new buffers. The
+ standard value is `fundamental-mode'.
+
+ If the value of `default-major-mode' is `nil', XEmacs uses the
+ (previously) current buffer's major mode for the major mode of a
+ new buffer. However, if the major mode symbol has a `mode-class'
+ property with value `special', then it is not used for new buffers;
+ Fundamental mode is used instead. The modes that have this
+ property are those such as Dired and Rmail that are useful only
+ with text that has been specially prepared.
+
+ - Function: set-buffer-major-mode BUFFER
+ This function sets the major mode of BUFFER to the value of
+ `default-major-mode'. If that variable is `nil', it uses the
+ current buffer's major mode (if that is suitable).
+
+ The low-level primitives for creating buffers do not use this
+ function, but medium-level commands such as `switch-to-buffer' and
+ `find-file-noselect' use it whenever they create buffers.
+
+ - Variable: initial-major-mode
+ The value of this variable determines the major mode of the initial
+ `*scratch*' buffer. The value should be a symbol that is a major
+ mode command name. The default value is `lisp-interaction-mode'.
+
+ - Variable: auto-mode-alist
+ This variable contains an association list of file name patterns
+ (regular expressions; *note Regular Expressions::.) and
+ corresponding major mode functions. Usually, the file name
+ patterns test for suffixes, such as `.el' and `.c', but this need
+ not be the case. An ordinary element of the alist looks like
+ `(REGEXP . MODE-FUNCTION)'.
+
+ For example,
+
+ (("^/tmp/fol/" . text-mode)
+ ("\\.texinfo\\'" . texinfo-mode)
+ ("\\.texi\\'" . texinfo-mode)
+
+ ("\\.el\\'" . emacs-lisp-mode)
+ ("\\.c\\'" . c-mode)
+ ("\\.h\\'" . c-mode)
+ ...)
+
+ When you visit a file whose expanded file name (*note File Name
+ Expansion::.) matches a REGEXP, `set-auto-mode' calls the
+ corresponding MODE-FUNCTION. This feature enables XEmacs to select
+ the proper major mode for most files.
+
+ If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
+ t)', then after calling FUNCTION, XEmacs searches
+ `auto-mode-alist' again for a match against the portion of the file
+ name that did not match before.
+
+ This match-again feature is useful for uncompression packages: an
+ entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
+ and then put the uncompressed file in the proper mode according to
+ the name sans `.gz'.
+
+ Here is an example of how to prepend several pattern pairs to
+ `auto-mode-alist'. (You might use this sort of expression in your
+ `.emacs' file.)
+
+ (setq auto-mode-alist
+ (append
+ ;; File name starts with a dot.
+ '(("/\\.[^/]*\\'" . fundamental-mode)
+ ;; File name has no dot.
+ ("[^\\./]*\\'" . fundamental-mode)
+ ;; File name ends in `.C'.
+ ("\\.C\\'" . c++-mode))
+ auto-mode-alist))
+
+ - Variable: interpreter-mode-alist
+ This variable specifies major modes to use for scripts that
+ specify a command interpreter in an `#!' line. Its value is a
+ list of elements of the form `(INTERPRETER . MODE)'; for example,
+ `("perl" . perl-mode)' is one element present by default. The
+ element says to use mode MODE if the file specifies INTERPRETER.
+
+ This variable is applicable only when the `auto-mode-alist' does
+ not indicate which major mode to use.
+
+ - Function: hack-local-variables &optional FORCE
+ This function parses, and binds or evaluates as appropriate, any
+ local variables for the current buffer.
+
+ The handling of `enable-local-variables' documented for
+ `normal-mode' actually takes place here. The argument FORCE
+ usually comes from the argument FIND-FILE given to `normal-mode'.
+
+\1f
+File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes
+
+Getting Help about a Major Mode
+-------------------------------
+
+ The `describe-mode' function is used to provide information about
+major modes. It is normally called with `C-h m'. The `describe-mode'
+function uses the value of `major-mode', which is why every major mode
+function needs to set the `major-mode' variable.
+
+ - Command: describe-mode
+ This function displays the documentation of the current major mode.
+
+ The `describe-mode' function calls the `documentation' function
+ using the value of `major-mode' as an argument. Thus, it displays
+ the documentation string of the major mode function. (*Note
+ Accessing Documentation::.)
+
+ - Variable: major-mode
+ This variable holds the symbol for the current buffer's major mode.
+ This symbol should have a function definition that is the command
+ to switch to that major mode. The `describe-mode' function uses
+ the documentation string of the function as the documentation of
+ the major mode.
+
+\1f
+File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes
+
+Defining Derived Modes
+----------------------
+
+ It's often useful to define a new major mode in terms of an existing
+one. An easy way to do this is to use `define-derived-mode'.
+
+ - Macro: define-derived-mode VARIANT PARENT NAME DOCSTRING BODY...
+ This construct defines VARIANT as a major mode command, using NAME
+ as the string form of the mode name.
+
+ The new command VARIANT is defined to call the function PARENT,
+ then override certain aspects of that parent mode:
+
+ * The new mode has its own keymap, named `VARIANT-map'.
+ `define-derived-mode' initializes this map to inherit from
+ `PARENT-map', if it is not already set.
+
+ * The new mode has its own syntax table, kept in the variable
+ `VARIANT-syntax-table'. `define-derived-mode' initializes
+ this variable by copying `PARENT-syntax-table', if it is not
+ already set.
+
+ * The new mode has its own abbrev table, kept in the variable
+ `VARIANT-abbrev-table'. `define-derived-mode' initializes
+ this variable by copying `PARENT-abbrev-table', if it is not
+ already set.
+
+ * The new mode has its own mode hook, `VARIANT-hook', which it
+ runs in standard fashion as the very last thing that it does.
+ (The new mode also runs the mode hook of PARENT as part of
+ calling PARENT.)
+
+ In addition, you can specify how to override other aspects of
+ PARENT with BODY. The command VARIANT evaluates the forms in BODY
+ after setting up all its usual overrides, just before running
+ `VARIANT-hook'.
+
+ The argument DOCSTRING specifies the documentation string for the
+ new mode. If you omit DOCSTRING, `define-derived-mode' generates
+ a documentation string.
+
+ Here is a hypothetical example:
+
+ (define-derived-mode hypertext-mode
+ text-mode "Hypertext"
+ "Major mode for hypertext.
+ \\{hypertext-mode-map}"
+ (setq case-fold-search nil))
+
+ (define-key hypertext-mode-map
+ [down-mouse-3] 'do-hyper-link)
+
+\1f
+File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes
+
+Minor Modes
+===========
+
+ A "minor mode" provides features that users may enable or disable
+independently of the choice of major mode. Minor modes can be enabled
+individually or in combination. Minor modes would be better named
+"Generally available, optional feature modes" except that such a name is
+unwieldy.
+
+ A minor mode is not usually a modification of single major mode. For
+example, Auto Fill mode may be used in any major mode that permits text
+insertion. To be general, a minor mode must be effectively independent
+of the things major modes do.
+
+ A minor mode is often much more difficult to implement than a major
+mode. One reason is that you should be able to activate and deactivate
+minor modes in any order. A minor mode should be able to have its
+desired effect regardless of the major mode and regardless of the other
+minor modes in effect.
+
+ Often the biggest problem in implementing a minor mode is finding a
+way to insert the necessary hook into the rest of XEmacs. Minor mode
+keymaps make this easier than it used to be.
+
+* Menu:
+
+* Minor Mode Conventions:: Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+
+\1f
+File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes
+
+Conventions for Writing Minor Modes
+-----------------------------------
+
+ There are conventions for writing minor modes just as there are for
+major modes. Several of the major mode conventions apply to minor
+modes as well: those regarding the name of the mode initialization
+function, the names of global symbols, and the use of keymaps and other
+tables.
+
+ In addition, there are several conventions that are specific to
+minor modes.
+
+ * Make a variable whose name ends in `-mode' to represent the minor
+ mode. Its value should enable or disable the mode (`nil' to
+ disable; anything else to enable.) We call this the "mode
+ variable".
+
+ This variable is used in conjunction with the `minor-mode-alist' to
+ display the minor mode name in the modeline. It can also enable
+ or disable a minor mode keymap. Individual commands or hooks can
+ also check the variable's value.
+
+ If you want the minor mode to be enabled separately in each buffer,
+ make the variable buffer-local.
+
+ * Define a command whose name is the same as the mode variable. Its
+ job is to enable and disable the mode by setting the variable.
+
+ The command should accept one optional argument. If the argument
+ is `nil', it should toggle the mode (turn it on if it is off, and
+ off if it is on). Otherwise, it should turn the mode on if the
+ argument is a positive integer, a symbol other than `nil' or `-',
+ or a list whose CAR is such an integer or symbol; it should turn
+ the mode off otherwise.
+
+ Here is an example taken from the definition of
+ `transient-mark-mode'. It shows the use of `transient-mark-mode'
+ as a variable that enables or disables the mode's behavior, and
+ also shows the proper way to toggle, enable or disable the minor
+ mode based on the raw prefix argument value.
+
+ (setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
+ (> (prefix-numeric-value arg) 0)))
+
+ * Add an element to `minor-mode-alist' for each minor mode (*note
+ Modeline Variables::.). This element should be a list of the
+ following form:
+
+ (MODE-VARIABLE STRING)
+
+ Here MODE-VARIABLE is the variable that controls enabling of the
+ minor mode, and STRING is a short string, starting with a space,
+ to represent the mode in the modeline. These strings must be
+ short so that there is room for several of them at once.
+
+ When you add an element to `minor-mode-alist', use `assq' to check
+ for an existing element, to avoid duplication. For example:
+
+ (or (assq 'leif-mode minor-mode-alist)
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist)))
+
+\1f
+File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes
+
+Keymaps and Minor Modes
+-----------------------
+
+ Each minor mode can have its own keymap, which is active when the
+mode is enabled. To set up a keymap for a minor mode, add an element
+to the alist `minor-mode-map-alist'. *Note Active Keymaps::.
+
+ One use of minor mode keymaps is to modify the behavior of certain
+self-inserting characters so that they do something else as well as
+self-insert. In general, this is the only way to do that, since the
+facilities for customizing `self-insert-command' are limited to special
+cases (designed for abbrevs and Auto Fill mode). (Do not try
+substituting your own definition of `self-insert-command' for the
+standard one. The editor command loop handles this function specially.)
+
+\1f
+File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes
+
+Modeline Format
+===============
+
+ Each Emacs window (aside from minibuffer windows) includes a
+modeline, which displays status information about the buffer displayed
+in the window. The modeline contains information about the buffer,
+such as its name, associated file, depth of recursive editing, and the
+major and minor modes.
+
+ This section describes how the contents of the modeline are
+controlled. It is in the chapter on modes because much of the
+information displayed in the modeline relates to the enabled major and
+minor modes.
+
+ `modeline-format' is a buffer-local variable that holds a template
+used to display the modeline of the current buffer. All windows for
+the same buffer use the same `modeline-format' and their modelines
+appear the same (except for scrolling percentages and line numbers).
+
+ The modeline of a window is normally updated whenever a different
+buffer is shown in the window, or when the buffer's modified-status
+changes from `nil' to `t' or vice-versa. If you modify any of the
+variables referenced by `modeline-format' (*note Modeline
+Variables::.), you may want to force an update of the modeline so as to
+display the new information.
+
+ - Function: redraw-modeline &optional ALL
+ Force redisplay of the current buffer's modeline. If ALL is
+ non-`nil', then force redisplay of all modelines.
+
+ The modeline is usually displayed in inverse video. This is
+controlled using the `modeline' face. *Note Faces::.
+
+* Menu:
+
+* Modeline Data:: The data structure that controls the modeline.
+* Modeline Variables:: Variables used in that data structure.
+* %-Constructs:: Putting information into a modeline.
+
+\1f
+File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format
+
+The Data Structure of the Modeline
+----------------------------------
+
+ The modeline contents are controlled by a data structure of lists,
+strings, symbols, and numbers kept in the buffer-local variable
+`mode-line-format'. The data structure is called a "modeline
+construct", and it is built in recursive fashion out of simpler modeline
+constructs. The same data structure is used for constructing frame
+titles (*note Frame Titles::.).
+
+ - Variable: modeline-format
+ The value of this variable is a modeline construct with overall
+ responsibility for the modeline format. The value of this variable
+ controls which other variables are used to form the modeline text,
+ and where they appear.
+
+ A modeline construct may be as simple as a fixed string of text, but
+it usually specifies how to use other variables to construct the text.
+Many of these variables are themselves defined to have modeline
+constructs as their values.
+
+ The default value of `modeline-format' incorporates the values of
+variables such as `mode-name' and `minor-mode-alist'. Because of this,
+very few modes need to alter `modeline-format'. For most purposes, it
+is sufficient to alter the variables referenced by `modeline-format'.
+
+ A modeline construct may be a list, a symbol, or a string. If the
+value is a list, each element may be a list, a symbol, or a string.
+
+`STRING'
+ A string as a modeline construct is displayed verbatim in the mode
+ line except for "`%'-constructs". Decimal digits after the `%'
+ specify the field width for space filling on the right (i.e., the
+ data is left justified). *Note %-Constructs::.
+
+`SYMBOL'
+ A symbol as a modeline construct stands for its value. The value
+ of SYMBOL is used as a modeline construct, in place of SYMBOL.
+ However, the symbols `t' and `nil' are ignored; so is any symbol
+ whose value is void.
+
+ There is one exception: if the value of SYMBOL is a string, it is
+ displayed verbatim: the `%'-constructs are not recognized.
+
+`(STRING REST...) or (LIST REST...)'
+ A list whose first element is a string or list means to process
+ all the elements recursively and concatenate the results. This is
+ the most common form of mode line construct.
+
+`(SYMBOL THEN ELSE)'
+ A list whose first element is a symbol is a conditional. Its
+ meaning depends on the value of SYMBOL. If the value is non-`nil',
+ the second element, THEN, is processed recursively as a modeline
+ element. But if the value of SYMBOL is `nil', the third element,
+ ELSE, is processed recursively. You may omit ELSE; then the mode
+ line element displays nothing if the value of SYMBOL is `nil'.
+
+`(WIDTH REST...)'
+ A list whose first element is an integer specifies truncation or
+ padding of the results of REST. The remaining elements REST are
+ processed recursively as modeline constructs and concatenated
+ together. Then the result is space filled (if WIDTH is positive)
+ or truncated (to -WIDTH columns, if WIDTH is negative) on the
+ right.
+
+ For example, the usual way to show what percentage of a buffer is
+ above the top of the window is to use a list like this: `(-3
+ "%p")'.
+
+ If you do alter `modeline-format' itself, the new value should use
+the same variables that appear in the default value (*note Modeline
+Variables::.), rather than duplicating their contents or displaying the
+information in another fashion. This way, customizations made by the
+user or by Lisp programs (such as `display-time' and major modes) via
+changes to those variables remain effective.
+
+ Here is an example of a `modeline-format' that might be useful for
+`shell-mode', since it contains the hostname and default directory.
+
+ (setq modeline-format
+ (list ""
+ 'modeline-modified
+ "%b--"
+ (getenv "HOST") ; One element is not constant.
+ ":"
+ 'default-directory
+ " "
+ 'global-mode-string
+ " %[("
+ 'mode-name
+ 'modeline-process
+ 'minor-mode-alist
+ "%n"
+ ")%]----"
+ '(line-number-mode "L%l--")
+ '(-3 . "%p")
+ "-%-"))
+
+\1f
+File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format
+
+Variables Used in the Modeline
+------------------------------
+
+ This section describes variables incorporated by the standard value
+of `modeline-format' into the text of the mode line. There is nothing
+inherently special about these variables; any other variables could
+have the same effects on the modeline if `modeline-format' were changed
+to use them.
+
+ - Variable: modeline-modified
+ This variable holds the value of the modeline construct that
+ displays whether the current buffer is modified.
+
+ The default value of `modeline-modified' is `("--%1*%1+-")'. This
+ means that the modeline displays `--**-' if the buffer is
+ modified, `-----' if the buffer is not modified, `--%%-' if the
+ buffer is read only, and `--%*--' if the buffer is read only and
+ modified.
+
+ Changing this variable does not force an update of the modeline.
+
+ - Variable: modeline-buffer-identification
+ This variable identifies the buffer being displayed in the window.
+ Its default value is `("%F: %17b")', which means that it usually
+ displays `Emacs:' followed by seventeen characters of the buffer
+ name. (In a terminal frame, it displays the frame name instead of
+ `Emacs'; this has the effect of showing the frame number.) You may
+ want to change this in modes such as Rmail that do not behave like
+ a "normal" XEmacs.
+
+ - Variable: global-mode-string
+ This variable holds a modeline spec that appears in the mode line
+ by default, just after the buffer name. The command `display-time'
+ sets `global-mode-string' to refer to the variable
+ `display-time-string', which holds a string containing the time and
+ load information.
+
+ The `%M' construct substitutes the value of `global-mode-string',
+ but this is obsolete, since the variable is included directly in
+ the modeline.
+
+ - Variable: mode-name
+ This buffer-local variable holds the "pretty" name of the current
+ buffer's major mode. Each major mode should set this variable so
+ that the mode name will appear in the modeline.
+
+ - Variable: minor-mode-alist
+ This variable holds an association list whose elements specify how
+ the modeline should indicate that a minor mode is active. Each
+ element of the `minor-mode-alist' should be a two-element list:
+
+ (MINOR-MODE-VARIABLE MODELINE-STRING)
+
+ More generally, MODELINE-STRING can be any mode line spec. It
+ appears in the mode line when the value of MINOR-MODE-VARIABLE is
+ non-`nil', and not otherwise. These strings should begin with
+ spaces so that they don't run together. Conventionally, the
+ MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
+ value when that minor mode is activated.
+
+ The default value of `minor-mode-alist' is:
+
+ minor-mode-alist
+ => ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
+ (auto-fill-function " Fill")
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
+
+ `minor-mode-alist' is not buffer-local. The variables mentioned
+ in the alist should be buffer-local if the minor mode can be
+ enabled separately in each buffer.
+
+ - Variable: modeline-process
+ This buffer-local variable contains the modeline information on
+ process status in modes used for communicating with subprocesses.
+ It is displayed immediately following the major mode name, with no
+ intervening space. For example, its value in the `*shell*' buffer
+ is `(": %s")', which allows the shell to display its status along
+ with the major mode as: `(Shell: run)'. Normally this variable is
+ `nil'.
+
+ - Variable: default-modeline-format
+ This variable holds the default `modeline-format' for buffers that
+ do not override it. This is the same as `(default-value
+ 'modeline-format)'.
+
+ The default value of `default-modeline-format' is:
+
+ (""
+ modeline-modified
+ modeline-buffer-identification
+ " "
+ global-mode-string
+ " %[("
+ mode-name
+ modeline-process
+ minor-mode-alist
+ "%n"
+ ")%]----"
+ (line-number-mode "L%l--")
+ (-3 . "%p")
+ "-%-")
+
+ - Variable: vc-mode
+ The variable `vc-mode', local in each buffer, records whether the
+ buffer's visited file is maintained with version control, and, if
+ so, which kind. Its value is `nil' for no version control, or a
+ string that appears in the mode line.
+
+\1f
+File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format
+
+`%'-Constructs in the ModeLine
+------------------------------
+
+ The following table lists the recognized `%'-constructs and what
+they mean. In any construct except `%%', you can add a decimal integer
+after the `%' to specify how many characters to display.
+
+`%b'
+ The current buffer name, obtained with the `buffer-name' function.
+ *Note Buffer Names::.
+
+`%f'
+ The visited file name, obtained with the `buffer-file-name'
+ function. *Note Buffer File Name::.
+
+`%F'
+ The name of the selected frame.
+
+`%c'
+ The current column number of point.
+
+`%l'
+ The current line number of point.
+
+`%*'
+ `%' if the buffer is read only (see `buffer-read-only');
+ `*' if the buffer is modified (see `buffer-modified-p');
+ `-' otherwise. *Note Buffer Modification::.
+
+`%+'
+ `*' if the buffer is modified (see `buffer-modified-p');
+ `%' if the buffer is read only (see `buffer-read-only');
+ `-' otherwise. This differs from `%*' only for a modified
+ read-only buffer. *Note Buffer Modification::.
+
+`%&'
+ `*' if the buffer is modified, and `-' otherwise.
+
+`%s'
+ The status of the subprocess belonging to the current buffer,
+ obtained with `process-status'. *Note Process Information::.
+
+`%l'
+ the current line number.
+
+`%S'
+ the name of the selected frame; this is only meaningful under the
+ X Window System. *Note Frame Name::.
+
+`%t'
+ Whether the visited file is a text file or a binary file. (This
+ is a meaningful distinction only on certain operating systems.)
+
+`%p'
+ The percentage of the buffer text above the *top* of window, or
+ `Top', `Bottom' or `All'.
+
+`%P'
+ The percentage of the buffer text that is above the *bottom* of
+ the window (which includes the text visible in the window, as well
+ as the text above the top), plus `Top' if the top of the buffer is
+ visible on screen; or `Bottom' or `All'.
+
+`%n'
+ `Narrow' when narrowing is in effect; nothing otherwise (see
+ `narrow-to-region' in *Note Narrowing::).
+
+`%['
+ An indication of the depth of recursive editing levels (not
+ counting minibuffer levels): one `[' for each editing level.
+ *Note Recursive Editing::.
+
+`%]'
+ One `]' for each recursive editing level (not counting minibuffer
+ levels).
+
+`%%'
+ The character `%'--this is how to include a literal `%' in a
+ string in which `%'-constructs are allowed.
+
+`%-'
+ Dashes sufficient to fill the remainder of the modeline.
+
+ The following two `%'-constructs are still supported, but they are
+obsolete, since you can get the same results with the variables
+`mode-name' and `global-mode-string'.
+
+`%m'
+ The value of `mode-name'.
+
+`%M'
+ The value of `global-mode-string'. Currently, only `display-time'
+ modifies the value of `global-mode-string'.
+
+\1f
+File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
+
+Hooks
+=====
+
+ A "hook" is a variable where you can store a function or functions
+to be called on a particular occasion by an existing program. XEmacs
+provides hooks for the sake of customization. Most often, hooks are set
+up in the `.emacs' file, but Lisp programs can set them also. *Note
+Standard Hooks::, for a list of standard hook variables.
+
+ Most of the hooks in XEmacs are "normal hooks". These variables
+contain lists of functions to be called with no arguments. The reason
+most hooks are normal hooks is so that you can use them in a uniform
+way. You can usually tell when a hook is a normal hook, because its
+name ends in `-hook'.
+
+ The recommended way to add a hook function to a normal hook is by
+calling `add-hook' (see below). The hook functions may be any of the
+valid kinds of functions that `funcall' accepts (*note What Is a
+Function::.). Most normal hook variables are initially void;
+`add-hook' knows how to deal with this.
+
+ As for abnormal hooks, those whose names end in `-function' have a
+value that is a single function. Those whose names end in `-hooks'
+have a value that is a list of functions. Any hook that is abnormal is
+abnormal because a normal hook won't do the job; either the functions
+are called with arguments, or their values are meaningful. The name
+shows you that the hook is abnormal and that you should look at its
+documentation string to see how to use it properly.
+
+ Major mode functions are supposed to run a hook called the "mode
+hook" as the last step of initialization. This makes it easy for a user
+to customize the behavior of the mode, by overriding the local variable
+assignments already made by the mode. But hooks are used in other
+contexts too. For example, the hook `suspend-hook' runs just before
+XEmacs suspends itself (*note Suspending XEmacs::.).
+
+ Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
+
+ (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+
+ The next example shows how to use a hook to customize the way XEmacs
+formats C code. (People often have strong personal preferences for one
+format or another.) Here the hook function is an anonymous lambda
+expression.
+
+ (add-hook 'c-mode-hook
+ (function (lambda ()
+ (setq c-indent-level 4
+ c-argdecl-indent 0
+ c-label-offset -4
+ c-continued-statement-indent 0
+ c-brace-offset 0
+ comment-column 40))))
+
+ (setq c++-mode-hook c-mode-hook)
+
+ The final example shows how the appearance of the modeline can be
+modified for a particular class of buffers only.
+
+ (add-hook 'text-mode-hook
+ (function (lambda ()
+ (setq modeline-format
+ '(modeline-modified
+ "Emacs: %14b"
+ " "
+ default-directory
+ " "
+ global-mode-string
+ "%[("
+ mode-name
+ minor-mode-alist
+ "%n"
+ modeline-process
+ ") %]---"
+ (-3 . "%p")
+ "-%-")))))
+
+ At the appropriate time, XEmacs uses the `run-hooks' function to run
+particular hooks. This function calls the hook functions you have
+added with `add-hooks'.
+
+ - Function: run-hooks &rest HOOKVAR
+ This function takes one or more hook variable names as arguments,
+ and runs each hook in turn. Each HOOKVAR argument should be a
+ symbol that is a hook variable. These arguments are processed in
+ the order specified.
+
+ If a hook variable has a non-`nil' value, that value may be a
+ function or a list of functions. If the value is a function
+ (either a lambda expression or a symbol with a function
+ definition), it is called. If it is a list, the elements are
+ called, in order. The hook functions are called with no arguments.
+
+ For example, here's how `emacs-lisp-mode' runs its mode hook:
+
+ (run-hooks 'emacs-lisp-mode-hook)
+
+ - Function: add-hook HOOK FUNCTION &optional APPEND LOCAL
+ This function is the handy way to add function FUNCTION to hook
+ variable HOOK. The argument FUNCTION may be any valid Lisp
+ function with the proper number of arguments. For example,
+
+ (add-hook 'text-mode-hook 'my-text-hook-function)
+
+ adds `my-text-hook-function' to the hook called `text-mode-hook'.
+
+ You can use `add-hook' for abnormal hooks as well as for normal
+ hooks.
+
+ It is best to design your hook functions so that the order in
+ which they are executed does not matter. Any dependence on the
+ order is "asking for trouble." However, the order is predictable:
+ normally, FUNCTION goes at the front of the hook list, so it will
+ be executed first (barring another `add-hook' call).
+
+ If the optional argument APPEND is non-`nil', the new hook
+ function goes at the end of the hook list and will be executed
+ last.
+
+ If LOCAL is non-`nil', that says to make the new hook function
+ local to the current buffer. Before you can do this, you must
+ make the hook itself buffer-local by calling `make-local-hook'
+ (*not* `make-local-variable'). If the hook itself is not
+ buffer-local, then the value of LOCAL makes no difference--the
+ hook function is always global.
+
+ - Function: remove-hook HOOK FUNCTION &optional LOCAL
+ This function removes FUNCTION from the hook variable HOOK.
+
+ If LOCAL is non-`nil', that says to remove FUNCTION from the local
+ hook list instead of from the global hook list. If the hook
+ itself is not buffer-local, then the value of LOCAL makes no
+ difference.
+
+ - Function: make-local-hook HOOK
+ This function makes the hook variable `hook' local to the current
+ buffer. When a hook variable is local, it can have local and
+ global hook functions, and `run-hooks' runs all of them.
+
+ This function works by making `t' an element of the buffer-local
+ value. That serves as a flag to use the hook functions in the
+ default value of the hook variable as well as those in the local
+ value. Since `run-hooks' understands this flag, `make-local-hook'
+ works with all normal hooks. It works for only some non-normal
+ hooks--those whose callers have been updated to understand this
+ meaning of `t'.
+
+ Do not use `make-local-variable' directly for hook variables; it is
+ not sufficient.
+
+\1f
+File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
+
+Documentation
+*************
+
+ XEmacs Lisp has convenient on-line help facilities, most of which
+derive their information from the documentation strings associated with
+functions and variables. This chapter describes how to write good
+documentation strings for your Lisp programs, as well as how to write
+programs to access documentation.
+
+ Note that the documentation strings for XEmacs are not the same thing
+as the XEmacs manual. Manuals have their own source files, written in
+the Texinfo language; documentation strings are specified in the
+definitions of the functions and variables they apply to. A collection
+of documentation strings is not sufficient as a manual because a good
+manual is not organized in that fashion; it is organized in terms of
+topics of discussion.
+
+* Menu:
+
+* Documentation Basics:: Good style for doc strings.
+ Where to put them. How XEmacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation:: Substituting current key bindings.
+* Describing Characters:: Making printable descriptions of
+ non-printing characters and key sequences.
+* Help Functions:: Subroutines used by XEmacs help facilities.
+* Obsoleteness:: Upgrading Lisp functionality over time.
+
+\1f
+File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
+
+Documentation Basics
+====================
+
+ A documentation string is written using the Lisp syntax for strings,
+with double-quote characters surrounding the text of the string. This
+is because it really is a Lisp string object. The string serves as
+documentation when it is written in the proper place in the definition
+of a function or variable. In a function definition, the documentation
+string follows the argument list. In a variable definition, the
+documentation string follows the initial value of the variable.
+
+ When you write a documentation string, make the first line a complete
+sentence (or two complete sentences) since some commands, such as
+`apropos', show only the first line of a multi-line documentation
+string. Also, you should not indent the second line of a documentation
+string, if you have one, because that looks odd when you use `C-h f'
+(`describe-function') or `C-h v' (`describe-variable'). *Note
+Documentation Tips::.
+
+ Documentation strings may contain several special substrings, which
+stand for key bindings to be looked up in the current keymaps when the
+documentation is displayed. This allows documentation strings to refer
+to the keys for related commands and be accurate even when a user
+rearranges the key bindings. (*Note Accessing Documentation::.)
+
+ Within the Lisp world, a documentation string is accessible through
+the function or variable that it describes:
+
+ * The documentation for a function is stored in the function
+ definition itself (*note Lambda Expressions::.). The function
+ `documentation' knows how to extract it.
+
+ * The documentation for a variable is stored in the variable's
+ property list under the property name `variable-documentation'.
+ The function `documentation-property' knows how to extract it.
+
+ To save space, the documentation for preloaded functions and
+variables (including primitive functions and autoloaded functions) is
+stored in the "internal doc file" `DOC'. The documentation for
+functions and variables loaded during the XEmacs session from
+byte-compiled files is stored in those very same byte-compiled files
+(*note Docs and Compilation::.).
+
+ XEmacs does not keep documentation strings in memory unless
+necessary. Instead, XEmacs maintains, for preloaded symbols, an
+integer offset into the internal doc file, and for symbols loaded from
+byte-compiled files, a list containing the filename of the
+byte-compiled file and an integer offset, in place of the documentation
+string. The functions `documentation' and `documentation-property' use
+that information to read the documentation from the appropriate file;
+this is transparent to the user.
+
+ For information on the uses of documentation strings, see *Note
+Help: (emacs)Help.
+
+ The `emacs/lib-src' directory contains two utilities that you can
+use to print nice-looking hardcopy for the file
+`emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
+
+\1f
+File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
+
+Access to Documentation Strings
+===============================
+
+ - Function: documentation-property SYMBOL PROPERTY &optional VERBATIM
+ This function returns the documentation string that is recorded in
+ SYMBOL's property list under property PROPERTY. It retrieves the
+ text from a file if necessary, and runs `substitute-command-keys'
+ to substitute actual key bindings. (This substitution is not done
+ if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
+ Emacs 19.)
+
+ (documentation-property 'command-line-processed
+ 'variable-documentation)
+ => "t once command line has been processed"
+
+ (symbol-plist 'command-line-processed)
+ => (variable-documentation 188902)
+
+ - Function: documentation FUNCTION &optional VERBATIM
+ This function returns the documentation string of FUNCTION. It
+ reads the text from a file if necessary. Then (unless VERBATIM is
+ non-`nil') it calls `substitute-command-keys', to return a value
+ containing the actual (current) key bindings.
+
+ The function `documentation' signals a `void-function' error if
+ FUNCTION has no function definition. However, it is ok if the
+ function definition has no documentation string. In that case,
+ `documentation' returns `nil'.
+
+ Here is an example of using the two functions, `documentation' and
+`documentation-property', to display the documentation strings for
+several symbols in a `*Help*' buffer.
+
+ (defun describe-symbols (pattern)
+ "Describe the XEmacs Lisp symbols matching PATTERN.
+ All symbols that have PATTERN in their name are described
+ in the `*Help*' buffer."
+ (interactive "sDescribe symbols matching: ")
+ (let ((describe-func
+ (function
+ (lambda (s)
+
+ ;; Print description of symbol.
+ (if (fboundp s) ; It is a function.
+ (princ
+ (format "%s\t%s\n%s\n\n" s
+ (if (commandp s)
+ (let ((keys (where-is-internal s)))
+ (if keys
+ (concat
+ "Keys: "
+ (mapconcat 'key-description
+ keys " "))
+ "Keys: none"))
+ "Function")
+
+ (or (documentation s)
+ "not documented"))))
+
+ (if (boundp s) ; It is a variable.
+
+ (princ
+ (format "%s\t%s\n%s\n\n" s
+ (if (user-variable-p s)
+ "Option " "Variable")
+
+ (or (documentation-property
+ s 'variable-documentation)
+ "not documented")))))))
+ sym-list)
+
+ ;; Build a list of symbols that match pattern.
+ (mapatoms (function
+ (lambda (sym)
+ (if (string-match pattern (symbol-name sym))
+ (setq sym-list (cons sym sym-list))))))
+
+ ;; Display the data.
+ (with-output-to-temp-buffer "*Help*"
+ (mapcar describe-func (sort sym-list 'string<))
+ (print-help-return-message))))
+
+ The `describe-symbols' function works like `apropos', but provides
+more information.
+
+ (describe-symbols "goal")
+
+ ---------- Buffer: *Help* ----------
+ goal-column Option
+ *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
+
+ set-goal-column Command: C-x C-n
+ Set the current horizontal position as a goal for C-n and C-p.
+
+ Those commands will move to this position in the line moved to
+ rather than trying to keep the same horizontal position.
+ With a non-nil argument, clears out the goal column
+ so that C-n and C-p resume vertical motion.
+ The goal column is stored in the variable `goal-column'.
+
+ temporary-goal-column Variable
+ Current goal column for vertical motion.
+ It is the column where point was
+ at the start of current run of vertical motion commands.
+ When the `track-eol' feature is doing its job, the value is 9999.
+ ---------- Buffer: *Help* ----------
+
+ - Function: Snarf-documentation FILENAME
+ This function is used only during XEmacs initialization, just
+ before the runnable XEmacs is dumped. It finds the file offsets
+ of the documentation strings stored in the file FILENAME, and
+ records them in the in-core function definitions and variable
+ property lists in place of the actual strings. *Note Building
+ XEmacs::.
+
+ XEmacs finds the file FILENAME in the `lib-src' directory. When
+ the dumped XEmacs is later executed, the same file is found in the
+ directory `doc-directory'. The usual value for FILENAME is `DOC',
+ but this can be changed by modifying the variable
+ `internal-doc-file-name'.
+
+ - Variable: internal-doc-file-name
+ This variable holds the name of the file containing documentation
+ strings of built-in symbols, usually `DOC'. The full pathname of
+ the internal doc file is `(concat doc-directory
+ internal-doc-file-name)'.
+
+ - Variable: doc-directory
+ This variable holds the name of the directory which contains the
+ "internal doc file" that contains documentation strings for
+ built-in and preloaded functions and variables.
+
+ In most cases, this is the same as `exec-directory'. They may be
+ different when you run XEmacs from the directory where you built
+ it, without actually installing it. See `exec-directory' in *Note
+ Help Functions::.
+
+ In older Emacs versions, `exec-directory' was used for this.
+
+ - Variable: data-directory
+ This variable holds the name of the directory in which XEmacs finds
+ certain system independent documentation and text files that come
+ with XEmacs. In older Emacs versions, `exec-directory' was used
+ for this.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
+
+Substituting Key Bindings in Documentation
+==========================================
+
+ When documentation strings refer to key sequences, they should use
+the current, actual key bindings. They can do so using certain special
+text sequences described below. Accessing documentation strings in the
+usual way substitutes current key binding information for these special
+sequences. This works by calling `substitute-command-keys'. You can
+also call that function yourself.
+
+ Here is a list of the special sequences and what they mean:
+
+`\[COMMAND]'
+ stands for a key sequence that will invoke COMMAND, or `M-x
+ COMMAND' if COMMAND has no key bindings.
+
+`\{MAPVAR}'
+ stands for a summary of the value of MAPVAR, which should be a
+ keymap. The summary is made by `describe-bindings'.
+
+`\<MAPVAR>'
+ stands for no text itself. It is used for a side effect: it
+ specifies MAPVAR as the keymap for any following `\[COMMAND]'
+ sequences in this documentation string.
+
+`\='
+ quotes the following character and is discarded; this `\=\=' puts
+ `\=' into the output, and `\=\[' puts `\[' into the output.
+
+ *Please note:* Each `\' must be doubled when written in a string in
+XEmacs Lisp.
+
+ - Function: substitute-command-keys STRING
+ This function scans STRING for the above special sequences and
+ replaces them by what they stand for, returning the result as a
+ string. This permits display of documentation that refers
+ accurately to the user's own customized key bindings.
+
+ Here are examples of the special sequences:
+
+ (substitute-command-keys
+ "To abort recursive edit, type: \\[abort-recursive-edit]")
+ => "To abort recursive edit, type: C-]"
+
+ (substitute-command-keys
+ "The keys that are defined for the minibuffer here are:
+ \\{minibuffer-local-must-match-map}")
+ => "The keys that are defined for the minibuffer here are:
+
+ ? minibuffer-completion-help
+ SPC minibuffer-complete-word
+ TAB minibuffer-complete
+ LFD minibuffer-complete-and-exit
+ RET minibuffer-complete-and-exit
+ C-g abort-recursive-edit
+ "
+ (substitute-command-keys
+ "To abort a recursive edit from the minibuffer, type\
+ \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
+ => "To abort a recursive edit from the minibuffer, type C-g."
+
+ (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.
+ Substrings of the form \\=\\<MAPVAR> 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.
+ Substrings of the form \<MAPVAR> 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."
+
+\1f
+File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
+
+Describing Characters for Help Messages
+=======================================
+
+ These functions convert events, key sequences or characters to
+textual descriptions. These descriptions are useful for including
+arbitrary text characters or key sequences in messages, because they
+convert non-printing and whitespace characters to sequences of printing
+characters. The description of a non-whitespace printing character is
+the character itself.
+
+ - Function: key-description SEQUENCE
+ This function returns a string containing the XEmacs standard
+ notation for the input events in SEQUENCE. The argument SEQUENCE
+ may be a string, vector or list. *Note Events::, for more
+ information about valid events. See also the examples for
+ `single-key-description', below.
+
+ - Function: single-key-description KEY
+ This function returns a string describing KEY in the standard
+ XEmacs notation for keyboard input. A normal printing character
+ appears as itself, but a control character turns into a string
+ starting with `C-', a meta character turns into a string starting
+ with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
+ A symbol appears as the name of the symbol. An event that is a
+ list appears as the name of the symbol in the CAR of the list.
+
+ (single-key-description ?\C-x)
+ => "C-x"
+
+ (key-description "\C-x \M-y \n \t \r \f123")
+ => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
+
+ (single-key-description 'kp_next)
+ => "kp_next"
+
+ (single-key-description '(shift button1))
+ => "Sh-button1"
+
+ - Function: text-char-description CHARACTER
+ This function returns a string describing CHARACTER in the
+ standard XEmacs notation for characters that appear in text--like
+ `single-key-description', except that control characters are
+ represented with a leading caret (which is how control characters
+ in XEmacs buffers are usually displayed).
+
+ (text-char-description ?\C-c)
+ => "^C"
+
+ (text-char-description ?\M-m)
+ => "M-m"
+
+ (text-char-description ?\C-\M-m)
+ => "M-^M"
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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")
+ => #<buffer 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.
+
+\1f
+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")
+ => #<buffer foo>
+ (create-file-buffer "foo")
+ => #<buffer foo<2>>
+ (create-file-buffer "foo")
+ => #<buffer foo<3>>
+
+ 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'.
+
+\1f
+File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
+
+Saving Buffers
+==============
+
+ When you edit a file in XEmacs, you are actually working on a buffer
+that is visiting that file--that is, the contents of the file are
+copied into the buffer and the copy is what you edit. Changes to the
+buffer do not change the file until you "save" the buffer, which means
+copying the contents of the buffer into the file.
+
+ - Command: save-buffer &optional BACKUP-OPTION
+ This function saves the contents of the current buffer in its
+ visited file if the buffer has been modified since it was last
+ visited or saved. Otherwise it does nothing.
+
+ `save-buffer' is responsible for making backup files. Normally,
+ BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
+ if this is the first save since visiting the file. Other values
+ for BACKUP-OPTION request the making of backup files in other
+ circumstances:
+
+ * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
+ `save-buffer' function marks this version of the file to be
+ backed up when the buffer is next saved.
+
+ * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
+ `save-buffer' function unconditionally backs up the previous
+ version of the file before saving it.
+
+ - Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
+ This command saves some modified file-visiting buffers. Normally
+ it asks the user about each buffer. But if SAVE-SILENTLY-P is
+ non-`nil', it saves all the file-visiting buffers without querying
+ the user.
+
+ The optional EXITING argument, if non-`nil', requests this
+ function to offer also to save certain other buffers that are not
+ visiting files. These are buffers that have a non-`nil' local
+ value of `buffer-offer-save'. (A user who says yes to saving one
+ of these is asked to specify a file name to use.) The
+ `save-buffers-kill-emacs' function passes a non-`nil' value for
+ this argument.
+
+ - Variable: buffer-offer-save
+ When this variable is non-`nil' in a buffer, XEmacs offers to save
+ the buffer on exit even if the buffer is not visiting a file. The
+ variable is automatically local in all buffers. Normally, Mail
+ mode (used for editing outgoing mail) sets this to `t'.
+
+ - Command: write-file FILENAME
+ This function writes the current buffer into file FILENAME, makes
+ the buffer visit that file, and marks it not modified. Then it
+ renames the buffer based on FILENAME, appending a string like `<2>'
+ if necessary to make a unique buffer name. It does most of this
+ work by calling `set-visited-file-name' and `save-buffer'.
+
+ - Variable: write-file-hooks
+ The value of this variable is a list of functions to be called
+ before writing out a buffer to its visited file. If one of them
+ returns non-`nil', the file is considered already written and the
+ rest of the functions are not called, nor is the usual code for
+ writing the file executed.
+
+ If a function in `write-file-hooks' returns non-`nil', it is
+ responsible for making a backup file (if that is appropriate). To
+ do so, execute the following code:
+
+ (or buffer-backed-up (backup-buffer))
+
+ You might wish to save the file modes value returned by
+ `backup-buffer' and use that to set the mode bits of the file that
+ you write. This is what `save-buffer' normally does.
+
+ Even though this is not a normal hook, you can use `add-hook' and
+ `remove-hook' to manipulate the list. *Note Hooks::.
+
+ - Variable: local-write-file-hooks
+ This works just like `write-file-hooks', but it is intended to be
+ made local to particular buffers. It's not a good idea to make
+ `write-file-hooks' local to a buffer--use this variable instead.
+
+ The variable is marked as a permanent local, so that changing the
+ major mode does not alter a buffer-local value. This is
+ convenient for packages that read "file" contents in special ways,
+ and set up hooks to save the data in a corresponding way.
+
+ - Variable: write-contents-hooks
+ This works just like `write-file-hooks', but it is intended for
+ hooks that pertain to the contents of the file, as opposed to
+ hooks that pertain to where the file came from. Such hooks are
+ usually set up by major modes, as buffer-local bindings for this
+ variable. Switching to a new major mode always resets this
+ variable.
+
+ - Variable: after-save-hook
+ This normal hook runs after a buffer has been saved in its visited
+ file.
+
+ - Variable: file-precious-flag
+ If this variable is non-`nil', then `save-buffer' protects against
+ I/O errors while saving by writing the new file to a temporary
+ name instead of the name it is supposed to have, and then renaming
+ it to the intended name after it is clear there are no errors.
+ This procedure prevents problems such as a lack of disk space from
+ resulting in an invalid file.
+
+ As a side effect, backups are necessarily made by copying. *Note
+ Rename or Copy::. Yet, at the same time, saving a precious file
+ always breaks all hard links between the file you save and other
+ file names.
+
+ Some modes set this variable non-`nil' locally in particular
+ buffers.
+
+ - User Option: require-final-newline
+ This variable determines whether files may be written out that do
+ *not* end with a newline. If the value of the variable is `t',
+ then `save-buffer' silently adds a newline at the end of the file
+ whenever the buffer being saved does not already end in one. If
+ the value of the variable is non-`nil', but not `t', then
+ `save-buffer' asks the user whether to add a newline each time the
+ case arises.
+
+ If the value of the variable is `nil', then `save-buffer' doesn't
+ add newlines at all. `nil' is the default value, but a few major
+ modes set it to `t' in particular buffers.
+
+\1f
+File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files
+
+Reading from Files
+==================
+
+ You can copy a file from the disk and insert it into a buffer using
+the `insert-file-contents' function. Don't use the user-level command
+`insert-file' in a Lisp program, as that sets the mark.
+
+ - Function: insert-file-contents FILENAME &optional VISIT BEG END
+ REPLACE
+ This function inserts the contents of file FILENAME into the
+ current buffer after point. It returns a list of the absolute
+ file name and the length of the data inserted. An error is
+ signaled if FILENAME is not the name of a file that can be read.
+
+ The function `insert-file-contents' checks the file contents
+ against the defined file formats, and converts the file contents if
+ appropriate. *Note Format Conversion::. It also calls the
+ functions in the list `after-insert-file-functions'; see *Note
+ Saving Properties::.
+
+ If VISIT is non-`nil', this function additionally marks the buffer
+ as unmodified and sets up various fields in the buffer so that it
+ is visiting the file FILENAME: these include the buffer's visited
+ file name and its last save file modtime. This feature is used by
+ `find-file-noselect' and you probably should not use it yourself.
+
+ If BEG and END are non-`nil', they should be integers specifying
+ the portion of the file to insert. In this case, VISIT must be
+ `nil'. For example,
+
+ (insert-file-contents filename nil 0 500)
+
+ inserts the first 500 characters of a file.
+
+ If the argument REPLACE is non-`nil', it means to replace the
+ contents of the buffer (actually, just the accessible portion)
+ with the contents of the file. This is better than simply
+ deleting the buffer contents and inserting the whole file, because
+ (1) it preserves some marker positions and (2) it puts less data
+ in the undo list.
+
+ If you want to pass a file name to another process so that another
+program can read the file, use the function `file-local-copy'; see
+*Note Magic File Names::.
+
+\1f
+File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files
+
+Writing to Files
+================
+
+ You can write the contents of a buffer, or part of a buffer, directly
+to a file on disk using the `append-to-file' and `write-region'
+functions. Don't use these functions to write to files that are being
+visited; that could cause confusion in the mechanisms for visiting.
+
+ - Command: append-to-file START END FILENAME
+ This function appends the contents of the region delimited by
+ START and END in the current buffer to the end of file FILENAME.
+ If that file does not exist, it is created. If that file exists
+ it is overwritten. This function returns `nil'.
+
+ An error is signaled if FILENAME specifies a nonwritable file, or
+ a nonexistent file in a directory where files cannot be created.
+
+ - Command: write-region START END FILENAME &optional APPEND VISIT
+ This function writes the region delimited by START and END in the
+ current buffer into the file specified by FILENAME.
+
+ If START is a string, then `write-region' writes or appends that
+ string, rather than text from the buffer.
+
+ If APPEND is non-`nil', then the specified text is appended to the
+ existing file contents (if any).
+
+ If VISIT is `t', then XEmacs establishes an association between
+ the buffer and the file: the buffer is then visiting that file.
+ It also sets the last file modification time for the current
+ buffer to FILENAME's modtime, and marks the buffer as not
+ modified. This feature is used by `save-buffer', but you probably
+ should not use it yourself.
+
+ If VISIT is a string, it specifies the file name to visit. This
+ way, you can write the data to one file (FILENAME) while recording
+ the buffer as visiting another file (VISIT). The argument VISIT
+ is used in the echo area message and also for file locking; VISIT
+ is stored in `buffer-file-name'. This feature is used to
+ implement `file-precious-flag'; don't use it yourself unless you
+ really know what you're doing.
+
+ The function `write-region' converts the data which it writes to
+ the appropriate file formats specified by `buffer-file-format'.
+ *Note Format Conversion::. It also calls the functions in the list
+ `write-region-annotate-functions'; see *Note Saving Properties::.
+
+ Normally, `write-region' displays a message `Wrote file FILENAME'
+ in the echo area. If VISIT is neither `t' nor `nil' nor a string,
+ then this message is inhibited. This feature is useful for
+ programs that use files for internal purposes, files that the user
+ does not need to know about.
+
+\1f
+File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files
+
+File Locks
+==========
+
+ When two users edit the same file at the same time, they are likely
+to interfere with each other. XEmacs tries to prevent this situation
+from arising by recording a "file lock" when a file is being modified.
+XEmacs can then detect the first attempt to modify a buffer visiting a
+file that is locked by another XEmacs process, and ask the user what to
+do.
+
+ File locks do not work properly when multiple machines can share
+file systems, such as with NFS. Perhaps a better file locking system
+will be implemented in the future. When file locks do not work, it is
+possible for two users to make changes simultaneously, but XEmacs can
+still warn the user who saves second. Also, the detection of
+modification of a buffer visiting a file changed on disk catches some
+cases of simultaneous editing; see *Note Modification Time::.
+
+ - Function: file-locked-p &optional FILENAME
+ This function returns `nil' if the file FILENAME is not locked by
+ this XEmacs process. It returns `t' if it is locked by this
+ XEmacs, and it returns the name of the user who has locked it if it
+ is locked by someone else.
+
+ (file-locked-p "foo")
+ => nil
+
+ - Function: lock-buffer &optional FILENAME
+ This function locks the file FILENAME, if the current buffer is
+ modified. The argument FILENAME defaults to the current buffer's
+ visited file. Nothing is done if the current buffer is not
+ visiting a file, or is not modified.
+
+ - Function: unlock-buffer
+ This function unlocks the file being visited in the current buffer,
+ if the buffer is modified. If the buffer is not modified, then
+ the file should not be locked, so this function does nothing. It
+ also does nothing if the current buffer is not visiting a file.
+
+ - Function: ask-user-about-lock FILE OTHER-USER
+ This function is called when the user tries to modify FILE, but it
+ is locked by another user named OTHER-USER. The value it returns
+ determines what happens next:
+
+ * A value of `t' says to grab the lock on the file. Then this
+ user may edit the file and OTHER-USER loses the lock.
+
+ * A value of `nil' says to ignore the lock and let this user
+ edit the file anyway.
+
+ * This function may instead signal a `file-locked' error, in
+ which case the change that the user was about to make does
+ not take place.
+
+ The error message for this error looks like this:
+
+ error--> File is locked: FILE OTHER-USER
+
+ where `file' is the name of the file and OTHER-USER is the
+ name of the user who has locked the file.
+
+ The default definition of this function asks the user to choose
+ what to do. If you wish, you can replace the `ask-user-about-lock'
+ function with your own version that decides in another way. The
+ code for its usual definition is in `userlock.el'.
+
+\1f
+File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files
+
+Information about Files
+=======================
+
+ The functions described in this section all operate on strings that
+designate file names. All the functions have names that begin with the
+word `file'. These functions all return information about actual files
+or directories, so their arguments must all exist as actual files or
+directories unless otherwise noted.
+
+* Menu:
+
+* Testing Accessibility:: Is a given file readable? Writable?
+* Kinds of Files:: Is it a directory? A symbolic link?
+* Truenames:: Eliminating symbolic links from a file name.
+* File Attributes:: How large is it? Any other names? Etc.
+
+\1f
+File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files
+
+Testing Accessibility
+---------------------
+
+ These functions test for permission to access a file in specific
+ways.
+
+ - Function: file-exists-p FILENAME
+ This function returns `t' if a file named FILENAME appears to
+ exist. This does not mean you can necessarily read the file, only
+ that you can find out its attributes. (On Unix, this is true if
+ the file exists and you have execute permission on the containing
+ directories, regardless of the protection of the file itself.)
+
+ If the file does not exist, or if fascist access control policies
+ prevent you from finding the attributes of the file, this function
+ returns `nil'.
+
+ - Function: file-readable-p FILENAME
+ This function returns `t' if a file named FILENAME exists and you
+ can read it. It returns `nil' otherwise.
+
+ (file-readable-p "files.texi")
+ => t
+ (file-exists-p "/usr/spool/mqueue")
+ => t
+ (file-readable-p "/usr/spool/mqueue")
+ => nil
+
+ - Function: file-executable-p FILENAME
+ This function returns `t' if a file named FILENAME exists and you
+ can execute it. It returns `nil' otherwise. If the file is a
+ directory, execute permission means you can check the existence and
+ attributes of files inside the directory, and open those files if
+ their modes permit.
+
+ - Function: file-writable-p FILENAME
+ This function returns `t' if the file FILENAME can be written or
+ created by you, and `nil' otherwise. A file is writable if the
+ file exists and you can write it. It is creatable if it does not
+ exist, but the specified directory does exist and you can write in
+ that directory.
+
+ In the third example below, `foo' is not writable because the
+ parent directory does not exist, even though the user could create
+ such a directory.
+
+ (file-writable-p "~/foo")
+ => t
+ (file-writable-p "/foo")
+ => nil
+ (file-writable-p "~/no-such-dir/foo")
+ => nil
+
+ - Function: file-accessible-directory-p DIRNAME
+ This function returns `t' if you have permission to open existing
+ files in the directory whose name as a file is DIRNAME; otherwise
+ (or if there is no such directory), it returns `nil'. The value
+ of DIRNAME may be either a directory name or the file name of a
+ directory.
+
+ Example: after the following,
+
+ (file-accessible-directory-p "/foo")
+ => nil
+
+ we can deduce that any attempt to read a file in `/foo/' will give
+ an error.
+
+ - Function: file-ownership-preserved-p FILENAME
+ This function returns `t' if deleting the file FILENAME and then
+ creating it anew would keep the file's owner unchanged.
+
+ - Function: file-newer-than-file-p FILENAME1 FILENAME2
+ This function returns `t' if the file FILENAME1 is newer than file
+ FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
+ FILENAME2 does not exist, it returns `t'.
+
+ In the following example, assume that the file `aug-19' was written
+ on the 19th, `aug-20' was written on the 20th, and the file
+ `no-file' doesn't exist at all.
+
+ (file-newer-than-file-p "aug-19" "aug-20")
+ => nil
+ (file-newer-than-file-p "aug-20" "aug-19")
+ => t
+ (file-newer-than-file-p "aug-19" "no-file")
+ => t
+ (file-newer-than-file-p "no-file" "aug-19")
+ => nil
+
+ You can use `file-attributes' to get a file's last modification
+ time as a list of two numbers. *Note File Attributes::.
+
+\1f
+File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files
+
+Distinguishing Kinds of Files
+-----------------------------
+
+ This section describes how to distinguish various kinds of files,
+such as directories, symbolic links, and ordinary files.
+
+ - Function: file-symlink-p FILENAME
+ If the file FILENAME is a symbolic link, the `file-symlink-p'
+ function returns the file name to which it is linked. This may be
+ the name of a text file, a directory, or even another symbolic
+ link, or it may be a nonexistent file name.
+
+ If the file FILENAME is not a symbolic link (or there is no such
+ file), `file-symlink-p' returns `nil'.
+
+ (file-symlink-p "foo")
+ => nil
+ (file-symlink-p "sym-link")
+ => "foo"
+ (file-symlink-p "sym-link2")
+ => "sym-link"
+ (file-symlink-p "/bin")
+ => "/pub/bin"
+
+
+ - Function: file-directory-p FILENAME
+ This function returns `t' if FILENAME is the name of an existing
+ directory, `nil' otherwise.
+
+ (file-directory-p "~rms")
+ => t
+ (file-directory-p "~rms/lewis/files.texi")
+ => nil
+ (file-directory-p "~rms/lewis/no-such-file")
+ => nil
+ (file-directory-p "$HOME")
+ => nil
+ (file-directory-p
+ (substitute-in-file-name "$HOME"))
+ => t
+
+ - Function: file-regular-p FILENAME
+ This function returns `t' if the file FILENAME exists and is a
+ regular file (not a directory, symbolic link, named pipe,
+ terminal, or other I/O device).
+
+\1f
+File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files
+
+Truenames
+---------
+
+ The "truename" of a file is the name that you get by following
+symbolic links until none remain, then expanding to get rid of `.' and
+`..' as components. Strictly speaking, a file need not have a unique
+truename; the number of distinct truenames a file has is equal to the
+number of hard links to the file. However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
+
+ - Function: file-truename FILENAME &optional DEFAULT
+ The function `file-truename' returns the true name of the file
+ FILENAME. This is the name that you get by following symbolic
+ links until none remain.
+
+ If the filename is relative, DEFAULT is the directory to start
+ with. If DEFAULT is `nil' or missing, the current buffer's value
+ of `default-directory' is used.
+
+ *Note Buffer File Name::, for related information.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: File Attributes, Prev: Truenames, Up: Information about Files
+
+Other Information about Files
+-----------------------------
+
+ This section describes the functions for getting detailed information
+about a file, other than its contents. This information includes the
+mode bits that control access permission, the owner and group numbers,
+the number of names, the inode number, the size, and the times of access
+and modification.
+
+ - Function: file-modes FILENAME
+ This function returns the mode bits of FILENAME, as an integer.
+ The mode bits are also called the file permissions, and they
+ specify access control in the usual Unix fashion. If the
+ low-order bit is 1, then the file is executable by all users, if
+ the second-lowest-order bit is 1, then the file is writable by all
+ users, etc.
+
+ The highest value returnable is 4095 (7777 octal), meaning that
+ everyone has read, write, and execute permission, that the SUID bit
+ is set for both others and group, and that the sticky bit is set.
+
+ (file-modes "~/junk/diffs")
+ => 492 ; Decimal integer.
+ (format "%o" 492)
+ => "754" ; Convert to octal.
+
+ (set-file-modes "~/junk/diffs" 438)
+ => nil
+
+ (format "%o" 438)
+ => "666" ; Convert to octal.
+
+ % ls -l diffs
+ -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
+
+ - Function: file-nlinks FILENAME
+ This functions returns the number of names (i.e., hard links) that
+ file FILENAME has. If the file does not exist, then this function
+ returns `nil'. Note that symbolic links have no effect on this
+ function, because they are not considered to be names of the files
+ they link to.
+
+ % ls -l foo*
+ -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
+ -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
+
+ (file-nlinks "foo")
+ => 2
+ (file-nlinks "doesnt-exist")
+ => nil
+
+ - Function: file-attributes FILENAME
+ This function returns a list of attributes of file FILENAME. If
+ the specified file cannot be opened, it returns `nil'.
+
+ The elements of the list, in order, are:
+
+ 0. `t' for a directory, a string for a symbolic link (the name
+ linked to), or `nil' for a text file.
+
+ 1. The number of names the file has. Alternate names, also
+ known as hard links, can be created by using the
+ `add-name-to-file' function (*note Changing File
+ Attributes::.).
+
+ 2. The file's UID.
+
+ 3. The file's GID.
+
+ 4. The time of last access, as a list of two integers. The
+ first integer has the high-order 16 bits of time, the second
+ has the low 16 bits. (This is similar to the value of
+ `current-time'; see *Note Time of Day::.)
+
+ 5. The time of last modification as a list of two integers (as
+ above).
+
+ 6. The time of last status change as a list of two integers (as
+ above).
+
+ 7. The size of the file in bytes.
+
+ 8. The file's modes, as a string of ten letters or dashes, as in
+ `ls -l'.
+
+ 9. `t' if the file's GID would change if file were deleted and
+ recreated; `nil' otherwise.
+
+ 10. The file's inode number.
+
+ 11. The file system number of the file system that the file is
+ in. This element and the file's inode number together give
+ enough information to distinguish any two files on the
+ system--no two files can have the same values for both of
+ these numbers.
+
+ For example, here are the file attributes for `files.texi':
+
+ (file-attributes "files.texi")
+ => (nil
+ 1
+ 2235
+ 75
+ (8489 20284)
+ (8489 20284)
+ (8489 20285)
+ 14906
+ "-rw-rw-rw-"
+ nil
+ 129500
+ -32252)
+
+ and here is how the result is interpreted:
+
+ `nil'
+ is neither a directory nor a symbolic link.
+
+ `1'
+ has only one name (the name `files.texi' in the current
+ default directory).
+
+ `2235'
+ is owned by the user with UID 2235.
+
+ `75'
+ is in the group with GID 75.
+
+ `(8489 20284)'
+ was last accessed on Aug 19 00:09. Use `format-time-string' to
+ ! convert this number into a time string. *Note Time
+ Conversion::.
+
+ `(8489 20284)'
+ was last modified on Aug 19 00:09.
+
+ `(8489 20285)'
+ last had its inode changed on Aug 19 00:09.
+
+ `14906'
+ is 14906 characters long.
+
+ `"-rw-rw-rw-"'
+ has a mode of read and write access for the owner, group, and
+ world.
+
+ `nil'
+ would retain the same GID if it were recreated.
+
+ `129500'
+ has an inode number of 129500.
+
+ `-32252'
+ is on file system number -32252.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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"
+
+\1f
+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"))
+
+\1f
+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
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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")
+
+\1f
+File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
+
+User Name Completion
+--------------------
+
+ This section describes low-level subroutines for completing a user
+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
+ 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.
+
+ 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.
+
+ - 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
+ `user-name-completion', and a boolean indicating whether that
+ completion was unique.
+
+\1f
+File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
+
+Contents of Directories
+=======================
+
+ A directory is a kind of file that contains other files entered under
+various names. Directories are a feature of the file system.
+
+ XEmacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the `ls' shell command. In the
+latter case, it can optionally display information about each file,
+depending on the value of switches passed to the `ls' command.
+
+ - Function: directory-files DIRECTORY &optional FULL-NAME MATCH-REGEXP
+ NOSORT FILES-ONLY
+ This function returns a list of the names of the files in the
+ directory DIRECTORY. By default, the list is in alphabetical
+ order.
+
+ If FULL-NAME is non-`nil', the function returns the files'
+ absolute file names. Otherwise, it returns just the names
+ relative to the specified directory.
+
+ If MATCH-REGEXP is non-`nil', this function returns only those
+ file names that contain that regular expression--the other file
+ names are discarded from the list.
+
+ If NOSORT is non-`nil', `directory-files' does not sort the list,
+ so you get the file names in no particular order. Use this if you
+ want the utmost possible speed and don't care what order the files
+ are processed in. If the order of processing is visible to the
+ user, then the user will probably be happier if you do sort the
+ names.
+
+ If FILES-ONLY is the symbol `t', then only the "files" in the
+ directory will be returned; subdirectories will be excluded. If
+ FILES-ONLY is not `nil' and not `t', then only the subdirectories
+ will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
+ then both files and subdirectories will be returned.
+
+ (directory-files "~lewis")
+ => ("#foo#" "#foo.el#" "." ".."
+ "dired-mods.el" "files.texi"
+ "files.texi.~1~")
+
+ An error is signaled if DIRECTORY is not the name of a directory
+ that can be read.
+
+ - Function: insert-directory FILE SWITCHES &optional WILDCARD
+ FULL-DIRECTORY-P
+ This function inserts (in the current buffer) a directory listing
+ for directory FILE, formatted with `ls' according to SWITCHES. It
+ leaves point after the inserted text.
+
+ The argument FILE may be either a directory name or a file
+ specification including wildcard characters. If WILDCARD is
+ non-`nil', that means treat FILE as a file specification with
+ wildcards.
+
+ If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
+ and switches do not contain `-d', so that the listing should show
+ the full contents of the directory. (The `-d' option to `ls' says
+ to describe a directory itself rather than its contents.)
+
+ This function works by running a directory listing program whose
+ name is in the variable `insert-directory-program'. If WILDCARD is
+ non-`nil', it also runs the shell specified by `shell-file-name',
+ to expand the wildcards.
+
+ - Variable: insert-directory-program
+ This variable's value is the program to run to generate a
+ directory listing for the function `insert-directory'.
+
+\1f
+File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
+
+Creating and Deleting Directories
+=================================
+
+ Most XEmacs Lisp file-manipulation functions get errors when used on
+files that are directories. For example, you cannot delete a directory
+with `delete-file'. These special functions exist to create and delete
+directories.
+
+ - Command: make-directory DIRNAME &optional PARENTS
+ This function creates a directory named DIRNAME. Interactively,
+ the default choice of directory to create is the current default
+ directory for file names. That is useful when you have visited a
+ file in a nonexistent directory.
+
+ Non-interactively, optional argument PARENTS says whether to
+ create parent directories if they don't exist. (Interactively, this
+ always happens.)
+
+ - Command: delete-directory DIRNAME
+ This function deletes the directory named DIRNAME. The function
+ `delete-file' does not work for files that are directories; you
+ must use `delete-directory' in that case.
+
+\1f
+File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
+
+Making Certain File Names "Magic"
+=================================
+
+ You can implement special handling for certain file names. This is
+called making those names "magic". You must supply a regular
+expression to define the class of names (all those that match the
+regular expression), plus a handler that implements all the primitive
+XEmacs file operations for file names that do match.
+
+ The variable `file-name-handler-alist' holds a list of handlers,
+together with regular expressions that determine when to apply each
+handler. Each element has this form:
+
+ (REGEXP . HANDLER)
+
+All the XEmacs primitives for file access and file name transformation
+check the given file name against `file-name-handler-alist'. If the
+file name matches REGEXP, the primitives handle that file by calling
+HANDLER.
+
+ The first argument given to HANDLER is the name of the primitive;
+the remaining arguments are the arguments that were passed to that
+operation. (The first of these arguments is typically the file name
+itself.) For example, if you do this:
+
+ (file-exists-p FILENAME)
+
+and FILENAME has handler HANDLER, then HANDLER is called like this:
+
+ (funcall HANDLER 'file-exists-p FILENAME)
+
+ Here are the operations that a magic file name handler gets to
+handle:
+
+`add-name-to-file', `copy-file', `delete-directory', `delete-file',
+`diff-latest-backup-file', `directory-file-name', `directory-files',
+`dired-compress-file', `dired-uncache', `expand-file-name',
+`file-accessible-directory-p', `file-attributes', `file-directory-p',
+`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
+`file-name-all-completions', `file-name-as-directory',
+`file-name-completion', `file-name-directory', `file-name-nondirectory',
+`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
+`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
+`get-file-buffer', `insert-directory', `insert-file-contents', `load',
+`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
+`set-visited-file-modtime', `unhandled-file-name-directory',
+`verify-visited-file-modtime', `write-region'.
+
+ Handlers for `insert-file-contents' typically need to clear the
+buffer's modified flag, with `(set-buffer-modified-p nil)', if the
+VISIT argument is non-`nil'. This also has the effect of unlocking the
+buffer if it is locked.
+
+ The handler function must handle all of the above operations, and
+possibly others to be added in the future. It need not implement all
+these operations itself--when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation "in the usual way". It should always reinvoke the primitive
+for an operation it does not recognize. Here's one way to do this:
+
+ (defun my-file-handler (operation &rest args)
+ ;; First check for the specific operations
+ ;; that we have special handling for.
+ (cond ((eq operation 'insert-file-contents) ...)
+ ((eq operation 'write-region) ...)
+ ...
+ ;; Handle any operation we don't know about.
+ (t (let ((inhibit-file-name-handlers
+ (cons 'my-file-handler
+ (and (eq inhibit-file-name-operation operation)
+ inhibit-file-name-handlers)))
+ (inhibit-file-name-operation operation))
+ (apply operation args)))))
+
+ When a handler function decides to call the ordinary Emacs primitive
+for the operation at hand, it needs to prevent the primitive from
+calling the same handler once again, thus leading to an infinite
+recursion. The example above shows how to do this, with the variables
+`inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
+careful to use them exactly as shown above; the details are crucial for
+proper behavior in the case of multiple handlers, and for operations
+that have two file names that may each have handlers.
+
+ - Variable: inhibit-file-name-handlers
+ This variable holds a list of handlers whose use is presently
+ inhibited for a certain operation.
+
+ - Variable: inhibit-file-name-operation
+ The operation for which certain handlers are presently inhibited.
+
+ - Function: find-file-name-handler FILE OPERATION
+ This function returns the handler function for file name FILE, or
+ `nil' if there is none. The argument OPERATION should be the
+ operation to be performed on the file--the value you will pass to
+ the handler as its first argument when you call it. The operation
+ is needed for comparison with `inhibit-file-name-operation'.
+
+ - Function: file-local-copy FILENAME
+ This function copies file FILENAME to an ordinary non-magic file,
+ if it isn't one already.
+
+ If FILENAME specifies a "magic" file name, which programs outside
+ Emacs cannot directly read or write, this copies the contents to
+ an ordinary file and returns that file's name.
+
+ If FILENAME is an ordinary file name, not magic, then this function
+ does nothing and returns `nil'.
+
+ - Function: unhandled-file-name-directory FILENAME
+ This function returns the name of a directory that is not magic.
+ It uses the directory part of FILENAME if that is not magic.
+ Otherwise, it asks the handler what to do.
+
+ This is useful for running a subprocess; every subprocess must
+ have a non-magic directory to serve as its current directory, and
+ this function is a good way to come up with one.
+
+\1f
+File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
+
+Partial Files
+=============
+
+* Menu:
+
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+
+\1f
+File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
+
+Intro to Partial Files
+----------------------
+
+ A "partial file" is a section of a buffer (called the "master
+buffer") that is placed in its own buffer and treated as its own file.
+Changes made to the partial file are not reflected in the master buffer
+until the partial file is "saved" using the standard buffer save
+commands. Partial files can be "reverted" (from the master buffer)
+just like normal files. When a file part is active on a master buffer,
+that section of the master buffer is marked as read-only. Two file
+parts on the same master buffer are not allowed to overlap. Partial
+file buffers are indicated by the words `File Part' in the modeline.
+
+ The master buffer knows about all the partial files that are active
+on it, and thus killing or reverting the master buffer will be handled
+properly. When the master buffer is saved, if there are any unsaved
+partial files active on it then the user will be given the opportunity
+to first save these files.
+
+ When a partial file buffer is first modified, the master buffer is
+automatically marked as modified so that saving the master buffer will
+work correctly.
+
+\1f
+File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
+
+Creating a Partial File
+-----------------------
+
+ - Function: make-file-part &optional START END NAME BUFFER
+ Make a file part on buffer BUFFER out of the region. Call it
+ NAME. This command creates a new buffer containing the contents
+ of the region and marks the buffer as referring to the specified
+ buffer, called the "master buffer". When the file-part buffer is
+ saved, its changes are integrated back into the master buffer.
+ When the master buffer is deleted, all file parts are deleted with
+ it.
+
+ When called from a function, expects four arguments, START, END,
+ NAME, and BUFFER, all of which are optional and default to the
+ beginning of BUFFER, the end of BUFFER, a name generated from
+ BUFFER name, and the current buffer, respectively.
+
+\1f
+File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
+
+Detached Partial Files
+----------------------
+
+ Every partial file has an extent in the master buffer associated
+with it (called the "master extent"), marking where in the master
+buffer the partial file begins and ends. If the text in master buffer
+that is contained by the extent is deleted, then the extent becomes
+"detached", meaning that it no longer refers to a specific region of
+the master buffer. This can happen either when the text is deleted
+directly or when the master buffer is reverted. Neither of these should
+happen in normal usage because the master buffer should generally not be
+edited directly.
+
+ Before doing any operation that references a partial file's master
+extent, XEmacs checks to make sure that the extent is not detached. If
+this is the case, XEmacs warns the user of this and the master extent is
+deleted out of the master buffer, disconnecting the file part. The file
+part's filename is cleared and thus must be explicitly specified if the
+detached file part is to be saved.
+
+\1f
+File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
+
+File Format Conversion
+======================
+
+ The variable `format-alist' defines a list of "file formats", which
+describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+ - Variable: format-alist
+ This list contains one format definition for each defined file
+ format.
+
+ Each format definition is a list of this form:
+
+ (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
+
+ Here is what the elements in a format definition mean:
+
+NAME
+ The name of this format.
+
+DOC-STRING
+ A documentation string for the format.
+
+REGEXP
+ A regular expression which is used to recognize files represented
+ in this format.
+
+FROM-FN
+ A function to call to decode data in this format (to convert file
+ data into the usual Emacs data representation).
+
+ The FROM-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. It should convert the
+ text by editing it in place. Since this can change the length of
+ the text, FROM-FN should return the modified end position.
+
+ One responsibility of FROM-FN is to make sure that the beginning
+ of the file no longer matches REGEXP. Otherwise it is likely to
+ get called again.
+
+TO-FN
+ A function to call to encode data in this format (to convert the
+ usual Emacs data representation into this format).
+
+ The TO-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. There are two ways it
+ can do the conversion:
+
+ * By editing the buffer in place. In this case, TO-FN should
+ return the end-position of the range of text, as modified.
+
+ * By returning a list of annotations. This is a list of
+ elements of the form `(POSITION . STRING)', where POSITION is
+ an integer specifying the relative position in the text to be
+ written, and STRING is the annotation to add there. The list
+ must be sorted in order of position when TO-FN returns it.
+
+ When `write-region' actually writes the text from the buffer
+ to the file, it intermixes the specified annotations at the
+ corresponding positions. All this takes place without
+ modifying the buffer.
+
+MODIFY
+ A flag, `t' if the encoding function modifies the buffer, and
+ `nil' if it works by returning a list of annotations.
+
+MODE
+ A mode function to call after visiting a file converted from this
+ format.
+
+ The function `insert-file-contents' automatically recognizes file
+formats when it reads the specified file. It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format. Then it checks all the known formats over again. It
+keeps checking them until none of them is applicable.
+
+ Visiting a file, with `find-file-noselect' or the commands that use
+it, performs conversion likewise (because it calls
+`insert-file-contents'); it also calls the mode function for each
+format that it decodes. It stores a list of the format names in the
+buffer-local variable `buffer-file-format'.
+
+ - Variable: buffer-file-format
+ This variable states the format of the visited file. More
+ precisely, this is a list of the file format names that were
+ decoded in the course of visiting the current buffer's file. It
+ is always local in all buffers.
+
+ When `write-region' writes data into a file, it first calls the
+encoding functions for the formats listed in `buffer-file-format', in
+the order of appearance in the list.
+
+ - Function: format-write-file FILE FORMAT
+ This command writes the current buffer contents into the file FILE
+ in format FORMAT, and makes that format the default for future
+ saves of the buffer. The argument FORMAT is a list of format
+ names.
+
+ - Function: format-find-file FILE FORMAT
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-insert-file FILE FORMAT &optional BEG END
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If BEG and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::.).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-find-file FILE FORMAT
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-insert-file FILE FORMAT &optional BEG END
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If BEG and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::.).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Variable: auto-save-file-format
+ This variable specifies the format to use for auto-saving. Its
+ value is a list of format names, just like the value of
+ `buffer-file-format'; but it is used instead of
+ `buffer-file-format' for writing auto-save files. This variable
+ is always local in all buffers.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
+
+Files and MS-DOS
+================
+
+ Emacs on MS-DOS makes a distinction between text files and binary
+files. This is necessary because ordinary text files on MS-DOS use a
+two character sequence between lines: carriage-return and linefeed
+(CRLF). Emacs expects just a newline character (a linefeed) between
+lines. When Emacs reads or writes a text file on MS-DOS, it needs to
+convert the line separators. This means it needs to know which files
+are text files and which are binary. It makes this decision when
+visiting a file, and records the decision in the variable
+`buffer-file-type' for use when the file is saved.
+
+ *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
+
+ - Variable: buffer-file-type
+ This variable, automatically local in each buffer, records the
+ file type of the buffer's visited file. The value is `nil' for
+ text, `t' for binary.
+
+ - Function: find-buffer-file-type FILENAME
+ This function determines whether file FILENAME is a text file or a
+ binary file. It returns `nil' for text, `t' for binary.
+
+ - User Option: file-name-buffer-file-type-alist
+ This variable holds an alist for distinguishing text files from
+ binary files. Each element has the form (REGEXP . TYPE), where
+ REGEXP is matched against the file name, and TYPE may be is `nil'
+ for text, `t' for binary, or a function to call to compute which.
+ If it is a function, then it is called with a single argument (the
+ file name) and should return `t' or `nil'.
+
+ - User Option: default-buffer-file-type
+ This variable specifies the default file type for files whose names
+ don't indicate anything in particular. Its value should be `nil'
+ for text, or `t' for binary.
+
+ - Command: find-file-text FILENAME
+ Like `find-file', but treat the file as text regardless of its
+ name.
+
+ - Command: find-file-binary FILENAME
+ Like `find-file', but treat the file as binary regardless of its
+ name.
+
+\1f
+File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
+
+Backups and Auto-Saving
+***********************
+
+ Backup files and auto-save files are two methods by which XEmacs
+tries to protect the user from the consequences of crashes or of the
+user's own errors. Auto-saving preserves the text from earlier in the
+current editing session; backup files preserve file contents prior to
+the current session.
+
+* Menu:
+
+* Backup Files:: How backup files are made; how their names are chosen.
+* Auto-Saving:: How auto-save files are made; how their names are chosen.
+* Reverting:: `revert-buffer', and how to customize what it does.
+
+\1f
+File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
+
+Backup Files
+============
+
+ A "backup file" is a copy of the old contents of a file you are
+editing. XEmacs makes a backup file the first time you save a buffer
+into its visited file. Normally, this means that the backup file
+contains the contents of the file as it was before the current editing
+session. The contents of the backup file normally remain unchanged once
+it exists.
+
+ Backups are usually made by renaming the visited file to a new name.
+Optionally, you can specify that backup files should be made by copying
+the visited file. This choice makes a difference for files with
+multiple names; it also can affect whether the edited file remains owned
+by the original owner or becomes owned by the user editing it.
+
+ By default, XEmacs makes a single backup file for each file edited.
+You can alternatively request numbered backups; then each new backup
+file gets a new name. You can delete old numbered backups when you
+don't want them any more, or XEmacs can delete them automatically.
+
+* Menu:
+
+* Making Backups:: How XEmacs makes backup files, and when.
+* Rename or Copy:: Two alternatives: renaming the old file or copying it.
+* Numbered Backups:: Keeping multiple backups for each source file.
+* Backup Names:: How backup file names are computed; customization.
+
+\1f
+File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
+
+Making Backup Files
+-------------------
+
+ - Function: backup-buffer
+ This function makes a backup of the file visited by the current
+ buffer, if appropriate. It is called by `save-buffer' before
+ saving the buffer the first time.
+
+ - Variable: buffer-backed-up
+ This buffer-local variable indicates whether this buffer's file has
+ been backed up on account of this buffer. If it is non-`nil', then
+ the backup file has been written. Otherwise, the file should be
+ backed up when it is next saved (if backups are enabled). This is
+ a permanent local; `kill-local-variables' does not alter it.
+
+ - User Option: make-backup-files
+ This variable determines whether or not to make backup files. If
+ it is non-`nil', then XEmacs creates a backup of each file when it
+ is saved for the first time--provided that `backup-inhibited' is
+ `nil' (see below).
+
+ The following example shows how to change the `make-backup-files'
+ variable only in the `RMAIL' buffer and not elsewhere. Setting it
+ `nil' stops XEmacs from making backups of the `RMAIL' file, which
+ may save disk space. (You would put this code in your `.emacs'
+ file.)
+
+ (add-hook 'rmail-mode-hook
+ (function (lambda ()
+ (make-local-variable
+ 'make-backup-files)
+ (setq make-backup-files nil))))
+
+ - Variable: backup-enable-predicate
+ This variable's value is a function to be called on certain
+ occasions to decide whether a file should have backup files. The
+ function receives one argument, a file name to consider. If the
+ function returns `nil', backups are disabled for that file.
+ Otherwise, the other variables in this section say whether and how
+ to make backups.
+
+ The default value is this:
+
+ (lambda (name)
+ (or (< (length name) 5)
+ (not (string-equal "/tmp/"
+ (substring name 0 5)))))
+
+ - Variable: backup-inhibited
+ If this variable is non-`nil', backups are inhibited. It records
+ the result of testing `backup-enable-predicate' on the visited file
+ name. It can also coherently be used by other mechanisms that
+ inhibit backups based on which file is visited. For example, VC
+ sets this variable non-`nil' to prevent making backups for files
+ managed with a version control system.
+
+ This is a permanent local, so that changing the major mode does
+ not lose its value. Major modes should not set this
+ variable--they should set `make-backup-files' instead.
+
+\1f
+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'.
+
+\1f
+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: trim-versions-without-asking
+ 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
+
+Buffer Basics
+=============
+
+ 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.
+
+ Buffers in Emacs editing are objects that have distinct names and
+hold text that can be edited. Buffers appear to Lisp programs as a
+special data type. You can think of the contents of a buffer as an
+extendable string; insertions and deletions may occur in any part of
+the buffer. *Note Text::.
+
+ A Lisp buffer object contains numerous pieces of information. Some
+of this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions. For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+ Buffer-specific information that is directly accessible is stored in
+"buffer-local" variable bindings, which are variable values that are
+effective only in a particular buffer. This feature allows each buffer
+to override the values of certain variables. Most major modes override
+variables such as `fill-column' or `comment-column' in this way. For
+more information about buffer-local variables and functions related to
+them, see *Note Buffer-Local Variables::.
+
+ For functions and variables related to visiting files in buffers, see
+*Note Visiting Files:: and *Note Saving Buffers::. For functions and
+variables related to the display of buffers in windows, see *Note
+Buffers and Windows::.
+
+ - Function: bufferp OBJECT
+ This function returns `t' if OBJECT is a buffer, `nil' otherwise.
+
+\1f
+File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
+
+The Current Buffer
+==================
+
+ There are, in general, many buffers in an Emacs session. At any
+time, one of them is designated as the "current buffer". This is the
+buffer in which most editing takes place, because most of the primitives
+for examining or changing text in a buffer operate implicitly on the
+current buffer (*note Text::.). Normally the buffer that is displayed
+on the screen in the selected window is the current buffer, but this is
+not always so: a Lisp program can designate any buffer as current
+temporarily in order to operate on its contents, without changing what
+is displayed on the screen.
+
+ The way to designate a current buffer in a Lisp program is by calling
+`set-buffer'. The specified buffer remains current until a new one is
+designated.
+
+ When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
+switch visibly to a different buffer so that the user can edit it. For
+this, you must use the functions described in *Note Displaying
+Buffers::.
+
+ However, Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands written in XEmacs Lisp can be called from other
+programs as well as from the command loop. It is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose). Therefore, you
+should normally use `set-buffer' within a `save-excursion' that will
+restore the current buffer when your function is done (*note
+Excursions::.). Here is an example, the code for the command
+`append-to-buffer' (with the documentation string abridged):
+
+ (defun append-to-buffer (buffer start end)
+ "Append to specified buffer the text of the region.
+ ..."
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end))))
+
+This function binds a local variable to the current buffer, and then
+`save-excursion' records the values of point, the mark, and the
+original buffer. Next, `set-buffer' makes another buffer current.
+Finally, `insert-buffer-substring' copies the string from the original
+current buffer to the new current buffer.
+
+ If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed. Otherwise, you
+will not see the change immediately on the screen. The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+ If you make local bindings (with `let' or function arguments) for a
+variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope. Otherwise you might bind it in one buffer and unbind
+it in another! There are two ways to do this. In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding. Otherwise, use `save-excursion' to make sure that the buffer
+current at the beginning is current again whenever the variable is
+unbound.
+
+ It is not reliable to change the current buffer back with
+`set-buffer', because that won't do the job if a quit happens while the
+wrong buffer is current. Here is what *not* to do:
+
+ (let (buffer-read-only
+ (obuf (current-buffer)))
+ (set-buffer ...)
+ ...
+ (set-buffer obuf))
+
+Using `save-excursion', as shown below, handles quitting, errors, and
+`throw', as well as ordinary evaluation.
+
+ (let (buffer-read-only)
+ (save-excursion
+ (set-buffer ...)
+ ...))
+
+ - Function: current-buffer
+ This function returns the current buffer.
+
+ (current-buffer)
+ => #<buffer buffers.texi>
+
+ - Function: set-buffer BUFFER-OR-NAME
+ This function makes BUFFER-OR-NAME the current buffer. It does
+ not display the buffer in the currently selected window or in any
+ other window, so the user cannot necessarily see the buffer. But
+ Lisp programs can in any case work on it.
+
+ This function returns the buffer identified by BUFFER-OR-NAME. An
+ error is signaled if BUFFER-OR-NAME does not identify an existing
+ buffer.
+
+\1f
+File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
+
+Buffer Names
+============
+
+ Each buffer has a unique name, which is a string. Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument. Any argument called BUFFER-OR-NAME is of this sort,
+and an error is signaled if it is neither a string nor a buffer. Any
+argument called BUFFER must be an actual buffer object, not a name.
+
+ Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the `list-buffers' and
+`buffer-menu' commands don't mention them. A name starting with space
+also initially disables recording undo information; see *Note Undo::.
+
+ - Function: buffer-name &optional BUFFER
+ This function returns the name of BUFFER as a string. If BUFFER
+ is not supplied, it defaults to the current buffer.
+
+ If `buffer-name' returns `nil', it means that BUFFER has been
+ killed. *Note Killing Buffers::.
+
+ (buffer-name)
+ => "buffers.texi"
+
+ (setq foo (get-buffer "temp"))
+ => #<buffer temp>
+ (kill-buffer foo)
+ => nil
+ (buffer-name foo)
+ => nil
+ foo
+ => #<killed buffer>
+
+ - Command: rename-buffer NEWNAME &optional UNIQUE
+ This function renames the current buffer to NEWNAME. An error is
+ signaled if NEWNAME is not a string, or if there is already a
+ buffer with that name. The function returns `nil'.
+
+ Ordinarily, `rename-buffer' signals an error if NEWNAME is already
+ in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
+ make a name that is not in use. Interactively, you can make
+ UNIQUE non-`nil' with a numeric prefix argument.
+
+ One application of this command is to rename the `*shell*' buffer
+ to some other name, thus making it possible to create a second
+ shell buffer under the name `*shell*'.
+
+ - Function: get-buffer BUFFER-OR-NAME
+ This function returns the buffer specified by BUFFER-OR-NAME. If
+ BUFFER-OR-NAME is a string and there is no buffer with that name,
+ the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
+ as given. (That is not very useful, so the argument is usually a
+ name.) For example:
+
+ (setq b (get-buffer "lewis"))
+ => #<buffer lewis>
+ (get-buffer b)
+ => #<buffer lewis>
+ (get-buffer "Frazzle-nots")
+ => nil
+
+ See also the function `get-buffer-create' in *Note Creating
+ Buffers::.
+
+ - Function: generate-new-buffer-name STARTING-NAME &optional IGNORE
+ This function returns a name that would be unique for a new
+ buffer--but does not create the buffer. It starts with
+ STARTING-NAME, and produces a name not currently in use for any
+ buffer by appending a number inside of `<...>'.
+
+ If IGNORE is given, it specifies a name that is okay to use (if it
+ is in the sequence to be tried), even if a buffer with that name
+ exists.
+
+ See the related function `generate-new-buffer' in *Note Creating
+ Buffers::.
+
+\1f
+File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
+
+Buffer File Name
+================
+
+ The "buffer file name" is the name of the file that is visited in
+that buffer. When a buffer is not visiting a file, its buffer file name
+is `nil'. Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently. *Note
+Visiting Files::.
+
+ - Function: buffer-file-name &optional BUFFER
+ This function returns the absolute file name of the file that
+ BUFFER is visiting. If BUFFER is not visiting any file,
+ `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
+ defaults to the current buffer.
+
+ (buffer-file-name (other-buffer))
+ => "/usr/user/lewis/manual/files.texi"
+
+ - Variable: buffer-file-name
+ This buffer-local variable contains the name of the file being
+ visited in the current buffer, or `nil' if it is not visiting a
+ file. It is a permanent local, unaffected by
+ `kill-local-variables'.
+
+ buffer-file-name
+ => "/usr/user/lewis/manual/buffers.texi"
+
+ It is risky to change this variable's value without doing various
+ other things. See the definition of `set-visited-file-name' in
+ `files.el'; some of the things done there, such as changing the
+ buffer name, are not strictly necessary, but others are essential
+ to avoid confusing XEmacs.
+
+ - Variable: buffer-file-truename
+ This buffer-local variable holds the truename of the file visited
+ in the current buffer, or `nil' if no file is visited. It is a
+ permanent local, unaffected by `kill-local-variables'. *Note
+ Truenames::.
+
+ - Variable: buffer-file-number
+ This buffer-local variable holds the file number and directory
+ device number of the file visited in the current buffer, or `nil'
+ if no file or a nonexistent file is visited. It is a permanent
+ local, unaffected by `kill-local-variables'. *Note Truenames::.
+
+ The value is normally a list of the form `(FILENUM DEVNUM)'. This
+ pair of numbers uniquely identifies the file among all files
+ accessible on the system. See the function `file-attributes', in
+ *Note File Attributes::, for more information about them.
+
+ - Function: get-file-buffer FILENAME
+ This function returns the buffer visiting file FILENAME. If there
+ is no such buffer, it returns `nil'. The argument FILENAME, which
+ must be a string, is expanded (*note File Name Expansion::.), then
+ compared against the visited file names of all live buffers.
+
+ (get-file-buffer "buffers.texi")
+ => #<buffer buffers.texi>
+
+ In unusual circumstances, there can be more than one buffer
+ visiting the same file name. In such cases, this function returns
+ the first such buffer in the buffer list.
+
+ - Command: set-visited-file-name FILENAME
+ If FILENAME is a non-empty string, this function changes the name
+ of the file visited in current buffer to FILENAME. (If the buffer
+ had no visited file, this gives it one.) The *next time* the
+ buffer is saved it will go in the newly-specified file. This
+ command marks the buffer as modified, since it does not (as far as
+ XEmacs knows) match the contents of FILENAME, even if it matched
+ the former visited file.
+
+ If FILENAME is `nil' or the empty string, that stands for "no
+ visited file". In this case, `set-visited-file-name' marks the
+ buffer as having no visited file.
+
+ When the function `set-visited-file-name' is called interactively,
+ it prompts for FILENAME in the minibuffer.
+
+ See also `clear-visited-file-modtime' and
+ `verify-visited-file-modtime' in *Note Buffer Modification::.
+
+ - Variable: list-buffers-directory
+ This buffer-local variable records a string to display in a buffer
+ listing in place of the visited file name, for buffers that don't
+ have a visited file name. Dired buffers use this variable.
+
+\1f
+File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
+
+Buffer Modification
+===================
+
+ XEmacs keeps a flag called the "modified flag" for each buffer, to
+record whether you have changed the text of the buffer. This flag is
+set to `t' whenever you alter the contents of the buffer, and cleared
+to `nil' when you save it. Thus, the flag shows whether there are
+unsaved changes. The flag value is normally shown in the modeline
+(*note Modeline Variables::.), and controls saving (*note Saving
+Buffers::.) and auto-saving (*note Auto-Saving::.).
+
+ Some Lisp programs set the flag explicitly. For example, the
+function `set-visited-file-name' sets the flag to `t', because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+ The functions that modify the contents of buffers are described in
+*Note Text::.
+
+ - Function: buffer-modified-p &optional BUFFER
+ This function returns `t' if the buffer BUFFER has been modified
+ since it was last read in from a file or saved, or `nil'
+ otherwise. If BUFFER is not supplied, the current buffer is
+ tested.
+
+ - Function: set-buffer-modified-p FLAG
+ This function marks the current buffer as modified if FLAG is
+ non-`nil', or as unmodified if the flag is `nil'.
+
+ Another effect of calling this function is to cause unconditional
+ redisplay of the modeline for the current buffer. In fact, the
+ function `redraw-modeline' works by doing this:
+
+ (set-buffer-modified-p (buffer-modified-p))
+
+ - Command: not-modified &optional ARG
+ This command marks the current buffer as unmodified, and not
+ needing to be saved. (If ARG is non-`nil', the buffer is instead
+ marked as modified.) Don't use this function in programs, since it
+ prints a message in the echo area; use `set-buffer-modified-p'
+ (above) instead.
+
+ - Function: buffer-modified-tick &optional BUFFER
+ This function returns BUFFER`s modification-count. This is a
+ counter that increments every time the buffer is modified. If
+ BUFFER is `nil' (or omitted), the current buffer is used.
+
+\1f
+File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
+
+Comparison of Modification Time
+===============================
+
+ Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk. At this point, saving the
+buffer would overwrite the changes in the file. Occasionally this may
+be what you want, but usually it would lose valuable information.
+XEmacs therefore checks the file's modification time using the functions
+described below before saving the file.
+
+ - Function: verify-visited-file-modtime BUFFER
+ This function compares what BUFFER has recorded for the
+ modification time of its visited file against the actual
+ modification time of the file as recorded by the operating system.
+ The two should be the same unless some other process has written
+ the file since XEmacs visited or saved it.
+
+ The function returns `t' if the last actual modification time and
+ XEmacs's recorded modification time are the same, `nil' otherwise.
+
+ - Function: clear-visited-file-modtime
+ This function clears out the record of the last modification time
+ of the file being visited by the current buffer. As a result, the
+ next attempt to save this buffer will not complain of a
+ discrepancy in file modification times.
+
+ This function is called in `set-visited-file-name' and other
+ exceptional places where the usual test to avoid overwriting a
+ changed file should not be done.
+
+ - Function: visited-file-modtime
+ This function returns the buffer's recorded last file modification
+ time, as a list of the form `(HIGH . LOW)'. (This is the same
+ format that `file-attributes' uses to return time values; see
+ *Note File Attributes::.)
+
+ - Function: set-visited-file-modtime &optional TIME
+ This function updates the buffer's record of the last modification
+ time of the visited file, to the value specified by TIME if TIME
+ is not `nil', and otherwise to the last modification time of the
+ visited file.
+
+ If TIME is not `nil', it should have the form `(HIGH . LOW)' or
+ `(HIGH LOW)', in either case containing two integers, each of
+ which holds 16 bits of the time.
+
+ This function is useful if the buffer was not read from the file
+ normally, or if the file itself has been changed for some known
+ benign reason.
+
+ - Function: ask-user-about-supersession-threat FILENAME
+ This function is used to ask a user how to proceed after an
+ attempt to modify an obsolete buffer visiting file FILENAME. An
+ "obsolete buffer" is an unmodified buffer for which the associated
+ file on disk is newer than the last save-time of the buffer. This
+ means some other program has probably altered the file.
+
+ Depending on the user's answer, the function may return normally,
+ in which case the modification of the buffer proceeds, or it may
+ signal a `file-supersession' error with data `(FILENAME)', in which
+ case the proposed buffer modification is not allowed.
+
+ This function is called automatically by XEmacs on the proper
+ occasions. It exists so you can customize XEmacs by redefining it.
+ See the file `userlock.el' for the standard definition.
+
+ See also the file locking mechanism in *Note File Locks::.
+
+\1f
+File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
+
+Read-Only Buffers
+=================
+
+ If a buffer is "read-only", then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+ Read-only buffers are used in two kinds of situations:
+
+ * A buffer visiting a write-protected file is normally read-only.
+
+ Here, the purpose is to show the user that editing the buffer with
+ the aim of saving it in the file may be futile or undesirable.
+ The user who wants to change the buffer text despite this can do
+ so after clearing the read-only flag with `C-x C-q'.
+
+ * Modes such as Dired and Rmail make buffers read-only when altering
+ the contents with the usual editing commands is probably a mistake.
+
+ The special commands of these modes bind `buffer-read-only' to
+ `nil' (with `let') or bind `inhibit-read-only' to `t' around the
+ places where they change the text.
+
+ - Variable: buffer-read-only
+ This buffer-local variable specifies whether the buffer is
+ read-only. The buffer is read-only if this variable is non-`nil'.
+
+ - Variable: inhibit-read-only
+ If this variable is non-`nil', then read-only buffers and read-only
+ characters may be modified. Read-only characters in a buffer are
+ those that have non-`nil' `read-only' properties (either text
+ properties or extent properties). *Note Extent Properties::, for
+ more information about text properties and extent properties.
+
+ If `inhibit-read-only' is `t', all `read-only' character
+ properties have no effect. If `inhibit-read-only' is a list, then
+ `read-only' character properties have no effect if they are members
+ of the list (comparison is done with `eq').
+
+ - Command: toggle-read-only
+ This command changes whether the current buffer is read-only. It
+ is intended for interactive use; don't use it in programs. At any
+ given point in a program, you should know whether you want the
+ read-only flag on or off; so you can set `buffer-read-only'
+ explicitly to the proper value, `t' or `nil'.
+
+ - Function: barf-if-buffer-read-only
+ This function signals a `buffer-read-only' error if the current
+ buffer is read-only. *Note Interactive Call::, for another way to
+ signal an error if the current buffer is read-only.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
+
+The Buffer List
+===============
+
+ The "buffer list" is a list of all live buffers. Creating a buffer
+adds it to this list, and killing a buffer deletes it. The order of
+the buffers in the list is based primarily on how recently each buffer
+has been displayed in the selected window. Buffers move to the front
+of the list when they are selected and to the end when they are buried.
+Several functions, notably `other-buffer', use this ordering. A
+buffer list displayed for the user also follows this order.
+
+ Every frame has its own order for the buffer list. Switching to a
+new buffer inside of a particular frame changes the buffer list order
+for that frame, but does not affect the buffer list order of any other
+frames. In addition, there is a global, non-frame buffer list order
+that is independent of the buffer list orders for any particular frame.
+
+ Note that the different buffer lists all contain the same elements.
+It is only the order of those elements that is different.
+
+ - Function: buffer-list &optional FRAME
+ This function returns a list of all buffers, including those whose
+ names begin with a space. The elements are actual buffers, not
+ their names. The order of the list is specific to FRAME, which
+ defaults to the current frame. If FRAME is `t', the global,
+ non-frame ordering is returned instead.
+
+ (buffer-list)
+ => (#<buffer buffers.texi>
+ #<buffer *Minibuf-1*> #<buffer buffer.c>
+ #<buffer *Help*> #<buffer TAGS>)
+
+ ;; Note that the name of the minibuffer
+ ;; begins with a space!
+ (mapcar (function buffer-name) (buffer-list))
+ => ("buffers.texi" " *Minibuf-1*"
+ "buffer.c" "*Help*" "TAGS")
+
+ Buffers appear earlier in the list if they were current more
+ recently.
+
+ This list is a copy of a list used inside XEmacs; modifying it has
+ no effect on the buffers.
+
+ - Function: other-buffer &optional BUFFER-OR-NAME FRAME VISIBLE-OK
+ This function returns the first buffer in the buffer list other
+ than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
+ (FRAME defaults to the current frame. If FRAME is `t', then the
+ global, non-frame ordering is used.) Usually this is the buffer
+ most recently shown in the selected window, aside from
+ BUFFER-OR-NAME. Buffers are moved to the front of the list when
+ they are selected and to the end when they are buried. Buffers
+ whose names start with a space are not considered.
+
+ If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
+ `other-buffer' returns the first buffer on the buffer list that is
+ not visible in any window in a visible frame.
+
+ If the selected frame has a non-`nil' `buffer-predicate' property,
+ then `other-buffer' uses that predicate to decide which buffers to
+ consider. It calls the predicate once for each buffer, and if the
+ value is `nil', that buffer is ignored. *Note X Frame
+ Properties::.
+
+ If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
+ visible in any window on any visible frame, except as a last
+ resort. If VISIBLE-OK is non-`nil', then it does not matter
+ whether a buffer is displayed somewhere or not.
+
+ If no suitable buffer exists, the buffer `*scratch*' is returned
+ (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.
+
+ - Command: list-buffers &optional FILES-ONLY
+ This function displays a listing of the names of existing buffers.
+ It clears the buffer `*Buffer List*', then inserts the listing
+ into that buffer and displays it in a window. `list-buffers' is
+ intended for interactive use, and is described fully in `The XEmacs
+ Reference Manual'. It returns `nil'.
+
+ - Command: bury-buffer &optional BUFFER-OR-NAME
+ 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
+ `other-buffer' to return.
+
+ If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
+ current buffer. In addition, if the buffer is displayed in the
+ selected window, this switches to some other buffer (obtained using
+ `other-buffer') in the selected window. But if the buffer is
+ displayed in some other window, it remains displayed there.
+
+ If you wish to replace a buffer in all the windows that display
+ it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
+
+\1f
+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")
+ => #<buffer 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 `<N>' 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")
+ => #<buffer bar>
+ (generate-new-buffer "bar")
+ => #<buffer bar<2>>
+ (generate-new-buffer "bar")
+ => #<buffer bar<3>>
+
+ 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::.
+
+\1f
+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::.
+
+\1f
+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")
+ => #<buffer "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"))
+ => #<buffer "*scratch*">
+
+ - 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*"))
+ => (#<buffer "indirect">)
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 8 on windows.texi>
+ (window-edges) ; Edges in order:
+ => (0 0 80 50) ; left-top-right-bottom
+
+ ;; Returns window created
+ (setq w2 (split-window w 15))
+ => #<window 28 on windows.texi>
+
+ (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 32 on windows.texi>
+
+ (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.
+
+\1f
+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'.
+
+\1f
+File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
+
+Selecting Windows
+=================
+
+ When a window is selected, the buffer in the window becomes the
+current buffer, and the cursor will appear in it.
+
+ - Function: selected-window &optional DEVICE
+ This function returns the selected window. This is the window in
+ which the cursor appears and to which many commands apply. Each
+ separate device can have its own selected window, which is
+ remembered as focus changes from device to device. Optional
+ argument DEVICE specifies which device to return the selected
+ window for, and defaults to the selected device.
+
+ - Function: select-window WINDOW &optional NORECORD
+ This function makes WINDOW the selected window. The cursor then
+ appears in WINDOW (on redisplay). The buffer being displayed in
+ WINDOW is immediately designated the current buffer.
+
+ If optional argument NORECORD is non-`nil' then the global and
+ per-frame buffer orderings are not modified, as by the function
+ `record-buffer'.
+
+ The return value is WINDOW.
+
+ (setq w (next-window))
+ (select-window w)
+ => #<window 65 on windows.texi>
+
+ - Macro: save-selected-window FORMS...
+ This macro records the selected window, executes FORMS in
+ sequence, then restores the earlier selected window. It does not
+ save or restore anything about the sizes, arrangement or contents
+ of windows; therefore, if the FORMS change them, the changes are
+ permanent.
+
+ The following functions choose one of the windows on the screen,
+offering various criteria for the choice.
+
+ - Function: get-lru-window &optional FRAME
+ This function returns the window least recently "used" (that is,
+ selected). The selected window is always the most recently used
+ window.
+
+ The selected window can be the least recently used window if it is
+ the only window. A newly created window becomes the least
+ recently used window until it is selected. A minibuffer window is
+ never a candidate.
+
+ The argument FRAME controls which windows are considered.
+
+ * If it is `nil', consider windows on the selected frame.
+
+ * If it is `t', consider windows on all frames.
+
+ * If it is `visible', consider windows on all visible frames.
+
+ * If it is 0, consider windows on all visible or iconified
+ frames.
+
+ * If it is a frame, consider windows on that frame.
+
+ - Function: get-largest-window &optional FRAME
+ This function returns the window with the largest area (height
+ times width). If there are no side-by-side windows, then this is
+ the window with the most lines. A minibuffer window is never a
+ candidate.
+
+ If there are two windows of the same size, then the function
+ returns the window that is first in the cyclic ordering of windows
+ (see following section), starting from the selected window.
+
+ The argument FRAME controls which set of windows are considered.
+ See `get-lru-window', above.
+
+\1f
+File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
+
+Cyclic Ordering of Windows
+==========================
+
+ When you use the command `C-x o' (`other-window') to select the next
+window, it moves through all the windows on the screen in a specific
+cyclic order. For any given configuration of windows, this order never
+varies. It is called the "cyclic ordering of windows".
+
+ This ordering generally goes from top to bottom, and from left to
+right. But it may go down first or go right first, depending on the
+order in which the windows were split.
+
+ If the first split was vertical (into windows one above each other),
+and then the subwindows were split horizontally, then the ordering is
+left to right in the top of the frame, and then left to right in the
+next lower part of the frame, and so on. If the first split was
+horizontal, the ordering is top to bottom in the left part, and so on.
+In general, within each set of siblings at any level in the window tree,
+the order is left to right, or top to bottom.
+
+ - Function: next-window &optional WINDOW MINIBUF ALL-FRAMES
+ This function returns the window following WINDOW in the cyclic
+ ordering of windows. This is the window that `C-x o' would select
+ if typed when WINDOW is selected. If WINDOW is the only window
+ visible, then this function returns WINDOW. If omitted, WINDOW
+ defaults to the selected window.
+
+ The value of the argument MINIBUF determines whether the
+ minibuffer is included in the window order. Normally, when
+ MINIBUF is `nil', the minibuffer is included if it is currently
+ active; this is the behavior of `C-x o'. (The minibuffer window
+ is active while the minibuffer is in use. *Note Minibuffers::.)
+
+ If MINIBUF is `t', then the cyclic ordering includes the
+ minibuffer window even if it is not active.
+
+ If MINIBUF is neither `t' nor `nil', then the minibuffer window is
+ not included even if it is active.
+
+ The argument ALL-FRAMES specifies which frames to consider. Here
+ are the possible values and their meanings:
+
+ `nil'
+ Consider all the windows in WINDOW's frame, plus the
+ minibuffer used by that frame even if it lies in some other
+ frame.
+
+ `t'
+ Consider all windows in all existing frames.
+
+ `visible'
+ Consider all windows in all visible frames. (To get useful
+ results, you must ensure WINDOW is in a visible frame.)
+
+ 0
+ Consider all windows in all visible or iconified frames.
+
+ anything else
+ Consider precisely the windows in WINDOW's frame, and no
+ others.
+
+ This example assumes there are two windows, both displaying the
+ buffer `windows.texi':
+
+ (selected-window)
+ => #<window 56 on windows.texi>
+ (next-window (selected-window))
+ => #<window 52 on windows.texi>
+ (next-window (next-window (selected-window)))
+ => #<window 56 on windows.texi>
+
+ - Function: previous-window &optional WINDOW MINIBUF ALL-FRAMES
+ This function returns the window preceding WINDOW in the cyclic
+ ordering of windows. The other arguments specify which windows to
+ include in the cycle, as in `next-window'.
+
+ - Command: other-window COUNT &optional FRAME
+ This function selects the COUNTth following window in the cyclic
+ order. If count is negative, then it selects the -COUNTth
+ preceding window. It returns `nil'.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The argument FRAME controls which set of windows are considered.
+ * If it is `nil' or omitted, then windows on the selected frame
+ are considered.
+
+ * If it is a frame, then windows on that frame are considered.
+
+ * If it is `t', then windows on all frames that currently exist
+ (including invisible and iconified frames) are considered.
+
+ * If it is the symbol `visible', then windows on all visible
+ frames are considered.
+
+ * If it is the number 0, then windows on all visible and
+ iconified frames are considered.
+
+ * If it is any other value, then the behavior is undefined.
+
+ - Function: walk-windows PROC &optional MINIBUF ALL-FRAMES
+ This function cycles through all windows, calling `proc' once for
+ each window with the window as its sole argument.
+
+ The optional arguments MINIBUF and ALL-FRAMES specify the set of
+ windows to include in the scan. See `next-window', above, for
+ details.
+
+\1f
+File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
+
+Buffers and Windows
+===================
+
+ This section describes low-level functions to examine windows or to
+display buffers in windows in a precisely controlled fashion. *Note
+Displaying Buffers::, for related functions that find a window to use
+and specify a buffer for it. The functions described there are easier
+to use than these, but they employ heuristics in choosing or creating a
+window; use these functions when you need complete control.
+
+ - Function: set-window-buffer WINDOW BUFFER-OR-NAME
+ This function makes WINDOW display BUFFER-OR-NAME as its contents.
+ It returns `nil'.
+
+ (set-window-buffer (selected-window) "foo")
+ => nil
+
+ - Function: window-buffer &optional WINDOW
+ This function returns the buffer that WINDOW is displaying. If
+ WINDOW is omitted, this function returns the buffer for the
+ selected window.
+
+ (window-buffer)
+ => #<buffer windows.texi>
+
+ - Function: get-buffer-window BUFFER-OR-NAME &optional FRAME
+ This function returns a window currently displaying
+ BUFFER-OR-NAME, or `nil' if there is none. If there are several
+ such windows, then the function returns the first one in the
+ cyclic ordering of windows, starting from the selected window.
+ *Note Cyclic Window Ordering::.
+
+ The argument ALL-FRAMES controls which windows to consider.
+
+ * If it is `nil', consider windows on the selected frame.
+
+ * If it is `t', consider windows on all frames.
+
+ * If it is `visible', consider windows on all visible frames.
+
+ * If it is 0, consider windows on all visible or iconified
+ frames.
+
+ * If it is a frame, consider windows on that frame.
+
+\1f
+File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
+
+Displaying Buffers in Windows
+=============================
+
+ In this section we describe convenient functions that choose a window
+automatically and use it to display a specified buffer. These functions
+can also split an existing window in certain circumstances. We also
+describe variables that parameterize the heuristics used for choosing a
+window. *Note Buffers and Windows::, for low-level functions that give
+you more precise control.
+
+ Do not use the functions in this section in order to make a buffer
+current so that a Lisp program can access or modify it; they are too
+drastic for that purpose, since they change the display of buffers in
+windows, which is gratuitous and will surprise the user. Instead, use
+`set-buffer' (*note Current Buffer::.) and `save-excursion' (*note
+Excursions::.), which designate buffers as current for programmed
+access without affecting the display of buffers in windows.
+
+ - Command: switch-to-buffer BUFFER-OR-NAME &optional NORECORD
+ This function makes BUFFER-OR-NAME the current buffer, and also
+ displays the buffer in the selected window. This means that a
+ human can see the buffer and subsequent keyboard commands will
+ apply to it. Contrast this with `set-buffer', which makes
+ BUFFER-OR-NAME the current buffer but does not display it in the
+ selected window. *Note Current Buffer::.
+
+ If BUFFER-OR-NAME does not identify an existing buffer, then a new
+ buffer by that name is created. The major mode for the new buffer
+ is set according to the variable `default-major-mode'. *Note Auto
+ Major Mode::.
+
+ Normally the specified buffer is put at the front of the buffer
+ list. This affects the operation of `other-buffer'. However, if
+ NORECORD is non-`nil', this is not done. *Note The Buffer List::.
+
+ The `switch-to-buffer' function is often used interactively, as
+ the binding of `C-x b'. It is also used frequently in programs.
+ It always returns `nil'.
+
+ - Command: switch-to-buffer-other-window BUFFER-OR-NAME
+ This function makes BUFFER-OR-NAME the current buffer and displays
+ it in a window not currently selected. It then selects that
+ window. The handling of the buffer is the same as in
+ `switch-to-buffer'.
+
+ The currently selected window is absolutely never used to do the
+ job. If it is the only window, then it is split to make a
+ distinct window for this purpose. If the selected window is
+ already displaying the buffer, then it continues to do so, but
+ another window is nonetheless found to display it in as well.
+
+ - Function: pop-to-buffer BUFFER-OR-NAME &optional OTHER-WINDOW
+ ON-FRAME
+ This function makes BUFFER-OR-NAME the current buffer and switches
+ to it in some window, preferably not the window previously
+ selected. The "popped-to" window becomes the selected window
+ within its frame.
+
+ If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
+ looks for a window in any visible frame already displaying the
+ buffer; if there is one, it returns that window and makes it be
+ selected within its frame. If there is none, it creates a new
+ frame and displays the buffer in it.
+
+ If `pop-up-frames' is `nil', then `pop-to-buffer' operates
+ entirely within the selected frame. (If the selected frame has
+ just a minibuffer, `pop-to-buffer' operates within the most
+ recently selected frame that was not just a minibuffer.)
+
+ If the variable `pop-up-windows' is non-`nil', windows may be
+ split to create a new window that is different from the original
+ window. For details, see *Note Choosing Window::.
+
+ If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
+ another window even if BUFFER-OR-NAME is already visible in the
+ selected window. Thus BUFFER-OR-NAME could end up displayed in
+ two windows. On the other hand, if BUFFER-OR-NAME is already
+ displayed in the selected window and OTHER-WINDOW is `nil', then
+ the selected window is considered sufficient display for
+ BUFFER-OR-NAME, so that nothing needs to be done.
+
+ All the variables that affect `display-buffer' affect
+ `pop-to-buffer' as well. *Note Choosing Window::.
+
+ If BUFFER-OR-NAME is a string that does not name an existing
+ buffer, a buffer by that name is created. The major mode for the
+ new buffer is set according to the variable `default-major-mode'.
+ *Note Auto Major Mode::.
+
+ If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
+
+ An example use of this function is found at the end of *Note
+ Filter Functions::.
+
+ - Command: replace-buffer-in-windows BUFFER
+ This function replaces BUFFER with some other buffer in all
+ windows displaying it. The other buffer used is chosen with
+ `other-buffer'. In the usual applications of this function, you
+ don't care which other buffer is used; you just want to make sure
+ that BUFFER is no longer displayed.
+
+ This function returns `nil'.
+
+\1f
+File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
+
+Choosing a Window for Display
+=============================
+
+ This section describes the basic facility that chooses a window to
+display a buffer in--`display-buffer'. All the higher-level functions
+and commands use this subroutine. Here we describe how to use
+`display-buffer' and how to customize it.
+
+ - Command: display-buffer BUFFER-OR-NAME &optional NOT-THIS-WINDOW
+ This command makes BUFFER-OR-NAME appear in some window, like
+ `pop-to-buffer', but it does not select that window and does not
+ make the buffer current. The identity of the selected window is
+ unaltered by this function.
+
+ If NOT-THIS-WINDOW is non-`nil', it means to display the specified
+ buffer in a window other than the selected one, even if it is
+ already on display in the selected window. This can cause the
+ buffer to appear in two windows at once. Otherwise, if
+ BUFFER-OR-NAME is already being displayed in any window, that is
+ good enough, so this function does nothing.
+
+ `display-buffer' returns the window chosen to display
+ BUFFER-OR-NAME.
+
+ Precisely how `display-buffer' finds or creates a window depends on
+ the variables described below.
+
+ A window can be marked as "dedicated" to a particular buffer. Then
+XEmacs will not automatically change which buffer appears in the
+window, such as `display-buffer' might normally do.
+
+ - Function: window-dedicated-p WINDOW
+ This function returns WINDOW's dedicated object, usually `t' or
+ `nil'.
+
+ - Function: set-window-buffer-dedicated WINDOW BUFFER
+ This function makes WINDOW display BUFFER and be dedicated to that
+ buffer. Then XEmacs will not automatically change which buffer
+ appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
+ not be dedicated (but doesn't change which buffer appears in it
+ currently).
+
+ - User Option: pop-up-windows
+ This variable controls whether `display-buffer' makes new windows.
+ If it is non-`nil' and there is only one window, then that window
+ is split. If it is `nil', then `display-buffer' does not split
+ the single window, but uses it whole.
+
+ - User Option: split-height-threshold
+ This variable determines when `display-buffer' may split a window,
+ if there are multiple windows. `display-buffer' always splits the
+ largest window if it has at least this many lines. If the largest
+ window is not this tall, it is split only if it is the sole window
+ and `pop-up-windows' is non-`nil'.
+
+ - User Option: pop-up-frames
+ This variable controls whether `display-buffer' makes new frames.
+ If it is non-`nil', `display-buffer' looks for an existing window
+ already displaying the desired buffer, on any visible frame. If
+ it finds one, it returns that window. Otherwise it makes a new
+ frame. The variables `pop-up-windows' and
+ `split-height-threshold' do not matter if `pop-up-frames' is
+ non-`nil'.
+
+ If `pop-up-frames' is `nil', then `display-buffer' either splits a
+ window or reuses one.
+
+ *Note Frames::, for more information.
+
+ - Variable: pop-up-frame-function
+ This variable specifies how to make a new frame if `pop-up-frames'
+ is non-`nil'.
+
+ Its value should be a function of no arguments. When
+ `display-buffer' makes a new frame, it does so by calling that
+ function, which should return a frame. The default value of the
+ variable is a function that creates a frame using properties from
+ `pop-up-frame-plist'.
+
+ - Variable: pop-up-frame-plist
+ This variable holds a plist specifying frame properties used when
+ `display-buffer' makes a new frame. *Note Frame Properties::, for
+ more information about frame properties.
+
+ - Variable: special-display-buffer-names
+ A list of buffer names for buffers that should be displayed
+ specially. If the buffer's name is in this list, `display-buffer'
+ handles the buffer specially.
+
+ By default, special display means to give the buffer a dedicated
+ frame.
+
+ If an element is a list, instead of a string, then the CAR of the
+ list is the buffer name, and the rest of the list says how to
+ create the frame. There are two possibilities for the rest of the
+ list. It can be a plist, specifying frame properties, or it can
+ contain a function and arguments to give to it. (The function's
+ first argument is always the buffer to be displayed; the arguments
+ from the list come after that.)
+
+ - Variable: special-display-regexps
+ A list of regular expressions that specify buffers that should be
+ displayed specially. If the buffer's name matches any of the
+ regular expressions in this list, `display-buffer' handles the
+ buffer specially.
+
+ By default, special display means to give the buffer a dedicated
+ frame.
+
+ If an element is a list, instead of a string, then the CAR of the
+ list is the regular expression, and the rest of the list says how
+ to create the frame. See above, under
+ `special-display-buffer-names'.
+
+ - Variable: special-display-function
+ This variable holds the function to call to display a buffer
+ specially. It receives the buffer as an argument, and should
+ return the window in which it is displayed.
+
+ The default value of this variable is
+ `special-display-popup-frame'.
+
+ - Function: special-display-popup-frame BUFFER
+ This function makes BUFFER visible in a frame of its own. If
+ BUFFER is already displayed in a window in some frame, it makes
+ the frame visible and raises it, to use that window. Otherwise, it
+ creates a frame that will be dedicated to BUFFER.
+
+ This function uses an existing window displaying BUFFER whether or
+ not it is in a frame of its own; but if you set up the above
+ variables in your init file, before BUFFER was created, then
+ presumably the window was previously made by this function.
+
+ - User Option: special-display-frame-plist
+ This variable holds frame properties for
+ `special-display-popup-frame' to use when it creates a frame.
+
+ - Variable: same-window-buffer-names
+ A list of buffer names for buffers that should be displayed in the
+ selected window. If the buffer's name is in this list,
+ `display-buffer' handles the buffer by switching to it in the
+ selected window.
+
+ - Variable: same-window-regexps
+ A list of regular expressions that specify buffers that should be
+ displayed in the selected window. If the buffer's name matches
+ any of the regular expressions in this list, `display-buffer'
+ handles the buffer by switching to it in the selected window.
+
+ - Variable: display-buffer-function
+ This variable is the most flexible way to customize the behavior of
+ `display-buffer'. If it is non-`nil', it should be a function
+ that `display-buffer' calls to do the work. The function should
+ accept two arguments, the same two arguments that `display-buffer'
+ received. It should choose or create a window, display the
+ specified buffer, and then return the window.
+
+ This hook takes precedence over all the other options and hooks
+ described above.
+
+ A window can be marked as "dedicated" to its buffer. Then
+`display-buffer' does not try to use that window.
+
+ - Function: window-dedicated-p WINDOW
+ This function returns `t' if WINDOW is marked as dedicated;
+ otherwise `nil'.
+
+ - Function: set-window-dedicated-p WINDOW FLAG
+ This function marks WINDOW as dedicated if FLAG is non-`nil', and
+ nondedicated otherwise.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
+
+Windows and Point
+=================
+
+ Each window has its own value of point, independent of the value of
+point in other windows displaying the same buffer. This makes it useful
+to have multiple windows showing one buffer.
+
+ * The window point is established when a window is first created; it
+ is initialized from the buffer's point, or from the window point
+ of another window opened on the buffer if such a window exists.
+
+ * Selecting a window sets the value of point in its buffer to the
+ window's value of point. Conversely, deselecting a window sets
+ the window's value of point from that of the buffer. Thus, when
+ you switch between windows that display a given buffer, the point
+ value for the selected window is in effect in the buffer, while
+ the point values for the other windows are stored in those windows.
+
+ * As long as the selected window displays the current buffer, the
+ window's point and the buffer's point always move together; they
+ remain equal.
+
+ * *Note Positions::, for more details on buffer positions.
+
+ As far as the user is concerned, point is where the cursor is, and
+when the user switches to another buffer, the cursor jumps to the
+position of point in that buffer.
+
+ - Function: window-point WINDOW
+ This function returns the current position of point in WINDOW.
+ For a nonselected 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.
+
+ Strictly speaking, it would be more correct to return the
+ "top-level" value of point, outside of any `save-excursion' forms.
+ But that value is hard to find.
+
+ - Function: set-window-point WINDOW POSITION
+ This function positions point in WINDOW at position POSITION in
+ WINDOW's buffer.
+
+\1f
+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::.
+
+\1f
+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)
+
+\1f
+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)))))
+
+\1f
+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 on "windows.texi" 0x679b>
+ (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 on "windows.texi" 0x7538>
+ (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 on "windows.texi" 0x68a6>
+ (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 on "windows.texi" 0x7538>
+ (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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
+
+Changing the Size of a Window
+=============================
+
+ The window size functions fall into two classes: high-level commands
+that change the size of windows and low-level functions that access
+window size. XEmacs does not permit overlapping windows or gaps between
+windows, so resizing one window affects other windows.
+
+ - Command: enlarge-window SIZE &optional HORIZONTAL WINDOW
+ This function makes the selected window SIZE lines taller,
+ stealing lines from neighboring windows. It takes the lines from
+ one window at a time until that window is used up, then takes from
+ another. If a window from which lines are stolen shrinks below
+ `window-min-height' lines, that window disappears.
+
+ If HORIZONTAL is non-`nil', this function makes WINDOW wider by
+ SIZE columns, stealing columns instead of lines. If a window from
+ which columns are stolen shrinks below `window-min-width' columns,
+ that window disappears.
+
+ If the requested size would exceed that of the window's frame,
+ then the function makes the window occupy the entire height (or
+ width) of the frame.
+
+ If SIZE is negative, this function shrinks the window by -SIZE
+ lines or columns. If that makes the window smaller than the
+ minimum size (`window-min-height' and `window-min-width'),
+ `enlarge-window' deletes the window.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ `enlarge-window' returns `nil'.
+
+ - Command: enlarge-window-horizontally COLUMNS
+ This function makes the selected window COLUMNS wider. It could
+ be defined as follows:
+
+ (defun enlarge-window-horizontally (columns)
+ (enlarge-window columns t))
+
+ - Command: enlarge-window-pixels COUNT &optional SIDE WINDOW
+ This function makes the selected window COUNT pixels larger. When
+ called from Lisp, optional second argument SIDE non-`nil' means to
+ grow sideways COUNT pixels, and optional third argument WINDOW
+ specifies the window to change instead of the selected window.
+
+ - Command: shrink-window SIZE &optional HORIZONTAL WINDOW
+ This function is like `enlarge-window' but negates the argument
+ SIZE, making the selected window smaller by giving lines (or
+ columns) to the other windows. If the window shrinks below
+ `window-min-height' or `window-min-width', then it disappears.
+
+ If SIZE is negative, the window is enlarged by -SIZE lines or
+ columns.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ - Command: shrink-window-horizontally COLUMNS
+ This function makes the selected window COLUMNS narrower. It
+ could be defined as follows:
+
+ (defun shrink-window-horizontally (columns)
+ (shrink-window columns t))
+
+ - Command: shrink-window-pixels COUNT &optional SIDE WINDOW
+ This function makes the selected window COUNT pixels smaller.
+ When called from Lisp, optional second argument SIDE non-`nil'
+ means to shrink sideways COUNT pixels, and optional third argument
+ WINDOW specifies the window to change instead of the selected
+ window.
+
+ The following two variables constrain the window-size-changing
+functions to a minimum height and width.
+
+ - User Option: window-min-height
+ The value of this variable determines how short a window may become
+ before it is automatically deleted. Making a window smaller than
+ `window-min-height' automatically deletes it, and no window may be
+ created shorter than this. The absolute minimum height is two
+ (allowing one line for the mode line, and one line for the buffer
+ display). Actions that change window sizes reset this variable to
+ two if it is less than two. The default value is 4.
+
+ - User Option: window-min-width
+ The value of this variable determines how narrow a window may
+ become before it automatically deleted. Making a window smaller
+ than `window-min-width' automatically deletes it, and no window
+ may be created narrower than this. The absolute minimum width is
+ one; any value below that is ignored. The default value is 10.
+
+ - Variable: window-size-change-functions
+ This variable holds a list of functions to be called if the size
+ of any window changes for any reason. The functions are called
+ just once per redisplay, and just once for each frame on which
+ size changes have occurred.
+
+ Each function receives the frame as its sole argument. There is no
+ direct way to find out which windows changed size, or precisely
+ how; however, if your size-change function keeps track, after each
+ change, of the windows that interest you, you can figure out what
+ has changed by comparing the old size data with the new.
+
+ Creating or deleting windows counts as a size change, and therefore
+ causes these functions to be called. Changing the frame size also
+ counts, because it changes the sizes of the existing windows.
+
+ It is not a good idea to use `save-window-excursion' in these
+ functions, because that always counts as a size change, and it
+ would cause these functions to be called over and over. In most
+ cases, `save-selected-window' is what you need here.
+
+\1f
+File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
+
+Window Configurations
+=====================
+
+ A "window configuration" records the entire layout of a frame--all
+windows, their sizes, which buffers they contain, what part of each
+buffer is displayed, and the values of point and the mark. You can
+bring back an entire previous layout by restoring a window
+configuration previously saved.
+
+ If you want to record all frames instead of just one, use a frame
+configuration instead of a window configuration. *Note Frame
+Configurations::.
+
+ - Function: current-window-configuration
+ This function returns a new object representing XEmacs's current
+ window configuration, namely the number of windows, their sizes
+ and current buffers, which window is the selected window, and for
+ each window the displayed buffer, the display-start position, and
+ the positions of point and the mark. An exception is made for
+ point in the current buffer, whose value is not saved.
+
+ - Function: set-window-configuration CONFIGURATION
+ This function restores the configuration of XEmacs's windows and
+ buffers to the state specified by CONFIGURATION. The argument
+ CONFIGURATION must be a value that was previously returned by
+ `current-window-configuration'.
+
+ This function always counts as a window size change and triggers
+ execution of the `window-size-change-functions'. (It doesn't know
+ how to tell whether the new configuration actually differs from
+ the old one.)
+
+ Here is a way of using this function to get the same effect as
+ `save-window-excursion':
+
+ (let ((config (current-window-configuration)))
+ (unwind-protect
+ (progn (split-window-vertically nil)
+ ...)
+ (set-window-configuration config)))
+
+ - Special Form: save-window-excursion FORMS...
+ This special form records the window configuration, executes FORMS
+ in sequence, then restores the earlier window configuration. The
+ window configuration includes the value of point and the portion
+ of the buffer that is visible. It also includes the choice of
+ selected window. However, it does not include the value of point
+ in the current buffer; use `save-excursion' if you wish to
+ preserve that.
+
+ Don't use this construct when `save-selected-window' is all you
+ need.
+
+ Exit from `save-window-excursion' always triggers execution of the
+ `window-size-change-functions'. (It doesn't know how to tell
+ whether the restored configuration actually differs from the one in
+ effect at the end of the FORMS.)
+
+ The return value is the value of the final form in FORMS. For
+ example:
+
+ (split-window)
+ => #<window 25 on control.texi>
+ (setq w (selected-window))
+ => #<window 19 on control.texi>
+ (save-window-excursion
+ (delete-other-windows w)
+ (switch-to-buffer "foo")
+ 'do-something)
+ => do-something
+ ;; The frame is now split again.
+
+ - Function: window-configuration-p OBJECT
+ This function returns `t' if OBJECT is a window configuration.
+
+ Primitives to look inside of window configurations would make sense,
+but none are implemented. It is not clear they are useful enough to be
+worth implementing.
+
+\1f
+File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
+
+Frames
+******
+
+ A FRAME is a rectangle on the screen that contains one or more
+XEmacs windows. A frame initially contains a single main window (plus
+perhaps a minibuffer window), which you can subdivide vertically or
+horizontally into smaller windows.
+
+ When XEmacs runs on a text-only terminal, it starts with one "TTY
+frame". If you create additional ones, XEmacs displays one and only
+one at any given time--on the terminal screen, of course.
+
+ When XEmacs communicates directly with an X server, it does not have
+a TTY frame; instead, it starts with a single "X window frame". It can
+display multiple X window frames at the same time, each in its own X
+window.
+
+ - Function: framep OBJECT
+ This predicate returns `t' if OBJECT is a frame, and `nil'
+ otherwise.
+
+* Menu:
+
+* Creating Frames:: Creating additional frames.
+* Frame Properties:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
+* Deleting Frames:: Frames last until explicitly deleted.
+* Finding All Frames:: How to examine all existing frames.
+* Frames and Windows:: A frame contains windows;
+ display of text always works through windows.
+* Minibuffers and Frames:: How a frame finds the minibuffer to use.
+* Input Focus:: Specifying the selected frame.
+* Visibility of Frames:: Frames may be visible or invisible, or icons.
+* Raising and Lowering:: Raising a frame makes it hide other X windows;
+ lowering it makes the others hide them.
+* Frame Configurations:: Saving the state of all frames.
+* Frame Hooks:: Hooks for customizing frame behavior.
+
+ *Note Display::, for related information.
+
+\1f
+File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
+
+Creating Frames
+===============
+
+ To create a new frame, call the function `make-frame'.
+
+ - Function: make-frame &optional PROPS DEVICE
+ This function creates a new frame on DEVICE, if DEVICE permits
+ creation of frames. (An X server does; an ordinary terminal does
+ not (yet).) DEVICE defaults to the selected device if omitted.
+ *Note Consoles and Devices::.
+
+ The argument PROPS is a property list (a list of alternating
+ keyword-value specifications) of properties for the new frame. (An
+ alist is accepted for backward compatibility but should not be
+ passed in.) Any properties not mentioned in PROPS default
+ according to the value of the variable `default-frame-plist'. For
+ X devices, properties not specified in `default-frame-plist'
+ default in turn from `default-x-frame-plist' and, if not specified
+ there, from the X resources. For TTY devices,
+ `default-tty-frame-plist' is consulted as well as
+ `default-frame-plist'.
+
+ The set of possible properties depends in principle on what kind of
+ window system XEmacs uses to display its frames. *Note X Frame
+ Properties::, for documentation of individual properties you can
+ specify when creating an X window frame.
+
+\1f
+File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
+
+Frame Properties
+================
+
+ A frame has many properties that control its appearance and behavior.
+Just what properties a frame has depends on which display mechanism it
+uses.
+
+ Frame properties exist for the sake of window systems. A terminal
+frame has few properties, mostly for compatibility's sake; only the
+height, width and `buffer-predicate' properties really do something.
+
+* Menu:
+
+* Property Access:: How to change a frame's properties.
+* Initial Properties:: Specifying frame properties when you make a frame.
+* X Frame Properties:: List of frame properties.
+* Size and Position:: Changing the size and position of a frame.
+* Frame Name:: The name of a frame (as opposed to its title).
+
+\1f
+File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
+
+Access to Frame Properties
+--------------------------
+
+ These functions let you read and change the properties of a frame.
+
+ - Function: frame-properties &optional FRAME
+ This function returns a plist listing all the properties of FRAME
+ and their values.
+
+ - Function: frame-property FRAME PROPERTY &optional DEFAULT
+ This function returns FRAME's value for the property PROPERTY.
+
+ - Function: set-frame-properties FRAME PLIST
+ This function alters the properties of frame FRAME based on the
+ elements of property list PLIST. If you don't mention a property
+ in PLIST, its value doesn't change.
+
+ - Function: set-frame-property FRAME PROP VAL
+ This function sets the property PROP of frame FRAME to the value
+ VAL.
+
+\1f
+File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
+
+Initial Frame Properties
+------------------------
+
+ You can specify the properties for the initial startup frame by
+setting `initial-frame-plist' in your `.emacs' file.
+
+ - Variable: initial-frame-plist
+ This variable's value is a plist of alternating property-value
+ pairs used when creating the initial X window frame.
+
+ XEmacs creates the initial frame before it reads your `~/.emacs'
+ file. After reading that file, XEmacs checks
+ `initial-frame-plist', and applies the property settings in the
+ altered value to the already created initial frame.
+
+ If these settings affect the frame geometry and appearance, you'll
+ see the frame appear with the wrong ones and then change to the
+ specified ones. If that bothers you, you can specify the same
+ geometry and appearance with X resources; those do take affect
+ before the frame is created. *Note X Resources: (xemacs)Resources
+ X.
+
+ X resource settings typically apply to all frames. If you want to
+ specify some X resources solely for the sake of the initial frame,
+ and you don't want them to apply to subsequent frames, here's how
+ to achieve this: specify properties in `default-frame-plist' to
+ override the X resources for subsequent frames; then, to prevent
+ these from affecting the initial frame, specify the same
+ properties in `initial-frame-plist' with values that match the X
+ resources.
+
+ If these properties specify a separate minibuffer-only frame via a
+`minibuffer' property of `nil', and you have not yet created one,
+XEmacs creates one for you.
+
+ - Variable: minibuffer-frame-plist
+ This variable's value is a plist of properties used when creating
+ an initial minibuffer-only frame--if such a frame is needed,
+ according to the properties for the main initial frame.
+
+ - Variable: default-frame-plist
+ This is a plist specifying default values of frame properties for
+ subsequent XEmacs frames (not the initial ones).
+
+ See also `special-display-frame-plist', in *Note Choosing Window::.
+
+ If you use options that specify window appearance when you invoke
+XEmacs, they take effect by adding elements to `default-frame-plist'.
+One exception is `-geometry', which adds the specified position to
+`initial-frame-plist' instead. *Note Command Arguments:
+(xemacs)Command Arguments.
+
+\1f
+File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
+
+X Window Frame Properties
+-------------------------
+
+ Just what properties a frame has depends on what display mechanism it
+uses. Here is a table of the properties of an X window frame; of these,
+`name', `height', `width', and `buffer-predicate' provide meaningful
+information in non-X frames.
+
+`name'
+ The name of the frame. Most window managers display the frame's
+ name in the frame's border, at the top of the frame. If you don't
+ specify a name, and you have more than one frame, XEmacs sets the
+ frame name based on the buffer displayed in the frame's selected
+ window.
+
+ If you specify the frame name explicitly when you create the
+ frame, the name is also used (instead of the name of the XEmacs
+ executable) when looking up X resources for the frame.
+
+`display'
+ The display on which to open this frame. It should be a string of
+ the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
+ variable.
+
+`left'
+ The screen position of the left edge, in pixels, with respect to
+ the left edge of the screen. The value may be a positive number
+ POS, or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the right edge of the window with
+ respect to the right edge of the screen. A positive value of POS
+ counts toward the left. If the property is a negative integer
+ -POS then POS is positive!
+
+`top'
+ The screen position of the top edge, in pixels, with respect to the
+ top edge of the screen. The value may be a positive number POS,
+ or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the bottom edge of the window with
+ respect to the bottom edge of the screen. A positive value of POS
+ counts toward the top. If the property is a negative integer -POS
+ then POS is positive!
+
+`icon-left'
+ The screen position of the left edge *of the frame's icon*, in
+ pixels, counting from the left edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`icon-top'
+ The screen position of the top edge *of the frame's icon*, in
+ pixels, counting from the top edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`user-position'
+ Non-`nil' if the screen position of the frame was explicitly
+ requested by the user (for example, with the `-geometry' option).
+ Nothing automatically makes this property non-`nil'; it is up to
+ Lisp programs that call `make-frame' to specify this property as
+ well as specifying the `left' and `top' properties.
+
+`height'
+ The height of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-height'; see *Note Size and
+ Position::.)
+
+`width'
+ The width of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-width'; see *Note Size and
+ Position::.)
+
+`window-id'
+ The number of the X window for the frame.
+
+`minibuffer'
+ Whether this frame has its own minibuffer. The value `t' means
+ yes, `nil' means no, `only' means this frame is just a minibuffer.
+ If the value is a minibuffer window (in some other frame), the
+ new frame uses that minibuffer. (Minibuffer-only and
+ minibuffer-less frames are not yet implemented in XEmacs.)
+
+`buffer-predicate'
+ The buffer-predicate function for this frame. The function
+ `other-buffer' uses this predicate (from the selected frame) to
+ decide which buffers it should consider, if the predicate is not
+ `nil'. It calls the predicate with one arg, a buffer, once for
+ each buffer; if the predicate returns a non-`nil' value, it
+ considers that buffer.
+
+`scroll-bar-width'
+ The width of the vertical scroll bar, in pixels.
+
+`cursor-color'
+ The color for the cursor that shows point.
+
+`border-color'
+ The color for the border of the frame.
+
+`border-width'
+ The width in pixels of the window border.
+
+`internal-border-width'
+ The distance in pixels between text and border.
+
+`unsplittable'
+ If non-`nil', this frame's window is never split automatically.
+
+`inter-line-space'
+ The space in pixels between adjacent lines of text. (Not currently
+ implemented.)
+
+`modeline'
+ Whether the frame has a modeline.
+
+\1f
+File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
+
+Frame Size And Position
+-----------------------
+
+ You can read or change the size and position of a frame using the
+frame properties `left', `top', `height', and `width'. Whatever
+geometry properties you don't specify are chosen by the window manager
+in its usual fashion.
+
+ Here are some special features for working with sizes and positions:
+
+ - Function: set-frame-position FRAME LEFT TOP
+ This function sets the position of the top left corner of FRAME to
+ LEFT and TOP. These arguments are measured in pixels, and count
+ from the top left corner of the screen. Negative property values
+ count up or rightward from the top left corner of the screen.
+
+ - Function: frame-height &optional FRAME
+ - Function: frame-width &optional FRAME
+ These functions return the height and width of FRAME, measured in
+ lines and columns. If you don't supply FRAME, they use the
+ selected frame.
+
+ - Function: frame-pixel-height &optional FRAME
+ - Function: frame-pixel-width &optional FRAME
+ These functions return the height and width of FRAME, measured in
+ pixels. If you don't supply FRAME, they use the selected frame.
+
+ - Function: set-frame-size FRAME COLS ROWS &optional PRETEND
+ This function sets the size of FRAME, measured in characters; COLS
+ and ROWS specify the new width and height. (If PRETEND is
+ non-nil, it means that redisplay should act as if the frame's size
+ is COLS by ROWS, but the actual size of the frame should not be
+ changed. You should not normally use this option.)
+
+ You can also use the functions `set-frame-height' and
+`set-frame-width' to set the height and width individually. The frame
+is the first argument and the size (in rows or columns) is the second.
+(There is an optional third argument, PRETEND, which has the same
+purpose as the corresponding argument in `set-frame-size'.)
+
+\1f
+File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
+
+The Name of a Frame (As Opposed to Its Title)
+---------------------------------------------
+
+ Under X, every frame has a name, which is not the same as the title
+of the frame. A frame's name is used to look up its resources and does
+not normally change over the lifetime of a frame. It is perfectly
+allowable, and quite common, for multiple frames to have the same name.
+
+ - Function: frame-name &optional FRAME
+ This function returns the name of FRAME, which defaults to the
+ selected frame if not specified. The name of a frame can also be
+ obtained from the frame's properties. *Note Frame Properties::.
+
+ - Variable: default-frame-name
+ This variable holds the default name to assign to newly-created
+ frames. This can be overridden by arguments to `make-frame'. This
+ must be a string.
+
+\1f
+File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
+
+Frame Titles
+============
+
+ Every frame has a title; most window managers display the frame
+title at the top of the frame. You can specify an explicit title with
+the `name' frame property. But normally you don't specify this
+explicitly, and XEmacs computes the title automatically.
+
+ XEmacs computes the frame title based on a template stored in the
+variable `frame-title-format'.
+
+ - Variable: frame-title-format
+ This variable specifies how to compute a title for a frame when
+ you have not explicitly specified one.
+
+ The variable's value is actually a modeline construct, just like
+ `modeline-format'. *Note Modeline Data::.
+
+ - Variable: frame-icon-title-format
+ This variable specifies how to compute the title for an iconified
+ frame, when you have not explicitly specified the frame title.
+ This title appears in the icon itself.
+
+ - Function: x-set-frame-icon-pixmap FRAME PIXMAP &optional MASK
+ This function sets the icon of the given frame to the given image
+ instance, which should be an image instance object (as returned by
+ `make-image-instance'), a glyph object (as returned by
+ `make-glyph'), or `nil'. If a glyph object is given, the glyph
+ will be instantiated on the frame to produce an image instance
+ object.
+
+ If the given image instance has a mask, that will be used as the
+ icon mask; however, not all window managers support this.
+
+ The window manager is also not required to support color pixmaps,
+ only bitmaps (one plane deep).
+
+ If the image instance does not have a mask, then the optional
+ third argument may be the image instance to use as the mask (it
+ must be one plane deep). *Note Glyphs::.
+
+\1f
+File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
+
+Deleting Frames
+===============
+
+ Frames remain potentially visible until you explicitly "delete"
+them. A deleted frame cannot appear on the screen, but continues to
+exist as a Lisp object until there are no references to it.
+
+ - Command: delete-frame &optional FRAME
+ This function deletes the frame FRAME. By default, FRAME is the
+ selected frame.
+
+ - Function: frame-live-p FRAME
+ The function `frame-live-p' returns non-`nil' if the frame FRAME
+ has not been deleted.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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::.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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) species a valid device type.
+
+ - Function: valid-device-class-p DEVICE-CLASS
+ This function returns whether DEVICE-CLASS (which should be a
+ symbol) species a valid device class.
+
+ - Variable: terminal-device
+ This variable holds the initial terminal device object, which
+ represents XEmacs's stdout.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
+
+The Selected Console and Device
+===============================
+
+ - Function: select-console CONSOLE
+ This function selects the console CONSOLE. Subsequent editing
+ commands apply to its selected device, selected frame, and selected
+ window. The selection of CONSOLE lasts until the next time the
+ user does something to select a different console, or until the
+ next time this function is called.
+
+ - Function: selected-console
+ This function returns the console which is currently active.
+
+ - Function: select-device DEVICE
+ This function selects the device DEVICE.
+
+ - Function: selected-device &optional CONSOLE
+ This function returns the device which is currently active. If
+ optional CONSOLE is non-`nil', this function returns the device
+ that would be currently active if CONSOLE were the selected
+ console.
+
+\1f
+File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
+
+Console and Device I/O
+======================
+
+ - Function: console-disable-input CONSOLE
+ This function disables input on console CONSOLE.
+
+ - Function: console-enable-input CONSOLE
+ This function enables input on console CONSOLE.
+
+ Each device has a "baud rate" value associated with it. On most
+systems, changing this value will affect the amount of padding and
+other strategic decisions made during redisplay.
+
+ - Function: device-baud-rate &optional DEVICE
+ This function returns the output baud rate of DEVICE.
+
+ - Function: set-device-baud-rate DEVICE RATE
+ This function sets the output baud rate of DEVICE to RATE.
+
+\1f
+File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
+
+Positions
+*********
+
+ A "position" is the index of a character in the text of a buffer.
+More precisely, a position identifies the place between two characters
+(or before the first character, or after the last character), so we can
+speak of the character before or after a given position. However, we
+often speak of the character "at" a position, meaning the character
+after that position.
+
+ Positions are usually represented as integers starting from 1, but
+can also be represented as "markers"--special objects that relocate
+automatically when text is inserted or deleted so they stay with the
+surrounding characters. *Note Markers::.
+
+* Menu:
+
+* Point:: The special position where editing takes place.
+* Motion:: Changing point.
+* Excursions:: Temporary motion and buffer changes.
+* Narrowing:: Restricting editing to a portion of the buffer.
+
+\1f
+File: lispref.info, Node: Point, Next: Motion, Up: Positions
+
+Point
+=====
+
+ "Point" is a special buffer position used by many editing commands,
+including the self-inserting typed characters and text insertion
+functions. Other commands move point through the text to allow editing
+and insertion at different places.
+
+ Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character. Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
+
+ The value of point is a number between 1 and the buffer size plus 1.
+If narrowing is in effect (*note Narrowing::.), then point is
+constrained to fall within the accessible portion of the buffer
+(possibly at one end of it).
+
+ Each buffer has its own value of point, which is independent of the
+value of point in other buffers. Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer. This is why point can have different values in various windows
+that display the same buffer. When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important. *Note Window Point::, for more
+details.
+
+ - Function: point &optional BUFFER
+ This function returns the value of point in BUFFER, as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ (point)
+ => 175
+
+ - Function: point-min &optional BUFFER
+ This function returns the minimum accessible value of point in
+ BUFFER. This is normally 1, but if narrowing is in effect, it is
+ the position of the start of the region that you narrowed to.
+ (*Note Narrowing::.) BUFFER defaults to the current buffer if
+ omitted.
+
+ - Function: point-max &optional BUFFER
+ This function returns the maximum accessible value of point in
+ BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
+ in effect, in which case it is the position of the end of the
+ region that you narrowed to. (*note Narrowing::.). BUFFER
+ defaults to the current buffer if omitted.
+
+ - Function: buffer-end FLAG &optional BUFFER
+ This function returns `(point-min buffer)' if FLAG is less than 1,
+ `(point-max buffer)' otherwise. The argument FLAG must be a
+ number. BUFFER defaults to the current buffer if omitted.
+
+ - Function: buffer-size &optional BUFFER
+ This function returns the total number of characters in BUFFER.
+ In the absence of any narrowing (*note Narrowing::.), `point-max'
+ returns a value one larger than this. BUFFER defaults to the
+ current buffer if omitted.
+
+ (buffer-size)
+ => 35
+ (point-max)
+ => 36
+
+ - Variable: buffer-saved-size
+ The value of this buffer-local variable is the former length of the
+ current buffer, as of the last time it was read in, saved or
+ auto-saved.
+
+\1f
+File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
+
+Motion
+======
+
+ Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window. *Note Point::.
+
+* Menu:
+
+* Character Motion:: Moving in terms of characters.
+* Word Motion:: Moving in terms of words.
+* Buffer End Motion:: Moving to the beginning or end of the buffer.
+* Text Lines:: Moving in terms of lines of text.
+* Screen Lines:: Moving in terms of lines as displayed.
+* List Motion:: Moving by parsing lists and sexps.
+* Skipping Characters:: Skipping characters belonging to a certain set.
+
+\1f
+File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
+
+Motion by Characters
+--------------------
+
+ These functions move point based on a count of characters.
+`goto-char' is the fundamental primitive; the other functions use that.
+
+ - Command: goto-char POSITION &optional BUFFER
+ This function sets point in `buffer' to the value POSITION. If
+ POSITION is less than 1, it moves point to the beginning of the
+ buffer. If POSITION is greater than the length of the buffer, it
+ moves point to the end. BUFFER defaults to the current buffer if
+ omitted.
+
+ If narrowing is in effect, POSITION still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. If POSITION is out of range, `goto-char' moves point to
+ the beginning or the end of the accessible portion.
+
+ When this function is called interactively, POSITION is the
+ numeric prefix argument, if provided; otherwise it is read from the
+ minibuffer.
+
+ `goto-char' returns POSITION.
+
+ - Command: forward-char &optional COUNT BUFFER
+ This function moves point COUNT characters forward, towards the
+ end of the buffer (or backward, towards the beginning of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Command: backward-char &optional COUNT BUFFER
+ This function moves point COUNT characters backward, towards the
+ beginning of the buffer (or forward, towards the end of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+\1f
+File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
+
+Motion by Words
+---------------
+
+ These functions for parsing words use the syntax table to decide
+whether a given character is part of a word. *Note Syntax Tables::.
+
+ - Command: forward-word COUNT &optional BUFFER
+ This function moves point forward COUNT words (or backward if
+ COUNT is negative). Normally it returns `t'. If this motion
+ encounters the beginning or end of the buffer, or the limits of the
+ accessible portion when narrowing is in effect, point stops there
+ and the value is `nil'. BUFFER defaults to the current buffer if
+ omitted.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ - Command: backward-word COUNT &optional BUFFER
+ This function is just like `forward-word', except that it moves
+ backward until encountering the front of a word, rather than
+ forward. BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ This function is rarely used in programs, as it is more efficient
+ to call `forward-word' with a negative argument.
+
+ - Variable: words-include-escapes
+ This variable affects the behavior of `forward-word' and everything
+ that uses it. If it is non-`nil', then characters in the "escape"
+ and "character quote" syntax classes count as part of words.
+ Otherwise, they do not.
+
+\1f
+File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
+
+Motion to an End of the Buffer
+------------------------------
+
+ To move point to the beginning of the buffer, write:
+
+ (goto-char (point-min))
+
+Likewise, to move to the end of the buffer, use:
+
+ (goto-char (point-max))
+
+ Here are two commands that users use to do these things. They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
+
+ - Command: beginning-of-buffer &optional N
+ This function moves point to the beginning of the buffer (or the
+ limits of the accessible portion, when narrowing is in effect),
+ setting the mark at the previous position. If N is non-`nil',
+ then it puts point N tenths of the way from the beginning of the
+ buffer.
+
+ In an interactive call, N is the numeric prefix argument, if
+ provided; otherwise N defaults to `nil'.
+
+ Don't use this function in Lisp programs!
+
+ - Command: end-of-buffer &optional N
+ This function moves point to the end of the buffer (or the limits
+ of the accessible portion, when narrowing is in effect), setting
+ the mark at the previous position. If N is non-`nil', then it puts
+ point N tenths of the way from the end of the buffer.
+
+ In an interactive call, N is the numeric prefix argument, if
+ provided; otherwise N defaults to `nil'.
+
+ Don't use this function in Lisp programs!
+
+\1f
+File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
+
+Motion by Text Lines
+--------------------
+
+ Text lines are portions of the buffer delimited by newline
+characters, which are regarded as part of the previous line. The first
+text line begins at the beginning of the buffer, and the last text line
+ends at the end of the buffer whether or not the last character is a
+newline. The division of the buffer into text lines is not affected by
+the width of the window, by line continuation in display, or by how
+tabs and control characters are displayed.
+
+ - Command: goto-line LINE
+ This function moves point to the front of the LINEth line,
+ counting from line 1 at beginning of the buffer. If LINE is less
+ than 1, it moves point to the beginning of the buffer. If LINE is
+ greater than the number of lines in the buffer, it moves point to
+ the end of the buffer--that is, the *end of the last line* of the
+ buffer. This is the only case in which `goto-line' does not
+ necessarily move to the beginning of a line.
+
+ If narrowing is in effect, then LINE still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. So `goto-line' moves point to the beginning or end of the
+ accessible portion, if the line number specifies an inaccessible
+ position.
+
+ The return value of `goto-line' is the difference between LINE and
+ the line number of the line to which point actually was able to
+ move (in the full buffer, before taking account of narrowing).
+ Thus, the value is positive if the scan encounters the real end of
+ the buffer. The value is zero if scan encounters the end of the
+ accessible portion but not the real end of the buffer.
+
+ In an interactive call, LINE is the numeric prefix argument if one
+ has been provided. Otherwise LINE is read in the minibuffer.
+
+ - Command: beginning-of-line &optional COUNT BUFFER
+ This function moves point to the beginning of the current line.
+ With an argument COUNT not `nil' or 1, it moves forward COUNT-1
+ lines and then to the beginning of the line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: end-of-line &optional COUNT BUFFER
+ This function moves point to the end of the current line. With an
+ argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
+ then to the end of the line. BUFFER defaults to the current
+ buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: forward-line &optional COUNT BUFFER
+ This function moves point forward COUNT lines, to the beginning of
+ the line. If COUNT is negative, it moves point -COUNT lines
+ backward, to the beginning of a line. If COUNT is zero, it moves
+ point to the beginning of the current line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If `forward-line' encounters the beginning or end of the buffer (or
+ of the accessible portion) before finding that many lines, it sets
+ point there. No error is signaled.
+
+ `forward-line' returns the difference between COUNT and the number
+ of lines actually moved. If you attempt to move down five lines
+ from the beginning of a buffer that has only three lines, point
+ stops at the end of the last line, and the value will be 2.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Function: count-lines START END
+ This function returns the number of lines between the positions
+ START and END in the current buffer. If START and END are equal,
+ then it returns 0. Otherwise it returns at least 1, even if START
+ and END are on the same line. This is because the text between
+ them, considered in isolation, must contain at least one line
+ unless it is empty.
+
+ Here is an example of using `count-lines':
+
+ (defun current-line ()
+ "Return the vertical position of point..."
+ (+ (count-lines (window-start) (point))
+ (if (= (current-column) 0) 1 0)
+ -1))
+
+ Also see the functions `bolp' and `eolp' in *Note Near Point::.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+\1f
+File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
+
+Motion by Screen Lines
+----------------------
+
+ The line functions in the previous section count text lines,
+delimited only by newline characters. By contrast, these functions
+count screen lines, which are defined by the way the text appears on
+the screen. A text line is a single screen line if it is short enough
+to fit the width of the selected window, but otherwise it may occupy
+several screen lines.
+
+ In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines. In these cases,
+`vertical-motion' moves point much like `forward-line'. *Note
+Truncation::.
+
+ Because the width of a given string depends on the flags that control
+the appearance of certain characters, `vertical-motion' behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows). *Note Usual
+Display::.
+
+ These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned. If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code. *Note cache-long-line-scans: Text Lines.
+
+ - Function: vertical-motion COUNT &optional WINDOW PIXELS
+ This function moves point to the start of the frame line COUNT
+ frame lines down from the frame line containing point. If COUNT
+ is negative, it moves up instead. The optional second argument
+ WINDOW may be used to specify a window other than the selected
+ window in which to perform the motion.
+
+ Normally, `vertical-motion' returns the number of lines moved. The
+ value may be less in absolute value than COUNT if the beginning or
+ end of the buffer was reached. If the optional third argument,
+ PIXELS is non-`nil', the vertical pixel height of the motion which
+ took place is returned instead of the actual number of lines
+ moved. A motion of zero lines returns the height of the current
+ line.
+
+ Note that `vertical-motion' sets WINDOW's buffer's point, not
+ WINDOW's point. (This differs from FSF Emacs, which buggily always
+ sets current buffer's point, regardless of WINDOW.)
+
+ - Function: vertical-motion-pixels COUNT &optional WINDOW HOW
+ This function moves point to the start of the frame line PIXELS
+ vertical pixels down from the frame line containing point, or up if
+ PIXELS is negative. The optional second argument WINDOW is the
+ window to move in, and defaults to the selected window. The
+ optional third argument HOW specifies the stopping condition. A
+ negative integer indicates that the motion should be no more than
+ PIXELS. A positive value indicates that the motion should be at
+ least PIXELS. Any other value indicates that the motion should be
+ as close as possible to PIXELS.
+
+ - Command: move-to-window-line COUNT &optional WINDOW
+ This function moves point with respect to the text currently
+ displayed in WINDOW, which defaults to the selected window. It
+ moves point to the beginning of the screen line COUNT screen lines
+ from the top of the window. If COUNT is negative, that specifies a
+ position -COUNT lines from the bottom (or the last line of the
+ buffer, if the buffer ends above the specified screen position).
+
+ If COUNT is `nil', then point moves to the beginning of the line
+ in the middle of the window. If the absolute value of COUNT is
+ greater than the size of the window, then point moves to the place
+ that would appear on that screen line if the window were tall
+ enough. This will probably cause the next redisplay to scroll to
+ bring that location onto the screen.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The value returned is the window line number point has moved to,
+ with the top line in the window numbered 0.
+
+\1f
+File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
+
+Moving over Balanced Expressions
+--------------------------------
+
+ Here are several functions concerned with balanced-parenthesis
+expressions (also called "sexps" in connection with moving across them
+in XEmacs). The syntax table controls how these functions interpret
+various characters; see *Note Syntax Tables::. *Note Parsing
+Expressions::, for lower-level primitives for scanning sexps or parts of
+sexps. For user-level commands, see *Note Lists and Sexps:
+(emacs)Lists and Sexps.
+
+ - Command: forward-list &optional ARG
+ This function moves forward across ARG balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
+ is negative, move backward across that many groups of parentheses.
+
+ - Command: backward-list &optional ARG
+ This function moves backward across ARG balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
+ is negative, move forward across that many groups of parentheses.
+
+ - Command: up-list ARG
+ This function moves forward out of ARG levels of parentheses. A
+ negative argument means move backward but still to a less deep
+ spot.
+
+ - Command: down-list ARG
+ This function moves forward into ARG levels of parentheses. A
+ negative argument means move backward but still go deeper in
+ parentheses (-ARG levels).
+
+ - Command: forward-sexp &optional ARG
+ This function moves forward across ARG balanced expressions.
+ Balanced expressions include both those delimited by parentheses
+ and other kinds, such as words and string constants. ARG defaults
+ to 1 if omitted. If ARG is negative, move backward across that
+ many balanced expressions. For example,
+
+ ---------- Buffer: foo ----------
+ (concat-!- "foo " (car x) y z)
+ ---------- Buffer: foo ----------
+
+ (forward-sexp 3)
+ => nil
+
+ ---------- Buffer: foo ----------
+ (concat "foo " (car x) y-!- z)
+ ---------- Buffer: foo ----------
+
+ - Command: backward-sexp &optional ARG
+ This function moves backward across ARG balanced expressions. ARG
+ defaults to 1 if omitted. If ARG is negative, move forward across
+ that many balanced expressions.
+
+ - Command: beginning-of-defun &optional ARG
+ This function moves back to the ARGth beginning of a defun. If
+ ARG is negative, this actually moves forward, but it still moves
+ to the beginning of a defun, not to the end of one. ARG defaults
+ to 1 if omitted.
+
+ - Command: end-of-defun &optional ARG
+ This function moves forward to the ARGth end of a defun. If ARG
+ is negative, this actually moves backward, but it still moves to
+ the end of a defun, not to the beginning of one. ARG defaults to
+ 1 if omitted.
+
+ - User Option: defun-prompt-regexp
+ If non-`nil', this variable holds a regular expression that
+ specifies what text can appear before the open-parenthesis that
+ starts a defun. That is to say, a defun begins on a line that
+ starts with a match for this regular expression, followed by a
+ character with open-parenthesis syntax.
+
+\1f
+File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
+
+Skipping Characters
+-------------------
+
+ The following two functions move point over a specified set of
+characters. For example, they are often used to skip whitespace. For
+related functions, see *Note Motion and Syntax::.
+
+ - Function: skip-chars-forward CHARACTER-SET &optional LIMIT BUFFER
+ This function moves point in BUFFER forward, skipping over a given
+ set of characters. It examines the character following point,
+ then advances point if the character matches CHARACTER-SET. This
+ continues until it reaches a character that does not match. The
+ function returns `nil'. BUFFER defaults to the current buffer if
+ omitted.
+
+ The argument CHARACTER-SET is like the inside of a `[...]' in a
+ regular expression except that `]' is never special and `\' quotes
+ `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
+ stopping before the first non-letter, and `"^a-zA-Z'" skips
+ non-letters stopping before the first letter. *Note Regular
+ Expressions::.
+
+ If LIMIT is supplied (it must be a number or a marker), it
+ specifies the maximum position in the buffer that point can be
+ skipped to. Point will stop at or before LIMIT.
+
+ In the following example, point is initially located directly
+ before the `T'. After the form is evaluated, point is located at
+ the end of that line (between the `t' of `hat' and the newline).
+ The function skips all letters and spaces, but not newlines.
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (skip-chars-forward "a-zA-Z ")
+ => nil
+
+ ---------- Buffer: foo ----------
+ I read "The cat in the hat-!-
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ - Function: skip-chars-backward CHARACTER-SET &optional LIMIT BUFFER
+ This function moves point backward, skipping characters that match
+ CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
+ except for the direction of motion.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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.
+
+\1f
+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 ----------
+
+\1f
+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".
+
+\1f
+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))
+ => #<marker in no buffer>
+
+ ;; Set `m1' to point between the 99th and 100th characters
+ ;; in the current buffer:
+ (set-marker m1 100)
+ => #<marker at 100 in markers.texi>
+
+ ;; Now insert one character at the beginning of the buffer:
+ (goto-char (point-min))
+ => 1
+ (insert "Q")
+ => nil
+
+ ;; `m1' is updated appropriately.
+ m1
+ => #<marker at 101 in markers.texi>
+
+ ;; Two markers that point to the same position
+ ;; are not `eq', but they are `equal'.
+ (setq m2 (copy-marker m1))
+ => #<marker at 101 in markers.texi>
+ (eq m1 m2)
+ => nil
+ (equal m1 m2)
+ => t
+
+ ;; When you are finished using a marker, make it point nowhere.
+ (set-marker m1 nil)
+ => #<marker in no buffer>
+
+\1f
+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.
+
+\1f
+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)
+ => #<marker in no buffer>
+
+ - 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)
+ => #<marker at 1 in markers.texi>
+ (point-max-marker)
+ => #<marker at 15573 in markers.texi>
+
+ (narrow-to-region 100 200)
+ => nil
+ (point-min-marker)
+ => #<marker at 100 in markers.texi>
+ (point-max-marker)
+ => #<marker at 200 in markers.texi>
+
+ - 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))
+ => #<marker at 2139 in markers.texi>
+
+ (setq q (copy-marker p))
+ => #<marker at 2139 in markers.texi>
+
+ (eq p q)
+ => nil
+
+ (equal p q)
+ => t
+
+ (point)
+ => 2139
+
+ (set-marker p 3000)
+ => #<marker at 3000 in markers.texi>
+
+ (point)
+ => 2139
+
+ (setq p (point-marker t))
+ => #<marker at 2139 in markers.texi>
+
+ (set-marker p 3000)
+ => #<marker at 3000 in markers.texi>
+
+ (point)
+ => 3000
+
+ (copy-marker 0)
+ => #<marker at 1 in markers.texi>
+
+ (copy-marker 20000)
+ => #<marker at 7572 in markers.texi>
+
+\1f
+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 in no buffer>
+ (marker-position m)
+ => nil
+ (marker-buffer m)
+ => nil
+
+ (set-marker m 3770 (current-buffer))
+ => #<marker at 3770 in markers.texi>
+ (marker-buffer m)
+ => #<buffer markers.texi>
+ (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.
+
+\1f
+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))
+ => #<marker at 4714 in markers.texi>
+ (set-marker m 55)
+ => #<marker at 55 in markers.texi>
+ (setq b (get-buffer "foo"))
+ => #<buffer foo>
+ (set-marker m 0 b)
+ => #<marker at 1 in foo>
+
+ - Function: move-marker MARKER POSITION &optional BUFFER
+ This is another name for `set-marker'.
+
+\1f
+File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
+
+The Mark
+========
+
+ One special marker in each buffer is designated "the mark". It
+records a position for the user for the sake of commands such as `C-w'
+and `C-x <TAB>'. Lisp programs should set the mark only to values that
+have a potential use to the user, and never for their own internal
+purposes. For example, the `replace-regexp' command sets the mark to
+the value of point before doing any replacements, because this enables
+the user to move back there conveniently after the replace is finished.
+
+ Once the mark "exists" in a buffer, it normally never ceases to
+exist. However, it may become "inactive", and usually does so after
+each command (other than simple motion commands and some commands that
+explicitly activate the mark). When the mark is active, the region
+between point and the mark is called the "active region" and is
+highlighted specially.
+
+ Many commands are designed so that when called interactively they
+operate on the text between point and the mark. Such commands work
+only when an active region exists, i.e. when the mark is active. (The
+reason for this is to prevent you from accidentally deleting or
+changing large chunks of your text.) If you are writing such a command,
+don't examine the mark directly; instead, use `interactive' with the
+`r' specification. This provides the values of point and the mark as
+arguments to the command in an interactive call, but permits other Lisp
+programs to specify arguments explicitly, and automatically signals an
+error if the command is called interactively when no active region
+exists. *Note Interactive Codes::.
+
+ Each buffer has its own value of the mark that is independent of the
+value of the mark in other buffers. (When a buffer is created, the mark
+exists but does not point anywhere. We consider this state as "the
+absence of a mark in that buffer.") However, only one active region can
+exist at a time. Activating the mark in one buffer automatically
+deactivates an active mark in any other buffer. Note that the user can
+explicitly activate a mark at any time by using the command
+`activate-region' (normally bound to `M-C-z') or by using the command
+`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
+side effect of activating the mark.
+
+ Some people do not like active regions, so they disable this behavior
+by setting the variable `zmacs-regions' to `nil'. This makes the mark
+always active (except when a buffer is just created and the mark points
+nowhere), and turns off the highlighting of the region between point
+and the mark. Commands that explicitly retrieve the value of the mark
+should make sure that they behave correctly and consistently
+irrespective of the setting of `zmacs-regions'; some primitives are
+provided to ensure this behavior.
+
+ In addition to the mark, each buffer has a "mark ring" which is a
+list of markers containing previous values of the mark. When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring. The variable `mark-ring-max' specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+ - Function: mark &optional FORCE BUFFER
+ This function returns BUFFER's mark position as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ If the mark is inactive, `mark' normally returns `nil'. However,
+ if FORCE is non-`nil', then `mark' returns the mark position
+ anyway--or `nil', if the mark is not yet set for the buffer.
+
+ (Remember that if ZMACS-REGIONS is `nil', the mark is always
+ active as long as it exists, and the FORCE argument will have no
+ effect.)
+
+ If you are using this in an editing command, you are most likely
+ making a mistake; see the documentation of `set-mark' below.
+
+ - Function: mark-marker INACTIVE-P BUFFER
+ This function returns BUFFER's mark. BUFFER defaults to the
+ current buffer if omitted. This is the very marker that records
+ the mark location inside XEmacs, not a copy. Therefore, changing
+ this marker's position will directly affect the position of the
+ mark. Don't do it unless that is the effect you want.
+
+ If the mark is inactive, `mark-marker' normally returns `nil'.
+ However, if FORCE is non-`nil', then `mark-marker' returns the
+ mark anyway.
+ (setq m (mark-marker))
+ => #<marker at 3420 in markers.texi>
+ (set-marker m 100)
+ => #<marker at 100 in markers.texi>
+ (mark-marker)
+ => #<marker at 100 in markers.texi>
+
+ Like any marker, this marker can be set to point at any buffer you
+ like. We don't recommend that you make it point at any buffer
+ other than the one of which it is the mark. If you do, it will
+ yield perfectly consistent, but rather odd, results.
+
+ - Function: set-mark POSITION &optional BUFFER
+ This function sets `buffer''s mark to POSITION, and activates the
+ mark. BUFFER defaults to the current buffer if omitted. The old
+ value of the mark is *not* pushed onto the mark ring.
+
+ *Please note:* Use this function only if you want the user to see
+ that the mark has moved, and you want the previous mark position to
+ be lost. Normally, when a new mark is set, the old one should go
+ on the `mark-ring'. For this reason, most applications should use
+ `push-mark' and `pop-mark', not `set-mark'.
+
+ Novice XEmacs Lisp programmers often try to use the mark for the
+ wrong purposes. The mark saves a location for the user's
+ convenience. An editing command should not alter the mark unless
+ altering the mark is part of the user-level functionality of the
+ command. (And, in that case, this effect should be documented.)
+ To remember a location for internal use in the Lisp program, store
+ it in a Lisp variable. For example:
+
+ (let ((beg (point)))
+ (forward-line 1)
+ (delete-region beg (point))).
+
+ - Command: exchange-point-and-mark &optional DONT-ACTIVATE-REGION
+ This function exchanges the positions of point and the mark. It
+ is intended for interactive use. The mark is also activated
+ unless DONT-ACTIVATE-REGION is non-`nil'.
+
+ - Function: push-mark &optional POSITION NOMSG ACTIVATE BUFFER
+ This function sets BUFFER's mark to POSITION, and pushes a copy of
+ the previous mark onto `mark-ring'. BUFFER defaults to the
+ current buffer if omitted. If POSITION is `nil', then the value
+ of point is used. `push-mark' returns `nil'.
+
+ If the last global mark pushed was not in BUFFER, also push
+ POSITION on the global mark ring (see below).
+
+ The function `push-mark' normally *does not* activate the mark.
+ To do that, specify `t' for the argument ACTIVATE.
+
+ A `Mark set' message is displayed unless NOMSG is non-`nil'.
+
+ - Function: pop-mark
+ This function pops off the top element of `mark-ring' and makes
+ that mark become the buffer's actual mark. This does not move
+ point in the buffer, and it does nothing if `mark-ring' is empty.
+ It deactivates the mark.
+
+ The return value is not meaningful.
+
+ - Variable: mark-ring
+ The value of this buffer-local variable is the list of saved former
+ marks of the current buffer, most recent first.
+
+ mark-ring
+ => (#<marker at 11050 in markers.texi>
+ #<marker at 10832 in markers.texi>
+ ...)
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of `mark-ring'. If
+ more marks than this are pushed onto the `mark-ring', `push-mark'
+ discards an old mark when it adds a new one.
+
+ In additional to a per-buffer mark ring, there is a "global mark
+ring". Marks are pushed onto the global mark ring the first time you
+set a mark after switching buffers.
+
+ - Variable: global-mark-ring
+ The value of this variable is the list of saved former global
+ marks, most recent first.
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of
+ `global-mark-ring'. If more marks than this are pushed onto the
+ `global-mark-ring', `push-mark' discards an old mark when it adds
+ a new one.
+
+ - Command: pop-global-mark
+ This function pops a mark off the global mark ring and jumps to
+ that location.
+
+\1f
+File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
+
+The Region
+==========
+
+ The text between point and the mark is known as "the region".
+Various functions operate on text delimited by point and the mark, but
+only those functions specifically related to the region itself are
+described here.
+
+ When `zmacs-regions' is non-`nil' (this is the default), the concept
+of an "active region" exists. The region is active when the
+corresponding mark is active. Note that only one active region at a
+time can exist - i.e. only one buffer's region is active at a time.
+*Note The Mark::, for more information about active regions.
+
+ - User Option: zmacs-regions
+ If non-`nil' (the default), active regions are used. *Note The
+ Mark::, for a detailed explanation of what this means.
+
+ A number of functions are provided for explicitly determining the
+bounds of the region and whether it is active. Few programs need to use
+these functions, however. A command designed to operate on a region
+should normally use `interactive' with the `r' specification to find
+the beginning and end of the region. This lets other Lisp programs
+specify the bounds explicitly as arguments and automatically respects
+the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.)
+
+ - Function: region-beginning &optional BUFFER
+ This function returns the position of the beginning of BUFFER's
+ region (as an integer). This is the position of either point or
+ the mark, whichever is smaller. BUFFER defaults to the current
+ buffer if omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-end &optional BUFFER
+ This function returns the position of the end of BUFFER's region
+ (as an integer). This is the position of either point or the mark,
+ whichever is larger. BUFFER defaults to the current buffer if
+ omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-exists-p
+ This function is non-`nil' if the region exists. If active regions
+ are in use (i.e. `zmacs-regions' is true), this means that the
+ region is active. Otherwise, this means that the user has pushed
+ a mark in this buffer at some point in the past. If this function
+ returns `nil', a function that uses the `r' interactive
+ specification will cause an error when called interactively.
+
+ - Function: region-active-p
+ If `zmacs-regions' is true, this is equivalent to
+ `region-exists-p'. Otherwise, this function always returns false.
+ This function is used by commands such as
+ `fill-paragraph-or-region' and `capitalize-region-or-word', which
+ operate either on the active region or on something else (e.g. the
+ word or paragraph at point).
+
+ - Variable: zmacs-region-stays
+ If a command sets this variable to true, the currently active
+ region will remain activated when the command finishes. (Normally
+ the region is deactivated when each command terminates.) If
+ ZMACS-REGIONS is false, however, this has no effect. Under normal
+ circumstances, you do not need to set this; use the interactive
+ specification `_' instead, if you want the region to remain active.
+
+ - Function: zmacs-activate-region
+ This function activates the region in the current buffer (this is
+ equivalent to activating the current buffer's mark). This will
+ normally also highlight the text in the active region and set
+ ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however,
+ this function has no effect.)
+
+ - Function: zmacs-deactivate-region
+ This function deactivates the region in the current buffer (this is
+ equivalent to deactivating the current buffer's mark). This will
+ normally also unhighlight the text in the active region and set
+ ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however,
+ this function has no effect.)
+
+ - Function: zmacs-update-region
+ This function updates the active region, if it's currently active.
+ (If there is no active region, this function does nothing.) This
+ has the effect of updating the highlighting on the text in the
+ region; but you should never need to call this except under rather
+ strange circumstances. The command loop automatically calls it
+ when appropriate. Calling this function will call the hook
+ `zmacs-update-region-hook', if the region is active.
+
+ - Variable: zmacs-activate-region-hook
+ This normal hook is called when a region becomes active. (Usually
+ this happens as a result of a command that activates the region,
+ such as `set-mark-command', `activate-region', or
+ `exchange-point-and-mark'.) Note that calling
+ `zmacs-activate-region' will call this hook, even if the region is
+ already active. If ZMACS-REGIONS is false, however, this hook
+ will never get called under any circumstances.
+
+ - Variable: zmacs-deactivate-region-hook
+ This normal hook is called when an active region becomes inactive.
+ (Calling `zmacs-deactivate-region' when the region is inactive will
+ *not* cause this hook to be called.) If ZMACS-REGIONS is false,
+ this hook will never get called.
+
+ - Variable: zmacs-update-region-hook
+ This normal hook is called when an active region is "updated" by
+ `zmacs-update-region'. This normally gets called at the end of
+ each command that sets ZMACS-REGION-STAYS to `t', indicating that
+ the region should remain activated. The motion commands do this.
+
+\1f
+File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
+
+Text
+****
+
+ This chapter describes the functions that deal with the text in a
+buffer. Most examine, insert, or delete text in the current buffer,
+often in the vicinity of point. Many are interactive. All the
+functions that change the text provide for undoing the changes (*note
+Undo::.).
+
+ Many text-related functions operate on a region of text defined by
+two buffer positions passed in arguments named START and END. These
+arguments should be either markers (*note Markers::.) or numeric
+character positions (*note Positions::.). The order of these arguments
+does not matter; it is all right for START to be the end of the region
+and END the beginning. For example, `(delete-region 1 10)' and
+`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
+signaled if either START or END is outside the accessible portion of
+the buffer. In an interactive call, point and the mark are used for
+these arguments.
+
+ Throughout this chapter, "text" refers to the characters in the
+buffer, together with their properties (when relevant).
+
+* Menu:
+
+* Near Point:: Examining text in the vicinity of point.
+* Buffer Contents:: Examining text in a general fashion.
+* Comparing Text:: Comparing substrings of buffers.
+* Insertion:: Adding new text to a buffer.
+* Commands for Insertion:: User-level commands to insert text.
+* Deletion:: Removing text from a buffer.
+* User-Level Deletion:: User-level commands to delete text.
+* The Kill Ring:: Where removed text sometimes is saved for later use.
+* Undo:: Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+ How to control how much information is kept.
+* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
+* Auto Filling:: How auto-fill mode is implemented to break lines.
+* Sorting:: Functions for sorting parts of the buffer.
+* Columns:: Computing horizontal positions, and using them.
+* Indentation:: Functions to insert or adjust indentation.
+* Case Changes:: Case conversion of parts of the buffer.
+* Text Properties:: Assigning Lisp property lists to text characters.
+* Substitution:: Replacing a given character wherever it appears.
+* Registers:: How registers are implemented. Accessing the text or
+ position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
+* Change Hooks:: Supplying functions to be run when text is changed.
+* Transformations:: MD5 and base64 support.
+
+\1f
+File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
+
+Examining Text Near Point
+=========================
+
+ Many functions are provided to look at the characters around point.
+Several simple functions are described here. See also `looking-at' in
+*Note Regexp Search::.
+
+ Many of these functions take an optional BUFFER argument. In all
+such cases, the current buffer will be used if this argument is
+omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
+usually did not have these optional BUFFER arguments and always
+operated on the current buffer.)
+
+ - Function: char-after POSITION &optional BUFFER
+ This function returns the character in the buffer at (i.e.,
+ immediately after) position POSITION. If POSITION is out of range
+ for this purpose, either before the beginning of the buffer, or at
+ or beyond the end, then the value is `nil'. If optional argument
+ BUFFER is `nil', the current buffer is assumed.
+
+ In the following example, assume that the first character in the
+ buffer is `@':
+
+ (char-to-string (char-after 1))
+ => "@"
+
+ - Function: following-char &optional BUFFER
+ This function returns the character following point in the buffer.
+ This is similar to `(char-after (point))'. However, if point is at
+ the end of the buffer, then the result of `following-char' is 0.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed.
+
+ Remember that point is always between characters, and the terminal
+ cursor normally appears over the character following point.
+ Therefore, the character returned by `following-char' is the
+ character the cursor is over.
+
+ In this example, point is between the `a' and the `c'.
+
+ ---------- Buffer: foo ----------
+ Gentlemen may cry ``Pea-!-ce! Peace!,''
+ but there is no peace.
+ ---------- Buffer: foo ----------
+
+ (char-to-string (preceding-char))
+ => "a"
+ (char-to-string (following-char))
+ => "c"
+
+ - Function: preceding-char &optional BUFFER
+ This function returns the character preceding point in the buffer.
+ See above, under `following-char', for an example. If point is at
+ the beginning of the buffer, `preceding-char' returns 0. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+
+ - Function: bobp &optional BUFFER
+ This function returns `t' if point is at the beginning of the
+ buffer. If narrowing is in effect, this means the beginning of the
+ accessible portion of the text. If optional argument BUFFER is
+ `nil', the current buffer is assumed. See also `point-min' in
+ *Note Point::.
+
+ - Function: eobp &optional BUFFER
+ This function returns `t' if point is at the end of the buffer.
+ If narrowing is in effect, this means the end of accessible
+ portion of the text. If optional argument BUFFER is `nil', the
+ current buffer is assumed. See also `point-max' in *Note Point::.
+
+ - Function: bolp &optional BUFFER
+ This function returns `t' if point is at the beginning of a line.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed. *Note Text Lines::. The beginning of the buffer (or its
+ accessible portion) always counts as the beginning of a line.
+
+ - Function: eolp &optional BUFFER
+ This function returns `t' if point is at the end of a line. The
+ end of the buffer is always considered the end of a line. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+ The end of the buffer (or of its accessible portion) is always
+ considered the end of a line.
+
+\1f
+File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
+
+Examining Buffer Contents
+=========================
+
+ This section describes two functions that allow a Lisp program to
+convert any portion of the text in the buffer into a string.
+
+ - Function: buffer-substring START END &optional BUFFER
+ - Function: buffer-string START END &optional BUFFER
+ These functions are equivalent and return a string containing a
+ copy of the text of the region defined by positions START and END
+ in the buffer. If the arguments are not positions in the
+ accessible portion of the buffer, `buffer-substring' signals an
+ `args-out-of-range' error. If optional argument BUFFER is `nil',
+ the current buffer is assumed.
+
+ If the region delineated by START and END contains duplicable
+ extents, they will be remembered in the string. *Note Duplicable
+ Extents::.
+
+ It is not necessary for START to be less than END; the arguments
+ can be given in either order. But most often the smaller argument
+ is written first.
+
+ ---------- Buffer: foo ----------
+ This is the contents of buffer foo
+
+ ---------- Buffer: foo ----------
+
+ (buffer-substring 1 10)
+ => "This is t"
+ (buffer-substring (point-max) 10)
+ => "he contents of buffer foo
+ "
+
+\1f
+File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
+
+Comparing Text
+==============
+
+ This function lets you compare portions of the text in a buffer,
+without copying them into strings first.
+
+ - Function: compare-buffer-substrings BUFFER1 START1 END1 BUFFER2
+ START2 END2
+ This function lets you compare two substrings of the same buffer
+ or two different buffers. The first three arguments specify one
+ substring, giving a buffer and two positions within the buffer.
+ The last three arguments specify the other substring in the same
+ way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
+ the current buffer.
+
+ The value is negative if the first substring is less, positive if
+ the first is greater, and zero if they are equal. The absolute
+ value of the result is one plus the index of the first differing
+ characters within the substrings.
+
+ This function ignores case when comparing characters if
+ `case-fold-search' is non-`nil'. It always ignores text
+ properties.
+
+ Suppose the current buffer contains the text `foobarbar
+ haha!rara!'; then in this example the two substrings are `rbar '
+ and `rara!'. The value is 2 because the first substring is greater
+ at the second character.
+
+ (compare-buffer-substring nil 6 11 nil 16 21)
+ => 2
+
+\1f
+File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
+
+Inserting Text
+==============
+
+ "Insertion" means adding new text to a buffer. The inserted text
+goes at point--between the character before point and the character
+after point.
+
+ Insertion relocates markers that point at positions after the
+insertion point, so that they stay with the surrounding text (*note
+Markers::.). When a marker points at the place of insertion, insertion
+normally doesn't relocate the marker, so that it points to the
+beginning of the inserted text; however, certain special functions such
+as `insert-before-markers' relocate such markers to point after the
+inserted text.
+
+ Some insertion functions leave point before the inserted text, while
+other functions leave it after. We call the former insertion "after
+point" and the latter insertion "before point".
+
+ If a string with non-`nil' extent data is inserted, the remembered
+extents will also be inserted. *Note Duplicable Extents::.
+
+ Insertion functions signal an error if the current buffer is
+read-only.
+
+ These functions copy text characters from strings and buffers along
+with their properties. The inserted characters have exactly the same
+properties as the characters they were copied from. By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
+ - Function: insert &rest ARGS
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. In other words, it
+ inserts the text before point. An error is signaled unless all
+ ARGS are either strings or characters. The value is `nil'.
+
+ - Function: insert-before-markers &rest ARGS
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. An error is
+ signaled unless all ARGS are either strings or characters. The
+ value is `nil'.
+
+ This function is unlike the other insertion functions in that it
+ relocates markers initially pointing at the insertion point, to
+ point after the inserted text.
+
+ - Function: insert-string STRING &optional BUFFER
+ This function inserts STRING into BUFFER before point. BUFFER
+ defaults to the current buffer if omitted. This function is
+ chiefly useful if you want to insert a string in a buffer other
+ than the current one (otherwise you could just use `insert').
+
+ - Function: insert-char CHARACTER COUNT &optional BUFFER
+ This function inserts COUNT instances of CHARACTER into BUFFER
+ before point. COUNT must be a number, and CHARACTER must be a
+ character. The value is `nil'. If optional argument BUFFER is
+ `nil', the current buffer is assumed. (In FSF Emacs, the third
+ argument is called INHERIT and refers to text properties.)
+
+ - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional
+ START END
+ This function inserts a portion of buffer FROM-BUFFER-OR-NAME
+ (which must already exist) into the current buffer before point.
+ The text inserted is the region from START and END. (These
+ arguments default to the beginning and end of the accessible
+ portion of that buffer.) This function returns `nil'.
+
+ In this example, the form is executed with buffer `bar' as the
+ current buffer. We assume that buffer `bar' is initially empty.
+
+ ---------- Buffer: foo ----------
+ We hold these truths to be self-evident, that all
+ ---------- Buffer: foo ----------
+
+ (insert-buffer-substring "foo" 1 20)
+ => nil
+
+ ---------- Buffer: bar ----------
+ We hold these truth-!-
+ ---------- Buffer: bar ----------
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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.
+
+\1f
+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'.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
+
+Internals of the Kill Ring
+--------------------------
+
+ The variable `kill-ring' holds the kill ring contents, in the form
+of a list of strings. The most recent kill is always at the front of
+the list.
+
+ The `kill-ring-yank-pointer' variable points to a link in the kill
+ring list, whose CAR is the text to yank next. We say it identifies
+the "front" of the ring. Moving `kill-ring-yank-pointer' to a
+different link is called "rotating the kill ring". We call the kill
+ring a "ring" because the functions that move the yank pointer wrap
+around from the end of the list to the beginning, or vice-versa.
+Rotation of the kill ring is virtual; it does not change the value of
+`kill-ring'.
+
+ Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
+whose values are normally lists. The word "pointer" in the name of the
+`kill-ring-yank-pointer' indicates that the variable's purpose is to
+identify one element of the list for use by the next yank command.
+
+ The value of `kill-ring-yank-pointer' is always `eq' to one of the
+links in the kill ring list. The element it identifies is the CAR of
+that link. Kill commands, which change the kill ring, also set this
+variable to the value of `kill-ring'. The effect is to rotate the ring
+so that the newly killed text is at the front.
+
+ Here is a diagram that shows the variable `kill-ring-yank-pointer'
+pointing to the second entry in the kill ring `("some text" "a
+different piece of text" "yet older text")'.
+
+ kill-ring kill-ring-yank-pointer
+ | |
+ | ___ ___ ---> ___ ___ ___ ___
+ --> |___|___|------> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ | | -->"yet older text"
+ | |
+ | --> "a different piece of text"
+ |
+ --> "some text"
+
+This state of affairs might occur after `C-y' (`yank') immediately
+followed by `M-y' (`yank-pop').
+
+ - Variable: kill-ring
+ This variable holds the list of killed text sequences, most
+ recently killed first.
+
+ - Variable: kill-ring-yank-pointer
+ This variable's value indicates which element of the kill ring is
+ at the "front" of the ring for yanking. More precisely, the value
+ is a tail of the value of `kill-ring', and its CAR is the kill
+ string that `C-y' should yank.
+
+ - User Option: kill-ring-max
+ The value of this variable is the maximum length to which the kill
+ ring can grow, before elements are thrown away at the end. The
+ default value for `kill-ring-max' is 30.
+
+\1f
+File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
+
+Undo
+====
+
+ Most buffers have an "undo list", which records all changes made to
+the buffer's text so that they can be undone. (The buffers that don't
+have one are usually special-purpose buffers for which XEmacs assumes
+that undoing is not useful.) All the primitives that modify the text
+in the buffer automatically add elements to the front of the undo list,
+which is in the variable `buffer-undo-list'.
+
+ - Variable: buffer-undo-list
+ This variable's value is the undo list of the current buffer. A
+ value of `t' disables the recording of undo information.
+
+ Here are the kinds of elements an undo list can have:
+
+`INTEGER'
+ This kind of element records a previous value of point. Ordinary
+ cursor motion does not get any sort of undo record, but deletion
+ commands use these entries to record where point was before the
+ command.
+
+`(BEG . END)'
+ This kind of element indicates how to delete text that was
+ inserted. Upon insertion, the text occupied the range BEG-END in
+ the buffer.
+
+`(TEXT . POSITION)'
+ This kind of element indicates how to reinsert text that was
+ deleted. The deleted text itself is the string TEXT. The place to
+ reinsert it is `(abs POSITION)'.
+
+`(t HIGH . LOW)'
+ This kind of element indicates that an unmodified buffer became
+ modified. The elements HIGH and LOW are two integers, each
+ recording 16 bits of the visited file's modification time as of
+ when it was previously visited or saved. `primitive-undo' uses
+ those values to determine whether to mark the buffer as unmodified
+ once again; it does so only if the file's modification time
+ matches those numbers.
+
+`(nil PROPERTY VALUE BEG . END)'
+ This kind of element records a change in a text property. Here's
+ how you might undo the change:
+
+ (put-text-property BEG END PROPERTY VALUE)
+
+`POSITION'
+ This element indicates where point was at an earlier time.
+ Undoing this element sets point to POSITION. Deletion normally
+ creates an element of this kind as well as a reinsertion element.
+
+`nil'
+ This element is a boundary. The elements between two boundaries
+ are called a "change group"; normally, each change group
+ corresponds to one keyboard command, and undo commands normally
+ undo an entire group as a unit.
+
+ - Function: undo-boundary
+ This function places a boundary element in the undo list. The undo
+ command stops at such a boundary, and successive undo commands undo
+ to earlier and earlier boundaries. This function returns `nil'.
+
+ The editor command loop automatically creates an undo boundary
+ before each key sequence is executed. Thus, each undo normally
+ undoes the effects of one command. Self-inserting input
+ characters are an exception. The command loop makes a boundary
+ for the first such character; the next 19 consecutive
+ self-inserting input characters do not make boundaries, and then
+ the 20th does, and so on as long as self-inserting characters
+ continue.
+
+ All buffer modifications add a boundary whenever the previous
+ undoable change was made in some other buffer. This way, a
+ command that modifies several buffers makes a boundary in each
+ buffer it changes.
+
+ Calling this function explicitly is useful for splitting the
+ effects of a command into more than one unit. For example,
+ `query-replace' calls `undo-boundary' after each replacement, so
+ that the user can undo individual replacements one by one.
+
+ - Function: primitive-undo COUNT LIST
+ This is the basic function for undoing elements of an undo list.
+ It undoes the first COUNT elements of LIST, returning the rest of
+ LIST. You could write this function in Lisp, but it is convenient
+ to have it in C.
+
+ `primitive-undo' adds elements to the buffer's undo list when it
+ changes the buffer. Undo commands avoid confusion by saving the
+ undo list value at the beginning of a sequence of undo operations.
+ Then the undo operations use and update the saved value. The new
+ elements added by undoing are not part of this saved value, so
+ they don't interfere with continuing to undo.
+
+\1f
+File: lispref.info, Node: Maintaining Undo, Next: Filling, Prev: Undo, Up: Text
+
+Maintaining Undo Lists
+======================
+
+ This section describes how to enable and disable undo information for
+a given buffer. It also explains how the undo list is truncated
+automatically so it doesn't get too big.
+
+ Recording of undo information in a newly created buffer is normally
+enabled to start with; but if the buffer name starts with a space, the
+undo recording is initially disabled. You can explicitly enable or
+disable undo recording with the following two functions, or by setting
+`buffer-undo-list' yourself.
+
+ - Command: buffer-enable-undo &optional BUFFER-OR-NAME
+ This command enables recording undo information for buffer
+ BUFFER-OR-NAME, so that subsequent changes can be undone. If no
+ argument is supplied, then the current buffer is used. This
+ function does nothing if undo recording is already enabled in the
+ buffer. It returns `nil'.
+
+ In an interactive call, BUFFER-OR-NAME is the current buffer. You
+ cannot specify any other buffer.
+
+ - Function: buffer-disable-undo &optional BUFFER
+ - Function: buffer-flush-undo &optional BUFFER
+ This function discards the undo list of BUFFER, and disables
+ further recording of undo information. As a result, it is no
+ longer possible to undo either previous changes or any subsequent
+ changes. If the undo list of BUFFER is already disabled, this
+ function has no effect.
+
+ This function returns `nil'. It cannot be called interactively.
+
+ The name `buffer-flush-undo' is not considered obsolete, but the
+ preferred name `buffer-disable-undo' is new as of Emacs versions
+ 19.
+
+ As editing continues, undo lists get longer and longer. To prevent
+them from using up all available memory space, garbage collection trims
+them back to size limits you can set. (For this purpose, the "size" of
+an undo list measures the cons cells that make up the list, plus the
+strings of deleted text.) Two variables control the range of acceptable
+sizes: `undo-limit' and `undo-strong-limit'.
+
+ - Variable: undo-limit
+ This is the soft limit for the acceptable size of an undo list.
+ The change group at which this size is exceeded is the last one
+ kept.
+
+ - Variable: undo-strong-limit
+ This is the upper limit for the acceptable size of an undo list.
+ The change group at which this size is exceeded is discarded
+ itself (along with all older change groups). There is one
+ exception: the very latest change group is never discarded no
+ matter how big it is.
+
+\1f
+File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
+
+Filling
+=======
+
+ "Filling" means adjusting the lengths of lines (by moving the line
+breaks) so that they are nearly (but no greater than) a specified
+maximum width. Additionally, lines can be "justified", which means
+inserting spaces to make the left and/or right margins line up
+precisely. The width is controlled by the variable `fill-column'. For
+ease of reading, lines should be no longer than 70 or so columns.
+
+ You can use Auto Fill mode (*note Auto Filling::.) to fill text
+automatically as you insert it, but changes to existing text may leave
+it improperly filled. Then you must fill the text explicitly.
+
+ Most of the commands in this section return values that are not
+meaningful. All the functions that do filling take note of the current
+left margin, current right margin, and current justification style
+(*note Margins::.). If the current justification style is `none', the
+filling functions don't actually do anything.
+
+ Several of the filling functions have an argument JUSTIFY. If it is
+non-`nil', that requests some kind of justification. It can be `left',
+`right', `full', or `center', to request a specific style of
+justification. If it is `t', that means to use the current
+justification style for this part of the text (see
+`current-justification', below).
+
+ When you call the filling functions interactively, using a prefix
+argument implies the value `full' for JUSTIFY.
+
+ - Command: fill-paragraph JUSTIFY
+ This command fills the paragraph at or after point. If JUSTIFY is
+ non-`nil', each line is justified as well. It uses the ordinary
+ paragraph motion commands to find paragraph boundaries. *Note
+ Paragraphs: (xemacs)Paragraphs.
+
+ - Command: fill-region START END &optional JUSTIFY
+ This command fills each of the paragraphs in the region from START
+ to END. It justifies as well if JUSTIFY is non-`nil'.
+
+ The variable `paragraph-separate' controls how to distinguish
+ paragraphs. *Note Standard Regexps::.
+
+ - Command: fill-individual-paragraphs START END &optional JUSTIFY
+ MAIL-FLAG
+ This command fills each paragraph in the region according to its
+ individual fill prefix. Thus, if the lines of a paragraph were
+ indented with spaces, the filled paragraph will remain indented in
+ the same fashion.
+
+ The first two arguments, START and END, are the beginning and end
+ of the region to be filled. The third and fourth arguments,
+ JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
+ paragraphs are justified as well as filled. If MAIL-FLAG is
+ non-`nil', it means the function is operating on a mail message
+ and therefore should not fill the header lines.
+
+ Ordinarily, `fill-individual-paragraphs' regards each change in
+ indentation as starting a new paragraph. If
+ `fill-individual-varying-indent' is non-`nil', then only separator
+ lines separate paragraphs. That mode can handle indented
+ paragraphs with additional indentation on the first line.
+
+ - User Option: fill-individual-varying-indent
+ This variable alters the action of `fill-individual-paragraphs' as
+ described above.
+
+ - Command: fill-region-as-paragraph START END &optional JUSTIFY
+ This command considers a region of text as a paragraph and fills
+ it. If the region was made up of many paragraphs, the blank lines
+ between paragraphs are removed. This function justifies as well
+ as filling when JUSTIFY is non-`nil'.
+
+ In an interactive call, any prefix argument requests justification.
+
+ In Adaptive Fill mode, which is enabled by default,
+ `fill-region-as-paragraph' on an indented paragraph when there is
+ no fill prefix uses the indentation of the second line of the
+ paragraph as the fill prefix.
+
+ - Command: justify-current-line HOW EOP NOSQUEEZE
+ This command inserts spaces between the words of the current line
+ so that the line ends exactly at `fill-column'. It returns `nil'.
+
+ The argument HOW, if non-`nil' specifies explicitly the style of
+ justification. It can be `left', `right', `full', `center', or
+ `none'. If it is `t', that means to do follow specified
+ justification style (see `current-justification', below). `nil'
+ means to do full justification.
+
+ If EOP is non-`nil', that means do left-justification when
+ `current-justification' specifies full justification. This is used
+ for the last line of a paragraph; even if the paragraph as a whole
+ is fully justified, the last line should not be.
+
+ If NOSQUEEZE is non-`nil', that means do not change interior
+ whitespace.
+
+ - User Option: default-justification
+ This variable's value specifies the style of justification to use
+ for text that doesn't specify a style with a text property. The
+ possible values are `left', `right', `full', `center', or `none'.
+ The default value is `left'.
+
+ - Function: current-justification
+ This function returns the proper justification style to use for
+ filling the text around point.
+
+ - Variable: fill-paragraph-function
+ This variable provides a way for major modes to override the
+ filling of paragraphs. If the value is non-`nil',
+ `fill-paragraph' calls this function to do the work. If the
+ function returns a non-`nil' value, `fill-paragraph' assumes the
+ job is done, and immediately returns that value.
+
+ The usual use of this feature is to fill comments in programming
+ language modes. If the function needs to fill a paragraph in the
+ usual way, it can do so as follows:
+
+ (let ((fill-paragraph-function nil))
+ (fill-paragraph arg))
+
+ - Variable: use-hard-newlines
+ If this variable is non-`nil', the filling functions do not delete
+ newlines that have the `hard' text property. These "hard
+ newlines" act as paragraph separators.
+
+\1f
+File: lispref.info, Node: Margins, Next: Auto Filling, Prev: Filling, Up: Text
+
+Margins for Filling
+===================
+
+ - User Option: fill-prefix
+ This variable specifies a string of text that appears at the
+ beginning of normal text lines and should be disregarded when
+ filling them. Any line that fails to start with the fill prefix
+ is considered the start of a paragraph; so is any line that starts
+ with the fill prefix followed by additional whitespace. Lines
+ that start with the fill prefix but no additional whitespace are
+ ordinary text lines that can be filled together. The resulting
+ filled lines also start with the fill prefix.
+
+ The fill prefix follows the left margin whitespace, if any.
+
+ - User Option: fill-column
+ This buffer-local variable specifies the maximum width of filled
+ lines. Its value should be an integer, which is a number of
+ columns. All the filling, justification and centering commands
+ are affected by this variable, including Auto Fill mode (*note
+ Auto Filling::.).
+
+ As a practical matter, if you are writing text for other people to
+ read, you should set `fill-column' to no more than 70. Otherwise
+ the line will be too long for people to read comfortably, and this
+ can make the text seem clumsy.
+
+ - Variable: default-fill-column
+ The value of this variable is the default value for `fill-column'
+ in buffers that do not override it. This is the same as
+ `(default-value 'fill-column)'.
+
+ The default value for `default-fill-column' is 70.
+
+ - Command: set-left-margin FROM TO MARGIN
+ This sets the `left-margin' property on the text from FROM to TO
+ to the value MARGIN. If Auto Fill mode is enabled, this command
+ also refills the region to fit the new margin.
+
+ - Command: set-right-margin FROM TO MARGIN
+ This sets the `right-margin' property on the text from FROM to TO
+ to the value MARGIN. If Auto Fill mode is enabled, this command
+ also refills the region to fit the new margin.
+
+ - Function: current-left-margin
+ This function returns the proper left margin value to use for
+ filling the text around point. The value is the sum of the
+ `left-margin' property of the character at the start of the
+ current line (or zero if none), and the value of the variable
+ `left-margin'.
+
+ - Function: current-fill-column
+ This function returns the proper fill column value to use for
+ filling the text around point. The value is the value of the
+ `fill-column' variable, minus the value of the `right-margin'
+ property of the character after point.
+
+ - Command: move-to-left-margin &optional N FORCE
+ This function moves point to the left margin of the current line.
+ The column moved to is determined by calling the function
+ `current-left-margin'. If the argument N is non-`nil',
+ `move-to-left-margin' moves forward N-1 lines first.
+
+ If FORCE is non-`nil', that says to fix the line's indentation if
+ that doesn't match the left margin value.
+
+ - Function: delete-to-left-margin FROM TO
+ This function removes left margin indentation from the text
+ between FROM and TO. The amount of indentation to delete is
+ determined by calling `current-left-margin'. In no case does this
+ function delete non-whitespace.
+
+ - Function: indent-to-left-margin
+ This is the default `indent-line-function', used in Fundamental
+ mode, Text mode, etc. Its effect is to adjust the indentation at
+ the beginning of the current line to the value specified by the
+ variable `left-margin'. This may involve either inserting or
+ deleting whitespace.
+
+ - Variable: left-margin
+ This variable specifies the base left margin column. In
+ Fundamental mode, <LFD> indents to this column. This variable
+ automatically becomes buffer-local when set in any fashion.
+
+\1f
+File: lispref.info, Node: Auto Filling, Next: Sorting, Prev: Margins, Up: Text
+
+Auto Filling
+============
+
+ Auto Fill mode is a minor mode that fills lines automatically as text
+is inserted. This section describes the hook used by Auto Fill mode.
+For a description of functions that you can call explicitly to fill and
+justify existing text, see *Note Filling::.
+
+ Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text. *Note Margins::.
+
+ - Variable: auto-fill-function
+ The value of this variable should be a function (of no arguments)
+ to be called after self-inserting a space or a newline. It may be
+ `nil', in which case nothing special is done in that case.
+
+ The value of `auto-fill-function' is `do-auto-fill' when Auto-Fill
+ mode is enabled. That is a function whose sole purpose is to
+ implement the usual strategy for breaking a line.
+
+ In older Emacs versions, this variable was named
+ `auto-fill-hook', but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `auto-fill-function' in version 19.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Character Type, Next: Symbol Type, Prev: Floating Point Type, Up: Programming Types
+
+Character Type
+--------------
+
+ In XEmacs version 19, and in all versions of FSF GNU Emacs, a
+"character" in XEmacs Lisp is nothing more than an integer. This is
+yet another holdover from XEmacs Lisp's derivation from vintage-1980
+Lisps; modern versions of Lisp consider this equivalence a bad idea,
+and have separate character types. In XEmacs version 20, the modern
+convention is followed, and characters are their own primitive types.
+(This change was necessary in order for MULE, i.e. Asian-language,
+support to be correctly implemented.)
+
+ Even in XEmacs version 20, remnants of the equivalence between
+characters and integers still exist; this is termed the "char-int
+confoundance disease". In particular, many functions such as `eq',
+`equal', and `memq' have equivalent functions (`old-eq', `old-equal',
+`old-memq', etc.) that pretend like characters are integers are the
+same. Byte code compiled under any version 19 Emacs will have all such
+functions mapped to their `old-' equivalents when the byte code is read
+into XEmacs 20. This is to preserve compatibility - Emacs 19 converts
+all constant characters to the equivalent integer during
+byte-compilation, and thus there is no other way to preserve byte-code
+compatibility even if the code has specifically been written with the
+distinction between characters and integers in mind.
+
+ Every character has an equivalent integer, called the "character
+code". For example, the character `A' is represented as the
+integer 65, following the standard ASCII representation of characters.
+If XEmacs was not compiled with MULE support, the range of this integer
+will always be 0 to 255 - eight bits, or one byte. (Integers outside
+this range are accepted but silently truncated; however, you should
+most decidedly *not* rely on this, because it will not work under
+XEmacs with MULE support.) When MULE support is present, the range of
+character codes is much larger. (Currently, 19 bits are used.)
+
+ FSF GNU Emacs uses kludgy character codes above 255 to represent
+keyboard input of ASCII characters in combination with certain
+modifiers. XEmacs does not use this (a more general mechanism is used
+that does not distinguish between ASCII keys and other keys), so you
+will never find character codes above 255 in a non-MULE XEmacs.
+
+ Individual characters are not often used in programs. It is far more
+common to work with *strings*, which are sequences composed of
+characters. *Note String Type::.
+
+ The read syntax for characters begins with a question mark, followed
+by the character (if it's printable) or some symbolic representation of
+it. In XEmacs 20, where characters are their own type, this is also the
+print representation. In XEmacs 19, however, where characters are
+really integers, the printed representation of a character is a decimal
+number. This is also a possible read syntax for a character, but
+writing characters that way in Lisp programs is a very bad idea. You
+should *always* use the special read syntax formats that XEmacs Lisp
+provides for characters.
+
+ The usual read syntax for alphanumeric characters is a question mark
+followed by the character; thus, `?A' for the character `A', `?B' for
+the character `B', and `?a' for the character `a'.
+
+ For example:
+
+ ;; Under XEmacs 20:
+ ?Q => ?Q ?q => ?q
+ (char-int ?Q) => 81
+ ;; Under XEmacs 19:
+ ?Q => 81 ?q => 113
+
+ You can use the same syntax for punctuation characters, but it is
+often a good idea to add a `\' so that the Emacs commands for editing
+Lisp code don't get confused. For example, `?\ ' is the way to write
+the space character. If the character is `\', you *must* use a second
+`\' to quote it: `?\\'. XEmacs 20 always prints punctuation characters
+with a `\' in front of them, to avoid confusion.
+
+ You can express the characters Control-g, backspace, tab, newline,
+vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
+`?\n', `?\v', `?\f', `?\r', `?\e', respectively. Their character codes
+are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal. Thus,
+
+ ;; Under XEmacs 20:
+ ?\a => ?\^G ; `C-g'
+ (char-int ?\a) => 7
+ ?\b => ?\^H ; backspace, <BS>, `C-h'
+ (char-int ?\b) => 8
+ ?\t => ?\t ; tab, <TAB>, `C-i'
+ (char-int ?\t) => 9
+ ?\n => ?\n ; newline, <LFD>, `C-j'
+ ?\v => ?\^K ; vertical tab, `C-k'
+ ?\f => ?\^L ; formfeed character, `C-l'
+ ?\r => ?\r ; carriage return, <RET>, `C-m'
+ ?\e => ?\^[ ; escape character, <ESC>, `C-['
+ ?\\ => ?\\ ; backslash character, `\'
+ ;; Under XEmacs 19:
+ ?\a => 7 ; `C-g'
+ ?\b => 8 ; backspace, <BS>, `C-h'
+ ?\t => 9 ; tab, <TAB>, `C-i'
+ ?\n => 10 ; newline, <LFD>, `C-j'
+ ?\v => 11 ; vertical tab, `C-k'
+ ?\f => 12 ; formfeed character, `C-l'
+ ?\r => 13 ; carriage return, <RET>, `C-m'
+ ?\e => 27 ; escape character, <ESC>, `C-['
+ ?\\ => 92 ; backslash character, `\'
+
+ These sequences which start with backslash are also known as "escape
+sequences", because backslash plays the role of an escape character;
+this usage has nothing to do with the character <ESC>.
+
+ Control characters may be represented using yet another read syntax.
+This consists of a question mark followed by a backslash, caret, and the
+corresponding non-control character, in either upper or lower case. For
+example, both `?\^I' and `?\^i' are valid read syntax for the character
+`C-i', the character whose value is 9.
+
+ Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
+`?\^I' and to `?\^i':
+
+ ;; Under XEmacs 20:
+ ?\^I => ?\t ?\C-I => ?\t
+ (char-int ?\^I) => 9
+ ;; Under XEmacs 19:
+ ?\^I => 9 ?\C-I => 9
+
+ There is also a character read syntax beginning with `\M-'. This
+sets the high bit of the character code (same as adding 128 to the
+character code). For example, `?\M-A' stands for the character with
+character code 193, or 128 plus 65. You should *not* use this syntax
+in your programs. It is a holdover of yet another confoundance disease
+from earlier Emacsen. (This was used to represent keyboard input with
+the <META> key set, thus the `M'; however, it conflicts with the
+legitimate ISO-8859-1 interpretation of the character code. For
+example, character code 193 is a lowercase `a' with an acute accent, in
+ISO-8859-1.)
+
+ Finally, the most general read syntax consists of a question mark
+followed by a backslash and the character code in octal (up to three
+octal digits); thus, `?\101' for the character `A', `?\001' for the
+character `C-a', and `?\002' for the character `C-b'. Although this
+syntax can represent any ASCII character, it is preferred only when the
+precise octal value is more important than the ASCII representation.
+
+ ;; Under XEmacs 20:
+ ?\012 => ?\n ?\n => ?\n ?\C-j => ?\n
+ ?\101 => ?A ?A => ?A
+ ;; Under XEmacs 19:
+ ?\012 => 10 ?\n => 10 ?\C-j => 10
+ ?\101 => 65 ?A => 65
+
+ A backslash is allowed, and harmless, preceding any character without
+a special escape meaning; thus, `?\+' is equivalent to `?+'. There is
+no reason to add a backslash before most characters. However, you
+should add a backslash before any of the characters `()\|;'`"#.,' to
+avoid confusing the Emacs commands for editing Lisp code. Also add a
+backslash before whitespace characters such as space, tab, newline and
+formfeed. However, it is cleaner to use one of the easily readable
+escape sequences, such as `\t', instead of an actual whitespace
+character such as a tab.
+
+\1f
+File: lispref.info, Node: Symbol Type, Next: Sequence Type, Prev: Character Type, Up: Programming Types
+
+Symbol Type
+-----------
+
+ A "symbol" in XEmacs Lisp is an object with a name. The symbol name
+serves as the printed representation of the symbol. In ordinary use,
+the name is unique--no two symbols have the same name.
+
+ A symbol can serve as a variable, as a function name, or to hold a
+property list. Or it may serve only to be distinct from all other Lisp
+objects, so that its presence in a data structure may be recognized
+reliably. In a given context, usually only one of these uses is
+intended. But you can use one symbol in all of these ways,
+independently.
+
+ A symbol name can contain any characters whatever. Most symbol names
+are written with letters, digits, and the punctuation characters
+`-+=*/'. Such names require no special punctuation; the characters of
+the name suffice as long as the name does not look like a number. (If
+it does, write a `\' at the beginning of the name to force
+interpretation as a symbol.) The characters `_~!@$%^&:<>{}' are less
+often used but also require no special punctuation. Any other
+characters may be included in a symbol's name by escaping them with a
+backslash. In contrast to its use in strings, however, a backslash in
+the name of a symbol simply quotes the single character that follows the
+backslash. For example, in a string, `\t' represents a tab character;
+in the name of a symbol, however, `\t' merely quotes the letter `t'.
+To have a symbol with a tab character in its name, you must actually
+use a tab (preceded with a backslash). But it's rare to do such a
+thing.
+
+ Common Lisp note: In Common Lisp, lower case letters are always
+ "folded" to upper case, unless they are explicitly escaped. In
+ Emacs Lisp, upper case and lower case letters are distinct.
+
+ Here are several examples of symbol names. Note that the `+' in the
+fifth example is escaped to prevent it from being read as a number.
+This is not necessary in the sixth example because the rest of the name
+makes it invalid as a number.
+
+ foo ; A symbol named `foo'.
+ FOO ; A symbol named `FOO', different from `foo'.
+ char-to-string ; A symbol named `char-to-string'.
+ 1+ ; A symbol named `1+'
+ ; (not `+1', which is an integer).
+ \+1 ; A symbol named `+1'
+ ; (not a very readable name).
+ \(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name).
+ +-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'.
+ ; These characters need not be escaped.
+
+\1f
+File: lispref.info, Node: Sequence Type, Next: Cons Cell Type, Prev: Symbol Type, Up: Programming Types
+
+Sequence Types
+--------------
+
+ A "sequence" is a Lisp object that represents an ordered set of
+elements. There are two kinds of sequence in XEmacs Lisp, lists and
+arrays. Thus, an object of type list or of type array is also
+considered a sequence.
+
+ Arrays are further subdivided into strings, vectors, and bit vectors.
+Vectors can hold elements of any type, but string elements must be
+characters, and bit vector elements must be either 0 or 1. However, the
+characters in a string can have extents (*note Extents::.) and text
+properties (*note Text Properties::.) like characters in a buffer;
+vectors do not support extents or text properties even when their
+elements happen to be characters.
+
+ Lists, strings, vectors, and bit vectors are different, but they have
+important similarities. For example, all have a length L, and all have
+elements which can be indexed from zero to L minus one. Also, several
+functions, called sequence functions, accept any kind of sequence. For
+example, the function `elt' can be used to extract an element of a
+sequence, given its index. *Note Sequences Arrays Vectors::.
+
+ It is impossible to read the same sequence twice, since sequences are
+always created anew upon reading. If you read the read syntax for a
+sequence twice, you get two sequences with equal contents. There is one
+exception: the empty list `()' always stands for the same object, `nil'.
+
+\1f
+File: lispref.info, Node: Cons Cell Type, Next: Array Type, Prev: Sequence Type, Up: Programming Types
+
+Cons Cell and List Types
+------------------------
+
+ A "cons cell" is an object comprising two pointers named the CAR and
+the CDR. Each of them can point to any Lisp object.
+
+ A "list" is a series of cons cells, linked together so that the CDR
+of each cons cell points either to another cons cell or to the empty
+list. *Note Lists::, for functions that work on lists. Because most
+cons cells are used as part of lists, the phrase "list structure" has
+come to refer to any structure made out of cons cells.
+
+ The names CAR and CDR have only historical meaning now. The
+original Lisp implementation ran on an IBM 704 computer which divided
+words into two parts, called the "address" part and the "decrement";
+CAR was an instruction to extract the contents of the address part of a
+register, and CDR an instruction to extract the contents of the
+decrement. By contrast, "cons cells" are named for the function `cons'
+that creates them, which in turn is named for its purpose, the
+construction of cells.
+
+ Because cons cells are so central to Lisp, we also have a word for
+"an object which is not a cons cell". These objects are called "atoms".
+
+ The read syntax and printed representation for lists are identical,
+and consist of a left parenthesis, an arbitrary number of elements, and
+a right parenthesis.
+
+ Upon reading, each object inside the parentheses becomes an element
+of the list. That is, a cons cell is made for each element. The CAR
+of the cons cell points to the element, and its CDR points to the next
+cons cell of the list, which holds the next element in the list. The
+CDR of the last cons cell is set to point to `nil'.
+
+ A list can be illustrated by a diagram in which the cons cells are
+shown as pairs of boxes. (The Lisp reader cannot read such an
+illustration; unlike the textual notation, which can be understood by
+both humans and computers, the box illustrations can be understood only
+by humans.) The following represents the three-element list `(rose
+violet buttercup)':
+
+ ___ ___ ___ ___ ___ ___
+ |___|___|--> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ --> rose --> violet --> buttercup
+
+ In this diagram, each box represents a slot that can refer to any
+Lisp object. Each pair of boxes represents a cons cell. Each arrow is
+a reference to a Lisp object, either an atom or another cons cell.
+
+ In this example, the first box, the CAR of the first cons cell,
+refers to or "contains" `rose' (a symbol). The second box, the CDR of
+the first cons cell, refers to the next pair of boxes, the second cons
+cell. The CAR of the second cons cell refers to `violet' and the CDR
+refers to the third cons cell. The CDR of the third (and last) cons
+cell refers to `nil'.
+
+ Here is another diagram of the same list, `(rose violet buttercup)',
+sketched in a different manner:
+
+ --------------- ---------------- -------------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | rose | o-------->| violet | o-------->| buttercup | nil |
+ | | | | | | | | |
+ --------------- ---------------- -------------------
+
+ A list with no elements in it is the "empty list"; it is identical
+to the symbol `nil'. In other words, `nil' is both a symbol and a list.
+
+ Here are examples of lists written in Lisp syntax:
+
+ (A 2 "A") ; A list of three elements.
+ () ; A list of no elements (the empty list).
+ nil ; A list of no elements (the empty list).
+ ("A ()") ; A list of one element: the string `"A ()"'.
+ (A ()) ; A list of two elements: `A' and the empty list.
+ (A nil) ; Equivalent to the previous.
+ ((A B C)) ; A list of one element
+ ; (which is a list of three elements).
+
+ Here is the list `(A ())', or equivalently `(A nil)', depicted with
+boxes and arrows:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> A --> nil
+
+* Menu:
+
+* Dotted Pair Notation:: An alternative syntax for lists.
+* Association List Type:: A specially constructed list.
+
+\1f
+File: lispref.info, Node: Dotted Pair Notation, Next: Association List Type, Up: Cons Cell Type
+
+Dotted Pair Notation
+....................
+
+ "Dotted pair notation" is an alternative syntax for cons cells that
+represents the CAR and CDR explicitly. In this syntax, `(A . B)'
+stands for a cons cell whose CAR is the object A, and whose CDR is the
+object B. Dotted pair notation is therefore more general than list
+syntax. In the dotted pair notation, the list `(1 2 3)' is written as
+`(1 . (2 . (3 . nil)))'. For `nil'-terminated lists, the two
+notations produce the same result, but list notation is usually clearer
+and more convenient when it is applicable. When printing a list, the
+dotted pair notation is only used if the CDR of a cell is not a list.
+
+ Here's how box notation can illustrate dotted pairs. This example
+shows the pair `(rose . violet)':
+
+ ___ ___
+ |___|___|--> violet
+ |
+ |
+ --> rose
+
+ Dotted pair notation can be combined with list notation to represent
+a chain of cons cells with a non-`nil' final CDR. For example, `(rose
+violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
+The object looks like this:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> buttercup
+ | |
+ | |
+ --> rose --> violet
+
+ These diagrams make it evident why `(rose . violet . buttercup)' is
+invalid syntax; it would require a cons cell that has three parts
+rather than two.
+
+ The list `(rose violet)' is equivalent to `(rose . (violet))' and
+looks like this:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> rose --> violet
+
+ Similarly, the three-element list `(rose violet buttercup)' is
+equivalent to `(rose . (violet . (buttercup)))'. It looks like this:
+
+ ___ ___ ___ ___ ___ ___
+ |___|___|--> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ --> rose --> violet --> buttercup
+
+\1f
+File: lispref.info, Node: Association List Type, Prev: Dotted Pair Notation, Up: Cons Cell Type
+
+Association List Type
+.....................
+
+ An "association list" or "alist" is a specially-constructed list
+whose elements are cons cells. In each element, the CAR is considered
+a "key", and the CDR is considered an "associated value". (In some
+cases, the associated value is stored in the CAR of the CDR.)
+Association lists are often used as stacks, since it is easy to add or
+remove associations at the front of the list.
+
+ For example,
+
+ (setq alist-of-colors
+ '((rose . red) (lily . white) (buttercup . yellow)))
+
+sets the variable `alist-of-colors' to an alist of three elements. In
+the first element, `rose' is the key and `red' is the value.
+
+ *Note Association Lists::, for a further explanation of alists and
+for functions that work on alists.
+
+\1f
+File: lispref.info, Node: Array Type, Next: String Type, Prev: Cons Cell Type, Up: Programming Types
+
+Array Type
+----------
+
+ An "array" is composed of an arbitrary number of slots for referring
+to other Lisp objects, arranged in a contiguous block of memory.
+Accessing any element of an array takes the same amount of time. In
+contrast, accessing an element of a list requires time proportional to
+the position of the element in the list. (Elements at the end of a
+list take longer to access than elements at the beginning of a list.)
+
+ XEmacs defines three types of array, strings, vectors, and bit
+vectors. A string is an array of characters, a vector is an array of
+arbitrary objects, and a bit vector is an array of 1's and 0's. All are
+one-dimensional. (Most other programming languages support
+multidimensional arrays, but they are not essential; you can get the
+same effect with an array of arrays.) Each type of array has its own
+read syntax; see *Note String Type::, *Note Vector Type::, and *Note
+Bit Vector Type::.
+
+ An array may have any length up to the largest integer; but once
+created, it has a fixed size. The first element of an array has index
+zero, the second element has index 1, and so on. This is called
+"zero-origin" indexing. For example, an array of four elements has
+indices 0, 1, 2, and 3.
+
+ The array type is contained in the sequence type and contains the
+string type, the vector type, and the bit vector type.
+
+\1f
+File: lispref.info, Node: String Type, Next: Vector Type, Prev: Array Type, Up: Programming Types
+
+String Type
+-----------
+
+ A "string" is an array of characters. Strings are used for many
+purposes in XEmacs, as can be expected in a text editor; for example, as
+the names of Lisp symbols, as messages for the user, and to represent
+text extracted from buffers. Strings in Lisp are constants: evaluation
+of a string returns the same string.
+
+ The read syntax for strings is a double-quote, an arbitrary number of
+characters, and another double-quote, `"like this"'. The Lisp reader
+accepts the same formats for reading the characters of a string as it
+does for reading single characters (without the question mark that
+begins a character literal). You can enter a nonprinting character such
+as tab or `C-a' using the convenient escape sequences, like this: `"\t,
+\C-a"'. You can include a double-quote in a string by preceding it
+with a backslash; thus, `"\""' is a string containing just a single
+double-quote character. (*Note Character Type::, for a description of
+the read syntax for characters.)
+
+ The printed representation of a string consists of a double-quote,
+the characters it contains, and another double-quote. However, you must
+escape any backslash or double-quote characters in the string with a
+backslash, like this: `"this \" is an embedded quote"'.
+
+ The newline character is not special in the read syntax for strings;
+if you write a new line between the double-quotes, it becomes a
+character in the string. But an escaped newline--one that is preceded
+by `\'--does not become part of the string; i.e., the Lisp reader
+ignores an escaped newline while reading a string.
+
+ "It is useful to include newlines
+ in documentation strings,
+ but the newline is \
+ ignored if escaped."
+ => "It is useful to include newlines
+ in documentation strings,
+ but the newline is ignored if escaped."
+
+ A string can hold extents and properties of the text it contains, in
+addition to the characters themselves. This enables programs that copy
+text between strings and buffers to preserve the extents and properties
+with no special effort. *Note Extents::, *Note Text Properties::.
+
+ Note that FSF GNU Emacs has a special read and print syntax for
+strings with text properties, but XEmacs does not currently implement
+this. It was judged better not to include this in XEmacs because it
+entails that `equal' return `nil' when passed a string with text
+properties and the equivalent string without text properties, which is
+often counter-intuitive.
+
+ *Note Strings and Characters::, for functions that work on strings.
+
+\1f
+File: lispref.info, Node: Vector Type, Next: Bit Vector Type, Prev: String Type, Up: Programming Types
+
+Vector Type
+-----------
+
+ A "vector" is a one-dimensional array of elements of any type. It
+takes a constant amount of time to access any element of a vector. (In
+a list, the access time of an element is proportional to the distance of
+the element from the beginning of the list.)
+
+ The printed representation of a vector consists of a left square
+bracket, the elements, and a right square bracket. This is also the
+read syntax. Like numbers and strings, vectors are considered constants
+for evaluation.
+
+ [1 "two" (three)] ; A vector of three elements.
+ => [1 "two" (three)]
+
+ *Note Vectors::, for functions that work with vectors.
+
+\1f
+File: lispref.info, Node: Bit Vector Type, Next: Function Type, Prev: Vector Type, Up: Programming Types
+
+Bit Vector Type
+---------------
+
+ A "bit vector" is a one-dimensional array of 1's and 0's. It takes
+a constant amount of time to access any element of a bit vector, as for
+vectors. Bit vectors have an extremely compact internal representation
+(one machine bit per element), which makes them ideal for keeping track
+of unordered sets, large collections of boolean values, etc.
+
+ The printed representation of a bit vector consists of `#*' followed
+by the bits in the vector. This is also the read syntax. Like
+numbers, strings, and vectors, bit vectors are considered constants for
+evaluation.
+
+ #*00101000 ; A bit vector of eight elements.
+ => #*00101000
+
+ *Note Bit Vectors::, for functions that work with bit vectors.
+
+\1f
+File: lispref.info, Node: Function Type, Next: Macro Type, Prev: Bit Vector Type, Up: Programming Types
+
+Function Type
+-------------
+
+ Just as functions in other programming languages are executable,
+"Lisp function" objects are pieces of executable code. However,
+functions in Lisp are primarily Lisp objects, and only secondarily the
+text which represents them. These Lisp objects are lambda expressions:
+lists whose first element is the symbol `lambda' (*note Lambda
+Expressions::.).
+
+ In most programming languages, it is impossible to have a function
+without a name. In Lisp, a function has no intrinsic name. A lambda
+expression is also called an "anonymous function" (*note Anonymous
+Functions::.). A named function in Lisp is actually a symbol with a
+valid function in its function cell (*note Defining Functions::.).
+
+ Most of the time, functions are called when their names are written
+in Lisp expressions in Lisp programs. However, you can construct or
+obtain a function object at run time and then call it with the primitive
+functions `funcall' and `apply'. *Note Calling Functions::.
+
+\1f
+File: lispref.info, Node: Macro Type, Next: Primitive Function Type, Prev: Function Type, Up: Programming Types
+
+Macro Type
+----------
+
+ A "Lisp macro" is a user-defined construct that extends the Lisp
+language. It is represented as an object much like a function, but with
+different parameter-passing semantics. A Lisp macro has the form of a
+list whose first element is the symbol `macro' and whose CDR is a Lisp
+function object, including the `lambda' symbol.
+
+ Lisp macro objects are usually defined with the built-in `defmacro'
+function, but any list that begins with `macro' is a macro as far as
+XEmacs is concerned. *Note Macros::, for an explanation of how to
+write a macro.
+
+\1f
+File: lispref.info, Node: Primitive Function Type, Next: Compiled-Function Type, Prev: Macro Type, Up: Programming Types
+
+Primitive Function Type
+-----------------------
+
+ A "primitive function" is a function callable from Lisp but written
+in the C programming language. Primitive functions are also called
+"subrs" or "built-in functions". (The word "subr" is derived from
+"subroutine".) Most primitive functions evaluate all their arguments
+when they are called. A primitive function that does not evaluate all
+its arguments is called a "special form" (*note Special Forms::.).
+
+ It does not matter to the caller of a function whether the function
+is primitive. However, this does matter if you try to substitute a
+function written in Lisp for a primitive of the same name. The reason
+is that the primitive function may be called directly from C code.
+Calls to the redefined function from Lisp will use the new definition,
+but calls from C code may still use the built-in definition.
+
+ The term "function" refers to all Emacs functions, whether written
+in Lisp or C. *Note Function Type::, for information about the
+functions written in Lisp.
+
+ Primitive functions have no read syntax and print in hash notation
+with the name of the subroutine.
+
+ (symbol-function 'car) ; Access the function cell
+ ; of the symbol.
+ => #<subr car>
+ (subrp (symbol-function 'car)) ; Is this a primitive function?
+ => t ; Yes.
+
+\1f
+File: lispref.info, Node: Compiled-Function Type, Next: Autoload Type, Prev: Primitive Function Type, Up: Programming Types
+
+Compiled-Function Type
+----------------------
+
+ The byte compiler produces "compiled-function objects". The
+evaluator handles this data type specially when it appears as a function
+to be called. *Note Byte Compilation::, for information about the byte
+compiler.
+
+ The printed representation for a compiled-function object is normally
+`#<compiled-function...>'. If `print-readably' is true, however, it is
+`#[...]'.
+
+\1f
+File: lispref.info, Node: Autoload Type, Next: Char Table Type, Prev: Compiled-Function Type, Up: Programming Types
+
+Autoload Type
+-------------
+
+ An "autoload object" is a list whose first element is the symbol
+`autoload'. It is stored as the function definition of a symbol as a
+placeholder for the real definition; it says that the real definition
+is found in a file of Lisp code that should be loaded when necessary.
+The autoload object contains the name of the file, plus some other
+information about the real definition.
+
+ After the file has been loaded, the symbol should have a new function
+definition that is not an autoload object. The new definition is then
+called as if it had been there to begin with. From the user's point of
+view, the function call works as expected, using the function definition
+in the loaded file.
+
+ An autoload object is usually created with the function `autoload',
+which stores the object in the function cell of a symbol. *Note
+Autoload::, for more details.
+
+\1f
+File: lispref.info, Node: Char Table Type, Next: Hash Table Type, Prev: Autoload Type, Up: Programming Types
+
+Char Table Type
+---------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Hash Table Type, Next: Range Table Type, Prev: Char Table Type, Up: Programming Types
+
+Hash Table Type
+---------------
+
+ A "hash table" is a table providing an arbitrary mapping from one
+Lisp object to another, using an internal indexing method called
+"hashing". Hash tables are very fast (much more efficient that using
+an association list, when there are a large number of elements in the
+table).
+
+ Hash tables have a special read syntax beginning with
+`#s(hash-table' (this is an example of "structure" read syntax. This
+notation is also used for printing when `print-readably' is `t'.
+
+ Otherwise they print in hash notation (The "hash" in "hash notation"
+has nothing to do with the "hash" in "hash table"), giving the number
+of elements, total space allocated for elements, and a unique number
+assigned at the time the hash table was created. (Hash tables
+automatically resize as necessary so there is no danger of running out
+of space for elements.)
+
+ (make-hash-table :size 50)
+ => #<hash-table 0/107 0x313a>
+
+ *Note Hash Tables::, for information on how to create and work with
+hash tables.
+
+\1f
+File: lispref.info, Node: Range Table Type, Next: Weak List Type, Prev: Hash Table Type, Up: Programming Types
+
+Range Table Type
+----------------
+
+ A "range table" is a table that maps from ranges of integers to
+arbitrary Lisp objects. Range tables automatically combine overlapping
+ranges that map to the same Lisp object, and operations are provided
+for mapping over all of the ranges in a range table.
+
+ Range tables have a special read syntax beginning with
+`#s(range-table' (this is an example of "structure" read syntax, which
+is also used for char tables and faces).
+
+ (setq x (make-range-table))
+ (put-range-table 20 50 'foo x)
+ (put-range-table 100 200 "bar" x)
+ x
+ => #s(range-table data ((20 50) foo (100 200) "bar"))
+
+ *Note Range Tables::, for information on how to create and work with
+range tables.
+
+\1f
+File: lispref.info, Node: Weak List Type, Prev: Range Table Type, Up: Programming Types
+
+Weak List Type
+--------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Editing Types, Next: Window-System Types, Prev: Programming Types, Up: Lisp Data Types
+
+Editing Types
+=============
+
+ The types in the previous section are common to many Lisp dialects.
+XEmacs Lisp provides several additional data types for purposes
+connected with editing.
+
+* Menu:
+
+* Buffer Type:: The basic object of editing.
+* Marker Type:: A position in a buffer.
+* Extent Type:: A range in a buffer or string, maybe with properties.
+* Window Type:: Buffers are displayed in windows.
+* Frame Type:: Windows subdivide frames.
+* Device Type:: Devices group all frames on a display.
+* Console Type:: Consoles group all devices with the same keyboard.
+* Window Configuration Type:: Recording the way a frame is subdivided.
+* Event Type:: An interesting occurrence in the system.
+* Process Type:: A process running on the underlying OS.
+* Stream Type:: Receive or send characters.
+* Keymap Type:: What function a keystroke invokes.
+* Syntax Table Type:: What a character means.
+* Display Table Type:: How display tables are represented.
+* Database Type:: A connection to an external DBM or DB database.
+* Charset Type:: A character set (e.g. all Kanji characters),
+ under XEmacs/MULE.
+* Coding System Type:: An object encapsulating a way of converting between
+ different textual encodings, under XEmacs/MULE.
+* ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
+* ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
+
+\1f
+File: lispref.info, Node: Buffer Type, Next: Marker Type, Up: Editing Types
+
+Buffer Type
+-----------
+
+ A "buffer" is an object that holds text that can be edited (*note
+Buffers::.). Most buffers hold the contents of a disk file (*note
+Files::.) so they can be edited, but some are used for other purposes.
+Most buffers are also meant to be seen by the user, and therefore
+displayed, at some time, in a window (*note Windows::.). But a buffer
+need not be displayed in any window.
+
+ The contents of a buffer are much like a string, but buffers are not
+used like strings in XEmacs Lisp, and the available operations are
+different. For example, insertion of text into a buffer is very
+efficient, whereas "inserting" text into a string requires
+concatenating substrings, and the result is an entirely new string
+object.
+
+ Each buffer has a designated position called "point" (*note
+Positions::.). At any time, one buffer is the "current buffer". Most
+editing commands act on the contents of the current buffer in the
+neighborhood of point. Many of the standard Emacs functions manipulate
+or test the characters in the current buffer; a whole chapter in this
+manual is devoted to describing these functions (*note Text::.).
+
+ Several other data structures are associated with each buffer:
+
+ * a local syntax table (*note Syntax Tables::.);
+
+ * a local keymap (*note Keymaps::.);
+
+ * a local variable binding list (*note Buffer-Local Variables::.);
+
+ * a list of extents (*note Extents::.);
+
+ * and various other related properties.
+
+The local keymap and variable list contain entries that individually
+override global bindings or values. These are used to customize the
+behavior of programs in different buffers, without actually changing the
+programs.
+
+ A buffer may be "indirect", which means it shares the text of
+another buffer. *Note Indirect Buffers::.
+
+ Buffers have no read syntax. They print in hash notation, showing
+the buffer name.
+
+ (current-buffer)
+ => #<buffer "objects.texi">
+
+\1f
+File: lispref.info, Node: Marker Type, Next: Extent Type, Prev: Buffer Type, Up: Editing Types
+
+Marker Type
+-----------
+
+ A "marker" denotes a position in a specific buffer. Markers
+therefore have two components: one for the buffer, and one for the
+position. Changes in the buffer's text automatically relocate the
+position value as necessary to ensure that the marker always points
+between the same two characters in the buffer.
+
+ Markers have no read syntax. They print in hash notation, giving the
+current character position and the name of the buffer.
+
+ (point-marker)
+ => #<marker at 50661 in objects.texi>
+
+ *Note Markers::, for information on how to test, create, copy, and
+move markers.
+
+\1f
+File: lispref.info, Node: Extent Type, Next: Window Type, Prev: Marker Type, Up: Editing Types
+
+Extent Type
+-----------
+
+ An "extent" specifies temporary alteration of the display appearance
+of a part of a buffer (or string). It contains markers delimiting a
+range of the buffer, plus a property list (a list whose elements are
+alternating property names and values). Extents are used to present
+parts of the buffer temporarily in a different display style. They
+have no read syntax, and print in hash notation, giving the buffer name
+and range of positions.
+
+ Extents can exist over strings as well as buffers; the primary use
+of this is to preserve extent and text property information as text is
+copied from one buffer to another or between different parts of a
+buffer.
+
+ Extents have no read syntax. They print in hash notation, giving the
+range of text they cover, the name of the buffer or string they are in,
+the address in core, and a summary of some of the properties attached to
+the extent.
+
+ (extent-at (point))
+ => #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
+
+ *Note Extents::, for how to create and use extents.
+
+ Extents are used to implement text properties. *Note Text
+Properties::.
+
+\1f
+File: lispref.info, Node: Window Type, Next: Frame Type, Prev: Extent Type, Up: Editing Types
+
+Window Type
+-----------
+
+ A "window" describes the portion of the frame that XEmacs uses to
+display a buffer. (In standard window-system usage, a "window" is what
+XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to
+refer to what is called a "pane" in standard window-system usage.)
+Every window has one associated buffer, whose contents appear in the
+window. By contrast, a given buffer may appear in one window, no
+window, or several windows.
+
+ Though many windows may exist simultaneously, at any time one window
+is designated the "selected window". This is the window where the
+cursor is (usually) displayed when XEmacs is ready for a command. The
+selected window usually displays the current buffer, but this is not
+necessarily the case.
+
+ Windows are grouped on the screen into frames; each window belongs to
+one and only one frame. *Note Frame Type::.
+
+ Windows have no read syntax. They print in hash notation, giving the
+name of the buffer being displayed and a unique number assigned at the
+time the window was created. (This number can be useful because the
+buffer displayed in any given window can change frequently.)
+
+ (selected-window)
+ => #<window on "objects.texi" 0x266c>
+
+ *Note Windows::, for a description of the functions that work on
+windows.
+
+\1f
+File: lispref.info, Node: Frame Type, Next: Device Type, Prev: Window Type, Up: Editing Types
+
+Frame Type
+----------
+
+ A FRAME is a rectangle on the screen (a "window" in standard
+window-system terminology) that contains one or more non-overlapping
+Emacs windows ("panes" in standard window-system terminology). A frame
+initially contains a single main window (plus perhaps a minibuffer
+window) which you can subdivide vertically or horizontally into smaller
+windows.
+
+ Frames have no read syntax. They print in hash notation, giving the
+frame's type, name as used for resourcing, and a unique number assigned
+at the time the frame was created.
+
+ (selected-frame)
+ => #<x-frame "emacs" 0x9db>
+
+ *Note Frames::, for a description of the functions that work on
+frames.
+
+\1f
+File: lispref.info, Node: Device Type, Next: Console Type, Prev: Frame Type, Up: Editing Types
+
+Device Type
+-----------
+
+ A "device" represents a single display on which frames exist.
+Normally, there is only one device object, but there may be more than
+one if XEmacs is being run on a multi-headed display (e.g. an X server
+with attached color and mono screens) or if XEmacs is simultaneously
+driving frames attached to different consoles, e.g. an X display and a
+TTY connection.
+
+ Devices do not have a read syntax. They print in hash notation,
+giving the device's type, connection name, and a unique number assigned
+at the time the device was created.
+
+ (selected-device)
+ => #<x-device on ":0.0" 0x5b9>
+
+ *Note Consoles and Devices::, for a description of several functions
+related to devices.
+
+\1f
+File: lispref.info, Node: Console Type, Next: Window Configuration Type, Prev: Device Type, Up: Editing Types
+
+Console Type
+------------
+
+ A "console" represents a single keyboard to which devices (i.e.
+displays on which frames exist) are connected. Normally, there is only
+one console object, but there may be more than one if XEmacs is
+simultaneously driving frames attached to different X servers and/or
+TTY connections. (XEmacs is capable of driving multiple X and TTY
+connections at the same time, and provides a robust mechanism for
+handling the differing display capabilities of such heterogeneous
+environments. A buffer with embedded glyphs and multiple fonts and
+colors, for example, will display reasonably if it simultaneously
+appears on a frame on a color X display, a frame on a mono X display,
+and a frame on a TTY connection.)
+
+ Consoles do not have a read syntax. They print in hash notation,
+giving the console's type, connection name, and a unique number assigned
+at the time the console was created.
+
+ (selected-console)
+ => #<x-console on "localhost:0" 0x5b7>
+
+ *Note Consoles and Devices::, for a description of several functions
+related to consoles.
+
+\1f
+File: lispref.info, Node: Window Configuration Type, Next: Event Type, Prev: Console Type, Up: Editing Types
+
+Window Configuration Type
+-------------------------
+
+ A "window configuration" stores information about the positions,
+sizes, and contents of the windows in a frame, so you can recreate the
+same arrangement of windows later.
+
+ Window configurations do not have a read syntax. They print in hash
+notation, giving a unique number assigned at the time the window
+configuration was created.
+
+ (current-window-configuration)
+ => #<window-configuration 0x2db4>
+
+ *Note Window Configurations::, for a description of several functions
+related to window configurations.
+
+\1f
+File: lispref.info, Node: Event Type, Next: Process Type, Prev: Window Configuration Type, Up: Editing Types
+
+Event Type
+----------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Process Type, Next: Stream Type, Prev: Event Type, Up: Editing Types
+
+Process Type
+------------
+
+ The word "process" usually means a running program. XEmacs itself
+runs in a process of this sort. However, in XEmacs Lisp, a process is a
+Lisp object that designates a subprocess created by the XEmacs process.
+Programs such as shells, GDB, ftp, and compilers, running in
+subprocesses of XEmacs, extend the capabilities of XEmacs.
+
+ An Emacs subprocess takes textual input from Emacs and returns
+textual output to Emacs for further manipulation. Emacs can also send
+signals to the subprocess.
+
+ Process objects have no read syntax. They print in hash notation,
+giving the name of the process, its associated process ID, and the
+current state of the process:
+
+ (process-list)
+ => (#<process "shell" pid 2909 state:run>)
+
+ *Note Processes::, for information about functions that create,
+delete, return information about, send input or signals to, and receive
+output from processes.
+
+\1f
+File: lispref.info, Node: Stream Type, Next: Keymap Type, Prev: Process Type, Up: Editing Types
+
+Stream Type
+-----------
+
+ A "stream" is an object that can be used as a source or sink for
+characters--either to supply characters for input or to accept them as
+output. Many different types can be used this way: markers, buffers,
+strings, and functions. Most often, input streams (character sources)
+obtain characters from the keyboard, a buffer, or a file, and output
+streams (character sinks) send characters to a buffer, such as a
+`*Help*' buffer, or to the echo area.
+
+ The object `nil', in addition to its other meanings, may be used as
+a stream. It stands for the value of the variable `standard-input' or
+`standard-output'. Also, the object `t' as a stream specifies input
+using the minibuffer (*note Minibuffers::.) or output in the echo area
+(*note The Echo Area::.).
+
+ Streams have no special printed representation or read syntax, and
+print as whatever primitive type they are.
+
+ *Note Read and Print::, for a description of functions related to
+streams, including parsing and printing functions.
+
+\1f
+File: lispref.info, Node: Keymap Type, Next: Syntax Table Type, Prev: Stream Type, Up: Editing Types
+
+Keymap Type
+-----------
+
+ A "keymap" maps keys typed by the user to commands. This mapping
+controls how the user's command input is executed.
+
+ NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU
+Emacs, a keymap is actually a list whose CAR is the symbol `keymap'.
+
+ *Note Keymaps::, for information about creating keymaps, handling
+prefix keys, local as well as global keymaps, and changing key bindings.
+
+\1f
+File: lispref.info, Node: Syntax Table Type, Next: Display Table Type, Prev: Keymap Type, Up: Editing Types
+
+Syntax Table Type
+-----------------
+
+ Under XEmacs 20, a "syntax table" is a particular type of char
+table. Under XEmacs 19, a syntax table a vector of 256 integers. In
+both cases, each element defines how one character is interpreted when
+it appears in a buffer. For example, in C mode (*note Major Modes::.),
+the `+' character is punctuation, but in Lisp mode it is a valid
+character in a symbol. These modes specify different interpretations by
+changing the syntax table entry for `+'.
+
+ Syntax tables are used only for scanning text in buffers, not for
+reading Lisp expressions. The table the Lisp interpreter uses to read
+expressions is built into the XEmacs source code and cannot be changed;
+thus, to change the list delimiters to be `{' and `}' instead of `('
+and `)' would be impossible.
+
+ *Note Syntax Tables::, for details about syntax classes and how to
+make and modify syntax tables.
+
+\1f
+File: lispref.info, Node: Display Table Type, Next: Database Type, Prev: Syntax Table Type, Up: Editing Types
+
+Display Table Type
+------------------
+
+ A "display table" specifies how to display each character code.
+Each buffer and each window can have its own display table. A display
+table is actually a vector of length 256, although in XEmacs 20 this may
+change to be a particular type of char table. *Note Display Tables::.
+
+\1f
+File: lispref.info, Node: Database Type, Next: Charset Type, Prev: Display Table Type, Up: Editing Types
+
+Database Type
+-------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Charset Type, Next: Coding System Type, Prev: Database Type, Up: Editing Types
+
+Charset Type
+------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Coding System Type, Next: ToolTalk Message Type, Prev: Charset Type, Up: Editing Types
+
+Coding System Type
+------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: ToolTalk Message Type, Next: ToolTalk Pattern Type, Prev: Coding System Type, Up: Editing Types
+
+ToolTalk Message Type
+---------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: ToolTalk Pattern Type, Prev: ToolTalk Message Type, Up: Editing Types
+
+ToolTalk Pattern Type
+---------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Window-System Types, Next: Type Predicates, Prev: Editing Types, Up: Lisp Data Types
+
+Window-System Types
+===================
+
+ XEmacs also has some types that represent objects such as faces
+(collections of display characters), fonts, and pixmaps that are
+commonly found in windowing systems.
+
+* Menu:
+
+* Face Type:: A collection of display characteristics.
+* Glyph Type:: An image appearing in a buffer or elsewhere.
+* Specifier Type:: A way of controlling display characteristics on
+ a per-buffer, -frame, -window, or -device level.
+* Font Instance Type:: The way a font appears on a particular device.
+* Color Instance Type:: The way a color appears on a particular device.
+* Image Instance Type:: The way an image appears on a particular device.
+* Toolbar Button Type:: An object representing a button in a toolbar.
+* Subwindow Type:: An externally-controlled window-system window
+ appearing in a buffer.
+* X Resource Type:: A miscellaneous X resource, if Epoch support was
+ compiled into XEmacs.
+
+\1f
+File: lispref.info, Node: Face Type, Next: Glyph Type, Up: Window-System Types
+
+Face Type
+---------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Glyph Type, Next: Specifier Type, Prev: Face Type, Up: Window-System Types
+
+Glyph Type
+----------
+
+ (not yet documented)
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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 `\<f\w*\>'. The
+ resulting expression looks like this:
+
+ (sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
+ (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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 <TAB>
+key to indent properly for the language being edited. This section
+describes the mechanism of the <TAB> 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 <TAB> (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 <TAB> does,
+ but in some text modes, where <TAB> 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 <TAB> does, but in some text modes, where <TAB>
+ inserts a tab, `reindent-then-newline-and-indent' indents to the
+ column specified by `left-margin'.
+
+\1f
+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').
+
+\1f
+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.
+
+\1f
+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 <TAB> 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.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Examining Properties, Next: Changing Properties, Up: Text Properties
+
+Examining Text Properties
+-------------------------
+
+ The simplest way to examine text properties is to ask for the value
+of a particular property of a particular character. For that, use
+`get-text-property'. Use `text-properties-at' to get the entire
+property list of a character. *Note Property Search::, for functions
+to examine the properties of a number of characters at once.
+
+ These functions handle both strings and buffers. (Keep in mind that
+positions in a string start from 0, whereas positions in a buffer start
+from 1.)
+
+ - Function: get-text-property POS PROP &optional OBJECT
+ This function returns the value of the PROP property of the
+ character after position POS in OBJECT (a buffer or string). The
+ argument OBJECT is optional and defaults to the current buffer.
+
+ - Function: get-char-property POS PROP &optional OBJECT
+ This function is like `get-text-property', except that it checks
+ all extents, not just text-property extents.
+
+
+ - Function: text-properties-at POSITION &optional OBJECT
+ This function returns the entire property list of the character at
+ POSITION in the string or buffer OBJECT. If OBJECT is `nil', it
+ defaults to the current buffer.
+
+ - Variable: default-text-properties
+ This variable holds a property list giving default values for text
+ properties. Whenever a character does not specify a value for a
+ property, the value stored in this list is used instead. Here is
+ an example:
+
+ (setq default-text-properties '(foo 69))
+ ;; Make sure character 1 has no properties of its own.
+ (set-text-properties 1 2 nil)
+ ;; What we get, when we ask, is the default value.
+ (get-text-property 1 'foo)
+ => 69
+
+\1f
+File: lispref.info, Node: Changing Properties, Next: Property Search, Prev: Examining Properties, Up: Text Properties
+
+Changing Text Properties
+------------------------
+
+ The primitives for changing properties apply to a specified range of
+text. The function `set-text-properties' (see end of section) sets the
+entire property list of the text in that range; more often, it is
+useful to add, change, or delete just certain properties specified by
+name.
+
+ Since text properties are considered part of the buffer's contents,
+and can affect how the buffer looks on the screen, any change in the
+text properties is considered a buffer modification. Buffer text
+property changes are undoable (*note Undo::.).
+
+ - Function: put-text-property START END PROP VALUE &optional OBJECT
+ This function sets the PROP property to VALUE for the text between
+ START and END in the string or buffer OBJECT. If OBJECT is `nil',
+ it defaults to the current buffer.
+
+ - Function: add-text-properties START END PROPS &optional OBJECT
+ This function modifies the text properties for the text between
+ START and END in the string or buffer OBJECT. If OBJECT is `nil',
+ it defaults to the current buffer.
+
+ The argument PROPS specifies which properties to change. It
+ should have the form of a property list (*note Property Lists::.):
+ a list whose elements include the property names followed
+ alternately by the corresponding values.
+
+ The return value is `t' if the function actually changed some
+ property's value; `nil' otherwise (if PROPS is `nil' or its values
+ agree with those in the text).
+
+ For example, here is how to set the `comment' and `face'
+ properties of a range of text:
+
+ (add-text-properties START END
+ '(comment t face highlight))
+
+ - Function: remove-text-properties START END PROPS &optional OBJECT
+ This function deletes specified text properties from the text
+ between START and END in the string or buffer OBJECT. If OBJECT
+ is `nil', it defaults to the current buffer.
+
+ The argument PROPS specifies which properties to delete. It
+ should have the form of a property list (*note Property Lists::.):
+ a list whose elements are property names alternating with
+ corresponding values. But only the names matter--the values that
+ accompany them are ignored. For example, here's how to remove the
+ `face' property.
+
+ (remove-text-properties START END '(face nil))
+
+ The return value is `t' if the function actually changed some
+ property's value; `nil' otherwise (if PROPS is `nil' or if no
+ character in the specified text had any of those properties).
+
+ - Function: set-text-properties START END PROPS &optional OBJECT
+ This function completely replaces the text property list for the
+ text between START and END in the string or buffer OBJECT. If
+ OBJECT is `nil', it defaults to the current buffer.
+
+ The argument PROPS is the new property list. It should be a list
+ whose elements are property names alternating with corresponding
+ values.
+
+ After `set-text-properties' returns, all the characters in the
+ specified range have identical properties.
+
+ If PROPS is `nil', the effect is to get rid of all properties from
+ the specified range of text. Here's an example:
+
+ (set-text-properties START END nil)
+
+ See also the function `buffer-substring-without-properties' (*note
+Buffer Contents::.) which copies text from the buffer but does not copy
+its properties.
+
+\1f
+File: lispref.info, Node: Property Search, Next: Special Properties, Prev: Changing Properties, Up: Text Properties
+
+Property Search Functions
+-------------------------
+
+ In typical use of text properties, most of the time several or many
+consecutive characters have the same value for a property. Rather than
+writing your programs to examine characters one by one, it is much
+faster to process chunks of text that have the same property value.
+
+ Here are functions you can use to do this. They use `eq' for
+comparing property values. In all cases, OBJECT defaults to the
+current buffer.
+
+ For high performance, it's very important to use the LIMIT argument
+to these functions, especially the ones that search for a single
+property--otherwise, they may spend a long time scanning to the end of
+the buffer, if the property you are interested in does not change.
+
+ Remember that a position is always between two characters; the
+position returned by these functions is between two characters with
+different properties.
+
+ - Function: next-property-change POS &optional OBJECT LIMIT
+ The function scans the text forward from position POS in the
+ string or buffer OBJECT till it finds a change in some text
+ property, then returns the position of the change. In other
+ words, it returns the position of the first character beyond POS
+ whose properties are not identical to those of the character just
+ after POS.
+
+ If LIMIT is non-`nil', then the scan ends at position LIMIT. If
+ there is no property change before that point,
+ `next-property-change' returns LIMIT.
+
+ The value is `nil' if the properties remain unchanged all the way
+ to the end of OBJECT and LIMIT is `nil'. If the value is
+ non-`nil', it is a position greater than or equal to POS. The
+ value equals POS only when LIMIT equals POS.
+
+ Here is an example of how to scan the buffer by chunks of text
+ within which all properties are constant:
+
+ (while (not (eobp))
+ (let ((plist (text-properties-at (point)))
+ (next-change
+ (or (next-property-change (point) (current-buffer))
+ (point-max))))
+ Process text from point to NEXT-CHANGE...
+ (goto-char next-change)))
+
+ - Function: next-single-property-change POS PROP &optional OBJECT LIMIT
+ The function scans the text forward from position POS in the
+ string or buffer OBJECT till it finds a change in the PROP
+ property, then returns the position of the change. In other
+ words, it returns the position of the first character beyond POS
+ whose PROP property differs from that of the character just after
+ POS.
+
+ If LIMIT is non-`nil', then the scan ends at position LIMIT. If
+ there is no property change before that point,
+ `next-single-property-change' returns LIMIT.
+
+ The value is `nil' if the property remains unchanged all the way to
+ the end of OBJECT and LIMIT is `nil'. If the value is non-`nil',
+ it is a position greater than or equal to POS; it equals POS only
+ if LIMIT equals POS.
+
+ - Function: previous-property-change POS &optional OBJECT LIMIT
+ This is like `next-property-change', but scans back from POS
+ instead of forward. If the value is non-`nil', it is a position
+ less than or equal to POS; it equals POS only if LIMIT equals POS.
+
+ - Function: previous-single-property-change POS PROP &optional OBJECT
+ LIMIT
+ This is like `next-single-property-change', but scans back from
+ POS instead of forward. If the value is non-`nil', it is a
+ position less than or equal to POS; it equals POS only if LIMIT
+ equals POS.
+
+ - Function: text-property-any START END PROP VALUE &optional OBJECT
+ This function returns non-`nil' if at least one character between
+ START and END has a property PROP whose value is VALUE. More
+ precisely, it returns the position of the first such character.
+ Otherwise, it returns `nil'.
+
+ The optional fifth argument, OBJECT, specifies the string or
+ buffer to scan. Positions are relative to OBJECT. The default
+ for OBJECT is the current buffer.
+
+ - Function: text-property-not-all START END PROP VALUE &optional OBJECT
+ This function returns non-`nil' if at least one character between
+ START and END has a property PROP whose value differs from VALUE.
+ More precisely, it returns the position of the first such
+ character. Otherwise, it returns `nil'.
+
+ The optional fifth argument, OBJECT, specifies the string or
+ buffer to scan. Positions are relative to OBJECT. The default
+ for OBJECT is the current buffer.
+
+\1f
+File: lispref.info, Node: Special Properties, Next: Saving Properties, Prev: Property Search, Up: Text Properties
+
+Properties with Special Meanings
+--------------------------------
+
+ The predefined properties are the same as those for extents. *Note
+Extent Properties::.
+
+\1f
+File: lispref.info, Node: Saving Properties, Prev: Special Properties, Up: Text Properties
+
+Saving Text Properties in Files
+-------------------------------
+
+ You can save text properties in files, and restore text properties
+when inserting the files, using these two hooks:
+
+ - Variable: write-region-annotate-functions
+ This variable's value is a list of functions for `write-region' to
+ run to encode text properties in some fashion as annotations to
+ the text being written in the file. *Note Writing to Files::.
+
+ Each function in the list is called with two arguments: the start
+ and end of the region to be written. These functions should not
+ alter the contents of the buffer. Instead, they should return
+ lists indicating annotations to write in the file in addition to
+ the text in the buffer.
+
+ Each function should return a list of elements of the form
+ `(POSITION . STRING)', where POSITION is an integer specifying the
+ relative position in the text to be written, and STRING is the
+ annotation to add there.
+
+ Each list returned by one of these functions must be already
+ sorted in increasing order by POSITION. If there is more than one
+ function, `write-region' merges the lists destructively into one
+ sorted list.
+
+ When `write-region' actually writes the text from the buffer to the
+ file, it intermixes the specified annotations at the corresponding
+ positions. All this takes place without modifying the buffer.
+
+ - Variable: after-insert-file-functions
+ This variable holds a list of functions for `insert-file-contents'
+ to call after inserting a file's contents. These functions should
+ scan the inserted text for annotations, and convert them to the
+ text properties they stand for.
+
+ Each function receives one argument, the length of the inserted
+ text; point indicates the start of that text. The function should
+ scan that text for annotations, delete them, and create the text
+ properties that the annotations specify. The function should
+ return the updated length of the inserted text, as it stands after
+ those changes. The value returned by one function becomes the
+ argument to the next function.
+
+ These functions should always return with point at the beginning of
+ the inserted text.
+
+ The intended use of `after-insert-file-functions' is for converting
+ some sort of textual annotations into actual text properties. But
+ other uses may be possible.
+
+ We invite users to write Lisp programs to store and retrieve text
+properties in files, using these hooks, and thus to experiment with
+various data formats and find good ones. Eventually we hope users will
+produce good, general extensions we can install in Emacs.
+
+ We suggest not trying to handle arbitrary Lisp objects as property
+names or property values--because a program that general is probably
+difficult to write, and slow. Instead, choose a set of possible data
+types that are reasonably flexible, and not too hard to encode.
+
+ *Note Format Conversion::, for a related feature.
+
+\1f
+File: lispref.info, Node: Substitution, Next: Registers, Prev: Text Properties, Up: Text
+
+Substituting for a Character Code
+=================================
+
+ The following functions replace characters within a specified region
+based on their character codes.
+
+ - Function: subst-char-in-region START END OLD-CHAR NEW-CHAR &optional
+ NOUNDO
+ This function replaces all occurrences of the character OLD-CHAR
+ with the character NEW-CHAR in the region of the current buffer
+ defined by START and END.
+
+ If NOUNDO is non-`nil', then `subst-char-in-region' does not
+ record the change for undo and does not mark the buffer as
+ modified. This feature is used for controlling selective display
+ (*note Selective Display::.).
+
+ `subst-char-in-region' does not move point and returns `nil'.
+
+ ---------- Buffer: foo ----------
+ This is the contents of the buffer before.
+ ---------- Buffer: foo ----------
+
+ (subst-char-in-region 1 20 ?i ?X)
+ => nil
+
+ ---------- Buffer: foo ----------
+ ThXs Xs the contents of the buffer before.
+ ---------- Buffer: foo ----------
+
+ - Function: translate-region START END TABLE
+ This function applies a translation table to the characters in the
+ buffer between positions START and END. The translation table
+ TABLE can be either a string, a vector, or a char-table.
+
+ If TABLE is a string, its Nth element is the mapping for the
+ character with code N.
+
+ If TABLE is a vector, its Nth element is the mapping for character
+ with code N. Legal mappings are characters, strings, or `nil'
+ (meaning don't replace.)
+
+ If TABLE is a char-table, its elements describe the mapping
+ between characters and their replacements. The char-table should
+ be of type `char' or `generic'.
+
+ When the TABLE is a string or vector and its length is less than
+ the total number of characters (256 without Mule), any characters
+ with codes larger than the length of TABLE are not altered by the
+ translation.
+
+ The return value of `translate-region' is the number of characters
+ that were actually changed by the translation. This does not
+ count characters that were mapped into themselves in the
+ translation table.
+
+ *NOTE*: Prior to XEmacs 21.2, the TABLE argument was allowed only
+ to be a string. This is still the case in FSF Emacs.
+
+ The following example creates a char-table that is passed to
+ `translate-region', which translates character `a' to `the letter
+ a', removes character `b', and translates character `c' to newline.
+
+ ---------- Buffer: foo ----------
+ Here is a sentence in the buffer.
+ ---------- Buffer: foo ----------
+
+ (let ((table (make-char-table 'generic)))
+ (put-char-table ?a "the letter a" table)
+ (put-char-table ?b "" table)
+ (put-char-table ?c ?\n table)
+ (translate-region (point-min) (point-max) table))
+ => 3
+
+ ---------- Buffer: foo ----------
+ Here is the letter a senten
+ e in the uffer.
+ ---------- Buffer: foo ----------
+
+\1f
+File: lispref.info, Node: Registers, Next: Transposition, Prev: Substitution, Up: Text
+
+Registers
+=========
+
+ A register is a sort of variable used in XEmacs editing that can
+hold a marker, a string, a rectangle, a window configuration (of one
+frame), or a frame configuration (of all frames). Each register is
+named by a single character. All characters, including control and
+meta characters (but with the exception of `C-g'), can be used to name
+registers. Thus, there are 255 possible registers. A register is
+designated in Emacs Lisp by a character that is its name.
+
+ The functions in this section return unpredictable values unless
+otherwise stated.
+
+ - Variable: register-alist
+ This variable is an alist of elements of the form `(NAME .
+ CONTENTS)'. Normally, there is one element for each XEmacs
+ register that has been used.
+
+ The object NAME is a character (an integer) identifying the
+ register. The object CONTENTS is a string, marker, or list
+ representing the register contents. A string represents text
+ stored in the register. A marker represents a position. A list
+ represents a rectangle; its elements are strings, one per line of
+ the rectangle.
+
+ - Function: get-register REG
+ This function returns the contents of the register REG, or `nil'
+ if it has no contents.
+
+ - Function: set-register REG VALUE
+ This function sets the contents of register REG to VALUE. A
+ register can be set to any value, but the other register functions
+ expect only certain data types. The return value is VALUE.
+
+ - Command: view-register REG
+ This command displays what is contained in register REG.
+
+ - Command: insert-register REG &optional BEFOREP
+ This command inserts contents of register REG into the current
+ buffer.
+
+ Normally, this command puts point before the inserted text, and the
+ mark after it. However, if the optional second argument BEFOREP
+ is non-`nil', it puts the mark before and point after. You can
+ pass a non-`nil' second argument BEFOREP to this function
+ interactively by supplying any prefix argument.
+
+ If the register contains a rectangle, then the rectangle is
+ inserted with its upper left corner at point. This means that
+ text is inserted in the current line and underneath it on
+ successive lines.
+
+ If the register contains something other than saved text (a
+ string) or a rectangle (a list), currently useless things happen.
+ This may be changed in the future.
+
+\1f
+File: lispref.info, Node: Transposition, Next: Change Hooks, Prev: Registers, Up: Text
+
+Transposition of Text
+=====================
+
+ This subroutine is used by the transposition commands.
+
+ - Function: transpose-regions START1 END1 START2 END2 &optional
+ LEAVE-MARKERS
+ This function exchanges two nonoverlapping portions of the buffer.
+ Arguments START1 and END1 specify the bounds of one portion and
+ arguments START2 and END2 specify the bounds of the other portion.
+
+ Normally, `transpose-regions' relocates markers with the transposed
+ text; a marker previously positioned within one of the two
+ transposed portions moves along with that portion, thus remaining
+ between the same two characters in their new position. However,
+ if LEAVE-MARKERS is non-`nil', `transpose-regions' does not do
+ this--it leaves all markers unrelocated.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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.
+
+\1f
+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
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 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 be achieved without the
+ use of greedy quantifier.
+
+ This construct has not been available prior to XEmacs 20.4. It is
+ not available in FSF Emacs.
+
+`+?'
+ is the `+' analog to `*?'.
+
+`\{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.
+
+`[ ... ]'
+ `[' 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. Then you can use
+ not want to remember them for later use with `match-string'.
+
+ 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-"))
+
+\1f
+File: lispref.info, Node: Regexp Example, Prev: Syntax of Regexps, Up: Regular Expressions
+
+Complex Regexp Example
+----------------------
+
+ Here is a complicated regexp, used by XEmacs to recognize the end of
+a sentence together with any whitespace that follows. It is the value
+of the variable `sentence-end'.
+
+ First, we show the regexp as a string in Lisp syntax to distinguish
+spaces from tab characters. The string constant begins and ends with a
+double-quote. `\"' stands for a double-quote as part of the string,
+`\\' for a backslash as part of the string, `\t' for a tab and `\n' for
+a newline.
+
+ "[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
+
+ In contrast, if you evaluate the variable `sentence-end', you will
+see the following:
+
+ sentence-end
+ =>
+ "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[
+ ]*"
+
+In this output, tab and newline appear as themselves.
+
+ This regular expression contains four parts in succession and can be
+deciphered as follows:
+
+`[.?!]'
+ The first part of the pattern is a character set that matches any
+ one of three characters: period, question mark, and exclamation
+ mark. The match must begin with one of these three characters.
+
+`[]\"')}]*'
+ The second part of the pattern matches any closing braces and
+ quotation marks, zero or more of them, that may follow the period,
+ question mark or exclamation mark. The `\"' is Lisp syntax for a
+ double-quote in a string. The `*' at the end indicates that the
+ immediately preceding regular expression (a character set, in this
+ case) may be repeated zero or more times.
+
+`\\($\\| $\\|\t\\| \\)'
+ The third part of the pattern matches the whitespace that follows
+ the end of a sentence: the end of a line, or a tab, or two spaces.
+ The double backslashes mark the parentheses and vertical bars as
+ regular expression syntax; the parentheses delimit a group and the
+ vertical bars separate alternatives. The dollar sign is used to
+ match the end of a line.
+
+`[ \t\n]*'
+ Finally, the last part of the pattern matches any additional
+ whitespace beyond the minimum needed to end a sentence.
+
+\1f
+File: lispref.info, Node: Regexp Search, Next: POSIX Regexps, Prev: Regular Expressions, Up: Searching and Matching
+
+Regular Expression Searching
+============================
+
+ In XEmacs, you can search for the next match for a regexp either
+incrementally or not. Incremental search commands are described in the
+`The XEmacs Reference Manual'. *Note Regular Expression Search:
+(emacs)Regexp Search. Here we describe only the search functions
+useful in programs. The principal one is `re-search-forward'.
+
+ - Command: re-search-forward REGEXP &optional LIMIT NOERROR REPEAT
+ This function searches forward in the current buffer for a string
+ of text that is matched by the regular expression REGEXP. The
+ function skips over any amount of text that is not matched by
+ REGEXP, and leaves point at the end of the first match found. It
+ returns the new value of point.
+
+ If LIMIT is non-`nil' (it must be a position in the current
+ buffer), then it is the upper bound to the search. No match
+ extending after that position is accepted.
+
+ What happens when the search fails depends on the value of
+ NOERROR. If NOERROR is `nil', a `search-failed' error is
+ signaled. If NOERROR is `t', `re-search-forward' does nothing and
+ returns `nil'. If NOERROR is neither `nil' nor `t', then
+ `re-search-forward' moves point to LIMIT (or the end of the
+ buffer) and returns `nil'.
+
+ If REPEAT is supplied (it must be a positive number), then the
+ search is repeated that many times (each time starting at the end
+ of the previous time's match). If these successive searches
+ succeed, the function succeeds, moving point and returning its new
+ value. Otherwise the search fails.
+
+ In the following example, point is initially before the `T'.
+ Evaluating the search call moves point to the end of that line
+ (between the `t' of `hat' and the newline).
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (re-search-forward "[a-z]+" nil t 5)
+ => 27
+
+ ---------- Buffer: foo ----------
+ I read "The cat in the hat-!-
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ - Command: re-search-backward REGEXP &optional LIMIT NOERROR REPEAT
+ This function searches backward in the current buffer for a string
+ of text that is matched by the regular expression REGEXP, leaving
+ point at the beginning of the first text found.
+
+ This function is analogous to `re-search-forward', but they are not
+ simple mirror images. `re-search-forward' finds the match whose
+ beginning is as close as possible to the starting point. If
+ `re-search-backward' were a perfect mirror image, it would find the
+ match whose end is as close as possible. However, in fact it
+ finds the match whose beginning is as close as possible. The
+ reason is that matching a regular expression at a given spot
+ always works from beginning to end, and starts at a specified
+ beginning position.
+
+ A true mirror-image of `re-search-forward' would require a special
+ feature for matching regexps from end to beginning. It's not
+ worth the trouble of implementing that.
+
+ - Function: string-match REGEXP STRING &optional START
+ This function returns the index of the start of the first match for
+ the regular expression REGEXP in STRING, or `nil' if there is no
+ match. If START is non-`nil', the search starts at that index in
+ STRING.
+
+ For example,
+
+ (string-match
+ "quick" "The quick brown fox jumped quickly.")
+ => 4
+ (string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+ => 27
+
+ The index of the first character of the string is 0, the index of
+ the second character is 1, and so on.
+
+ After this function returns, the index of the first character
+ beyond the match is available as `(match-end 0)'. *Note Match
+ Data::.
+
+ (string-match
+ "quick" "The quick brown fox jumped quickly." 8)
+ => 27
+
+ (match-end 0)
+ => 32
+
+ - Function: split-string STRING &optional PATTERN
+ This function splits STRING to substrings delimited by PATTERN,
+ and returns a list of substrings. If PATTERN is omitted, it
+ defaults to `[ \f\t\n\r\v]+', which means that it splits STRING by
+ white-space.
+
+ (split-string "foo bar")
+ => ("foo" "bar")
+
+ (split-string "something")
+ => ("something")
+
+ (split-string "a:b:c" ":")
+ => ("a" "b" "c")
+
+ (split-string ":a::b:c" ":")
+ => ("" "a" "" "b" "c")
+
+ - Function: split-path PATH
+ This function splits a search path into a list of strings. The
+ path components are separated with the characters specified with
+ `path-separator'. Under Unix, `path-separator' will normally be
+ `:', while under Windows, it will be `;'.
+
+ - Function: looking-at REGEXP
+ This function determines whether the text in the current buffer
+ directly following point matches the regular expression REGEXP.
+ "Directly following" means precisely that: the search is
+ "anchored" and it can succeed only starting with the first
+ character following point. The result is `t' if so, `nil'
+ otherwise.
+
+ This function does not move point, but it updates the match data,
+ which you can access using `match-beginning' and `match-end'.
+ *Note Match Data::.
+
+ In this example, point is located directly before the `T'. If it
+ were anywhere else, the result would be `nil'.
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (looking-at "The cat in the hat$")
+ => t
+
+\1f
+File: lispref.info, Node: POSIX Regexps, Next: Search and Replace, Prev: Regexp Search, Up: Searching and Matching
+
+POSIX Regular Expression Searching
+==================================
+
+ The usual regular expression functions do backtracking when necessary
+to handle the `\|' and repetition constructs, but they continue this
+only until they find *some* match. Then they succeed and report the
+first match found.
+
+ This section describes alternative search functions which perform the
+full backtracking specified by the POSIX standard for regular expression
+matching. They continue backtracking until they have tried all
+possibilities and found all matches, so they can report the longest
+match, as required by POSIX. This is much slower, so use these
+functions only when you really need the longest match.
+
+ In Emacs versions prior to 19.29, these functions did not exist, and
+the functions described above implemented full POSIX backtracking.
+
+ - Function: posix-search-forward REGEXP &optional LIMIT NOERROR REPEAT
+ This is like `re-search-forward' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+ - Function: posix-search-backward REGEXP &optional LIMIT NOERROR REPEAT
+ This is like `re-search-backward' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+ - Function: posix-looking-at REGEXP
+ This is like `looking-at' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+ - Function: posix-string-match REGEXP STRING &optional START
+ This is like `string-match' except that it performs the full
+ backtracking specified by the POSIX standard for regular expression
+ matching.
+
+\1f
+File: lispref.info, Node: Search and Replace, Next: Match Data, Prev: POSIX Regexps, Up: Searching and Matching
+
+Search and Replace
+==================
+
+ - Function: perform-replace FROM-STRING REPLACEMENTS QUERY-FLAG
+ REGEXP-FLAG DELIMITED-FLAG &optional REPEAT-COUNT MAP
+ This function is the guts of `query-replace' and related commands.
+ It searches for occurrences of FROM-STRING and replaces some or
+ all of them. If QUERY-FLAG is `nil', it replaces all occurrences;
+ otherwise, it asks the user what to do about each one.
+
+ If REGEXP-FLAG is non-`nil', then FROM-STRING is considered a
+ regular expression; otherwise, it must match literally. If
+ DELIMITED-FLAG is non-`nil', then only replacements surrounded by
+ word boundaries are considered.
+
+ The argument REPLACEMENTS specifies what to replace occurrences
+ with. If it is a string, that string is used. It can also be a
+ list of strings, to be used in cyclic order.
+
+ If REPEAT-COUNT is non-`nil', it should be an integer. Then it
+ specifies how many times to use each of the strings in the
+ REPLACEMENTS list before advancing cyclicly to the next one.
+
+ Normally, the keymap `query-replace-map' defines the possible user
+ responses for queries. The argument MAP, if non-`nil', is a
+ keymap to use instead of `query-replace-map'.
+
+ - Variable: query-replace-map
+ This variable holds a special keymap that defines the valid user
+ responses for `query-replace' and related functions, as well as
+ `y-or-n-p' and `map-y-or-n-p'. It is unusual in two ways:
+
+ * The "key bindings" are not commands, just symbols that are
+ meaningful to the functions that use this map.
+
+ * Prefix keys are not supported; each key binding must be for a
+ single event key sequence. This is because the functions
+ don't use read key sequence to get the input; instead, they
+ read a single event and look it up "by hand."
+
+ Here are the meaningful "bindings" for `query-replace-map'. Several
+of them are meaningful only for `query-replace' and friends.
+
+`act'
+ Do take the action being considered--in other words, "yes."
+
+`skip'
+ Do not take action for this question--in other words, "no."
+
+`exit'
+ Answer this question "no," and give up on the entire series of
+ questions, assuming that the answers will be "no."
+
+`act-and-exit'
+ Answer this question "yes," and give up on the entire series of
+ questions, assuming that subsequent answers will be "no."
+
+`act-and-show'
+ Answer this question "yes," but show the results--don't advance yet
+ to the next question.
+
+`automatic'
+ Answer this question and all subsequent questions in the series
+ with "yes," without further user interaction.
+
+`backup'
+ Move back to the previous place that a question was asked about.
+
+`edit'
+ Enter a recursive edit to deal with this question--instead of any
+ other action that would normally be taken.
+
+`delete-and-edit'
+ Delete the text being considered, then enter a recursive edit to
+ replace it.
+
+`recenter'
+ Redisplay and center the window, then ask the same question again.
+
+`quit'
+ Perform a quit right away. Only `y-or-n-p' and related functions
+ use this answer.
+
+`help'
+ Display some help, then ask again.
+
+\1f
+File: lispref.info, Node: Match Data, Next: Searching and Case, Prev: Search and Replace, Up: Searching and Matching
+
+The Match Data
+==============
+
+ XEmacs keeps track of the positions of the start and end of segments
+of text found during a regular expression search. This means, for
+example, that you can search for a complex pattern, such as a date in
+an Rmail message, and then extract parts of the match under control of
+the pattern.
+
+ Because the match data normally describe the most recent search only,
+you must be careful not to do another search inadvertently between the
+search you wish to refer back to and the use of the match data. If you
+can't avoid another intervening search, you must save and restore the
+match data around it, to prevent it from being overwritten.
+
+* Menu:
+
+* Simple Match Data:: Accessing single items of match data,
+ such as where a particular subexpression started.
+* Replacing Match:: Replacing a substring that was matched.
+* Entire Match Data:: Accessing the entire match data at once, as a list.
+* Saving Match Data:: Saving and restoring the match data.
+
+\1f
+File: lispref.info, Node: Simple Match Data, Next: Replacing Match, Up: Match Data
+
+Simple Match Data Access
+------------------------
+
+ This section explains how to use the match data to find out what was
+matched by the last search or match operation.
+
+ You can ask about the entire matching text, or about a particular
+parenthetical subexpression of a regular expression. The COUNT
+argument in the functions below specifies which. If COUNT is zero, you
+are asking about the entire match. If COUNT is positive, it specifies
+which subexpression you want.
+
+ Recall that the subexpressions of a regular expression are those
+expressions grouped with escaped parentheses, `\(...\)'. The COUNTth
+subexpression is found by counting occurrences of `\(' from the
+beginning of the whole regular expression. The first subexpression is
+numbered 1, the second 2, and so on. Only regular expressions can have
+subexpressions--after a simple string search, the only information
+available is about the entire match.
+
+ - Function: match-string COUNT &optional IN-STRING
+ This function returns, as a string, the text matched in the last
+ search or match operation. It returns the entire text if COUNT is
+ zero, or just the portion corresponding to the COUNTth
+ parenthetical subexpression, if COUNT is positive. If COUNT is
+ out of range, or if that subexpression didn't match anything, the
+ value is `nil'.
+
+ If the last such operation was done against a string with
+ `string-match', then you should pass the same string as the
+ argument IN-STRING. Otherwise, after a buffer search or match,
+ you should omit IN-STRING or pass `nil' for it; but you should
+ make sure that the current buffer when you call `match-string' is
+ the one in which you did the searching or matching.
+
+ - Function: match-beginning COUNT
+ This function returns the position of the start of text matched by
+ the last regular expression searched for, or a subexpression of it.
+
+ If COUNT is zero, then the value is the position of the start of
+ the entire match. Otherwise, COUNT specifies a subexpression in
+ the regular expression, and the value of the function is the
+ starting position of the match for that subexpression.
+
+ The value is `nil' for a subexpression inside a `\|' alternative
+ that wasn't used in the match.
+
+ - Function: match-end COUNT
+ This function is like `match-beginning' except that it returns the
+ position of the end of the match, rather than the position of the
+ beginning.
+
+ Here is an example of using the match data, with a comment showing
+the positions within the text:
+
+ (string-match "\\(qu\\)\\(ick\\)"
+ "The quick fox jumped quickly.")
+ ;0123456789
+ => 4
+
+ (match-string 0 "The quick fox jumped quickly.")
+ => "quick"
+ (match-string 1 "The quick fox jumped quickly.")
+ => "qu"
+ (match-string 2 "The quick fox jumped quickly.")
+ => "ick"
+
+ (match-beginning 1) ; The beginning of the match
+ => 4 ; with `qu' is at index 4.
+
+ (match-beginning 2) ; The beginning of the match
+ => 6 ; with `ick' is at index 6.
+
+ (match-end 1) ; The end of the match
+ => 6 ; with `qu' is at index 6.
+
+ (match-end 2) ; The end of the match
+ => 9 ; with `ick' is at index 9.
+
+ Here is another example. Point is initially located at the beginning
+of the line. Searching moves point to between the space and the word
+`in'. The beginning of the entire match is at the 9th character of the
+buffer (`T'), and the beginning of the match for the first
+subexpression is at the 13th character (`c').
+
+ (list
+ (re-search-forward "The \\(cat \\)")
+ (match-beginning 0)
+ (match-beginning 1))
+ => (9 9 13)
+
+ ---------- Buffer: foo ----------
+ I read "The cat -!-in the hat comes back" twice.
+ ^ ^
+ 9 13
+ ---------- Buffer: foo ----------
+
+(In this case, the index returned is a buffer position; the first
+character of the buffer counts as 1.)
+
+\1f
+File: lispref.info, Node: Replacing Match, Next: Entire Match Data, Prev: Simple Match Data, Up: Match Data
+
+Replacing the Text That Matched
+-------------------------------
+
+ This function replaces the text matched by the last search with
+REPLACEMENT.
+
+ - Function: replace-match REPLACEMENT &optional FIXEDCASE LITERAL
+ STRING
+ This function replaces the text in the buffer (or in STRING) that
+ was matched by the last search. It replaces that text with
+ REPLACEMENT.
+
+ If you did the last search in a buffer, you should specify `nil'
+ for STRING. Then `replace-match' does the replacement by editing
+ the buffer; it leaves point at the end of the replacement text,
+ and returns `t'.
+
+ If you did the search in a string, pass the same string as STRING.
+ Then `replace-match' does the replacement by constructing and
+ returning a new string.
+
+ If FIXEDCASE is non-`nil', then the case of the replacement text
+ is not changed; otherwise, the replacement text is converted to a
+ different case depending upon the capitalization of the text to be
+ replaced. If the original text is all upper case, the replacement
+ text is converted to upper case. If the first word of the
+ original text is capitalized, then the first word of the
+ replacement text is capitalized. If the original text contains
+ just one word, and that word is a capital letter, `replace-match'
+ considers this a capitalized first word rather than all upper case.
+
+ If `case-replace' is `nil', then case conversion is not done,
+ regardless of the value of FIXED-CASE. *Note Searching and Case::.
+
+ If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
+ it is, the only alterations being case changes as needed. If it
+ is `nil' (the default), then the character `\' is treated
+ specially. If a `\' appears in REPLACEMENT, then it must be part
+ of one of the following sequences:
+
+ `\&'
+ `\&' stands for the entire text being replaced.
+
+ `\N'
+ `\N', where N is a digit, stands for the text that matched
+ the Nth subexpression in the original regexp. Subexpressions
+ are those expressions grouped inside `\(...\)'.
+
+ `\\'
+ `\\' stands for a single `\' in the replacement text.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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)
+ => (#<marker at 9 in foo>
+ #<marker at 17 in foo>
+ #<marker at 13 in foo>
+ #<marker at 17 in foo>)
+
+ - 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'.
+
+\1f
+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::.).
+
+\1f
+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)'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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 `@'.
+
+\1f
+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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Parsing Expressions, Next: Standard Syntax Tables, Prev: Motion and Syntax, Up: Syntax Tables
+
+Parsing Balanced Expressions
+============================
+
+ Here are several functions for parsing and scanning balanced
+expressions, also known as "sexps", in which parentheses match in
+pairs. The syntax table controls the interpretation of characters, so
+these functions can be used for Lisp expressions when in Lisp mode and
+for C expressions when in C mode. *Note List Motion::, for convenient
+higher-level functions for moving over balanced expressions.
+
+ - Function: parse-partial-sexp START LIMIT &optional TARGET-DEPTH
+ STOP-BEFORE STATE STOP-COMMENT BUFFER
+ This function parses a sexp in the current buffer starting at
+ START, not scanning past LIMIT. It stops at position LIMIT or
+ when certain criteria described below are met, and sets point to
+ the location where parsing stops. It returns a value describing
+ the status of the parse at the point where it stops.
+
+ If STATE is `nil', START is assumed to be at the top level of
+ parenthesis structure, such as the beginning of a function
+ definition. Alternatively, you might wish to resume parsing in the
+ middle of the structure. To do this, you must provide a STATE
+ argument that describes the initial status of parsing.
+
+ If the third argument TARGET-DEPTH is non-`nil', parsing stops if
+ the depth in parentheses becomes equal to TARGET-DEPTH. The depth
+ starts at 0, or at whatever is given in STATE.
+
+ If the fourth argument STOP-BEFORE is non-`nil', parsing stops
+ when it comes to any character that starts a sexp. If
+ STOP-COMMENT is non-`nil', parsing stops when it comes to the
+ start of a comment.
+
+ The fifth argument STATE is an eight-element list of the same form
+ as the value of this function, described below. The return value
+ of one call may be used to initialize the state of the parse on
+ another call to `parse-partial-sexp'.
+
+ The result is a list of eight elements describing the final state
+ of the parse:
+
+ 0. The depth in parentheses, counting from 0.
+
+ 1. The character position of the start of the innermost
+ parenthetical grouping containing the stopping point; `nil'
+ if none.
+
+ 2. The character position of the start of the last complete
+ subexpression terminated; `nil' if none.
+
+ 3. Non-`nil' if inside a string. More precisely, this is the
+ character that will terminate the string.
+
+ 4. `t' if inside a comment (of either style).
+
+ 5. `t' if point is just after a quote character.
+
+ 6. The minimum parenthesis depth encountered during this scan.
+
+ 7. `t' if inside a comment of style "b".
+
+ Elements 0, 3, 4, 5 and 7 are significant in the argument STATE.
+
+ This function is most often used to compute indentation for
+ languages that have nested parentheses.
+
+ - Function: scan-lists FROM COUNT DEPTH &optional BUFFER NOERROR
+ This function scans forward COUNT balanced parenthetical groupings
+ from character number FROM. It returns the character position
+ where the scan stops.
+
+ If DEPTH is nonzero, parenthesis depth counting begins from that
+ value. The only candidates for stopping are places where the
+ depth in parentheses becomes zero; `scan-lists' counts COUNT such
+ places and then stops. Thus, a positive value for DEPTH means go
+ out DEPTH levels of parenthesis.
+
+ Scanning ignores comments if `parse-sexp-ignore-comments' is
+ non-`nil'.
+
+ If the scan reaches the beginning or end of the buffer (or its
+ accessible portion), and the depth is not zero, an error is
+ signaled. If the depth is zero but the count is not used up,
+ `nil' is returned.
+
+ If optional arg BUFFER is non-`nil', scanning occurs in that
+ buffer instead of in the current buffer.
+
+ If optional arg NOERROR is non-`nil', `scan-lists' will return
+ `nil' instead of signalling an error.
+
+ - Function: scan-sexps FROM COUNT &optional BUFFER NOERROR
+ This function scans forward COUNT sexps from character position
+ FROM. It returns the character position where the scan stops.
+
+ Scanning ignores comments if `parse-sexp-ignore-comments' is
+ non-`nil'.
+
+ If the scan reaches the beginning or end of (the accessible part
+ of) the buffer in the middle of a parenthetical grouping, an error
+ is signaled. If it reaches the beginning or end between groupings
+ but before count is used up, `nil' is returned.
+
+ If optional arg BUFFER is non-`nil', scanning occurs in that
+ buffer instead of in the current buffer.
+
+ If optional arg NOERROR is non-`nil', `scan-sexps' will return nil
+ instead of signalling an error.
+
+ - Variable: parse-sexp-ignore-comments
+ If the value is non-`nil', then comments are treated as whitespace
+ by the functions in this section and by `forward-sexp'.
+
+ In older Emacs versions, this feature worked only when the comment
+ terminator is something like `*/', and appears only to end a
+ comment. In languages where newlines terminate comments, it was
+ necessary make this variable `nil', since not every newline is the
+ end of a comment. This limitation no longer exists.
+
+ You can use `forward-comment' to move forward or backward over one
+comment or several comments.
+
+ - Function: forward-comment COUNT &optional BUFFER
+ This function moves point forward across COUNT comments (backward,
+ if COUNT is negative). If it finds anything other than a comment
+ or whitespace, it stops, leaving point at the place where it
+ stopped. It also stops after satisfying COUNT.
+
+ Optional argument BUFFER defaults to the current buffer.
+
+ To move forward over all comments and whitespace following point, use
+`(forward-comment (buffer-size))'. `(buffer-size)' is a good argument
+to use, because the number of comments in the buffer cannot exceed that
+many.
+
+\1f
+File: lispref.info, Node: Standard Syntax Tables, Next: Syntax Table Internals, Prev: Parsing Expressions, Up: Syntax Tables
+
+Some Standard Syntax Tables
+===========================
+
+ Most of the major modes in XEmacs have their own syntax tables. Here
+are several of them:
+
+ - Function: standard-syntax-table
+ This function returns the standard syntax table, which is the
+ syntax table used in Fundamental mode.
+
+ - Variable: text-mode-syntax-table
+ The value of this variable is the syntax table used in Text mode.
+
+ - Variable: c-mode-syntax-table
+ The value of this variable is the syntax table for C-mode buffers.
+
+ - Variable: emacs-lisp-mode-syntax-table
+ The value of this variable is the syntax table used in Emacs Lisp
+ mode by editing commands. (It has no effect on the Lisp `read'
+ function.)
+
+\1f
+File: lispref.info, Node: Syntax Table Internals, Prev: Standard Syntax Tables, Up: Syntax Tables
+
+Syntax Table Internals
+======================
+
+ Each element of a syntax table is an integer that encodes the syntax
+of one character: the syntax class, possible matching character, and
+flags. Lisp programs don't usually work with the elements directly; the
+Lisp-level syntax table functions usually work with syntax descriptors
+(*note Syntax Descriptors::.).
+
+ The low 8 bits of each element of a syntax table indicate the syntax
+class.
+
+Integer
+ Class
+
+0
+ whitespace
+
+1
+ punctuation
+
+2
+ word
+
+3
+ symbol
+
+4
+ open parenthesis
+
+5
+ close parenthesis
+
+6
+ expression prefix
+
+7
+ string quote
+
+8
+ paired delimiter
+
+9
+ escape
+
+10
+ character quote
+
+11
+ comment-start
+
+12
+ comment-end
+
+13
+ inherit
+
+ The next 8 bits are the matching opposite parenthesis (if the
+character has parenthesis syntax); otherwise, they are not meaningful.
+The next 6 bits are the flags.
+
+\1f
+File: lispref.info, Node: Abbrevs, Next: Extents, Prev: Syntax Tables, Up: Top
+
+Abbrevs And Abbrev Expansion
+****************************
+
+ An abbreviation or "abbrev" is a string of characters that may be
+expanded to a longer string. The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev. This
+saves typing.
+
+ The set of abbrevs currently in effect is recorded in an "abbrev
+table". Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table. There is also a global
+abbrev table. Normally both are used.
+
+ An abbrev table is represented as an obarray containing a symbol for
+each abbreviation. The symbol's name is the abbreviation; its value is
+the expansion; its function definition is the hook function to do the
+expansion (*note Defining Abbrevs::.); its property list cell contains
+the use count, the number of times the abbreviation has been expanded.
+Because these symbols are not interned in the usual obarray, they will
+never appear as the result of reading a Lisp expression; in fact,
+normally they are never used except by the code that handles abbrevs.
+Therefore, it is safe to use them in an extremely nonstandard way.
+*Note Creating Symbols::.
+
+ For the user-level commands for abbrevs, see *Note Abbrev Mode:
+(emacs)Abbrevs.
+
+* Menu:
+
+* Abbrev Mode:: Setting up XEmacs for abbreviation.
+* Tables: Abbrev Tables. Creating and working with abbrev tables.
+* Defining Abbrevs:: Specifying abbreviations and their expansions.
+* Files: Abbrev Files. Saving abbrevs in files.
+* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables:: Abbrev tables used by various major modes.
+
+\1f
+File: lispref.info, Node: Abbrev Mode, Next: Abbrev Tables, Up: Abbrevs
+
+Setting Up Abbrev Mode
+======================
+
+ Abbrev mode is a minor mode controlled by the value of the variable
+`abbrev-mode'.
+
+ - Variable: abbrev-mode
+ A non-`nil' value of this variable turns on the automatic expansion
+ of abbrevs when their abbreviations are inserted into a buffer.
+ If the value is `nil', abbrevs may be defined, but they are not
+ expanded automatically.
+
+ This variable automatically becomes local when set in any fashion.
+
+ - Variable: default-abbrev-mode
+ This is the value of `abbrev-mode' for buffers that do not
+ override it. This is the same as `(default-value 'abbrev-mode)'.
+
+\1f
+File: lispref.info, Node: Abbrev Tables, Next: Defining Abbrevs, Prev: Abbrev Mode, Up: Abbrevs
+
+Abbrev Tables
+=============
+
+ This section describes how to create and manipulate abbrev tables.
+
+ - Function: make-abbrev-table
+ This function creates and returns a new, empty abbrev table--an
+ obarray containing no symbols. It is a vector filled with zeros.
+
+ - Function: clear-abbrev-table TABLE
+ This function undefines all the abbrevs in abbrev table TABLE,
+ leaving it empty. The function returns `nil'.
+
+ - Function: define-abbrev-table TABNAME DEFINITIONS
+ This function defines TABNAME (a symbol) as an abbrev table name,
+ i.e., as a variable whose value is an abbrev table. It defines
+ abbrevs in the table according to DEFINITIONS, a list of elements
+ of the form `(ABBREVNAME EXPANSION HOOK USECOUNT)'. The value is
+ always `nil'.
+
+ - Variable: abbrev-table-name-list
+ This is a list of symbols whose values are abbrev tables.
+ `define-abbrev-table' adds the new abbrev table name to this list.
+
+ - Function: insert-abbrev-table-description NAME &optional HUMAN
+ This function inserts before point a description of the abbrev
+ table named NAME. The argument NAME is a symbol whose value is an
+ abbrev table. The value is always `nil'.
+
+ If HUMAN is non-`nil', the description is human-oriented.
+ Otherwise the description is a Lisp expression--a call to
+ `define-abbrev-table' that would define NAME exactly as it is
+ currently defined.
+
+\1f
+File: lispref.info, Node: Defining Abbrevs, Next: Abbrev Files, Prev: Abbrev Tables, Up: Abbrevs
+
+Defining Abbrevs
+================
+
+ These functions define an abbrev in a specified abbrev table.
+`define-abbrev' is the low-level basic function, while `add-abbrev' is
+used by commands that ask for information from the user.
+
+ - Function: add-abbrev TABLE TYPE ARG
+ This function adds an abbreviation to abbrev table TABLE based on
+ information from the user. The argument TYPE is a string
+ describing in English the kind of abbrev this will be (typically,
+ `"global"' or `"mode-specific"'); this is used in prompting the
+ user. The argument ARG is the number of words in the expansion.
+
+ The return value is the symbol that internally represents the new
+ abbrev, or `nil' if the user declines to confirm redefining an
+ existing abbrev.
+
+ - Function: define-abbrev TABLE NAME EXPANSION HOOK
+ This function defines an abbrev in TABLE named NAME, to expand to
+ EXPANSION, and call HOOK. The return value is an uninterned
+ symbol that represents the abbrev inside XEmacs; its name is NAME.
+
+ The argument NAME should be a string. The argument EXPANSION
+ should be a string, or `nil' to undefine the abbrev.
+
+ The argument HOOK is a function or `nil'. If HOOK is non-`nil',
+ then it is called with no arguments after the abbrev is replaced
+ with EXPANSION; point is located at the end of EXPANSION when HOOK
+ is called.
+
+ The use count of the abbrev is initialized to zero.
+
+ - User Option: only-global-abbrevs
+ If this variable is non-`nil', it means that the user plans to use
+ global abbrevs only. This tells the commands that define
+ mode-specific abbrevs to define global ones instead. This
+ variable does not alter the behavior of the functions in this
+ section; it is examined by their callers.
+
+\1f
+File: lispref.info, Node: Abbrev Files, Next: Abbrev Expansion, Prev: Defining Abbrevs, Up: Abbrevs
+
+Saving Abbrevs in Files
+=======================
+
+ A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents. Therefore, you can load the file
+with `load' (*note How Programs Do Loading::.). However, the function
+`quietly-read-abbrev-file' is provided as a more convenient interface.
+
+ User-level facilities such as `save-some-buffers' can save abbrevs
+in a file automatically, under the control of variables described here.
+
+ - User Option: abbrev-file-name
+ This is the default file name for reading and saving abbrevs.
+
+ - Function: quietly-read-abbrev-file FILENAME
+ This function reads abbrev definitions from a file named FILENAME,
+ previously written with `write-abbrev-file'. If FILENAME is
+ `nil', the file specified in `abbrev-file-name' is used.
+ `save-abbrevs' is set to `t' so that changes will be saved.
+
+ This function does not display any messages. It returns `nil'.
+
+ - User Option: save-abbrevs
+ A non-`nil' value for `save-abbrev' means that XEmacs should save
+ abbrevs when files are saved. `abbrev-file-name' specifies the
+ file to save the abbrevs in.
+
+ - Variable: abbrevs-changed
+ This variable is set non-`nil' by defining or altering any
+ abbrevs. This serves as a flag for various XEmacs commands to
+ offer to save your abbrevs.
+
+ - Command: write-abbrev-file FILENAME
+ Save all abbrev definitions, in all abbrev tables, in the file
+ FILENAME, in the form of a Lisp program that when loaded will
+ define the same abbrevs. This function returns `nil'.
+
+\1f
+File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs
+
+Looking Up and Expanding Abbreviations
+======================================
+
+ Abbrevs are usually expanded by commands for interactive use,
+including `self-insert-command'. This section describes the
+subroutines used in writing such functions, as well as the variables
+they use for communication.
+
+ - Function: abbrev-symbol ABBREV &optional TABLE
+ This function returns the symbol representing the abbrev named
+ ABBREV. The value returned is `nil' if that abbrev is not
+ defined. The optional second argument TABLE is the abbrev table
+ to look it up in. If TABLE is `nil', this function tries first
+ the current buffer's local abbrev table, and second the global
+ abbrev table.
+
+ - Function: abbrev-expansion ABBREV &optional TABLE
+ This function returns the string that ABBREV would expand into (as
+ defined by the abbrev tables used for the current buffer). The
+ optional argument TABLE specifies the abbrev table to use, as in
+ `abbrev-symbol'.
+
+ - Command: expand-abbrev
+ This command expands the abbrev before point, if any. If point
+ does not follow an abbrev, this command does nothing. The command
+ returns `t' if it did expansion, `nil' otherwise.
+
+ - Command: abbrev-prefix-mark &optional ARG
+ Mark current point as the beginning of an abbrev. The next call to
+ `expand-abbrev' will use the text from here to point (where it is
+ then) as the abbrev to expand, rather than using the previous word
+ as usual.
+
+ - User Option: abbrev-all-caps
+ When this is set non-`nil', an abbrev entered entirely in upper
+ case is expanded using all upper case. Otherwise, an abbrev
+ entered entirely in upper case is expanded by capitalizing each
+ word of the expansion.
+
+ - Variable: abbrev-start-location
+ This is the buffer position for `expand-abbrev' to use as the start
+ of the next abbrev to be expanded. (`nil' means use the word
+ before point instead.) `abbrev-start-location' is set to `nil'
+ each time `expand-abbrev' is called. This variable is also set by
+ `abbrev-prefix-mark'.
+
+ - Variable: abbrev-start-location-buffer
+ The value of this variable is the buffer for which
+ `abbrev-start-location' has been set. Trying to expand an abbrev
+ in any other buffer clears `abbrev-start-location'. This variable
+ is set by `abbrev-prefix-mark'.
+
+ - Variable: last-abbrev
+ This is the `abbrev-symbol' of the last abbrev expanded. This
+ information is left by `expand-abbrev' for the sake of the
+ `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-location
+ This is the location of the last abbrev expanded. This contains
+ information left by `expand-abbrev' for the sake of the
+ `unexpand-abbrev' command.
+
+ - Variable: last-abbrev-text
+ This is the exact expansion text of the last abbrev expanded,
+ after case conversion (if any). Its value is `nil' if the abbrev
+ has already been unexpanded. This contains information left by
+ `expand-abbrev' for the sake of the `unexpand-abbrev' command.
+
+ - Variable: pre-abbrev-expand-hook
+ This is a normal hook whose functions are executed, in sequence,
+ just before any expansion of an abbrev. *Note Hooks::. Since it
+ is a normal hook, the hook functions receive no arguments.
+ However, they can find the abbrev to be expanded by looking in the
+ buffer before point.
+
+ The following sample code shows a simple use of
+`pre-abbrev-expand-hook'. If the user terminates an abbrev with a
+punctuation character, the hook function asks for confirmation. Thus,
+this hook allows the user to decide whether to expand the abbrev, and
+aborts expansion if it is not confirmed.
+
+ (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
+
+ ;; This is the function invoked by `pre-abbrev-expand-hook'.
+
+ ;; If the user terminated the abbrev with a space, the function does
+ ;; nothing (that is, it returns so that the abbrev can expand). If the
+ ;; user entered some other character, this function asks whether
+ ;; expansion should continue.
+
+ ;; If the user answers the prompt with `y', the function returns
+ ;; `nil' (because of the `not' function), but that is
+ ;; acceptable; the return value has no effect on expansion.
+
+ (defun query-if-not-space ()
+ (if (/= ?\ (preceding-char))
+ (if (not (y-or-n-p "Do you want to expand this abbrev? "))
+ (error "Not expanding this abbrev"))))
+
+\1f
+File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs
+
+Standard Abbrev Tables
+======================
+
+ Here we list the variables that hold the abbrev tables for the
+preloaded major modes of XEmacs.
+
+ - Variable: global-abbrev-table
+ This is the abbrev table for mode-independent abbrevs. The abbrevs
+ defined in it apply to all buffers. Each buffer may also have a
+ local abbrev table, whose abbrev definitions take precedence over
+ those in the global table.
+
+ - Variable: local-abbrev-table
+ The value of this buffer-local variable is the (mode-specific)
+ abbreviation table of the current buffer.
+
+ - Variable: fundamental-mode-abbrev-table
+ This is the local abbrev table used in Fundamental mode; in other
+ words, it is the local abbrev table in all buffers in Fundamental
+ mode.
+
+ - Variable: text-mode-abbrev-table
+ This is the local abbrev table used in Text mode.
+
+ - Variable: c-mode-abbrev-table
+ This is the local abbrev table used in C mode.
+
+ - Variable: lisp-mode-abbrev-table
+ This is the local abbrev table used in Lisp mode and Emacs Lisp
+ mode.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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.
+
+\1f
+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 its
+deleted. Otherwise, it will simply shrink down to zero-length and sit
+it 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::.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
+
+Properties of Extents
+=====================
+
+ Each extent has a property list associating property names with
+values. Some property names have predefined meanings, and can usually
+only assume particular values. Assigning other values to such a
+property either cause the value to be converted into a legal value
+(e.g., assigning anything but `nil' to a Boolean property will cause
+the value of `t' to be assigned to the property) or will cause an
+error. Property names without predefined meanings can be assigned any
+value. An undefined property is equivalent to a property with a value
+of `nil', or with a particular default value in the case of properties
+with predefined meanings. Note that, when an extent is created, the
+`end-open' and `detachable' properties are set on it.
+
+ If an extent has a parent, all of its properties actually derive
+from that parent (or from the root ancestor if the parent in turn has a
+parent), and setting a property of the extent actually sets that
+property on the parent. *Note Extent Parents::.
+
+ - Function: extent-property EXTENT PROPERTY
+ This function returns the value of PROPERTY in EXTENT. If
+ PROPERTY is undefined, `nil' is returned.
+
+ - Function: extent-properties EXTENT
+ This function returns a list of all of EXTENT's properties that do
+ not have the value of `nil' (or the default value, for properties
+ with predefined meanings).
+
+ - Function: set-extent-property EXTENT PROPERTY VALUE
+ This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
+ predefined meaning, only certain values are allowed, and some
+ values may be converted to others before being stored.)
+
+ - Function: set-extent-properties EXTENT PLIST
+ Change some properties of EXTENT. PLIST is a property list. This
+ is useful to change many extent properties at once.
+
+ The following table lists the properties with predefined meanings,
+along with their allowable values.
+
+`detached'
+ (Boolean) Whether the extent is detached. Setting this is the
+ same as calling `detach-extent'. *Note Detached Extents::.
+
+`destroyed'
+ (Boolean) Whether the extent has been deleted. Setting this is
+ the same as calling `delete-extent'.
+
+`priority'
+ (integer) The extent's redisplay priority. Defaults to 0. *Note
+ priority: Intro to Extents. This property can also be set with
+ `set-extent-priority' and accessed with `extent-priority'.
+
+`start-open'
+ (Boolean) Whether the start position of the extent is open,
+ meaning that characters inserted at that position go outside of
+ the extent. *Note Extent Endpoints::.
+
+`start-closed'
+ (Boolean) Same as `start-open' but with the opposite sense.
+ Setting this property clears `start-open' and vice-versa.
+
+`end-open'
+ (Boolean) Whether the end position of the extent is open, meaning
+ that characters inserted at that position go outside of the
+ extent. This is `t' by default. *Note Extent Endpoints::.
+
+`end-closed'
+ (Boolean) Same as `end-open' but with the opposite sense. Setting
+ this property clears `end-open' and vice-versa.
+
+`read-only'
+ (Boolean) Whether text within this extent will be unmodifiable.
+
+`face'
+ (face, face name, list of faces or face names, or `nil') The face
+ in which to display the extent's text. This property can also be
+ set with `set-extent-face' and accessed with `extent-face'. Note
+ that if a list of faces is specified, the faces are merged
+ together, with faces earlier in the list having priority over
+ faces later in the list.
+
+`mouse-face'
+ (face, face name, list of faces or face names, or `nil') The face
+ used to display the extent when the mouse moves over it. This
+ property can also be set with `set-extent-mouse-face' and accessed
+ with `extent-mouse-face'. Note that if a list of faces is
+ specified, the faces are merged together, with faces earlier in
+ the list having priority over faces later in the list. *Note
+ Extents and Events::.
+
+`pointer'
+ (pointer glyph) The glyph used as the pointer when the mouse
+ moves over the extent. This takes precedence over the
+ `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
+ for any reason this glyph is an invalid pointer, the standard
+ glyphs will be used as fallbacks. *Note Mouse Pointer::.
+
+`detachable'
+ (Boolean) Whether this extent becomes detached when all of the
+ text it covers is deleted. This is `t' by default. *Note
+ Detached Extents::.
+
+`duplicable'
+ (Boolean) Whether this extent should be copied into strings, so
+ that kill, yank, and undo commands will restore or copy it. *Note
+ Duplicable Extents::.
+
+`unique'
+ (Boolean) Meaningful only in conjunction with `duplicable'. When
+ this is set, there may be only one instance of this extent
+ attached at a time. *Note Duplicable Extents::.
+
+`invisible'
+ (Boolean) If `t', text under this extent will not be displayed -
+ it will look as if the text is not there at all.
+
+`keymap'
+ (keymap or `nil') This keymap is consulted for mouse clicks on this
+ extent or keypresses made while `point' is within the extent.
+ *Note Extents and Events::.
+
+`copy-function'
+ This is a hook that is run when a duplicable extent is about to be
+ copied from a buffer to a string (or the kill ring). *Note
+ Duplicable Extents::.
+
+`paste-function'
+ This is a hook that is run when a duplicable extent is about to be
+ copied from a string (or the kill ring) into a buffer. *Note
+ Duplicable Extents::.
+
+`begin-glyph'
+ (glyph or `nil') This extent's begin glyph. *Note Annotations::.
+
+`end-glyph'
+ (glyph or `nil') This extent's end glyph. *Note Annotations::.
+
+`begin-glyph-layout'
+ (`text', `whitespace', `inside-margin', or `outside-margin') The
+ layout policy for this extent's begin glyph. Defaults to `text'.
+ *Note Annotations::.
+
+`end-glyph-layout'
+ (`text', `whitespace', `inside-margin', or `outside-margin') The
+ layout policy for this extent's end glyph. Defaults to `text'.
+ *Note Annotations::.
+
+`initial-redisplay-function'
+ (any funcallable object) The function to be called the first time
+ (a part of) the extent is redisplayed. It will be called with the
+ extent as its argument.
+
+ This is used by `lazy-shot' to implement lazy font-locking. The
+ functionality is still experimental, and may change without further
+ notice.
+
+ The following convenience functions are provided for accessing
+particular properties of an extent.
+
+ - Function: extent-face EXTENT
+ This function returns the `face' property of EXTENT. This might
+ also return a list of face names. Do not modify this list
+ directly! Instead, use `set-extent-face'.
+
+ Note that you can use `eq' to compare lists of faces as returned
+ by `extent-face'. In other words, if you set the face of two
+ different extents to two lists that are `equal' but not `eq', then
+ the return value of `extent-face' on the two extents will return
+ the identical list.
+
+ - Function: extent-mouse-face EXTENT
+ This function returns the `mouse-face' property of EXTENT. This
+ might also return a list of face names. Do not modify this list
+ directly! Instead, use `set-extent-mouse-face'.
+
+ Note that you can use `eq' to compare lists of faces as returned
+ by `extent-mouse-face', just like for `extent-face'.
+
+ - Function: extent-priority EXTENT
+ This function returns the `priority' property of EXTENT.
+
+ - Function: extent-keymap EXTENT
+ This function returns the `keymap' property of EXTENT.
+
+ - Function: extent-begin-glyph-layout EXTENT
+ This function returns the `begin-glyph-layout' property of EXTENT,
+ i.e. the layout policy associated with the EXTENT's begin glyph.
+
+ - Function: extent-end-glyph-layout EXTENT
+ This function returns the `end-glyph-layout' property of EXTENT,
+ i.e. the layout policy associated with the EXTENT's end glyph.
+
+ - Function: extent-begin-glyph EXTENT
+ This function returns the `begin-glyph' property of EXTENT, i.e.
+ the glyph object displayed at the beginning of EXTENT. If there
+ is none, `nil' is returned.
+
+ - Function: extent-end-glyph EXTENT
+ This function returns the `end-glyph' property of EXTENT, i.e. the
+ glyph object displayed at the end of EXTENT. If there is none,
+ `nil' is returned.
+
+ The following convenience functions are provided for setting
+particular properties of an extent.
+
+ - Function: set-extent-priority EXTENT PRI
+ This function sets the `priority' property of EXTENT to PRI.
+
+ - Function: set-extent-face EXTENT FACE
+ This function sets the `face' property of EXTENT to FACE.
+
+ - Function: set-extent-mouse-face EXTENT FACE
+ This function sets the `mouse-face' property of EXTENT to FACE.
+
+ - Function: set-extent-keymap EXTENT KEYMAP
+ This function sets the `keymap' property of EXTENT to KEYMAP.
+ KEYMAP must be either a keymap object, or `nil'.
+
+ - Function: set-extent-begin-glyph-layout EXTENT LAYOUT
+ This function sets the `begin-glyph-layout' property of EXTENT to
+ LAYOUT.
+
+ - Function: set-extent-end-glyph-layout EXTENT LAYOUT
+ This function sets the `end-glyph-layout' property of EXTENT to
+ LAYOUT.
+
+ - Function: set-extent-begin-glyph EXTENT BEGIN-GLYPH &optional LAYOUT
+ This function sets the `begin-glyph' and `glyph-layout' properties
+ of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
+ defaults to `text' if not specified.)
+
+ - Function: set-extent-end-glyph EXTENT END-GLYPH &optional LAYOUT
+ This function sets the `end-glyph' and `glyph-layout' properties
+ of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
+ to `text' if not specified.)
+
+ - Function: set-extent-initial-redisplay-function EXTENT FUNCTION
+ This function sets the `initial-redisplay-function' property of the
+ extent to FUNCTION.
+
+\1f
+File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
+
+Detached Extents
+================
+
+ A detached extent is an extent that is not attached to a buffer or
+string but can be re-inserted. Detached extents have a start position
+and end position of `nil'. Extents can be explicitly detached using
+`detach-extent'. An extent is also detached when all of its characters
+are all killed by a deletion, if its `detachable' property is set; if
+this property is not set, the extent becomes a zero-length extent.
+(Zero-length extents with the `detachable' property set behave
+specially. *Note zero-length extents: Extent Endpoints.)
+
+ - Function: detach-extent EXTENT
+ This function detaches EXTENT from its buffer or string. If
+ EXTENT has the `duplicable' property, its detachment is tracked by
+ the undo mechanism. *Note Duplicable Extents::.
+
+ - Function: extent-detached-p EXTENT
+ This function returns `nil' if EXTENT is detached, and `t'
+ otherwise.
+
+ - Function: copy-extent EXTENT &optional OBJECT
+ This function makes a copy of EXTENT. It is initially detached.
+ Optional argument OBJECT defaults to EXTENT's object (normally a
+ buffer or string, but could be `nil').
+
+ - Function: insert-extent EXTENT &optional START END NO-HOOKS OBJECT
+ This function inserts EXTENT from START to END in OBJECT (a buffer
+ or string). If EXTENT is detached from a different buffer or
+ string, or in most cases when EXTENT is already attached, the
+ extent will first be copied as if with `copy-extent'. This
+ function operates the same as if `insert' were called on a string
+ whose extent data calls for EXTENT to be inserted, except that if
+ NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
+ invoked. *Note Duplicable Extents::.
+
+\1f
+File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
+
+Extent Parents
+==============
+
+ An extent can have a parent extent set for it. If this is the case,
+the extent derives all its properties from that extent and has no
+properties of its own. The only "properties" that the extent keeps are
+the buffer or string it refers to and the start and end points. (More
+correctly, the extent's own properties are shadowed. If you later
+change the extent to have no parent, its own properties will become
+visible again.)
+
+ It is possible for an extent's parent to itself have a parent, and
+so on. Through this, a whole tree of extents can be created, all
+deriving their properties from one root extent. Note, however, that
+you cannot create an inheritance loop - this is explicitly disallowed.
+
+ Parent extents are used to implement the extents over the modeline.
+
+ - Function: set-extent-parent EXTENT PARENT
+ This function sets the parent of EXTENT to PARENT. If PARENT is
+ `nil', the extent is set to have no parent.
+
+ - Function: extent-parent EXTENT
+ This function return the parents (if any) of EXTENT, or `nil'.
+
+ - Function: extent-children EXTENT
+ This function returns a list of the children (if any) of EXTENT.
+ The children of an extent are all those extents whose parent is
+ that extent. This function does not recursively trace children of
+ children.
+
+ - Function: extent-descendants EXTENT
+ This function returns a list of all descendants of EXTENT,
+ including EXTENT. This recursively applies `extent-children' to
+ any children of EXTENT, until no more children can be found.
+
+\1f
+File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
+
+Duplicable Extents
+==================
+
+ If an extent has the `duplicable' property, it will be copied into
+strings, so that kill, yank, and undo commands will restore or copy it.
+
+ Specifically:
+
+ * When a string is created using `buffer-substring' or
+ `buffer-string', any duplicable extents in the region corresponding
+ to the string will be copied into the string (*note Buffer
+ Contents::.). When the string in inserted into a buffer using
+ `insert', `insert-before-markers', `insert-buffer' or
+ `insert-buffer-substring', the extents in the string will be copied
+ back into the buffer (*note Insertion::.). The extents in a
+ string can, of course, be retrieved explicitly using the standard
+ extent primitives over the string.
+
+ * Similarly, when text is copied or cut into the kill ring, any
+ duplicable extents will be remembered and reinserted later when
+ the text is pasted back into a buffer.
+
+ * When `concat' is called on strings, the extents in the strings are
+ copied into the resulting string.
+
+ * When `substring' is called on a string, the relevant extents are
+ copied into the resulting string.
+
+ * When a duplicable extent is detached by `detach-extent' or string
+ deletion, or inserted by `insert-extent' or string insertion, the
+ action is recorded by the undo mechanism so that it can be undone
+ later. Note that if an extent gets detached and then a later undo
+ causes the extent to get reinserted, the new extent will not be
+ `eq' to the original extent.
+
+ * Extent motion, face changes, and attachment via `make-extent' are
+ not recorded by the undo mechanism. This means that extent changes
+ which are to be undo-able must be performed by character editing,
+ or by insertion and detachment of duplicable extents.
+
+ * A duplicable extent's `copy-function' property, if non-`nil',
+ should be a function, and will be run when a duplicable extent is
+ about to be copied from a buffer to a string (or the kill ring).
+ It is called with three arguments: the extent and the buffer
+ positions within it which are being copied. If this function
+ returns `nil', then the extent will not be copied; otherwise it
+ will.
+
+ * A duplicable extent's `paste-function' property, if non-`nil',
+ should be a function, and will be run when a duplicable extent is
+ about to be copied from a string (or the kill ring) into a buffer.
+ It is called with three arguments: the original extent and the
+ buffer positions which the copied extent will occupy. (This hook
+ is run after the corresponding text has already been inserted into
+ the buffer.) Note that the extent argument may be detached when
+ this function is run. If this function returns `nil', no extent
+ will be inserted. Otherwise, there will be an extent covering the
+ range in question.
+
+ Note: if the extent to be copied is already attached to the buffer
+ and overlaps the new range, the extent will simply be extended and
+ the `paste-function' will not be called.
+
+\1f
+File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
+
+Interaction of Extents with Keyboard and Mouse Events
+=====================================================
+
+ If an extent has the `mouse-face' property set, it will be
+highlighted when the mouse passes over it. Highlighting is accomplished
+by merging the extent's face with the face or faces specified by the
+`mouse-face' property. The effect is as if a pseudo-extent with the
+`mouse-face' face were inserted after the extent in the display order
+(*note Extent Endpoints::., display order).
+
+ - Variable: mouse-highlight-priority
+ This variable holds the priority to use when merging in the
+ highlighting pseudo-extent. The default is 1000. This is
+ purposely set very high so that the highlighting pseudo-extent
+ shows up even if there are other extents with various priorities
+ at the same location.
+
+ You can also explicitly cause an extent to be highlighted. Only one
+extent at a time can be highlighted in this fashion, and any other
+highlighted extent will be de-highlighted.
+
+ - Function: highlight-extent EXTENT &optional HIGHLIGHT-P
+ This function highlights (if HIGHLIGHT-P is non-`nil') or
+ de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
+ `mouse-face' property. (Nothing happens if EXTENT does not have
+ the `mouse-face' property.)
+
+ - Function: force-highlight-extent EXTENT &optional HIGHLIGHT-P
+ This function is similar to `highlight-extent' but highlights or
+ de-highlights the extent regardless of whether it has the
+ `mouse-face' property.
+
+ If an extent has a `keymap' property, this keymap will be consulted
+for mouse clicks on the extent and keypresses made while `point' is
+within the extent. The behavior of mouse clicks and keystrokes not
+defined in the keymap is as normal for the buffer.
+
+\1f
+File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
+
+Atomic Extents
+==============
+
+ If the Lisp file `atomic-extents' is loaded, then the atomic extent
+facility is available. An "atomic extent" is an extent for which
+`point' cannot be positioned anywhere within it. This ensures that
+when selecting text, either all or none of the extent is selected.
+
+ To make an extent atomic, set its `atomic' property.
+
+\1f
+File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
+
+Specifiers
+**********
+
+ A specifier is an object used to keep track of a property whose value
+may vary depending on the particular situation (e.g. particular buffer
+displayed in a particular window) that it is used in. The value of many
+built-in properties, such as the font, foreground, background, and such
+properties of a face and variables such as `modeline-shadow-thickness'
+and `top-toolbar-height', is actually a specifier object. The
+specifier object, in turn, is "instanced" in a particular situation to
+yield the real value of the property in that situation.
+
+ - Function: specifierp OBJECT
+ This function returns non-`nil' if OBJECT is a specifier.
+
+* Menu:
+
+* Introduction to Specifiers:: Specifiers provide a clean way for
+ display and other properties to vary
+ (under user control) in a wide variety
+ of contexts.
+* Specifiers In-Depth:: Gory details about specifier innards.
+* Specifier Instancing:: Instancing means obtaining the "value" of
+ a specifier in a particular context.
+* Specifier Types:: Specifiers come in different flavors.
+* Adding Specifications:: Specifications control a specifier's "value"
+ by giving conditions under which a
+ particular value is valid.
+* Retrieving Specifications:: Querying a specifier's specifications.
+* Specifier Tag Functions:: Working with specifier tags.
+* Specifier Instancing Functions::
+ Functions to instance a specifier.
+* Specifier Example:: Making all this stuff clearer.
+* Creating Specifiers:: Creating specifiers for your own use.
+* Specifier Validation Functions::
+ Validating the components of a specifier.
+* Other Specification Functions::
+ Other ways of working with specifications.
+
+\1f
+File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
+
+Introduction to Specifiers
+==========================
+
+ Sometimes you may want the value of a property to vary depending on
+the context the property is used in. A simple example of this in XEmacs
+is buffer-local variables. For example, the variable
+`modeline-format', which controls the format of the modeline, can have
+different values depending on the particular buffer being edited. The
+variable has a default value which most modes will use, but a
+specialized package such as Calendar might change the variable so as to
+tailor the modeline to its own purposes.
+
+ Other properties (such as those that can be changed by the
+`modify-frame-parameters' function, for example the color of the text
+cursor) can have frame-local values, although it might also make sense
+for them to have buffer-local values. In other cases, you might want
+the property to vary depending on the particular window within the
+frame that applies (e.g. the top or bottom window in a split frame), the
+device type that that frame appears on (X or tty), etc. Perhaps you can
+envision some more complicated scenario where you want a particular
+value in a specified buffer, another value in all other buffers
+displayed on a particular frame, another value in all other buffers
+displayed in all other frames on any mono (two-color, e.g. black and
+white only) displays, and a default value in all other circumstances.
+
+ A "specifier" is a generalization of this, allowing a great deal of
+flexibility in controlling exactly what value a property has in which
+circumstances. It is most commonly used for display properties, such as
+an image or the foreground color of a face. As a simple example, you
+can specify that the foreground of the default face be
+
+ * blue for a particular buffer
+
+ * green for all other buffers
+
+ As a more complicated example, you could specify that the foreground
+of the default face be
+
+ * forest green for all buffers displayed in a particular Emacs
+ window, or green if the X server doesn't recognize the color
+ `forest green'
+
+ * blue for all buffers displayed in a particular frame
+
+ * red for all other buffers displayed on a color device
+
+ * white for all other buffers
+
+\1f
+File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
+
+In-Depth Overview of a Specifier
+================================
+
+ A specifier object encapsulates a set of "specifications", each of
+which says what its value should be if a particular condition applies.
+For example, one specification might be "The value should be
+darkseagreen2 on X devices" another might be "The value should be blue
+in the *Help* buffer". In specifier terminology, these conditions are
+called "locales" and the values are called "instantiators". Given a
+specifier, a logical question is "What is its value in a particular
+situation?" This involves looking through the specifications to see
+which ones apply to this particular situation, and perhaps preferring
+one over another if more than one applies. In specifier terminology, a
+"particular situation" is called a "domain", and determining its value
+in a particular domain is called "instancing". Most of the time, a
+domain is identified by a particular window. For example, if the
+redisplay engine is drawing text in the default face in a particular
+window, it retrieves the specifier for the foreground color of the
+default face and "instances" it in the domain given by that window; in
+other words, it asks the specifier, "What is your value in this
+window?".
+
+ More specifically, a specifier contains a set of "specifications",
+each of which associates a "locale" (a window object, a buffer object,
+a frame object, a device object, or the symbol `global') with an
+"inst-list", which is a list of one or more "inst-pairs". (For each
+possible locale, there can be at most one specification containing that
+locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
+zero or more symbols, or "tags") and an "instantiator" (the allowed
+form of this varies depending on the type of specifier). In a given
+specification, there may be more than one inst-pair with the same tag
+set; this is unlike for locales.
+
+ The tag set is used to restrict the sorts of devices over which the
+instantiator is valid and to uniquely identify instantiators added by a
+particular application, so that different applications can work on the
+same specifier and not interfere with each other. Each tag can have a
+"predicate" associated with it, which is a function of one argument (a
+device) that specifies whether the tag matches that particular device.
+(If a tag does not have a predicate, it matches all devices.) All tags
+in a tag set must match a device for the associated inst-pair to be
+instantiable over that device. (A null tag set is perfectly valid.)
+
+ The valid device types (normally `x', `tty', and `stream') and
+device classes (normally `color', `grayscale', and `mono') can always
+be used as tags, and match devices of the associated type or class
+(*note Consoles and Devices::.). User-defined tags may be defined,
+with an optional predicate specified. An application can create its
+own tag, use it to mark all its instantiators, and be fairly confident
+that it will not interfere with other applications that modify the same
+specifier - Functions that add a specification to a specifier usually
+only overwrite existing inst-pairs with the same tag set as was given,
+and a particular tag or tag set can be specified when removing
+instantiators.
+
+ When a specifier is instanced in a domain, both the locale and the
+tag set can be viewed as specifying necessary conditions that must
+apply in that domain for an instantiator to be considered as a possible
+result of the instancing. More specific locales always override more
+general locales (thus, there is no particular ordering of the
+specifications in a specifier); however, the tag sets are simply
+considered in the order that the inst-pairs occur in the
+specification's inst-list.
+
+ Note also that the actual object that results from the instancing
+(called an "instance object") may not be the same as the instantiator
+from which it was derived. For some specifier types (such as integer
+specifiers and boolean specifiers), the instantiator will be returned
+directly as the instance object. For other types, however, this is not
+the case. For example, for font specifiers, the instantiator is a
+font-description string and the instance object is a font-instance
+object, which describes how the font is displayed on a particular
+device. A font-instance object encapsulates such things as the actual
+font name used to display the font on that device (a font-description
+string under X is usually a wildcard specification that may resolve to
+different font names, with possibly different foundries, widths, etc.,
+on different devices), the extra properties of that font on that
+device, etc. Furthermore, this conversion (called "instantiation")
+might fail - a font or color might not exist on a particular device,
+for example.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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.
+
+\1f
+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.
+
+\1f
+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'.
+
+\1f
+File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
+
+Retrieving the Specifications from a Specifier
+==============================================
+
+ - Function: specifier-spec-list SPECIFIER &optional LOCALE TAG-SET
+ EXACT-P
+ This function returns the spec-list of specifications for
+ SPECIFIER in LOCALE.
+
+ If LOCALE is a particular locale (a window, buffer, frame, device,
+ or the symbol `global'), a spec-list consisting of the
+ specification for that locale will be returned.
+
+ If LOCALE is a locale type (i.e. a symbol `window', `buffer',
+ `frame', or `device'), a spec-list of the specifications for all
+ locales of that type will be returned.
+
+ If LOCALE is `nil' or the symbol `all', a spec-list of all
+ specifications in SPECIFIER will be returned.
+
+ LOCALE can also be a list of locales, locale types, and/or `all';
+ the result is as if `specifier-spec-list' were called on each
+ element of the list and the results concatenated together.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ returned. (The default value of` nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be returned.
+
+ - Function: specifier-specs SPECIFIER &optional LOCALE TAG-SET EXACT-P
+ This function returns the specification(s) for SPECIFIER in LOCALE.
+
+ If LOCALE is a single locale or is a list of one element
+ containing a single locale, then a "short form" of the
+ instantiators for that locale will be returned. Otherwise, this
+ function is identical to `specifier-spec-list'.
+
+ The "short form" is designed for readability and not for ease of
+ use in Lisp programs, and is as follows:
+
+ 1. If there is only one instantiator, then an inst-pair (i.e.
+ cons of tag and instantiator) will be returned; otherwise a
+ list of inst-pairs will be returned.
+
+ 2. For each inst-pair returned, if the instantiator's tag is
+ `any', the tag will be removed and the instantiator itself
+ will be returned instead of the inst-pair.
+
+ 3. If there is only one instantiator, its value is `nil', and
+ its tag is `any', a one-element list containing `nil' will be
+ returned rather than just `nil', to distinguish this case
+ from there being no instantiators at all.
+
+
+ - Function: specifier-fallback SPECIFIER
+ This function returns the fallback value for SPECIFIER. Fallback
+ values are provided by the C code for certain built-in specifiers
+ to make sure that instancing won't fail even if all specs are
+ removed from the specifier, or to implement simple inheritance
+ behavior (e.g. this method is used to ensure that faces other than
+ `default' inherit their attributes from `default'). By design,
+ you cannot change the fallback value, and specifiers created with
+ `make-specifier' will never have a fallback (although a similar,
+ Lisp-accessible capability may be provided in the future to allow
+ for inheritance).
+
+ The fallback value will be an inst-list that is instanced like any
+ other inst-list, a specifier of the same type as SPECIFIER
+ (results in inheritance), or `nil' for no fallback.
+
+ When you instance a specifier, you can explicitly request that the
+ fallback not be consulted. (The C code does this, for example, when
+ merging faces.) See `specifier-instance'.
+
+\1f
+File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
+
+Working With Specifier Tags
+===========================
+
+ A specifier tag set is an entity that is attached to an instantiator
+and can be used to restrict the scope of that instantiator to a
+particular device class or device type and/or to mark instantiators
+added by a particular package so that they can be later removed.
+
+ A specifier tag set consists of a list of zero of more specifier
+tags, each of which is a symbol that is recognized by XEmacs as a tag.
+(The valid device types and device classes are always tags, as are any
+tags defined by `define-specifier-tag'.) It is called a "tag set" (as
+opposed to a list) because the order of the tags or the number of times
+a particular tag occurs does not matter.
+
+ Each tag has a predicate associated with it, which specifies whether
+that tag applies to a particular device. The tags which are device
+types and classes match devices of that type or class. User-defined
+tags can have any predicate, or none (meaning that all devices match).
+When attempting to instance a specifier, a particular instantiator is
+only considered if the device of the domain being instanced over matches
+all tags in the tag set attached to that instantiator.
+
+ Most of the time, a tag set is not specified, and the instantiator
+gets a null tag set, which matches all devices.
+
+ - Function: valid-specifier-tag-p TAG
+ This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-specifier-tag-set-p TAG-SET
+ This function returns non-`nil' if TAG-SET is a valid specifier
+ tag set.
+
+ - Function: canonicalize-tag-set TAG-SET
+ This function canonicalizes the given tag set. Two canonicalized
+ tag sets can be compared with `equal' to see if they represent the
+ same tag set. (Specifically, canonicalizing involves sorting by
+ symbol name and removing duplicates.)
+
+ - Function: device-matches-specifier-tag-set-p DEVICE TAG-SET
+ This function returns non-`nil' if DEVICE matches specifier tag
+ set TAG-SET. This means that DEVICE matches each tag in the tag
+ set.
+
+ - Function: define-specifier-tag TAG &optional PREDICATE
+ This function defines a new specifier tag. If PREDICATE is
+ specified, it should be a function of one argument (a device) that
+ specifies whether the tag matches that particular device. If
+ PREDICATE is omitted, the tag matches all devices.
+
+ You can redefine an existing user-defined specifier tag. However,
+ you cannot redefine the built-in specifier tags (the device types
+ and classes) or the symbols `nil', `t', `all', or `global'.
+
+ - Function: device-matching-specifier-tag-list &optional DEVICE
+ This function returns a list of all specifier tags matching
+ DEVICE. DEVICE defaults to the selected device if omitted.
+
+ - Function: specifier-tag-list
+ This function returns a list of all currently-defined specifier
+ tags. This includes the built-in ones (the device types and
+ classes).
+
+ - Function: specifier-tag-predicate TAG
+ This function returns the predicate for the given specifier tag.
+
+\1f
+File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
+
+Functions for Instancing a Specifier
+====================================
+
+ - Function: specifier-instance SPECIFIER &optional DOMAIN DEFAULT
+ NO-FALLBACK
+ This function instantiates SPECIFIER (return its value) in DOMAIN.
+ If no instance can be generated for this domain, return DEFAULT.
+
+ DOMAIN should be a window, frame, or device. Other values that
+ are legal as a locale (e.g. a buffer) are not valid as a domain
+ because they do not provide enough information to identify a
+ particular device (see `valid-specifier-domain-p'). DOMAIN
+ defaults to the selected window if omitted.
+
+ "Instantiating" a specifier in a particular domain means
+ determining the specifier's "value" in that domain. This is
+ accomplished by searching through the specifications in the
+ specifier that correspond to all locales that can be derived from
+ the given domain, from specific to general. In most cases, the
+ domain is an Emacs window. In that case specifications are
+ searched for as follows:
+
+ 1. A specification whose locale is the window itself;
+
+ 2. A specification whose locale is the window's buffer;
+
+ 3. A specification whose locale is the window's frame;
+
+ 4. A specification whose locale is the window's frame's device;
+
+ 5. A specification whose locale is the symbol `global'.
+
+ If all of those fail, then the C-code-provided fallback value for
+ this specifier is consulted (see `specifier-fallback'). If it is
+ an inst-list, then this function attempts to instantiate that list
+ just as when a specification is located in the first five steps
+ above. If the fallback is a specifier, `specifier-instance' is
+ called recursively on this specifier and the return value used.
+ Note, however, that if the optional argument NO-FALLBACK is
+ non-`nil', the fallback value will not be consulted.
+
+ Note that there may be more than one specification matching a
+ particular locale; all such specifications are considered before
+ looking for any specifications for more general locales. Any
+ particular specification that is found may be rejected because it
+ is tagged to a particular device class (e.g. `color') or device
+ type (e.g. `x') or both and the device for the given domain does
+ not match this, or because the specification is not valid for the
+ device of the given domain (e.g. the font or color name does not
+ exist for this particular X server).
+
+ The returned value is dependent on the type of specifier. For
+ example, for a font specifier (as returned by the `face-font'
+ function), the returned value will be a font-instance object. For
+ images, the returned value will be a string, pixmap, or subwindow.
+
+ - Function: specifier-instance-from-inst-list SPECIFIER DOMAIN
+ INST-LIST &optional DEFAULT
+ This function attempts to convert a particular inst-list into an
+ instance. This attempts to instantiate INST-LIST in the given
+ DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
+ If the instantiation fails, DEFAULT is returned. In most
+ circumstances, you should not use this function; use
+ `specifier-instance' instead.
+
+\1f
+File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
+
+Example of Specifier Usage
+==========================
+
+ Now let us present an example to clarify the theoretical discussions
+we have been through. In this example, we will use the general
+specifier functions for clarity. Keep in mind that many types of
+specifiers, and some other types of objects that are associated with
+specifiers (e.g. faces), provide convenience functions making it easier
+to work with objects of that type.
+
+ Let us consider the background color of the default face. A
+specifier is used to specify how that color will appear in different
+domains. First, let's retrieve the specifier:
+
+ (setq sp (face-property 'default 'background))
+ => #<color-specifier 0x3da>
+
+ (specifier-specs sp)
+ => ((#<buffer "device.c"> (nil . "forest green"))
+ (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
+ (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
+ (nil . "moccasin"))
+ (#<x-frame "VM" 0x4ac> (nil . "magenta"))
+ (global ((tty) . "cyan") (nil . "white"))
+ )
+
+ Then, say we want to determine what the background color of the
+default face is for the window currently displaying the buffer
+`*scratch*'. We call
+
+ (get-buffer-window "*scratch*")
+ => #<window on "*scratch*" 0x4ad>
+ (window-frame (get-buffer-window "*scratch*"))
+ => #<x-frame "emacs" 0x4ac>
+ (specifier-instance sp (get-buffer-window "*scratch*"))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
+
+ Note that we passed a window to `specifier-instance', not a buffer.
+We cannot pass a buffer because a buffer by itself does not provide
+enough information. The buffer might not be displayed anywhere at all,
+or could be displayed in many different frames on different devices.
+
+ The result is arrived at like this:
+
+ 1. First, we look for a specification matching the buffer displayed
+ in the window, i.e. `*scratch'. There are none, so we proceed.
+
+ 2. Then, we look for a specification matching the window itself.
+ Again, there are none.
+
+ 3. Then, we look for a specification matching the window's frame. The
+ specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
+ found. We call the instantiation method for colors, passing it the
+ locale we were searching over (i.e. the window, in this case) and
+ the instantiator (`"puke orange"'). However, the particular device
+ which this window is on (let's say it's an X connection) doesn't
+ recognize the color `"puke orange"', so the specification is
+ rejected.
+
+ 4. So we continue looking for a specification matching the window's
+ frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
+ we call the instantiation method for colors. This time, the X
+ server our window is on recognizes the color `moccasin', and so the
+ instantiation method succeeds and returns a color instance.
+
+\1f
+File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
+
+Creating New Specifier Objects
+==============================
+
+ - Function: make-specifier TYPE
+ This function creates a new specifier.
+
+ A specifier is an object that can be used to keep track of a
+ property whose value can be per-buffer, per-window, per-frame, or
+ per-device, and can further be restricted to a particular
+ device-type or device-class. Specifiers are used, for example,
+ for the various built-in properties of a face; this allows a face
+ to have different values in different frames, buffers, etc. For
+ more information, see `specifier-instance', `specifier-specs', and
+ `add-spec-to-specifier'; or, for a detailed description of
+ specifiers, including how they are instantiated over a particular
+ domain (i.e. how their value in that domain is determined), see
+ the chapter on specifiers in the XEmacs Lisp Reference Manual.
+
+ TYPE specifies the particular type of specifier, and should be one
+ of the symbols `generic', `integer', `natnum', `boolean', `color',
+ `font', `image', `face-boolean', or `toolbar'.
+
+ For more information on particular types of specifiers, see the
+ functions `generic-specifier-p', `integer-specifier-p',
+ `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p',
+ `font-specifier-p', `image-specifier-p',
+ `face-boolean-specifier-p', and `toolbar-specifier-p'.
+
+ - Function: make-specifier-and-init TYPE SPEC-LIST &optional
+ DONT-CANONICALIZE
+ This function creates and initialize a new specifier.
+
+ This is a front-end onto `make-specifier' that allows you to create
+ a specifier and add specs to it at the same time. TYPE specifies
+ the specifier type. SPEC-LIST supplies the specification(s) to be
+ added to the specifier. Normally, almost any reasonable
+ abbreviation of the full spec-list form is accepted, and is
+ converted to the full form; however, if optional argument
+ DONT-CANONICALIZE is non-`nil', this conversion is not performed,
+ and the SPEC-LIST must already be in full form. See
+ `canonicalize-spec-list'.
+
+\1f
+File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
+
+Functions for Checking the Validity of Specifier Components
+===========================================================
+
+ - Function: valid-specifier-domain-p DOMAIN
+ This function returns non-`nil' if DOMAIN is a valid specifier
+ domain. A domain is used to instance a specifier (i.e. determine
+ the specifier's value in that domain). Valid domains are a
+ window, frame, or device. (`nil' is not valid.)
+
+ - Function: valid-specifier-locale-p LOCALE
+ This function returns non-`nil' if LOCALE is a valid specifier
+ locale. Valid locales are a device, a frame, a window, a buffer,
+ and `global'. (`nil' is not valid.)
+
+ - Function: valid-specifier-locale-type-p LOCALE-TYPE
+ Given a specifier LOCALE-TYPE, this function returns non-nil if it
+ is valid. Valid locale types are the symbols `global', `device',
+ `frame', `window', and `buffer'. (Note, however, that in functions
+ that accept either a locale or a locale type, `global' is
+ considered an individual locale.)
+
+ - Function: valid-specifier-type-p SPECIFIER-TYPE
+ Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
+ valid. Valid types are `generic', `integer', `boolean', `color',
+ `font', `image', `face-boolean', and `toolbar'.
+
+ - Function: valid-specifier-tag-p TAG
+ This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-instantiator-p INSTANTIATOR SPECIFIER-TYPE
+ This function returns non-`nil' if INSTANTIATOR is valid for
+ SPECIFIER-TYPE.
+
+ - Function: valid-inst-list-p INST-LIST TYPE
+ This function returns non-`nil' if INST-LIST is valid for
+ specifier type TYPE.
+
+ - Function: valid-spec-list-p SPEC-LIST TYPE
+ This function returns non-`nil' if SPEC-LIST is valid for
+ specifier type TYPE.
+
+ - Function: check-valid-instantiator INSTANTIATOR SPECIFIER-TYPE
+ This function signals an error if INSTANTIATOR is invalid for
+ SPECIFIER-TYPE.
+
+ - Function: check-valid-inst-list INST-LIST TYPE
+ This function signals an error if INST-LIST is invalid for
+ specifier type TYPE.
+
+ - Function: check-valid-spec-list SPEC-LIST TYPE
+ This function signals an error if SPEC-LIST is invalid for
+ specifier type TYPE.
+
+\1f
+File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
+
+Other Functions for Working with Specifications in a Specifier
+==============================================================
+
+ - Function: copy-specifier SPECIFIER &optional DEST LOCALE TAG-SET
+ EXACT-P HOW-TO-ADD
+ This function copies SPECIFIER to DEST, or creates a new one if
+ DEST is `nil'.
+
+ If DEST is `nil' or omitted, a new specifier will be created and
+ the specifications copied into it. Otherwise, the specifications
+ will be copied into the existing specifier in DEST.
+
+ If LOCALE is `nil' or the symbol `all', all specifications will be
+ copied. If LOCALE is a particular locale, the specification for
+ that particular locale will be copied. If LOCALE is a locale
+ type, the specifications for all locales of that type will be
+ copied. LOCALE can also be a list of locales, locale types,
+ and/or `all'; this is equivalent to calling `copy-specifier' for
+ each of the elements of the list. See `specifier-spec-list' for
+ more information about LOCALE.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ copied. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be copied.
+
+ Optional argument HOW-TO-ADD specifies what to do with existing
+ specifications in DEST. If nil, then whichever locales or locale
+ types are copied will first be completely erased in DEST.
+ Otherwise, it is the same as in `add-spec-to-specifier'.
+
+ - Function: remove-specifier SPECIFIER &optional LOCALE TAG-SET EXACT-P
+ This function removes specification(s) for SPECIFIER.
+
+ If LOCALE is a particular locale (a buffer, window, frame, device,
+ or the symbol `global'), the specification for that locale will be
+ removed.
+
+ If instead, LOCALE is a locale type (i.e. a symbol `buffer',
+ `window', `frame', or `device'), the specifications for all
+ locales of that type will be removed.
+
+ If LOCALE is `nil' or the symbol `all', all specifications will be
+ removed.
+
+ LOCALE can also be a list of locales, locale types, and/or `all';
+ this is equivalent to calling `remove-specifier' for each of the
+ elements in the list.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ removed. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be removed.
+
+ - Function: map-specifier SPECIFIER FUNC &optional LOCALE MAPARG
+ This function applies FUNC to the specification(s) for LOCALE in
+ SPECIFIER.
+
+ If LOCALE is a locale, FUNC will be called for that locale. If
+ LOCALE is a locale type, FUNC will be mapped over all locales of
+ that type. If LOCALE is `nil' or the symbol `all', FUNC will be
+ mapped over all locales in SPECIFIER.
+
+ FUNC is called with four arguments: the SPECIFIER, the locale
+ being mapped over, the inst-list for that locale, and the optional
+ MAPARG. If any invocation of FUNC returns non-`nil', the mapping
+ will stop and the returned value becomes the value returned from
+ `map-specifier'. Otherwise, `map-specifier' returns `nil'.
+
+ - Function: specifier-locale-type-from-locale LOCALE
+ Given a specifier LOCALE, this function returns its type.
+
+\1f
+File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
+
+Faces and Window-System Objects
+*******************************
+
+* Menu:
+
+* Faces:: Controlling the way text looks.
+* Fonts:: Controlling the typeface of text.
+* Colors:: Controlling the color of text and pixmaps.
+
+\1f
+File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
+
+Faces
+=====
+
+ A "face" is a named collection of graphical properties: font,
+foreground color, background color, background pixmap, optional
+underlining, and (on TTY devices) whether the text is to be highlighted,
+dimmed, blinking, or displayed in reverse video. Faces control the
+display of text on the screen. Every face has a name, which is a symbol
+such as `default' or `modeline'.
+
+ Each built-in property of a face is controlled using a specifier,
+which allows it to have separate values in particular buffers, frames,
+windows, and devices and to further vary according to device type (X or
+TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
+for more information.
+
+ The face named `default' is used for ordinary text. The face named
+`modeline' is used for displaying the modeline. The face named
+`highlight' is used for highlighted extents (*note Extents::.). The
+faces named `left-margin' and `right-margin' are used for the left and
+right margin areas, respectively (*note Annotations::.). The face
+named `zmacs-region' is used for the highlighted region between point
+and mark.
+
+* Menu:
+
+* Merging Faces:: How XEmacs decides which face to use
+ for a character.
+* Basic Face Functions:: How to define and examine faces.
+* Face Properties:: How to access and modify a face's properties.
+* Face Convenience Functions:: Convenience functions for accessing
+ particular properties of a face.
+* Other Face Display Functions:: Other functions pertaining to how a
+ a face appears.
+
+\1f
+File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
+
+Merging Faces for Display
+-------------------------
+
+ Here are all the ways to specify which face to use for display of
+text:
+
+ * With defaults. Each frame has a "default face", which is used for
+ all text that doesn't somehow specify another face. The face named
+ `default' applies to the text area, while the faces `left-margin'
+ and `right-margin' apply to the left and right margin areas.
+
+ * With text properties. A character may have a `face' property; if
+ so, it's displayed with that face. (Text properties are actually
+ implemented in terms of extents.) *Note Text Properties::.
+
+ * With extents. An extent may have a `face' property, which applies
+ to all the text covered by the extent; in addition, if the
+ `highlight' property is set, the `highlight' property applies when
+ the mouse moves over the extent or if the extent is explicitly
+ highlighted. *Note Extents::.
+
+ * With annotations. Annotations that are inserted into a buffer can
+ specify their own face. (Annotations are actually implemented in
+ terms of extents.) *Note Annotations::.
+
+ If these various sources together specify more than one face for a
+particular character, XEmacs merges the properties of the various faces
+specified. Extents, text properties, and annotations all use the same
+underlying representation (as extents). When multiple extents cover one
+character, an extent with higher priority overrides those with lower
+priority. *Note Extents::. If no extent covers a particular character,
+the `default' face is used.
+
+ If a background pixmap is specified, it determines what will be
+displayed in the background of text characters. If the background
+pixmap is actually a pixmap, with its colors specified, those colors are
+used; if it is a bitmap, the face's foreground and background colors are
+used to color it.
+
+\1f
+File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
+
+Basic Functions for Working with Faces
+--------------------------------------
+
+ The properties a face can specify include the font, the foreground
+color, the background color, the background pixmap, the underlining,
+the display table, and (for TTY devices) whether the text is to be
+highlighted, dimmed, blinking, or displayed in reverse video. The face
+can also leave these unspecified, causing them to assume the value of
+the corresponding property of the `default' face.
+
+ Here are the basic primitives for working with faces.
+
+ - Function: make-face NAME &optional DOC-STRING TEMPORARY
+ This function defines and returns a new face named NAME, initially
+ with all properties unspecified. It does nothing if there is
+ already a face named NAME. Optional argument DOC-STRING specifies
+ an explanatory string used for descriptive purposes. If optional
+ argument TEMPORARY is non-`nil', the face will automatically
+ disappear when there are no more references to it anywhere in text
+ or Lisp code (otherwise, the face will continue to exist
+ indefinitely even if it is not used).
+
+ - Function: face-list &optional TEMPORARY
+ This function returns a list of the names of all defined faces. If
+ TEMPORARY is `nil', only the permanent faces are included. If it
+ is `t', only the temporary faces are included. If it is any other
+ non-`nil' value both permanent and temporary are included.
+
+ - Function: facep OBJECT
+ This function returns whether the given object is a face.
+
+ - Function: copy-face OLD-FACE NEW-NAME &optional LOCALE HOW-TO-ADD
+ This function defines a new face named NEW-NAME which is a copy of
+ the existing face named OLD-FACE. If there is already a face
+ named NEW-NAME, then it alters the face to have the same
+ properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
+ parts of the old face rather than the whole face, and are as in
+ `copy-specifier' (*note Specifiers::.).
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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: 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::.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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
+ This function returns the properties (an alist or `nil') of
+ FONT-INSTANCE.
+
+ - Function: x-make-font-bold FONT &optional DEVICE
+ Given an X font specification, this attempts to make a "bold" font.
+ If it fails, it returns `nil'.
+
+ - Function: x-make-font-unbold FONT &optional DEVICE
+ Given an X font specification, this attempts to make a non-bold
+ font. If it fails, it returns `nil'.
+
+ - Function: x-make-font-italic FONT &optional DEVICE
+ Given an X font specification, this attempts to make an "italic"
+ font. If it fails, it returns `nil'.
+
+ - Function: x-make-font-unitalic FONT &optional DEVICE
+ Given an X font specification, this attempts to make a non-italic
+ font. If it fails, it returns `nil'.
+
+ - Function: x-make-font-bold-italic FONT &optional DEVICE
+ Given an X font specification, this attempts to make a
+ "bold-italic" font. If it fails, it returns `nil'.
+
+\1f
+File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
+
+Font Convenience Functions
+--------------------------
+
+ - Function: font-name FONT &optional DOMAIN
+ This function returns the name of the FONT in the specified
+ DOMAIN, if any. FONT should be a font specifier object and DOMAIN
+ is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-name' to the result.
+
+ - Function: font-truename FONT &optional DOMAIN
+ This function returns the truename of the FONT in the specified
+ DOMAIN, if any. FONT should be a font specifier object and DOMAIN
+ is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-truename' to the result.
+
+ - Function: font-properties FONT &optional DOMAIN
+ This function returns the properties of the FONT in the specified
+ DOMAIN, if any. FONT should be a font specifier object and DOMAIN
+ is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-properties' to the result.
+
+\1f
+File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
+
+Colors
+======
+
+* Menu:
+
+* Color Specifiers:: Specifying how a color will appear.
+* Color Instances:: What a color specifier gets instanced as.
+* Color Instance Properties:: Properties of color instances.
+* Color Convenience Functions:: Convenience functions that automatically
+ instance and retrieve the properties
+ of a color specifier.
+
+\1f
+File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
+
+Color Specifiers
+----------------
+
+ - Function: color-specifier-p OBJECT
+ This function returns non-`nil' if OBJECT is a color specifier.
+
+\1f
+File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
+
+Color Instances
+---------------
+
+ A "color-instance object" is an object describing the way a color
+specifier is instanced in a particular domain. Functions such as
+`face-background-instance' return a color-instance object. For example,
+
+ (face-background-instance 'default (next-window))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+
+ The color-instance object returned describes the way the background
+color of the `default' face is displayed in the next window after the
+selected one.
+
+ - Function: color-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is a color-instance.
+
+\1f
+File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
+
+Color Instance Properties
+-------------------------
+
+ - Function: color-instance-name COLOR-INSTANCE
+ This function returns the name used to allocate COLOR-INSTANCE.
+
+ - Function: color-instance-rgb-components COLOR-INSTANCE
+ This function returns a three element list containing the red,
+ green, and blue color components of COLOR-INSTANCE.
+
+ (color-instance-rgb-components
+ (face-background-instance 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
+
+Color Convenience Functions
+---------------------------
+
+ - Function: color-name COLOR &optional DOMAIN
+ This function returns the name of the COLOR in the specified
+ DOMAIN, if any. COLOR should be a color specifier object and
+ DOMAIN is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `color-instance-name' to the result.
+
+ - Function: color-rgb-components COLOR &optional DOMAIN
+ This function returns the RGB components of the COLOR in the
+ specified DOMAIN, if any. COLOR should be a color specifier
+ object and DOMAIN is normally a window and defaults to the
+ selected window if omitted. This is equivalent to using
+ `specifier-instance' and applying `color-instance-rgb-components'
+ to the result.
+
+ (color-rgb-components (face-background 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
+
+Glyphs
+******
+
+ A "glyph" is an object that is used for pixmaps and images of all
+sorts, as well as for things that "act" like pixmaps, such as
+non-textual strings ("annotations") displayed in a buffer or in the
+margins. It is used in begin-glyphs and end-glyphs attached to extents,
+marginal and textual annotations, overlay arrows (`overlay-arrow-*'
+variables), toolbar buttons, mouse pointers, frame icons, truncation and
+continuation markers, and the like. (Basically, any place there is an
+image or something that acts like an image, there will be a glyph object
+representing it.)
+
+ The actual image that is displayed (as opposed to its position or
+clipping) is defined by an "image specifier" object contained within
+the glyph. The separation between an image specifier object and a
+glyph object is made because the glyph includes other properties than
+just the actual image: e.g. the face it is displayed in (for text
+images), the alignment of the image (when it is in a buffer), etc.
+
+ - Function: glyphp OBJECT
+ This function returns `t' if OBJECT is a glyph.
+
+* Menu:
+
+* Glyph Functions:: Functions for working with glyphs.
+* Images:: Graphical images displayed in a frame.
+* Glyph Types:: Each glyph has a particular type.
+* Mouse Pointer:: Controlling the mouse pointer.
+* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+* Subwindows:: Inserting an externally-controlled subwindow
+ into a buffer.
+
+\1f
+File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
+
+Glyph Functions
+===============
+
+* Menu:
+
+* Creating Glyphs:: Creating new glyphs.
+* Glyph Properties:: Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions::
+ Convenience functions for accessing particular
+ properties of a glyph.
+* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+
+\1f
+File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
+
+Creating Glyphs
+---------------
+
+ - Function: make-glyph &optional SPEC-LIST TYPE
+ This function creates a new glyph object of type TYPE.
+
+ SPEC-LIST is used to initialize the glyph's image. It is
+ typically an image instantiator (a string or a vector; *Note Image
+ Specifiers::), but can also be a list of such instantiators (each
+ one in turn is tried until an image is successfully produced), a
+ cons of a locale (frame, buffer, etc.) and an instantiator, a list
+ of such conses, or any other form accepted by
+ `canonicalize-spec-list'. *Note Specifiers::, for more
+ information about specifiers.
+
+ TYPE specifies the type of the glyph, which specifies in which
+ contexts the glyph can be used, and controls the allowable image
+ types into which the glyph's image can be instantiated. TYPE
+ should be one of `buffer' (used for glyphs in an extent, the
+ modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
+ for the mouse-pointer), or `icon' (used for a frame's icon), and
+ defaults to `buffer'. *Note Glyph Types::.
+
+ - Function: make-glyph-internal &optional TYPE
+ This function creates a new, uninitialized glyph of type TYPE.
+
+ - Function: make-pointer-glyph &optional SPEC-LIST
+ This function is equivalent to calling `make-glyph' with a TYPE of
+ `pointer'.
+
+ - Function: make-icon-glyph &optional SPEC-LIST
+ This function is equivalent to calling `make-glyph' with a TYPE of
+ `icon'.
+
+\1f
+File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
+
+Glyph Properties
+----------------
+
+ Each glyph has a list of properties, which control all of the
+aspects of the glyph's appearance. The following symbols have
+predefined meanings:
+
+`image'
+ The image used to display the glyph.
+
+`baseline'
+ Percent above baseline that glyph is to be displayed. Only for
+ glyphs displayed inside of a buffer.
+
+`contrib-p'
+ Whether the glyph contributes to the height of the line it's on.
+ Only for glyphs displayed inside of a buffer.
+
+`face'
+ Face of this glyph (*not* a specifier).
+
+ - Function: set-glyph-property GLYPH PROPERTY VALUE &optional LOCALE
+ TAG-SET HOW-TO-ADD
+ This function changes a property of a GLYPH.
+
+ For built-in properties, the actual value of the property is a
+ specifier and you cannot change this; but you can change the
+ specifications within the specifier, and that is what this
+ function will do. For user-defined properties, you can use this
+ function to either change the actual value of the property or, if
+ this value is a specifier, change the specifications within it.
+
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
+
+ * If VALUE is a simple instantiator (e.g. a string naming a
+ pixmap filename) or a list of instantiators, then the
+ instantiator(s) will be added as a specification of the
+ property for the given LOCALE (which defaults to `global' if
+ omitted).
+
+ * If VALUE is a list of specifications (each of which is a cons
+ of a locale and a list of instantiators), then LOCALE must be
+ `nil' (it does not make sense to explicitly specify a locale
+ in this case), and specifications will be added as given.
+
+ * If VALUE is a specifier (as would be returned by
+ `glyph-property' if no LOCALE argument is given), then some
+ or all of the specifications in the specifier will be added
+ to the property. In this case, the function is really
+ equivalent to `copy-specifier' and LOCALE has the same
+ semantics (if it is a particular locale, the specification
+ for the locale will be copied; if a locale type,
+ specifications for all locales of that type will be copied;
+ if `nil' or `all', then all specifications will be copied).
+
+ HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append',
+ `remove-locale', `remove-locale-type', or `remove-all'. See
+ `copy-specifier' and `add-spec-to-specifier' for a description of
+ what each of these means. Most of the time, you do not need to
+ worry about this argument; the default behavior usually is fine.
+
+ In general, it is OK to pass an instance object (e.g. as returned
+ by `glyph-property-instance') as an instantiator in place of an
+ actual instantiator. In such a case, the instantiator used to
+ create that instance object will be used (for example, if you set
+ a font-instance object as the value of the `font' property, then
+ the font name used to create that object will be used instead).
+ If some cases, however, doing this conversion does not make sense,
+ and this will be noted in the documentation for particular types
+ of instance objects.
+
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ given, then this function will attempt to add VALUE as the
+ instantiator for the given LOCALE, using `add-spec-to-specifier'.
+ If the value of the property is not a specifier, it will
+ automatically be converted into a `generic' specifier.
+
+ - Function: glyph-property GLYPH PROPERTY &optional LOCALE
+ This function returns GLYPH's value of the given PROPERTY.
+
+ If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
+ be returned. For built-in properties, this will be a specifier
+ object of a type appropriate to the property (e.g. a font or color
+ specifier). For other properties, this could be anything.
+
+ If LOCALE is supplied, then instead of returning the actual value,
+ the specification(s) for the given locale or locale type will be
+ returned. This will only work if the actual value of PROPERTY is
+ a specifier (this will always be the case for built-in properties,
+ but may or may not apply to user-defined properties). If the
+ actual value of PROPERTY is not a specifier, this value will
+ simply be returned regardless of LOCALE.
+
+ The return value will be a list of instantiators (e.g. vectors
+ specifying pixmap data), or a list of specifications, each of
+ which is a cons of a locale and a list of instantiators.
+ Specifically, if LOCALE is a particular locale (a buffer, window,
+ frame, device, or `global'), a list of instantiators for that
+ locale will be returned. Otherwise, if LOCALE is a locale type
+ (one of the symbols `buffer', `window', `frame', or `device'), the
+ specifications for all locales of that type will be returned.
+ Finally, if LOCALE is `all', the specifications for all locales of
+ all types will be returned.
+
+ The specifications in a specifier determine what the value of
+ PROPERTY will be in a particular "domain" or set of circumstances,
+ which is typically a particular Emacs window along with the buffer
+ it contains and the frame and device it lies within. The value is
+ derived from the instantiator associated with the most specific
+ locale (in the order buffer, window, frame, device, and `global')
+ that matches the domain in question. In other words, given a
+ domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+ will first be searched for a specification whose locale is the
+ buffer contained within that window; then for a specification
+ whose locale is the window itself; then for a specification whose
+ locale is the frame that the window is contained within; etc. The
+ first instantiator that is valid for the domain (usually this
+ means that the instantiator is recognized by the device [i.e. the
+ X server or TTY device] that the domain is on). The function
+ `glyph-property-instance' actually does all this, and is used to
+ determine how to display the glyph.
+
+ - Function: glyph-property-instance GLYPH PROPERTY &optional DOMAIN
+ DEFAULT NO-FALLBACK
+ This function returns the instance of GLYPH's PROPERTY in the
+ specified DOMAIN.
+
+ Under most circumstances, DOMAIN will be a particular window, and
+ the returned instance describes how the specified property
+ actually is displayed for that window and the particular buffer in
+ it. Note that this may not be the same as how the property
+ appears when the buffer is displayed in a different window or
+ frame, or how the property appears in the same window if you
+ switch to another buffer in that window; and in those cases, the
+ returned instance would be different.
+
+ The returned instance is an image-instance object, and you can
+ query it using the appropriate image instance functions. For
+ example, you could use `image-instance-depth' to find out the
+ depth (number of color planes) of a pixmap displayed in a
+ particular window. The results might be different from the
+ results you would get for another window (perhaps the user
+ specified a different image for the frame that window is on; or
+ perhaps the same image was specified but the window is on a
+ different X server, and that X server has different color
+ capabilities from this one).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for such a domain is used in special circumstances when a
+ more specific domain does not apply; for example, a frame value
+ might be used for coloring a toolbar, which is conceptually
+ attached to a frame rather than a particular window. The value is
+ also useful in determining what the value would be for a
+ particular window within the frame or device, if it is not
+ overridden by a more specific specification.
+
+ If PROPERTY does not name a built-in property, its value will
+ simply be returned unless it is a specifier object, in which case
+ it will be instanced using `specifier-instance'.
+
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
+
+ - Function: remove-glyph-property GLYPH PROPERTY &optional LOCALE
+ TAG-SET EXACT-P
+ This function removes a property from a glyph. For built-in
+ properties, this is analogous to `remove-specifier'. *Note
+ remove-specifier-p: Specifiers, for the meaning of the LOCALE,
+ TAG-SET, and EXACT-P arguments.
+
+\1f
+File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
+
+Glyph Convenience Functions
+---------------------------
+
+ The following functions are provided for working with specific
+properties of a glyph. Note that these are exactly like calling the
+general functions described above and passing in the appropriate value
+for PROPERTY.
+
+ Remember that if you want to determine the "value" of a specific
+glyph property, you probably want to use the `*-instance' functions.
+For example, to determine whether a glyph contributes to its line
+height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
+latter will return a boolean specifier or a list of specifications, and
+you probably aren't concerned with these.)
+
+ - Function: glyph-image GLYPH &optional LOCALE
+ This function is equivalent to calling `glyph-property' with a
+ property of `image'. The return value will be an image specifier
+ if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-image GLYPH SPEC &optional LOCALE TAG-SET
+ HOW-TO-ADD
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `image'.
+
+ - Function: glyph-image-instance GLYPH &optional DOMAIN DEFAULT
+ NO-FALLBACK
+ This function returns the instance of GLYPH's image in the given
+ DOMAIN, and is equivalent to calling `glyph-property-instance'
+ with a property of `image'. The return value will be an image
+ instance.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing how the image appears
+ in that particular window and buffer will be returned.
+
+ - Function: glyph-contrib-p GLYPH &optional LOCALE
+ This function is equivalent to calling `glyph-property' with a
+ property of `contrib-p'. The return value will be a boolean
+ specifier if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-contrib-p GLYPH SPEC &optional LOCALE TAG-SET
+ HOW-TO-ADD
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `contrib-p'.
+
+ - Function: glyph-contrib-p-instance GLYPH &optional DOMAIN DEFAULT
+ NO-FALLBACK
+ This function returns whether the glyph contributes to its line
+ height in the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `contrib-p'. The
+ return value will be either `nil' or `t'. (Normally DOMAIN will be
+ a window or `nil', meaning the selected window.)
+
+ - Function: glyph-baseline GLYPH &optional LOCALE
+ This function is equivalent to calling `glyph-property' with a
+ property of `baseline'. The return value will be a specifier if
+ LOCALE is `nil' or omitted; otherwise, it will be a specification
+ or list of specifications.
+
+ - Function: set-glyph-baseline GLYPH SPEC &optional LOCALE TAG-SET
+ HOW-TO-ADD
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `baseline'.
+
+ - Function: glyph-baseline-instance GLYPH &optional DOMAIN DEFAULT
+ NO-FALLBACK
+ This function returns the instance of GLYPH's baseline value in
+ the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `baseline'. The
+ return value will be an integer or `nil'.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing the baseline value
+ appears in that particular window and buffer will be returned.
+
+ - Function: glyph-face GLYPH
+ This function returns the face of GLYPH. (Remember, this is not a
+ specifier, but a simple property.)
+
+ - Function: set-glyph-face GLYPH FACE
+ This function changes the face of GLYPH to FACE.
+
+\1f
+File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
+
+Glyph Dimensions
+----------------
+
+ - Function: glyph-width GLYPH &optional WINDOW
+ This function returns the width of GLYPH on WINDOW. This may not
+ be exact as it does not take into account all of the context that
+ redisplay will.
+
+ - Function: glyph-ascent GLYPH &optional WINDOW
+ This function returns the ascent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
+
+ - Function: glyph-descent GLYPH &optional WINDOW
+ This function returns the descent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
+
+ - Function: glyph-height GLYPH &optional WINDOW
+ This function returns the height of GLYPH on WINDOW. (This is
+ equivalent to the sum of the ascent and descent values.) This may
+ not be exact as it does not take into account all of the context
+ that redisplay will.
+
+\1f
+File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
+
+Images
+======
+
+* Menu:
+
+* Image Specifiers:: Specifying how an image will appear.
+* Image Instantiator Conversion::
+ Conversion is applied to image instantiators
+ at the time they are added to an
+ image specifier or at the time they
+ are passed to `make-image-instance'.
+* Image Instances:: What an image specifier gets instanced as.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+
+Image Specifiers
+----------------
+
+ An image specifier is used to describe the actual image of a glyph.
+It works like other specifiers (*note Specifiers::.), in that it
+contains a number of specifications describing how the image should
+appear in a variety of circumstances. These specifications are called
+"image instantiators". When XEmacs wants to display the image, it
+instantiates the image into an "image instance". Image instances are
+their own primitive object type (similar to font instances and color
+instances), describing how the image appears in a particular domain.
+(On the other hand, image instantiators, which are just descriptions of
+how the image should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p OBJECT
+ This function returns non-`nil' if OBJECT is an image specifier.
+ Usually, an image specifier results from calling `glyph-image' on
+ a glyph.
+
+ - Function: make-image-specifier SPEC-LIST
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. It is unlikely that you will ever want
+ to do this, but this function is provided for completeness and for
+ experimentation purposes. *Note Specifiers::.
+
+ Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc. This describes the format of the data describing the
+image. The resulting image instances also come in many types -
+`mono-pixmap', `color-pixmap', `text', `pointer', etc. This refers to
+the behavior of the image and the sorts of places it can appear. (For
+example, a color-pixmap image has fixed colors specified for it, while
+a mono-pixmap image comes in two unspecified shades "foreground" and
+"background" that are determined from the face of the glyph or
+surrounding text; a text image appears as a string of text and has an
+unspecified foreground, background, and font; a pointer image behaves
+like a mono-pixmap image but can only be used as a mouse pointer
+[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
+important to keep the distinction between image instantiator format and
+image instance type in mind. Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different image
+instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+ `[FORMAT :KEYWORD VALUE ...]'
+
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs. The "format" field should be a symbol, one of
+
+`nothing'
+ (Don't display anything; no keywords are valid for this. Can only
+ be instanced as `nothing'.)
+
+`string'
+ (Display this image as a text string. Can only be instanced as
+ `text', although support for instancing as `mono-pixmap' should be
+ added.)
+
+`formatted-string'
+ (Display this image as a text string with replaceable fields,
+ similar to a modeline format string; not currently implemented.)
+
+`xbm'
+ (An X bitmap; only if X support was compiled into this XEmacs.
+ Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
+
+`xpm'
+ (An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+ XPM is an add-on library for X that was designed to rectify the
+ shortcomings of the XBM format. Most implementations of X include
+ the XPM library as a standard part. If your vendor does not, it
+ is highly recommended that you download it and install it. You
+ can get it from the standard XEmacs FTP site, among other places.)
+
+`xface'
+ (An X-Face bitmap, used to encode people's faces in e-mail
+ messages; only if X-Face support was compiled into this XEmacs.
+ Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
+
+`gif'
+ (A GIF87 or GIF89 image; only if GIF support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
+ includes GIF decoding functions as a standard part of it, so if
+ you have X support, you will normally have GIF support, unless you
+ explicitly disable it at configure time.)
+
+`jpeg'
+ (A JPEG-format image; only if JPEG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
+ libraries present on your system when XEmacs is built, XEmacs will
+ automatically detect this and use them, unless you explicitly
+ disable it at configure time.)
+
+`png'
+ (A PNG/GIF24 image; only if PNG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'.)
+
+`tiff'
+ (A TIFF-format image; only if TIFF support was compiled into this
+ XEmacs. Not currently implemented.)
+
+`cursor-font'
+ (One of the standard cursor-font names, such as `watch' or
+ `right_ptr' under X. Under X, this is, more specifically, any of
+ the standard cursor names from appendix B of the Xlib manual [also
+ known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
+ other window systems, the valid names will be specific to the type
+ of window system. Can only be instanced as `pointer'.)
+
+`font'
+ (A glyph from a font; i.e. the name of a font, and glyph index
+ into it of the form `FONT fontname index [[mask-font] mask-index]'.
+ Only if X support was compiled into this XEmacs. Currently can
+ only be instanced as `pointer', although this should probably be
+ fixed.)
+
+`subwindow'
+ (An embedded X window; not currently implemented.)
+
+`autodetect'
+ (XEmacs tries to guess what format the data is in. If X support
+ exists, the data string will be checked to see if it names a
+ filename. If so, and this filename contains XBM or XPM data, the
+ appropriate sort of pixmap or pointer will be created. [This
+ includes picking up any specified hotspot or associated mask
+ file.] Otherwise, if `pointer' is one of the allowable
+ image-instance types and the string names a valid cursor-font
+ name, the image will be created as a pointer. Otherwise, the
+ image will be displayed as text. If no X support exists, the
+ image will always be displayed as text.)
+
+ The valid keywords are:
+
+`:data'
+ (Inline data. For most formats above, this should be a string.
+ For XBM images, this should be a list of three elements: width,
+ height, and a string of bit data. This keyword is not valid for
+ instantiator format `nothing'.)
+
+`:file'
+ (Data is contained in a file. The value is the name of this file.
+ If both `:data' and `:file' are specified, the image is created
+ from what is specified in `:data' and the string in `:file'
+ becomes the value of the `image-instance-file-name' function when
+ applied to the resulting image-instance. This keyword is not
+ valid for instantiator formats `nothing', `string',
+ `formatted-string', `cursor-font', `font', and `autodetect'.)
+
+`:foreground'
+`:background'
+ (For `xbm', `xface', `cursor-font', and `font'. These keywords
+ allow you to explicitly specify foreground and background colors.
+ The argument should be anything acceptable to
+ `make-color-instance'. This will cause what would be a
+ `mono-pixmap' to instead be colorized as a two-color color-pixmap,
+ and specifies the foreground and/or background colors for a pointer
+ instead of black and white.)
+
+`:mask-data'
+ (For `xbm' and `xface'. This specifies a mask to be used with the
+ bitmap. The format is a list of width, height, and bits, like for
+ `:data'.)
+
+`:mask-file'
+ (For `xbm' and `xface'. This specifies a file containing the mask
+ data. If neither a mask file nor inline mask data is given for an
+ XBM image, and the XBM image comes from a file, XEmacs will look
+ for a mask file with the same name as the image file but with
+ `Mask' or `msk' appended. For example, if you specify the XBM file
+ `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
+ associated mask file `left_ptrmsk' will automatically be picked
+ up.)
+
+`:hotspot-x'
+`:hotspot-y'
+ (For `xbm' and `xface'. These keywords specify a hotspot if the
+ image is instantiated as a `pointer'. Note that if the XBM image
+ file specifies a hotspot, it will automatically be picked up if no
+ explicit hotspot is given.)
+
+`:color-symbols'
+ (Only for `xpm'. This specifies an alist that maps strings that
+ specify symbolic color names to the actual color to be used for
+ that symbolic color (in the form of a string or a color-specifier
+ object). If this is not specified, the contents of
+ `xpm-color-symbols' are used to generate the alist.)
+
+ If instead of a vector, the instantiator is a string, it will be
+converted into a vector by looking it up according to the specs in the
+`console-type-image-conversion-list' for the console type of the domain
+(usually a window; sometimes a frame or device) over which the image is
+being instantiated.
+
+ If the instantiator specifies data from a file, the data will be
+read in at the time that the instantiator is added to the image
+specifier (which may be well before the image is actually displayed),
+and the instantiator will be converted into one of the inline-data
+forms, with the filename retained using a `:file' keyword. This
+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
+ 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.
+
+ - Function: image-instantiator-format-list
+ This function return a list of valid image-instantiator formats.
+
+ - Variable: xpm-color-symbols
+ This variable holds definitions of logical color-names used when
+ reading XPM files. Elements of this list should be of the form
+ `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
+ string, which is the name of the color to define; the
+ FORM-TO-EVALUATE should evaluate to a color specifier object, or a
+ string to be passed to `make-color-instance' (*note Colors::.). If
+ a loaded XPM file references a symbolic color called COLOR-NAME,
+ it will display as the computed color instead.
+
+ The default value of this variable defines the logical color names
+ `"foreground"' and `"background"' to be the colors of the
+ `default' face.
+
+ - 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).
+
+\1f
+File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
+
+Image Instantiator Conversion
+-----------------------------
+
+ - Function: set-console-type-image-conversion-list CONSOLE-TYPE LIST
+ This function sets the image-conversion-list for consoles of the
+ given CONSOLE-TYPE. The image-conversion-list specifies how image
+ instantiators that are strings should be interpreted. Each
+ element of the list should be a list of two elements (a regular
+ expression string and a vector) or a list of three elements (the
+ preceding two plus an integer index into the vector). The string
+ is converted to the vector associated with the first matching
+ regular expression. If a vector index is specified, the string
+ itself is substituted into that position in the vector.
+
+ Note: The conversion above is applied when the image instantiator
+ is added to an image specifier, not when the specifier is actually
+ instantiated. Therefore, changing the image-conversion-list only
+ affects newly-added instantiators. Existing instantiators in
+ glyphs and image specifiers will not be affected.
+
+ - Function: console-type-image-conversion-list CONSOLE-TYPE
+ This function returns the image-conversion-list for consoles of
+ the given CONSOLE-TYPE.
+
+\1f
+File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+
+Image Instances
+---------------
+
+ Image-instance objects encapsulate the way a particular image
+(pixmap, etc.) is displayed on a particular device.
+
+ In most circumstances, you do not need to directly create image
+instances; use a glyph instead. However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+ - Function: image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance.
+
+* Menu:
+
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+
+\1f
+File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
+
+Image Instance Types
+....................
+
+ Image instances come in a number of different types. The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
+
+ The valid image instance types are
+
+`nothing'
+ Nothing is displayed.
+
+`text'
+ Displayed as text. The foreground and background colors and the
+ font of the text are specified independent of the pixmap.
+ Typically these attributes will come from the face of the
+ surrounding text, unless a face is specified for the glyph in
+ which the image appears.
+
+`mono-pixmap'
+ Displayed as a mono pixmap (a pixmap with only two colors where the
+ foreground and background can be specified independent of the
+ pixmap; typically the pixmap assumes the foreground and background
+ colors of the text around it, unless a face is specified for the
+ glyph in which the image appears).
+
+`color-pixmap'
+ Displayed as a color pixmap.
+
+`pointer'
+ Used as the mouse pointer for a window.
+
+`subwindow'
+ A child window that is treated as an image. This allows (e.g.)
+ another program to be responsible for drawing into the window.
+ Not currently implemented.
+
+ - Function: valid-image-instance-type-p TYPE
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
+
+ - Function: image-instance-type-list
+ This function returns a list of the valid image instance types.
+
+ - Function: image-instance-type IMAGE-INSTANCE
+ This function returns the type of the given image instance. The
+ return value will be one of `nothing', `text', `mono-pixmap',
+ `color-pixmap', `pointer', or `subwindow'.
+
+ - Function: text-image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `text'.
+
+ - Function: mono-pixmap-image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `mono-pixmap'.
+
+ - Function: color-pixmap-image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `color-pixmap'.
+
+ - Function: pointer-image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `pointer'.
+
+ - Function: subwindow-image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `subwindow'.
+
+ - Function: nothing-image-instance-p OBJECT
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `nothing'.
+
+\1f
+File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+
+Image Instance Functions
+........................
+
+ - Function: make-image-instance DATA &optional DEVICE DEST-TYPES
+ NO-ERROR
+ This function creates a new image-instance object.
+
+ DATA is an image instantiator, which describes the image (*note
+ Image Specifiers::.).
+
+ DEST-TYPES should be a list of allowed image instance types that
+ can be generated. The DEST-TYPES list is unordered. If multiple
+ destination types are possible for a given instantiator, the "most
+ natural" type for the instantiator's format is chosen. (For XBM,
+ the most natural types are `mono-pixmap', followed by
+ `color-pixmap', followed by `pointer'. For the other normal image
+ formats, the most natural types are `color-pixmap', followed by
+ `mono-pixmap', followed by `pointer'. For the string and
+ formatted-string formats, the most natural types are `text',
+ followed by `mono-pixmap' (not currently implemented), followed by
+ `color-pixmap' (not currently implemented). The other formats can
+ only be instantiated as one type. (If you want to control more
+ specifically the order of the types into which an image is
+ instantiated, just call `make-image-instance' repeatedly until it
+ succeeds, passing less and less preferred destination types each
+ time.
+
+ If DEST-TYPES is omitted, all possible types are allowed.
+
+ 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.
+
+ - Function: colorize-image-instance IMAGE-INSTANCE FOREGROUND
+ BACKGROUND
+ This function makes the image instance be displayed in the given
+ colors. Image instances come in two varieties: bitmaps, which are
+ 1 bit deep which are rendered in the prevailing foreground and
+ background colors; and pixmaps, which are of arbitrary depth
+ (including 1) and which have the colors explicitly specified.
+ This function converts a bitmap to a pixmap. If the image
+ instance was a pixmap already, nothing is done (and `nil' is
+ returned). Otherwise `t' is returned.
+
+ - Function: image-instance-name IMAGE-INSTANCE
+ This function returns the name of the given image instance.
+
+ - Function: image-instance-string IMAGE-INSTANCE
+ This function returns the string of the given image instance.
+ This will only be non-`nil' for text image instances.
+
+ - Function: image-instance-file-name IMAGE-INSTANCE
+ This function returns the file name from which IMAGE-INSTANCE was
+ read, if known.
+
+ - Function: image-instance-mask-file-name IMAGE-INSTANCE
+ This function returns the file name from which IMAGE-INSTANCE's
+ mask was read, if known.
+
+ - Function: image-instance-depth IMAGE-INSTANCE
+ This function returns the depth of the image instance. This is 0
+ for a mono pixmap, or a positive integer for a color pixmap.
+
+ - Function: image-instance-height IMAGE-INSTANCE
+ This function returns the height of the image instance, in pixels.
+
+ - Function: image-instance-width IMAGE-INSTANCE
+ This function returns the width of the image instance, in pixels.
+
+ - Function: image-instance-hotspot-x IMAGE-INSTANCE
+ This function returns the X coordinate of the image instance's
+ hotspot, if known. This is a point relative to the origin of the
+ pixmap. When an image is used as a mouse pointer, the hotspot is
+ the point on the image that sits over the location that the
+ pointer points to. This is, for example, the tip of the arrow or
+ the center of the crosshairs.
+
+ This will always be `nil' for a non-pointer image instance.
+
+ - Function: image-instance-hotspot-y IMAGE-INSTANCE
+ This function returns the Y coordinate of the image instance's
+ hotspot, if known.
+
+ - Function: image-instance-foreground IMAGE-INSTANCE
+ This function returns the foreground color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+ - Function: image-instance-background IMAGE-INSTANCE
+ This function returns the background color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+\1f
+File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
+
+Glyph Types
+===========
+
+ Each glyph has a particular type, which controls how the glyph's
+image is generated. Each glyph type has a corresponding list of
+allowable image instance types that can be generated. When you call
+`glyph-image-instance' to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling `make-image-instance' and passing
+in DEST-TYPES the list of allowable image instance types for the
+glyph's type.
+
+ * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
+ extent, in the modeline, and in the toolbar. Their image can be
+ instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
+ and `subwindow'.
+
+ * `pointer' glyphs can be used to specify the mouse pointer. Their
+ image can be instantiated as `pointer'.
+
+ * `icon' glyphs can be used to specify the icon used when a frame is
+ iconified. Their image can be instantiated as `mono-pixmap' and
+ `color-pixmap'.
+
+ - Function: glyph-type GLYPH
+ This function returns the type of the given glyph. The return
+ value will be a symbol, one of `buffer', `pointer', or `icon'.
+
+ - Function: valid-glyph-type-p GLYPH-TYPE
+ Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+
+ - Function: glyph-type-list
+ This function returns a list of valid glyph types.
+
+ - Function: buffer-glyph-p OBJECT
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `buffer'.
+
+ - Function: icon-glyph-p OBJECT
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `icon'.
+
+ - Function: pointer-glyph-p OBJECT
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `pointer'.
+
+\1f
+File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
+
+Mouse Pointer
+=============
+
+ The shape of the mouse pointer when over a particular section of a
+frame is controlled using various glyph variables. Since the image of
+a glyph is a specifier, it can be controlled on a per-buffer,
+per-frame, per-window, or per-device basis.
+
+ You should use `set-glyph-image' to set the following variables,
+*not* `setq'.
+
+ - Glyph: text-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ text.
+
+ - Glyph: nontext-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ buffer, but not over text. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: modeline-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the modeline. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ - Glyph: selection-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ selectable text region. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: gc-pointer-glyph
+ This variable specifies the shape of the mouse pointer when a
+ garbage collection is in progress. If the selected window is on a
+ window system and this glyph specifies a value (i.e. a pointer
+ image instance) in the domain of the selected window, the pointer
+ will be changed as specified during garbage collection.
+ Otherwise, a message will be printed in the echo area, as
+ controlled by `gc-message'.
+
+ - Glyph: busy-pointer-glyph
+ This variable specifies the shape of the mouse pointer when XEmacs
+ is busy. If unspecified in a particular domain, the pointer is
+ not changed when XEmacs is busy.
+
+ - Glyph: menubar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the menubar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: scrollbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ scrollbar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: toolbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ toolbar. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves. That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
+
+ - Function: set-frame-pointer FRAME IMAGE-INSTANCE
+ This function sets the mouse pointer of FRAME to the given pointer
+ image instance. You should not call this function directly. (If
+ you do, the pointer will change again the next time the mouse
+ moves.)
+
+\1f
+File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
+
+Redisplay Glyphs
+================
+
+ - Glyph: truncation-glyph
+ This variable specifies what is displayed at the end of truncated
+ lines.
+
+ - Glyph: continuation-glyph
+ This variable specifies what is displayed at the end of wrapped
+ lines.
+
+ - Glyph: octal-escape-glyph
+ This variable specifies what to prefix character codes displayed
+ in octal with.
+
+ - Glyph: hscroll-glyph
+ This variable specifies what to display at the beginning of
+ horizontally scrolled lines.
+
+ - Glyph: invisible-text-glyph
+ This variable specifies what to use to indicate the presence of
+ invisible text. This is the glyph that is displayed when an
+ ellipsis is called for, according to `selective-display-ellipses'
+ or `buffer-invisibility-spec'). Normally this is three dots
+ ("...").
+
+ - Glyph: control-arrow-glyph
+ This variable specifies what to use as an arrow for control
+ characters.
+
+\1f
+File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
+
+Subwindows
+==========
+
+ Subwindows are not currently implemented.
+
+ - Function: subwindowp OBJECT
+ This function returns non-`nil' if OBJECT is a subwindow.
+
+\1f
+File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
+
+Annotations
+***********
+
+ An "annotation" is a pixmap or string that is not part of a buffer's
+text but is displayed next to a particular location in a buffer.
+Annotations can be displayed intermixed with text, in any whitespace at
+the beginning or end of a line, or in a special area at the left or
+right side of the frame called a "margin", whose size is controllable.
+Annotations are implemented using extents (*note Extents::.); but you
+can work with annotations without knowing how extents work.
+
+* Menu:
+
+* Annotation Basics:: Introduction to annotations.
+* Annotation Primitives:: Creating and deleting annotations.
+* Annotation Properties:: Retrieving and changing the characteristics
+ of an annotation.
+* Margin Primitives:: Controlling the size of the margins.
+* Locating Annotations:: Looking for annotations in a buffer.
+* Annotation Hooks:: Hooks called at certain times during an
+ annotation's lifetime.
+
+\1f
+File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
+
+Annotation Basics
+=================
+
+ Marginal annotations are notes associated with a particular location
+in a buffer. They may be displayed in a margin created on the
+left-hand or right-hand side of the frame, in any whitespace at the
+beginning or end of a line, or inside of the text itself. Every
+annotation may have an associated action to be performed when the
+annotation is selected. The term "annotation" is used to refer to an
+individual note. The term "margin" is generically used to refer to the
+whitespace before the first character on a line or after the last
+character on a line.
+
+ Each annotation has the following characteristics:
+GLYPH
+ This is a glyph object and is used as the displayed representation
+ of the annotation.
+
+DOWN-GLYPH
+ If given, this glyph is used as the displayed representation of
+ the annotation when the mouse is pressed down over the annotation.
+
+FACE
+ The face with which to display the glyph.
+
+SIDE
+ Which side of the text (left or right) the annotation is displayed
+ at.
+
+ACTION
+ If non-`nil', this field must contain a function capable of being
+ the first argument to `funcall'. This function is normally
+ evaluated with a single argument, the value of the DATA field,
+ each time the annotation is selected. However, if the WITH-EVENT
+ parameter to `make-annotation' is non-`nil', the function is
+ called with two arguments. The first argument is the same as
+ before, and the second argument is the event (a button-up event,
+ usually) that activated the annotation.
+
+DATA
+ Not used internally. This field can contain any E-Lisp object.
+ It is passed as the first argument to ACTION described above.
+
+MENU
+ A menu displayed when the right mouse button is pressed over the
+ annotation.
+
+ The margin is divided into "outside" and "inside". The outside
+margin is space on the left or right side of the frame which normal text
+cannot be displayed in. The inside margin is that space between the
+leftmost or rightmost point at which text can be displayed and where the
+first or last character actually is.
+
+ There are four different "layout types" which affect the exact
+location an annotation appears.
+
+`outside-margin'
+ The annotation is placed in the outside margin area. as close as
+ possible to the edge of the frame. If the outside margin is not
+ wide enough for an annotation to fit, it is not displayed.
+
+`inside-margin'
+ The annotation is placed in the inside margin area, as close as
+ possible to the edge of the frame. If the inside margin is not
+ wide enough for the annotation to fit, it will be displayed using
+ any available outside margin space if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`whitespace'
+ The annotation is placed in the inside margin area, as close as
+ possible to the first or last non-whitespace character on a line.
+ If the inside margin is not wide enough for the annotation to fit,
+ it will be displayed if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`text'
+ The annotation is placed at the position it is inserted. It will
+ create enough space for itself inside of the text area. It does
+ not take up a place in the logical buffer, only in the display of
+ the buffer.
+
+ The current layout policy is that all `whitespace' annotations are
+displayed first. Next, all `inside-margin' annotations are displayed
+using any remaining space. Finally as many `outside-margin'
+annotations are displayed as possible. The `text' annotations will
+always display as they create their own space to display in.
+
+\1f
+File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
+
+Annotation Primitives
+=====================
+
+ - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER
+ WITH-EVENT D-GLYPH RIGHTP
+ This function creates a marginal annotation at position POS in
+ BUFFER. The annotation is displayed using GLYPH, which should be
+ a glyph object or a string, and is positioned using layout policy
+ LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil',
+ `whitespace' is used. If BUFFER is `nil', the current buffer is
+ used.
+
+ If WITH-EVENT is non-`nil', then when an annotation is activated,
+ the triggering event is passed as the second arg to the annotation
+ function. If D-GLYPH is non-`nil' then it is used as the glyph
+ that will be displayed when button1 is down. If RIGHTP is
+ non-`nil' then the glyph will be displayed on the right side of
+ the buffer instead of the left.
+
+ The newly created annotation is returned.
+
+ - Function: delete-annotation ANNOTATION
+ This function removes ANNOTATION from its buffer. This does not
+ modify the buffer text.
+
+ - Function: annotationp ANNOTATION
+ This function returns `t' if ANNOTATION is an annotation, `nil'
+ otherwise.
+
+\1f
+File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
+
+Annotation Properties
+=====================
+
+ - Function: annotation-glyph ANNOTATION
+ This function returns the glyph object used to display ANNOTATION.
+
+ - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE
+ This function sets the glyph of ANNOTATION to GLYPH, which should
+ be a glyph object. If LAYOUT is non-`nil', set the layout policy
+ of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
+ side of the buffer at which the annotation is displayed to the
+ given side. The new value of `annotation-glyph' is returned.
+
+ - Function: annotation-down-glyph ANNOTATION
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation.
+
+ - Function: set-annotation-down-glyph ANNOTATION GLYPH
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation to GLYPH,
+ which should be a glyph object.
+
+ - Function: annotation-face ANNOTATION
+ This function returns the face associated with ANNOTATION.
+
+ - Function: set-annotation-face ANNOTATION FACE
+ This function sets the face associated with ANNOTATION to FACE.
+
+ - Function: annotation-layout ANNOTATION
+ This function returns the layout policy of ANNOTATION.
+
+ - Function: set-annotation-layout ANNOTATION LAYOUT
+ This function sets the layout policy of ANNOTATION to LAYOUT.
+
+ - Function: annotation-side ANNOTATION
+ This function returns the side of the buffer that ANNOTATION is
+ displayed on. Return value is a symbol, either `left' or `right'.
+
+ - Function: annotation-data ANNOTATION
+ This function returns the data associated with ANNOTATION.
+
+ - Function: set-annotation-data ANNOTATION DATA
+ This function sets the data field of ANNOTATION to DATA. DATA is
+ returned.
+
+ - Function: annotation-action ANNOTATION
+ This function returns the action associated with ANNOTATION.
+
+ - Function: set-annotation-action ANNOTATION ACTION
+ This function sets the action field of ANNOTATION to ACTION.
+ ACTION is returned..
+
+ - Function: annotation-menu ANNOTATION
+ This function returns the menu associated with ANNOTATION.
+
+ - Function: set-annotation-menu ANNOTATION MENU
+ This function sets the menu associated with ANNOTATION to MENU.
+ This menu will be displayed when the right mouse button is pressed
+ over the annotation.
+
+ - Function: annotation-visible ANNOTATION
+ This function returns `t' if there is enough available space to
+ display ANNOTATION, `nil' otherwise.
+
+ - Function: annotation-width ANNOTATION
+ This function returns the width of ANNOTATION in pixels.
+
+ - Function: hide-annotation ANNOTATION
+ This function removes ANNOTATION's glyph, making it invisible.
+
+ - Function: reveal-annotation ANNOTATION
+ This function restores ANNOTATION's glyph, making it visible.
+
+\1f
+File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
+
+Locating Annotations
+====================
+
+ - Function: annotations-in-region START END BUFFER
+ This function returns a list of all annotations in BUFFER which
+ are between START and END inclusively.
+
+ - Function: annotations-at &optional POSITION BUFFER
+ This function returns a list of all annotations at POSITION in
+ BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
+ the current buffer is used.
+
+ - Function: annotation-list &optional BUFFER
+ This function returns a list of all annotations in BUFFER. If
+ BUFFER is `nil', the current buffer is used.
+
+ - Function: all-annotations
+ This function returns a list of all annotations in all buffers in
+ existence.
+
+\1f
+File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
+
+Margin Primitives
+=================
+
+ The margin widths are controllable on a buffer-local, window-local,
+frame-local, device-local, or device-type-local basis through the use
+of specifiers. *Note Specifiers::.
+
+ - Specifier: left-margin-width
+ This is a specifier variable controlling the width of the left
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: right-margin-width
+ This is a specifier variable controlling the width of the right
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: use-left-overflow
+ If non-`nil', use the left outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Specifier: use-right-overflow
+ If non-`nil', use the right outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Function: window-left-margin-pixel-width &optional WINDOW
+ This function returns the width in pixels of the left outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ - Function: window-right-margin-pixel-width &optional WINDOW
+ This function returns the width in pixels of the right outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ The margin colors are controlled by the faces `left-margin' and
+`right-margin'. These can be set using the X resources
+`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
+likewise for the right margin.
+
+\1f
+File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
+
+Annotation Hooks
+================
+
+ The following three hooks are provided for use with the marginal
+annotations:
+
+`before-delete-annotation-hook'
+ This hook is called immediately before an annotation is destroyed.
+ It is passed a single argument, the annotation being destroyed.
+
+`after-delete-annotation-hook'
+ This normal hook is called immediately after an annotation is
+ destroyed.
+
+`make-annotation-hook'
+ This hook is called immediately after an annotation is created.
+ It is passed a single argument, the newly created annotation.
+
+\1f
+File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
+
+Emacs Display
+*************
+
+ This chapter describes a number of other features related to the
+display that XEmacs presents to the user.
+
+* Menu:
+
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Warnings:: Display of Warnings.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Overlay Arrow:: Display of an arrow to indicate position.
+* Temporary Displays:: Displays that go away automatically.
+* Blinking:: How XEmacs shows the matching open parenthesis.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
+* Beeping:: Audible signal to the user.
+
+\1f
+File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
+
+Refreshing the Screen
+=====================
+
+ The function `redraw-frame' redisplays the entire contents of a
+given frame. *Note Frames::.
+
+ - Function: redraw-frame FRAME
+ This function clears and redisplays frame FRAME.
+
+ Even more powerful is `redraw-display':
+
+ - Command: redraw-display &optional DEVICE
+ This function redraws all frames on DEVICE marked as having their
+ image garbled. DEVICE defaults to the selected device. If DEVICE
+ is `t', all devices will have their frames checked.
+
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually--after all the
+input has been processed.
+
+ Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display. If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption. *Note Suspending XEmacs::.
+
+ - Variable: no-redraw-on-reenter
+ This variable controls whether XEmacs redraws the entire screen
+ after it has been suspended and resumed. Non-`nil' means yes,
+ `nil' means no.
+
+ The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch. Normally this occurs the next time that
+`next-event' or `sit-for' is called; however, a display update will not
+occur if there is input pending. *Note Command Loop::.
+
+ - Function: force-cursor-redisplay
+ This function causes an immediate update of the cursor on the
+ selected frame. (This function does not exist in FSF Emacs.)
+
+\1f
+File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
+
+Truncation
+==========
+
+ When a line of text extends beyond the right edge of a window, the
+line can either be truncated or continued on the next line. When a line
+is truncated, this is normally shown with a `\' in the rightmost column
+of the window on X displays, and with a `$' on TTY devices. When a
+line is continued or "wrapped" onto the next line, this is shown with a
+curved arrow in the rightmost column of the window (or with a `\' on
+TTY devices). The additional screen lines used to display a long text
+line are called "continuation" lines.
+
+ Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars. *Note Scrollbars::.
+
+ Note that continuation is different from filling; continuation
+happens on the screen only, not in the buffer contents, and it breaks a
+line precisely at the right margin, not at a word boundary. *Note
+Filling::.
+
+ - User Option: truncate-lines
+ This buffer-local variable controls how XEmacs displays lines that
+ extend beyond the right edge of the window. If it is non-`nil',
+ then XEmacs does not display continuation lines; rather each line
+ of text occupies exactly one screen line, and a backslash appears
+ at the edge of any line that extends to or beyond the edge of the
+ window. The default is `nil'.
+
+ If the variable `truncate-partial-width-windows' is non-`nil',
+ then truncation is always used for side-by-side windows (within one
+ frame) regardless of the value of `truncate-lines'.
+
+ - User Option: default-truncate-lines
+ This variable is the default value for `truncate-lines', for
+ buffers that do not have local values for it.
+
+ - User Option: truncate-partial-width-windows
+ This variable controls display of lines that extend beyond the
+ right edge of the window, in side-by-side windows (*note Splitting
+ Windows::.). If it is non-`nil', these lines are truncated;
+ otherwise, `truncate-lines' says what to do with them.
+
+ The backslash and curved arrow used to indicate truncated or
+continued lines are only defaults, and can be changed. These images
+are actually glyphs (*note Glyphs::.). XEmacs provides a great deal of
+flexibility in how glyphs can be controlled. (This differs from FSF
+Emacs, which uses display tables to control these images.)
+
+ For details, *Note Redisplay Glyphs::.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
+
+The Echo Area
+=============
+
+ The "echo area" is used for displaying messages made with the
+`message' primitive, and for echoing keystrokes. It is not the same as
+the minibuffer, despite the fact that the minibuffer appears (when
+active) in the same place on the screen as the echo area. The `XEmacs
+Reference Manual' specifies the rules for resolving conflicts between
+the echo area and the minibuffer for use of that screen space (*note
+The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
+area; see *Note Errors::.
+
+ You can write output in the echo area by using the Lisp printing
+functions with `t' as the stream (*note Output Functions::.), or as
+follows:
+
+ - Function: message STRING &rest ARGUMENTS
+ This function displays a one-line message in the echo area. The
+ argument STRING is similar to a C language `printf' control
+ string. See `format' in *Note String Conversion::, for the details
+ on the conversion specifications. `message' returns the
+ constructed string.
+
+ In batch mode, `message' prints the message text on the standard
+ error stream, followed by a newline.
+
+ If STRING is `nil', `message' clears the echo area. If the
+ minibuffer is active, this brings the minibuffer contents back onto
+ the screen immediately.
+
+ (message "Minibuffer depth is %d."
+ (minibuffer-depth))
+ -| Minibuffer depth is 0.
+ => "Minibuffer depth is 0."
+
+ ---------- Echo Area ----------
+ Minibuffer depth is 0.
+ ---------- Echo Area ----------
+
+ In addition to only displaying a message, XEmacs allows you to
+"label" your messages, giving you fine-grained control of their
+display. Message label is a symbol denoting the message type. Some
+standard labels are:
+
+ * `message'--default label used by the `message' function;
+
+ * `error'--default label used for reporting errors;
+
+ * `progress'--progress indicators like `Converting... 45%' (not
+ logged by default);
+
+ * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+ default);
+
+ * `command'--helper command messages like `Mark set' (not logged by
+ default);
+
+ * `no-log'--messages that should never be logged
+
+ Several messages may be stacked in the echo area at once. Lisp
+programs may access these messages, or remove them as appropriate, via
+the message stack.
+
+ - Function: display-message LABEL MESSAGE &optional FRAME STDOUT-P
+ This function displays MESSAGE (a string) labeled as LABEL, as
+ described above.
+
+ The FRAME argument specifies the frame to whose minibuffer the
+ message should be printed. This is currently unimplemented. The
+ STDOUT-P argument is used internally.
+
+ (display-message 'command "Mark set")
+
+ - Function: lmessage LABEL STRING &rest ARGUMENTS
+ This function displays a message STRING with label LABEL. It is
+ similar to `message' in that it accepts a `printf'-like strings
+ and any number of arguments.
+
+ ;; Display a command message.
+ (lmessage 'command "Comment column set to %d" comment-column)
+
+ ;; Display a progress message.
+ (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
+
+ ;; Display a message that should not be logged.
+ (lmessage 'no-log "Done")
+
+ - Function: clear-message &optional LABEL FRAME STDOUT-P NO-RESTORE
+ This function remove any message with the given LABEL from the
+ message-stack, erasing it from the echo area if it's currently
+ displayed there.
+
+ 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 cleared.
+
+ ;; Show a message, wait for 2 seconds, and restore old minibuffer
+ ;; contents.
+ (message "A message")
+ -| A message
+ => "A Message"
+ (lmessage 'my-label "Newsflash! Newsflash!")
+ -| Newsflash! Newsflash!
+ => "Newsflash! Newsflash!"
+ (sit-for 2)
+ (clear-message 'my-label)
+ -| A message
+ => "A message"
+
+ Unless you need the return value or you need to specify a label,
+ you should just use `(message nil)'.
+
+ - Function: current-message &optional FRAME
+ This function returns the current message in the echo area, or
+ `nil'. The FRAME argument is currently unused.
+
+ Some of the messages displayed in the echo area are also recorded in
+the ` *Message-Log*' buffer. Exactly which messages will be recorded
+can be tuned using the following variables.
+
+ - User Option: log-message-max-size
+ This variable specifies the maximum size of the ` *Message-log*'
+ buffer.
+
+ - Variable: log-message-ignore-labels
+ This variable specifies the labels whose messages will not be
+ logged. It should be a list of symbols.
+
+ - Variable: log-message-ignore-regexps
+ This variable specifies the regular expressions matching messages
+ that will not be logged. It should be a list of regular
+ expressions.
+
+ Normally, packages that generate messages that might need to be
+ ignored should label them with `progress', `prompt', or `no-log',
+ so they can be filtered by `log-message-ignore-labels'.
+
+ - Variable: echo-keystrokes
+ This variable determines how much time should elapse before command
+ characters echo. Its value must be a number, which specifies the
+ number of seconds to wait before echoing. If the user types a
+ prefix key (such as `C-x') and then delays this many seconds
+ before continuing, the prefix key is echoed in the echo area. Any
+ subsequent characters in the same command will be echoed as well.
+
+ If the value is zero, then command input is not echoed.
+
+ - Variable: cursor-in-echo-area
+ This variable controls where the cursor appears when a message is
+ displayed in the echo area. If it is non-`nil', then the cursor
+ appears at the end of the message. Otherwise, the cursor appears
+ at point--not in the echo area at all.
+
+ The value is normally `nil'; Lisp programs bind it to `t' for
+ brief periods of time.
+
+\1f
+File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
+
+Warnings
+========
+
+ XEmacs contains a facility for unified display of various warnings.
+Unlike errors, warnings are displayed in the situations when XEmacs
+encounters a problem that is recoverable, but which should be fixed for
+safe future operation.
+
+ For example, warnings are printed by the startup code when it
+encounters problems with X keysyms, when there is an error in `.emacs',
+and in other problematic situations. Unlike messages, warnings are
+displayed in a separate buffer, and include an explanatory message that
+may span across several lines. Here is an example of how a warning is
+displayed:
+
+ (1) (initialization/error) An error has occurred while loading ~/.emacs:
+
+ Symbol's value as variable is void: bogus-variable
+
+ To ensure normal operation, you should investigate the cause of the error
+ in your initialization file and remove it. Use the `-debug-init' option
+ to XEmacs to view a complete error backtrace.
+
+ Each warning has a "class" and a "priority level". The class is a
+symbol describing what sort of warning this is, such as
+`initialization', `resource' or `key-mapping'.
+
+ The warning priority level specifies how important the warning is.
+The recognized warning levels, in increased order of priority, are:
+`debug', `info', `notice', `warning', `error', `critical', `alert' and
+`emergency'.
+
+ - Function: display-warning CLASS MESSAGE &optional LEVEL
+ This function displays a warning message MESSAGE (a string).
+ CLASS should be a warning class symbol, as described above, or a
+ list of such symbols. LEVEL describes the warning priority level.
+ If unspecified, it default to `warning'.
+
+ (display-warning 'resource
+ "Bad resource specification encountered:
+ something like
+
+ Emacs*foo: bar
+
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.")
+
+ ---------- Warning buffer ----------
+ (1) (resource/warning) Bad resource specification encountered:
+ something like
+
+ Emacs*foo: bar
+
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.
+ ---------- Warning buffer ----------
+
+ - Function: lwarn CLASS LEVEL MESSAGE &rest ARGS
+ This function displays a formatted labeled warning message. As
+ above, CLASS should be the warning class symbol, or a list of such
+ symbols, and LEVEL should specify the warning priority level
+ (`warning' by default).
+
+ Unlike in `display-warning', MESSAGE may be a formatted message,
+ which will be, together with the rest of the arguments, passed to
+ `format'.
+
+ (lwarn 'message-log 'warning
+ "Error caught in `remove-message-hook': %s"
+ (error-message-string e))
+
+ - Variable: log-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be generated. Warnings with level lower than defined by this
+ variable are completely ignored, as if they never happened.
+
+ - Variable: display-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be displayed. Unlike `log-warning-minimum-level', setting this
+ function does not suppress warnings entirely--they are still
+ generated in the `*Warnings*' buffer, only they are not displayed
+ by default.
+
+ - Variable: log-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will be completely ignored, as it they never happened.
+
+ - Variable: display-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will not be displayed. The warning will still logged in
+ the *Warnings* buffer (unless also contained in
+ `log-warning-suppressed-classes'), but the buffer will not be
+ automatically popped up.
+
+\1f
+File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
+
+Invisible Text
+==============
+
+ You can make characters "invisible", so that they do not appear on
+the screen, with the `invisible' property. This can be either a text
+property or a property of an overlay.
+
+ In the simplest case, any non-`nil' `invisible' property makes a
+character invisible. This is the default case--if you don't alter the
+default value of `buffer-invisibility-spec', this is how the
+`invisibility' property works. This feature is much like selective
+display (*note Selective Display::.), but more general and cleaner.
+
+ More generally, you can use the variable `buffer-invisibility-spec'
+to control which values of the `invisible' property make text
+invisible. This permits you to classify the text into different subsets
+in advance, by giving them different `invisible' values, and
+subsequently make various subsets visible or invisible by changing the
+value of `buffer-invisibility-spec'.
+
+ Controlling visibility with `buffer-invisibility-spec' is especially
+useful in a program to display the list of entries in a data base. It
+permits the implementation of convenient filtering commands to view
+just a part of the entries in the data base. Setting this variable is
+very fast, much faster than scanning all the text in the buffer looking
+for properties to change.
+
+ - Variable: buffer-invisibility-spec
+ This variable specifies which kinds of `invisible' properties
+ actually make a character invisible.
+
+ `t'
+ A character is invisible if its `invisible' property is
+ non-`nil'. This is the default.
+
+ a list
+ Each element of the list makes certain characters invisible.
+ Ultimately, a character is invisible if any of the elements
+ of this list applies to it. The list can have two kinds of
+ elements:
+
+ `ATOM'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+
+ `(ATOM . t)'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+ Moreover, if this character is at the end of a line and
+ is followed by a visible newline, it displays an
+ ellipsis.
+
+ Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible. However, the user-level line motion
+commands explicitly ignore invisible newlines.
+
+\1f
+File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
+
+Selective Display
+=================
+
+ "Selective display" is a pair of features that hide certain lines on
+the screen.
+
+ The first variant, explicit selective display, is designed for use in
+a Lisp program. The program controls which lines are hidden by altering
+the text. Outline mode has traditionally used this variant. It has
+been partially replaced by the invisible text feature (*note Invisible
+Text::.); there is a new version of Outline mode which uses that
+instead.
+
+ In the second variant, the choice of lines to hide is made
+automatically based on indentation. This variant is designed to be a
+user-level feature.
+
+ The way you control explicit selective display is by replacing a
+newline (control-j) with a carriage return (control-m). The text that
+was formerly a line following that newline is now invisible. Strictly
+speaking, it is temporarily no longer a line at all, since only newlines
+can separate lines; it is now part of the previous line.
+
+ Selective display does not directly affect editing commands. For
+example, `C-f' (`forward-char') moves point unhesitatingly into
+invisible text. However, the replacement of newline characters with
+carriage return characters affects some editing commands. For example,
+`next-line' skips invisible lines, since it searches only for newlines.
+Modes that use selective display can also define commands that take
+account of the newlines, or that make parts of the text visible or
+invisible.
+
+ When you write a selectively displayed buffer into a file, all the
+control-m's are output as newlines. This means that when you next read
+in the file, it looks OK, with nothing invisible. The selective display
+effect is seen only within XEmacs.
+
+ - Variable: selective-display
+ This buffer-local variable enables selective display. This means
+ that lines, or portions of lines, may be made invisible.
+
+ * If the value of `selective-display' is `t', then any portion
+ of a line that follows a control-m is not displayed.
+
+ * If the value of `selective-display' is a positive integer,
+ then lines that start with more than that many columns of
+ indentation are not displayed.
+
+ When some portion of a buffer is invisible, the vertical movement
+ commands operate as if that portion did not exist, allowing a
+ single `next-line' command to skip any number of invisible lines.
+ However, character movement commands (such as `forward-char') do
+ not skip the invisible portion, and it is possible (if tricky) to
+ insert or delete text in an invisible portion.
+
+ In the examples below, we show the *display appearance* of the
+ buffer `foo', which changes with the value of `selective-display'.
+ The *contents* of the buffer do not change.
+
+ (setq selective-display nil)
+ => nil
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column
+ 3n this column
+ 3n this column
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ (setq selective-display 2)
+ => 2
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ - Variable: selective-display-ellipses
+ If this buffer-local variable is non-`nil', then XEmacs displays
+ `...' at the end of a line that is followed by invisible text.
+ This example is a continuation of the previous one.
+
+ (setq selective-display-ellipses t)
+ => t
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column ...
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ You can use a display table to substitute other text for the
+ ellipsis (`...'). *Note Display Tables::.
+
+\1f
+File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
+
+The Overlay Arrow
+=================
+
+ The "overlay arrow" is useful for directing the user's attention to
+a particular line in a buffer. For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed.
+
+ - Variable: overlay-arrow-string
+ This variable holds the string to display to call attention to a
+ particular line, or `nil' if the arrow feature is not in use.
+ Despite its name, the value of this variable can be either a string
+ or a glyph (*note Glyphs::.).
+
+ - Variable: overlay-arrow-position
+ This variable holds a marker that indicates where to display the
+ overlay arrow. It should point at the beginning of a line. The
+ arrow text appears at the beginning of that line, overlaying any
+ text that would otherwise appear. Since the arrow is usually
+ short, and the line usually begins with indentation, normally
+ nothing significant is overwritten.
+
+ The overlay string is displayed only in the buffer that this marker
+ points into. Thus, only one buffer can have an overlay arrow at
+ any given time.
+
+ You can do the same job by creating an extent with a `begin-glyph'
+property. *Note Extent Properties::.
+
+\1f
+File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
+
+Temporary Displays
+==================
+
+ Temporary displays are used by commands to put output into a buffer
+and then present it to the user for perusal rather than for editing.
+Many of the help commands use this feature.
+
+ - Special Form: with-output-to-temp-buffer BUFFER-NAME FORMS...
+ This function executes FORMS while arranging to insert any output
+ they print into the buffer named BUFFER-NAME. The buffer is then
+ shown in some window for viewing, displayed but not selected.
+
+ The string BUFFER-NAME specifies the temporary buffer, which need
+ not already exist. The argument must be a string, not a buffer.
+ The buffer is erased initially (with no questions asked), and it is
+ marked as unmodified after `with-output-to-temp-buffer' exits.
+
+ `with-output-to-temp-buffer' binds `standard-output' to the
+ temporary buffer, then it evaluates the forms in FORMS. Output
+ using the Lisp output functions within FORMS goes by default to
+ that buffer (but screen display and messages in the echo area,
+ although they are "output" in the general sense of the word, are
+ not affected). *Note Output Functions::.
+
+ The value of the last form in FORMS is returned.
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ ---------- Buffer: foo ----------
+
+ (with-output-to-temp-buffer "foo"
+ (print 20)
+ (print standard-output))
+ => #<buffer foo>
+
+ ---------- Buffer: foo ----------
+ 20
+
+ #<buffer foo>
+
+ ---------- Buffer: foo ----------
+
+ - Variable: temp-buffer-show-function
+ If this variable is non-`nil', `with-output-to-temp-buffer' calls
+ it as a function to do the job of displaying a help buffer. The
+ function gets one argument, which is the buffer it should display.
+
+ In Emacs versions 18 and earlier, this variable was called
+ `temp-buffer-show-hook'.
+
+ - Function: momentary-string-display STRING POSITION &optional CHAR
+ MESSAGE
+ This function momentarily displays STRING in the current buffer at
+ POSITION. It has no effect on the undo list or on the buffer's
+ modification status.
+
+ The momentary display remains until the next input event. If the
+ next input event is CHAR, `momentary-string-display' ignores it
+ and returns. Otherwise, that event remains buffered for
+ subsequent use as input. Thus, typing CHAR will simply remove the
+ string from the display, while typing (say) `C-f' will remove the
+ string from the display and later (presumably) move point forward.
+ The argument CHAR is a space by default.
+
+ The return value of `momentary-string-display' is not meaningful.
+
+ You can do the same job in a more general way by creating an extent
+ with a begin-glyph property. *Note Extent Properties::.
+
+ If MESSAGE is non-`nil', it is displayed in the echo area while
+ STRING is displayed in the buffer. If it is `nil', a default
+ message says to type CHAR to continue.
+
+ In this example, point is initially located at the beginning of the
+ second line:
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ -!-Second line.
+ ---------- Buffer: foo ----------
+
+ (momentary-string-display
+ "**** Important Message! ****"
+ (point) ?\r
+ "Type RET when done reading")
+ => t
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ **** Important Message! ****Second line.
+ ---------- Buffer: foo ----------
+
+ ---------- Echo Area ----------
+ Type RET when done reading
+ ---------- Echo Area ----------
+
+ This function works by actually changing the text in the buffer.
+ As a result, if you later undo in this buffer, you will see the
+ message come and go.
+
+\1f
+File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
+
+Blinking Parentheses
+====================
+
+ This section describes the mechanism by which XEmacs shows a matching
+open parenthesis when the user inserts a close parenthesis.
+
+ - Variable: blink-paren-function
+ The value of this variable should be a function (of no arguments)
+ to be called whenever a character with close parenthesis syntax is
+ inserted. The value of `blink-paren-function' may be `nil', in
+ which case nothing is done.
+
+ *Please note:* This variable was named `blink-paren-hook' in
+ older Emacs versions, but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `blink-paren-function' in version 19.
+
+ - Variable: blink-matching-paren
+ If this variable is `nil', then `blink-matching-open' does nothing.
+
+ - Variable: blink-matching-paren-distance
+ This variable specifies the maximum distance to scan for a matching
+ parenthesis before giving up.
+
+ - Variable: blink-matching-paren-delay
+ This variable specifies the number of seconds for the cursor to
+ remain at the matching parenthesis. A fraction of a second often
+ gives good results, but the default is 1, which works on all
+ systems.
+
+ - Function: 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
+ character. If that character is not already on the screen, it
+ displays the character's context in the echo area. To avoid long
+ delays, this function does not search farther than
+ `blink-matching-paren-distance' characters.
+
+ Here is an example of calling this function explicitly.
+
+ (defun interactive-blink-matching-open ()
+ "Indicate momentarily the start of sexp before point."
+ (interactive)
+
+ (let ((blink-matching-paren-distance
+ (buffer-size))
+ (blink-matching-paren t))
+ (blink-matching-open)))
+
+\1f
+File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
+
+Usual Display Conventions
+=========================
+
+ The usual display conventions define how to display each character
+code. You can override these conventions by setting up a display table
+(*note Display Tables::.). Here are the usual display conventions:
+
+ * Character codes 32 through 126 map to glyph codes 32 through 126.
+ Normally this means they display as themselves.
+
+ * Character code 9 is a horizontal tab. It displays as whitespace
+ up to a position determined by `tab-width'.
+
+ * Character code 10 is a newline.
+
+ * All other codes in the range 0 through 31, and code 127, display
+ in one of two ways according to the value of `ctl-arrow'. If it is
+ non-`nil', these codes map to sequences of two glyphs, where the
+ first glyph is the ASCII code for `^'. (A display table can
+ specify a glyph to use instead of `^'.) Otherwise, these codes map
+ just like the codes in the range 128 to 255.
+
+ * Character codes 128 through 255 map to sequences of four glyphs,
+ where the first glyph is the ASCII code for `\', and the others are
+ digit characters representing the code in octal. (A display table
+ can specify a glyph to use instead of `\'.)
+
+ The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+`nil'. Thus, when you set up a display table, you need only specify
+the characters for which you want unusual behavior.
+
+ These variables affect the way certain characters are displayed on
+the screen. Since they change the number of columns the characters
+occupy, they also affect the indentation functions.
+
+ - User Option: ctl-arrow
+ This buffer-local variable controls how control characters are
+ displayed. If it is non-`nil', they are displayed as a caret
+ followed by the character: `^A'. If it is `nil', they are
+ displayed as a backslash followed by three octal digits: `\001'.
+
+ - Variable: default-ctl-arrow
+ The value of this variable is the default value for `ctl-arrow' in
+ buffers that do not override it. *Note Default Value::.
+
+ - User Option: tab-width
+ The value of this variable is the spacing between tab stops used
+ for displaying tab characters in Emacs buffers. The default is 8.
+ Note that this feature is completely independent from the
+ user-settable tab stops used by the command `tab-to-tab-stop'.
+ *Note Indent Tabs::.
+
+\1f
+File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
+
+Display Tables
+==============
+
+ You can use the "display table" feature to control how all 256
+possible character codes display on the screen. This is useful for
+displaying European languages that have letters not in the ASCII
+character set.
+
+ The display table maps each character code into a sequence of
+"runes", each rune being an image that takes up one character position
+on the screen. You can also define how to display each rune on your
+terminal, using the "rune table".
+
+* Menu:
+
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How XEmacs selects a display table to use.
+* Character Descriptors:: Format of an individual element of a
+ display table.
+
+\1f
+File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
+
+Display Table Format
+--------------------
+
+ A display table is an array of 256 elements. (In FSF Emacs, a display
+table is 262 elements. The six extra elements specify the truncation
+and continuation glyphs, etc. This method is very kludgey, and in
+XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
+used. *Note Truncation::.)
+
+ - Function: make-display-table
+ This creates and returns a display table. The table initially has
+ `nil' in all elements.
+
+ The 256 elements correspond to character codes; the Nth element says
+how to display the character code N. The value should be `nil', a
+string, a glyph, or a vector of strings and glyphs (*note Character
+Descriptors::.). If an element is `nil', it says to display that
+character according to the usual display conventions (*note Usual
+Display::.).
+
+ If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long "line."
+
+ For example, here is how to construct a display table that mimics the
+effect of setting `ctl-arrow' to a non-`nil' value:
+
+ (setq disptab (make-display-table))
+ (let ((i 0))
+ (while (< i 32)
+ (or (= i ?\t) (= i ?\n)
+ (aset disptab i (concat "^" (char-to-string (+ i 64)))))
+ (setq i (1+ i)))
+ (aset disptab 127 "^?"))
+
+\1f
+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.)
+
+ 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::.
+
+\1f
+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::.).
+
+\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
+
+Beeping
+=======
+
+ You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention. Be conservative about how often you do
+this; frequent bells can become irritating. Also be careful not to use
+beeping alone when signaling an error is appropriate. (*Note Errors::.)
+
+ - Function: ding &optional DONT-TERMINATE SOUND DEVICE
+ This function beeps, or flashes the screen (see `visible-bell'
+ below). It also terminates any keyboard macro currently executing
+ unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
+
+ - Function: beep &optional DONT-TERMINATE SOUND DEVICE
+ This is a synonym for `ding'.
+
+ - User Option: visible-bell
+ This variable determines whether XEmacs should flash the screen to
+ represent a bell. Non-`nil' means yes, `nil' means no. On TTY
+ devices, this is effective only if the Termcap entry for the
+ terminal type has the visible bell flag (`vb') set.
+
+ - Variable: sound-alist
+ This variable holds an alist associating names with sounds. When
+ `beep' or `ding' is called with one of the name symbols, the
+ associated sound will be generated instead of the standard beep.
+
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
+
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
+
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+ `duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be:
+
+ * `( sound-name . <sound> )'
+
+ * `( sound-name <volume> <sound> )'
+
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
+
+ Caveats:
+
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
+
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
+
+ The following beep-types are used by XEmacs itself:
+
+ `auto-save-error'
+ when an auto-save does not succeed
+
+ `command-error'
+ when the XEmacs command loop catches an error
+
+ `undefined-key'
+ when you type a key that is undefined
+
+ `undefined-click'
+ when you use an undefined mouse-click combination
+
+ `no-completion'
+ during completing-read
+
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
+
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
+
+ `default'
+ used when nothing else is appropriate.
+
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
+
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
+
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
+
+ - Command: load-sound-file FILENAME SOUND-NAME &optional VOLUME
+ This function reads in an audio file and adds it to `sound-alist'.
+ The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
+ should be a symbol, specifying the name of the sound. If VOLUME
+ is specified, the sound will be played at that volume; otherwise,
+ the value of BELL-VOLUME will be used.
+
+ - Function: play-sound SOUND &optional VOLUME DEVICE
+ This function plays sound SOUND, which should be a symbol
+ mentioned in `sound-alist'. If VOLUME is specified, it overrides
+ the value (if any) specified in `sound-alist'. DEVICE specifies
+ the device to play the sound on, and defaults to the selected
+ device.
+
+ - Command: play-sound-file FILE &optional VOLUME DEVICE
+ This function plays the named sound file at volume VOLUME, which
+ defaults to `bell-volume'. DEVICE specifies the device to play
+ the sound on, and defaults to the selected device.
+
+\1f
+File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
+
+Hash Tables
+***********
+
+ - Function: hash-table-p OBJECT
+ This function returns `t' if OBJECT is a hash table, else `nil'.
+
+* Menu:
+
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
+
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+ A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::.) and property lists (*note Property Lists::.), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
+
+ A weak hash table is one whose pointers do not count as GC
+ referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ - Function: copy-hash-table HASH-TABLE
+ This function returns a new hash table which contains the same
+ keys and values as HASH-TABLE. The keys and values will not
+ themselves be copied.
+
+ - Function: hash-table-count HASH-TABLE
+ This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test HASH-TABLE
+ This function returns the test function of HASH-TABLE. This can
+ be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size HASH-TABLE
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ - Function: hash-table-rehash-size HASH-TABLE
+ This function returns the current rehash size of HASH-TABLE. This
+ is a float greater than 1.0; the factor by which HASH-TABLE is
+ enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold HASH-TABLE
+ This function returns the current rehash threshold of HASH-TABLE.
+ This is a float between 0.0 and 1.0; the maximum "load factor" of
+ HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness HASH-TABLE
+ This function returns the weakness of HASH-TABLE. This can be one
+ of `nil', `t', `key' or `value'.
+
+\1f
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
+
+Working With Hash Tables
+========================
+
+ - Function: puthash KEY VALUE HASH-TABLE
+ This function hashes KEY to VALUE in HASH-TABLE.
+
+ - Function: gethash KEY HASH-TABLE &optional DEFAULT
+ This function finds the hash value for KEY in HASH-TABLE. If
+ there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+ (which in turn defaults to `nil').
+
+ - Function: remhash KEY HASH-TABLE
+ This function removes the entry for KEY from HASH-TABLE. Does
+ nothing if there is no entry for KEY in HASH-TABLE.
+
+ - Function: clrhash HASH-TABLE
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
+
+ - Function: maphash FUNCTION HASH-TABLE
+ This function maps FUNCTION over entries in HASH-TABLE, calling it
+ with two args, each key and value in the hash table.
+
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
+
+\1f
+File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
+
+Weak Hash Tables
+================
+
+ A "weak hash table" is a special variety of hash table whose
+elements do not count as GC referents. For any key-value pair in such a
+hash table, if either the key or value (or in some cases, if one
+particular one of the two) has no references to it outside of weak hash
+tables (and similar structures such as weak lists), the pair will be
+removed from the table, and the key and value collected. A non-weak
+hash table (or any other pointer) would prevent the objects from being
+collected.
+
+ Weak hash tables are useful for keeping track of information in a
+non-obtrusive way, for example to implement caching. If the cache
+contains objects such as buffers, markers, image instances, etc. that
+will eventually disappear and get garbage-collected, using a weak hash
+table ensures that these objects are collected normally rather than
+remaining around forever, long past their actual period of use.
+(Otherwise, you'd have to explicitly map over the hash table every so
+often and remove unnecessary elements.)
+
+ There are three types of weak hash tables:
+
+fully weak hash tables
+ In these hash tables, a pair disappears if either the key or the
+ value is unreferenced outside of the table.
+
+key-weak hash tables
+ In these hash tables, a pair disappears if the key is unreferenced
+ outside of the table, regardless of how the value is referenced.
+
+value-weak hash tables
+ In these hash tables, a pair disappears if the value is
+ unreferenced outside of the table, regardless of how the key is
+ referenced.
+
+ Also see *Note Weak Lists::.
+
+ Weak hash tables are created by specifying the `:weakness' keyword to
+`make-hash-table'.
+
+\1f
+File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
+
+Range Tables
+************
+
+ A range table is a table that efficiently associated values with
+ranges of integers.
+
+ Note that range tables have a read syntax, like this:
+
+ #s(range-table data ((-3 2) foo (5 20) bar))
+
+ This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
+
+ - Function: range-table-p OBJECT
+ Return non-`nil' if OBJECT is a range table.
+
+* Menu:
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+ integers to values.
+* Working With Range Tables:: Range table functions.
+
+\1f
+File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
+
+Introduction to Range Tables
+============================
+
+ - Function: make-range-table
+ Make a new, empty range table.
+
+ - Function: copy-range-table OLD-TABLE
+ Make a new range table which contains the same values for the same
+ ranges as the given table. The values will not themselves be
+ copied.
+
+\1f
+File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
+
+Working With Range Tables
+=========================
+
+ - Function: get-range-table POS TABLE &optional DEFAULT
+ This function finds value for position POS in TABLE. If there is
+ no corresponding value, return DEFAULT (defaults to `nil').
+
+ - Function: put-range-table START END VAL TABLE
+ This function sets the value for range (START, END) to be VAL in
+ TABLE.
+
+ - Function: remove-range-table START END TABLE
+ This function removes the value for range (START, END) in TABLE.
+
+ - Function: clear-range-table TABLE
+ This function flushes TABLE.
+
+ - Function: map-range-table FUNCTION TABLE
+ This function maps FUNCTION over entries in TABLE, calling it with
+ three args, the beginning and end of the range and the
+ corresponding value.
+
+\1f
+File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
+
+Databases
+*********
+
+ - Function: databasep OBJECT
+ This function returns non-`nil' if OBJECT is a database.
+
+* Menu:
+
+* Connecting to a Database::
+* Working With a Database::
+* Other Database Functions::
+
+\1f
+File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
+
+Connecting to a Database
+========================
+
+ - Function: open-database FILE &optional TYPE SUBTYPE ACCESS MODE
+ This function opens database FILE, using database method TYPE and
+ SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
+ can be any combination of `r' `w' and `+', for read, write, and
+ creation flags.
+
+ TYPE can have the value `'dbm' or `'berkeley_db' to select the
+ type of database file to use. (Note: XEmacs may not support both
+ of these types.)
+
+ For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by
+ `nil'.
+
+ For a TYPE of `'berkeley_db', the following subtypes are
+ available: `'hash', `'btree', and `'recno'. See the manpages for
+ the Berkeley DB functions to more information about these types.
+
+ - Function: close-database OBJ
+ This function closes database OBJ.
+
+ - Function: database-live-p OBJ
+ This function returns `t' iff OBJ is an active database, else
+ `nil'.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
+
+Working With a Database
+=======================
+
+ - Function: get-database KEY DBASE &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
+ 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
+ database.
+
+ - Function: remove-database KEY DBASE
+ This function removes KEY from DATABASE.
+
+\1f
+File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
+
+Other Database Functions
+========================
+
+ - Function: database-file-name OBJ
+ This function returns the filename associated with the database
+ OBJ.
+
+ - Function: database-last-error &optional OBJ
+ This function returns the last error associated with database OBJ.
+
+ - Function: database-subtype OBJ
+ This function returns the subtype of database OBJ, if any.
+
+ - Function: database-type OBJ
+ This function returns the type of database OBJ.
+
+\1f
+File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
+
+Processes
+*********
+
+ In the terminology of operating systems, a "process" is a space in
+which a program can execute. XEmacs runs in a process. XEmacs Lisp
+programs can invoke other programs in processes of their own. These are
+called "subprocesses" or "child processes" of the XEmacs process, which
+is their "parent process".
+
+ A subprocess of XEmacs may be "synchronous" or "asynchronous",
+depending on how it is created. When you create a synchronous
+subprocess, the Lisp program waits for the subprocess to terminate
+before continuing execution. When you create an asynchronous
+subprocess, it can run in parallel with the Lisp program. This kind of
+subprocess is represented within XEmacs by a Lisp object which is also
+called a "process". Lisp programs can use this object to communicate
+with the subprocess or to control it. For example, you can send
+signals, obtain status information, receive output from the process, or
+send input to it.
+
+ - Function: processp OBJECT
+ This function returns `t' if OBJECT is a process, `nil' otherwise.
+
+* Menu:
+
+* Subprocess Creation:: Functions that start subprocesses.
+* Synchronous Processes:: Details of using synchronous subprocesses.
+* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
+ for data sent to and from a subprocess.
+* Asynchronous Processes:: Starting up an asynchronous subprocess.
+* Deleting Processes:: Eliminating an asynchronous subprocess.
+* Process Information:: Accessing run-status and other attributes.
+* Input to Processes:: Sending input to an asynchronous subprocess.
+* Signals to Processes:: Stopping, continuing or interrupting
+ an asynchronous subprocess.
+* Output from Processes:: Collecting output from an asynchronous subprocess.
+* Sentinels:: Sentinels run when process run-status changes.
+* Process Window Size:: Changing the logical window size of a process.
+* Transaction Queues:: Transaction-based communication with subprocesses.
+* Network:: Opening network connections.
+
+\1f
+File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
+
+Functions that Create Subprocesses
+==================================
+
+ There are three functions that create a new subprocess in which to
+run a program. One of them, `start-process', creates an asynchronous
+process and returns a process object (*note Asynchronous Processes::.).
+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
+sections. Since the three functions are all called in a similar
+fashion, their common arguments are described here.
+
+ In all cases, the function's PROGRAM argument specifies the program
+to be run. An error is signaled if the file is not found or cannot be
+executed. If the file name is relative, the variable `exec-path'
+contains a list of directories to search. Emacs initializes
+`exec-path' when it starts up, based on the value of the environment
+variable `PATH'. The standard file name constructs, `~', `.', and
+`..', are interpreted as usual in `exec-path', but environment variable
+substitutions (`$HOME', etc.) are not recognized; use
+`substitute-in-file-name' to perform them (*note File Name
+Expansion::.).
+
+ Each of the subprocess-creating functions has a BUFFER-OR-NAME
+argument which specifies where the standard output from the program will
+go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
+a filter function handles it. (*Note Filter Functions::, and *Note
+Read and Print::.) Normally, you should avoid having multiple
+processes send output to the same buffer because their output would be
+intermixed randomly.
+
+ All three of the subprocess-creating functions have a `&rest'
+argument, ARGS. The ARGS must all be strings, and they are supplied to
+PROGRAM as separate command line arguments. Wildcard characters and
+other shell constructs are not allowed in these strings, since they are
+passed directly to the specified program.
+
+ *Please note:* The argument PROGRAM contains only the name of the
+program; it may not contain any command-line arguments. You must use
+ARGS to provide those.
+
+ The subprocess gets its current directory from the value of
+`default-directory' (*note File Name Expansion::.).
+
+ The subprocess inherits its environment from XEmacs; but you can
+specify overrides for it with `process-environment'. *Note System
+Environment::.
+
+ - Variable: exec-directory
+ The value of this variable is the name of a directory (a string)
+ that contains programs that come with XEmacs, that are intended
+ for XEmacs to invoke. The program `wakeup' is an example of such
+ a program; the `display-time' command uses it to get a reminder
+ once per minute.
+
+ - User Option: exec-path
+ The value of this variable is a list of directories to search for
+ programs to run in subprocesses. Each element is either the name
+ of a directory (i.e., a string), or `nil', which stands for the
+ default directory (which is the value of `default-directory').
+
+ The value of `exec-path' is used by `call-process' and
+ `start-process' when the PROGRAM argument is not an absolute file
+ name.
+
+\1f
+File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
+
+Creating a Synchronous Process
+==============================
+
+ After a "synchronous process" is created, XEmacs waits for the
+process to terminate before continuing. Starting Dired is an example of
+this: it runs `ls' in a synchronous process, then modifies the output
+slightly. Because the process is synchronous, the entire directory
+listing arrives in the buffer before XEmacs tries to do anything with
+it.
+
+ While Emacs waits for the synchronous subprocess to terminate, the
+user can quit by typing `C-g'. The first `C-g' tries to kill the
+subprocess with a `SIGINT' signal; but it waits until the subprocess
+actually terminates before quitting. If during that time the user
+types another `C-g', that kills the subprocess instantly with `SIGKILL'
+and quits immediately. *Note Quitting::.
+
+ The synchronous subprocess functions returned `nil' in version 18.
+In version 19, they return an indication of how the process terminated.
+
+ - Function: call-process PROGRAM &optional INFILE DESTINATION DISPLAY
+ &rest ARGS
+ This function calls PROGRAM in a separate process and waits for it
+ to finish.
+
+ The standard input for the process comes from file INFILE if
+ INFILE is not `nil' and from `/dev/null' otherwise. The argument
+ DESTINATION says where to put the process output. Here are the
+ possibilities:
+
+ a buffer
+ Insert the output in that buffer, before point. This
+ includes both the standard output stream and the standard
+ error stream of the process.
+
+ a string
+ Find or create a buffer with that name, then insert the
+ output in that buffer, before point.
+
+ `t'
+ Insert the output in the current buffer, before point.
+
+ `nil'
+ Discard the output.
+
+ 0
+ Discard the output, and return immediately without waiting
+ for the subprocess to finish.
+
+ In this case, the process is not truly synchronous, since it
+ can run in parallel with Emacs; but you can think of it as
+ synchronous in that Emacs is essentially finished with the
+ subprocess as soon as this function returns.
+
+ (REAL-DESTINATION ERROR-DESTINATION)
+ Keep the standard output stream separate from the standard
+ error stream; deal with the ordinary output as specified by
+ REAL-DESTINATION, and dispose of the error output according
+ to ERROR-DESTINATION. The value `nil' means discard it, `t'
+ means mix it with the ordinary output, and a string specifies
+ a file name to redirect error output into.
+
+ You can't directly specify a buffer to put the error output
+ in; that is too difficult to implement. But you can achieve
+ this result by sending the error output to a temporary file
+ and then inserting the file into a buffer.
+
+ If DISPLAY is non-`nil', then `call-process' redisplays the buffer
+ as output is inserted. Otherwise the function does no redisplay,
+ and the results become visible on the screen only when XEmacs
+ redisplays that buffer in the normal course of events.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The value returned by `call-process' (unless you told it not to
+ wait) indicates the reason for process termination. A number
+ gives the exit status of the subprocess; 0 means success, and any
+ other value means failure. If the process terminated with a
+ signal, `call-process' returns a string describing the signal.
+
+ In the examples below, the buffer `foo' is current.
+
+ (call-process "pwd" nil t)
+ => nil
+
+ ---------- Buffer: foo ----------
+ /usr/user/lewis/manual
+ ---------- Buffer: foo ----------
+
+ (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
+ => nil
+
+ ---------- Buffer: bar ----------
+ lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+
+ ---------- Buffer: bar ----------
+
+ The `insert-directory' function contains a good example of the use
+ of `call-process':
+
+ (call-process insert-directory-program nil t nil switches
+ (if full-directory-p
+ (concat (file-name-as-directory file) ".")
+ file))
+
+ - Function: call-process-region START END PROGRAM &optional DELETE
+ DESTINATION DISPLAY &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
+ the output in the current buffer.
+
+ The arguments DESTINATION and DISPLAY 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'
+ discards the output and returns `nil' immediately, without waiting
+ for the subprocess to finish.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The return value of `call-process-region' is just like that of
+ `call-process': `nil' if you told it to return without waiting;
+ otherwise, a number or string which indicates how the subprocess
+ terminated.
+
+ In the following example, we use `call-process-region' to run the
+ `cat' utility, with standard input being the first five characters
+ in buffer `foo' (the word `input'). `cat' copies its standard
+ input into its standard output. Since the argument DESTINATION is
+ `t', this output is inserted in the current buffer.
+
+ ---------- Buffer: foo ----------
+ input-!-
+ ---------- Buffer: foo ----------
+
+ (call-process-region 1 6 "cat" nil t)
+ => nil
+
+ ---------- Buffer: foo ----------
+ inputinput-!-
+ ---------- Buffer: foo ----------
+
+ The `shell-command-on-region' command uses `call-process-region'
+ like this:
+
+ (call-process-region
+ start end
+ shell-file-name ; Name of program.
+ nil ; Do not delete region.
+ buffer ; Send output to `buffer'.
+ nil ; No redisplay during output.
+ "-c" command) ; Arguments for the shell.
+
+\1f
+File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
+
+MS-DOS Subprocesses
+===================
+
+ On MS-DOS, you must indicate whether the data going to and from a
+synchronous subprocess are text or binary. Text data requires
+translation between the end-of-line convention used within Emacs (a
+single newline character) and the convention used outside Emacs (the
+two-character sequence, CRLF).
+
+ The variable `binary-process-input' applies to input sent to the
+subprocess, and `binary-process-output' applies to output received from
+it. A non-`nil' value means the data is non-text; `nil' means the data
+is text, and calls for conversion.
+
+ - Variable: binary-process-input
+ If this variable is `nil', convert newlines to CRLF sequences in
+ the input to a synchronous subprocess.
+
+ - Variable: binary-process-output
+ If this variable is `nil', convert CRLF sequences to newlines in
+ the output from a synchronous subprocess.
+
+ *Note Files and MS-DOS::, for related information.
+
+\1f
+File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
+
+Creating an Asynchronous Process
+================================
+
+ After an "asynchronous process" is created, Emacs and the Lisp
+program both continue running immediately. The process may thereafter
+run in parallel with Emacs, and the two may communicate with each other
+using the functions described in following sections. Here we describe
+how to create an asynchronous process with `start-process'.
+
+ - Function: start-process NAME BUFFER-OR-NAME PROGRAM &rest ARGS
+ This function creates a new asynchronous subprocess and starts the
+ program PROGRAM running in it. It returns a process object that
+ stands for the new subprocess in Lisp. The argument NAME
+ specifies the name for the process object; if a process with this
+ name already exists, then NAME is modified (by adding `<1>', etc.)
+ to be unique. The buffer BUFFER-OR-NAME is the buffer to
+ associate with the process.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ In the example below, the first process is started and runs
+ (rather, sleeps) for 100 seconds. Meanwhile, the second process
+ is started, and given the name `my-process<1>' for the sake of
+ uniqueness. It inserts the directory listing at the end of the
+ buffer `foo', before the first process finishes. Then it
+ finishes, and a message to that effect is inserted in the buffer.
+ Much later, the first process finishes, and another message is
+ inserted in the buffer for it.
+
+ (start-process "my-process" "foo" "sleep" "100")
+ => #<process my-process>
+
+ (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+ => #<process my-process<1>>
+
+ ---------- Buffer: foo ----------
+ total 2
+ lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
+ -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+
+ Process my-process<1> finished
+
+ Process my-process finished
+ ---------- Buffer: foo ----------
+
+ - Function: start-process-shell-command NAME BUFFER-OR-NAME COMMAND
+ &rest COMMAND-ARGS
+ This function is like `start-process' except that it uses a shell
+ to execute the specified command. The argument COMMAND is a shell
+ command name, and COMMAND-ARGS are the arguments for the shell
+ command.
+
+ - Variable: process-connection-type
+ This variable controls the type of device used to communicate with
+ asynchronous subprocesses. If it is non-`nil', then PTYs are
+ used, when available. Otherwise, pipes are used.
+
+ PTYs are usually preferable for processes visible to the user, as
+ in Shell mode, because they allow job control (`C-c', `C-z', etc.)
+ to work between the process and its children whereas pipes do not.
+ 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.
+
+ The value `process-connection-type' is used when `start-process'
+ is called. So you can specify how to communicate with one
+ subprocess by binding the variable around the call to
+ `start-process'.
+
+ (let ((process-connection-type nil)) ; Use a pipe.
+ (start-process ...))
+
+ To determine whether a given subprocess actually got a pipe or a
+ PTY, use the function `process-tty-name' (*note Process
+ Information::.).
+
+\1f
+File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
+
+Deleting Processes
+==================
+
+ "Deleting a process" disconnects XEmacs immediately from the
+subprocess, and removes it from the list of active processes. It sends
+a signal to the subprocess to make the subprocess terminate, but this is
+not guaranteed to happen immediately. The process object itself
+continues to exist as long as other Lisp objects point to it.
+
+ You can delete a process explicitly at any time. Processes are
+deleted automatically after they terminate, but not necessarily right
+away. If you delete a terminated process explicitly before it is
+deleted automatically, no harm results.
+
+ - Variable: delete-exited-processes
+ This variable controls automatic deletion of processes that have
+ terminated (due to calling `exit' or to a signal). If it is
+ `nil', then they continue to exist until the user runs
+ `list-processes'. Otherwise, they are deleted immediately after
+ they exit.
+
+ - Function: delete-process NAME
+ This function deletes the process associated with NAME, killing it
+ with a `SIGHUP' signal. The argument NAME may be a process, the
+ name of a process, a buffer, or the name of a buffer.
+
+ (delete-process "*shell*")
+ => nil
+
+ - Function: process-kill-without-query PROCESS &optional
+ REQUIRE-QUERY-P
+ This function declares that XEmacs need not query the user if
+ PROCESS is still running when XEmacs is exited. The process will
+ be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
+ *will* query the user (this is the default). The return value is
+ `t' if a query was formerly required, and `nil' otherwise.
+
+ (process-kill-without-query (get-process "shell"))
+ => t
+
+\1f
+File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
+
+Process Information
+===================
+
+ Several functions return information about processes.
+`list-processes' is provided for interactive use.
+
+ - Command: list-processes
+ This command displays a listing of all living processes. In
+ addition, it finally deletes any process whose status was `Exited'
+ or `Signaled'. It returns `nil'.
+
+ - Function: process-list
+ This function returns a list of all processes that have not been
+ deleted.
+
+ (process-list)
+ => (#<process display-time> #<process shell>)
+
+ - 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.
+
+ (get-process "shell")
+ => #<process shell>
+
+ - Function: process-command PROCESS
+ This function returns the command that was executed to start
+ PROCESS. This is a list of strings, the first string being the
+ program executed and the rest of the strings being the arguments
+ that were given to the program.
+
+ (process-command (get-process "shell"))
+ => ("/bin/csh" "-i")
+
+ - Function: process-id PROCESS
+ This function returns the PID of PROCESS. This is an integer that
+ distinguishes the process PROCESS from all other processes running
+ on the same computer at the current time. The PID of a process is
+ chosen by the operating system kernel when the process is started
+ and remains constant as long as the process exists.
+
+ - 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
+ (string) or a buffer name (string).
+
+ The possible values for an actual subprocess are:
+
+ `run'
+ for a process that is running.
+
+ `stop'
+ for a process that is stopped but continuable.
+
+ `exit'
+ for a process that has exited.
+
+ `signal'
+ for a process that has received a fatal signal.
+
+ `open'
+ for a network connection that is open.
+
+ `closed'
+ for a network connection that is closed. Once a connection
+ is closed, you cannot reopen it, though you might be able to
+ open a new connection to the same place.
+
+ `nil'
+ if PROCESS-NAME is not the name of an existing process.
+
+ (process-status "shell")
+ => run
+
+ (process-status (get-buffer "*shell*"))
+ => run
+
+ x
+ => #<process xx<1>>
+ (process-status x)
+ => exit
+
+ For a network connection, `process-status' returns one of the
+ symbols `open' or `closed'. The latter means that the other side
+ closed the connection, or XEmacs did `delete-process'.
+
+ In earlier Emacs versions (prior to version 19), the status of a
+ network connection was `run' if open, and `exit' if closed.
+
+ - Function: process-kill-without-query-p PROCESS
+ This function returns whether PROCESS will be killed without
+ querying the user, if it is running when XEmacs is exited. The
+ default value is `nil'.
+
+ - Function: process-exit-status PROCESS
+ This function returns the exit status of PROCESS or the signal
+ number that killed it. (Use the result of `process-status' to
+ determine which of those it is.) If PROCESS has not yet
+ terminated, the value is 0.
+
+ - Function: process-tty-name PROCESS
+ This function returns the terminal name that PROCESS is using for
+ its communication with Emacs--or `nil' if it is using pipes
+ instead of a terminal (see `process-connection-type' in *Note
+ Asynchronous Processes::).
+
+\1f
+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"
+
+\1f
+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 usually indicates that the user
+hung up the phone.)
+
+ Each of the signal-sending functions takes two optional arguments:
+PROCESS-NAME and CURRENT-GROUP.
+
+ The argument PROCESS-NAME must be either a process, 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-NAME 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 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::.
+
+ - Function: interrupt-process &optional PROCESS-NAME CURRENT-GROUP
+ This function interrupts the process PROCESS-NAME by sending the
+ signal `SIGINT'. Outside of XEmacs, typing the "interrupt
+ character" (normally `C-c' on some systems, and `DEL' on others)
+ 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-NAME CURRENT-GROUP
+ This function kills the process PROCESS-NAME by sending the signal
+ `SIGKILL'. This signal kills the subprocess immediately, and
+ cannot be handled by the subprocess.
+
+ - Function: quit-process &optional PROCESS-NAME CURRENT-GROUP
+ This function sends the signal `SIGQUIT' to the process
+ PROCESS-NAME. This signal is the one sent by the "quit character"
+ (usually `C-b' or `C-\') when you are not inside XEmacs.
+
+ - Function: stop-process &optional PROCESS-NAME CURRENT-GROUP
+ This function stops the process PROCESS-NAME 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-NAME CURRENT-GROUP
+ This function resumes execution of the process PROCESS by sending
+ it the signal `SIGCONT'. This presumes that PROCESS-NAME was
+ stopped previously.
+
+ - Function: signal-process PID SIGNAL
+ This function sends a signal to process PID, which need not be a
+ child of XEmacs. The argument SIGNAL specifies which signal to
+ send; it should be an integer.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
+
+Process Buffers
+---------------
+
+ A process can (and usually does) have an "associated buffer", which
+is an ordinary Emacs buffer that is used for two purposes: storing the
+output from the process, and deciding when to kill the process. You
+can also use the buffer to identify a process to operate on, since in
+normal practice only one process is associated with any given buffer.
+Many applications of processes also use the buffer for editing input to
+be sent to the process, but this is not built into XEmacs Lisp.
+
+ Unless the process has a filter function (*note Filter Functions::.),
+its output is inserted in the associated buffer. The position to insert
+the output is determined by the `process-mark', which is then updated
+to point to the end of the text just inserted. Usually, but not
+always, the `process-mark' is at the end of the buffer.
+
+ - Function: process-buffer PROCESS
+ This function returns the associated buffer of the process PROCESS.
+
+ (process-buffer (get-process "shell"))
+ => #<buffer *shell*>
+
+ - Function: process-mark PROCESS
+ This function returns the process marker for PROCESS, which is the
+ marker that says where to insert output from the process.
+
+ If PROCESS does not have a buffer, `process-mark' returns a marker
+ that points nowhere.
+
+ Insertion of process output in a buffer uses this marker to decide
+ where to insert, and updates it to point after the inserted text.
+ That is why successive batches of output are inserted
+ consecutively.
+
+ Filter functions normally should use this marker in the same
+ fashion as is done by direct insertion of output in the buffer. A
+ good example of a filter function that uses `process-mark' is
+ found at the end of the following section.
+
+ When the user is expected to enter input in the process buffer for
+ transmission to the process, the process marker is useful for
+ distinguishing the new input from previous output.
+
+ - Function: set-process-buffer PROCESS BUFFER
+ This function sets the buffer associated with PROCESS to BUFFER.
+ If BUFFER is `nil', the process becomes associated with no buffer.
+
+ - Function: get-buffer-process BUFFER-OR-NAME
+ This function returns the process associated with BUFFER-OR-NAME.
+ If there are several processes associated with it, then one is
+ chosen. (Presently, the one chosen is the one most recently
+ created.) It is usually a bad idea to have more than one process
+ associated with the same buffer.
+
+ (get-buffer-process "*shell*")
+ => #<process shell>
+
+ Killing the process's buffer deletes the process, which kills the
+ subprocess with a `SIGHUP' signal (*note Signals to Processes::.).
+
+\1f
+File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
+
+Process Filter Functions
+------------------------
+
+ A process "filter function" is a function that receives the standard
+output from the associated process. If a process has a filter, then
+*all* output from that process is passed to the filter. The process
+buffer is used directly for output from the process only when there is
+no filter.
+
+ A filter function must accept two arguments: the associated process
+and a string, which is the output. The function is then free to do
+whatever it chooses with the output.
+
+ A filter function runs only while XEmacs is waiting (e.g., for
+terminal input, or for time to elapse, or for process output). This
+avoids the timing errors that could result from running filters at
+random places in the middle of other Lisp programs. You may explicitly
+cause Emacs to wait, so that filter functions will run, by calling
+`sit-for' or `sleep-for' (*note Waiting::.), or `accept-process-output'
+(*note Accepting Output::.). Emacs is also waiting when the command
+loop is reading input.
+
+ Quitting is normally inhibited within a filter function--otherwise,
+the effect of typing `C-g' at command level or to quit a user command
+would be unpredictable. If you want to permit quitting inside a filter
+function, bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ If an error happens during execution of a filter function, it is
+caught automatically, so that it doesn't stop the execution of whatever
+program was running when the filter function was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the filter
+function. *Note Debugger::.
+
+ Many filter functions sometimes or always insert the text in the
+process's buffer, mimicking the actions of XEmacs when there is no
+filter. Such filter functions need to use `set-buffer' in order to be
+sure to insert in that buffer. To avoid setting the current buffer
+semipermanently, these filter functions must use `unwind-protect' to
+make sure to restore the previous current buffer. They should also
+update the process marker, and in some cases update the value of point.
+Here is how to do these things:
+
+ (defun ordinary-insertion-filter (proc string)
+ (let ((old-buffer (current-buffer)))
+ (unwind-protect
+ (let (moving)
+ (set-buffer (process-buffer proc))
+ (setq moving (= (point) (process-mark proc)))
+
+ (save-excursion
+ ;; Insert the text, moving the process-marker.
+ (goto-char (process-mark proc))
+ (insert string)
+ (set-marker (process-mark proc) (point)))
+ (if moving (goto-char (process-mark proc))))
+ (set-buffer old-buffer))))
+
+The reason to use an explicit `unwind-protect' rather than letting
+`save-excursion' restore the current buffer is so as to preserve the
+change in point made by `goto-char'.
+
+ To make the filter force the process buffer to be visible whenever
+new text arrives, insert the following line just before the
+`unwind-protect':
+
+ (display-buffer (process-buffer proc))
+
+ To force point to move to the end of the new output no matter where
+it was previously, eliminate the variable `moving' and call `goto-char'
+unconditionally.
+
+ In earlier Emacs versions, every filter function that did regexp
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically; filter functions never need to do it
+explicitly. *Note Match Data::.
+
+ A filter function that writes the output into the buffer of the
+process should check whether the buffer is still alive. If it tries to
+insert into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ The output to the function may come in chunks of any size. A program
+that produces the same output twice in a row may send it as one batch
+of 200 characters one time, and five batches of 40 characters the next.
+
+ - Function: set-process-filter PROCESS FILTER
+ This function gives PROCESS the filter function FILTER. If FILTER
+ is `nil', then the process will have no filter. If FILTER is `t',
+ then no output from the process will be accepted until the filter
+ is changed. (Output received during this time is not discarded,
+ but is queued, and will be processed as soon as the filter is
+ changed.)
+
+ - Function: process-filter PROCESS
+ This function returns the filter function of PROCESS, or `nil' if
+ it has none. `t' means that output processing has been stopped.
+
+ Here is an example of use of a filter function:
+
+ (defun keep-output (process output)
+ (setq kept (cons output kept)))
+ => keep-output
+
+ (setq kept nil)
+ => nil
+
+ (set-process-filter (get-process "shell") 'keep-output)
+ => keep-output
+
+ (process-send-string "shell" "ls ~/other\n")
+ => nil
+ kept
+ => ("lewis@slug[8] % "
+
+ "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
+ address.txt backup.psf kolstad.psf
+ backup.bib~ david.mss resume-Dec-86.mss~
+ backup.err david.psf resume-Dec.psf
+ backup.mss dland syllabus.mss
+ "
+ "#backups.mss# backup.mss~ kolstad.mss
+ ")
+
+\1f
+File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
+
+Accepting Output from Processes
+-------------------------------
+
+ Output from asynchronous subprocesses normally arrives only while
+XEmacs is waiting for some sort of external event, such as elapsed time
+or terminal input. Occasionally it is useful in a Lisp program to
+explicitly permit output to arrive at a specific point, or even to wait
+until output arrives from a process.
+
+ - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
+ This function allows XEmacs to read pending output from processes.
+ The output is inserted in the associated buffers or given to
+ their filter functions. If PROCESS is non-`nil' then this
+ function does not return until some output has been received from
+ PROCESS.
+
+ The arguments SECONDS and MILLISEC let you specify timeout
+ periods. The former specifies a period measured in seconds and the
+ latter specifies one measured in milliseconds. The two time
+ periods thus specified are added together, and
+ `accept-process-output' returns after that much time whether or
+ not there has been any subprocess output. Note that SECONDS is
+ allowed to be a floating-point number; thus, there is no need to
+ ever use MILLISEC. (It is retained for compatibility purposes.)
+
+ The function `accept-process-output' returns non-`nil' if it did
+ get some output, or `nil' if the timeout expired before output
+ arrived.
+
+\1f
+File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
+
+Sentinels: Detecting Process Status Changes
+===========================================
+
+ A "process sentinel" is a function that is called whenever the
+associated process changes status for any reason, including signals
+(whether sent by XEmacs or caused by the process's own actions) that
+terminate, stop, or continue the process. The process sentinel is also
+called if the process exits. The sentinel receives two arguments: the
+process for which the event occurred, and a string describing the type
+of event.
+
+ The string describing the event looks like one of the following:
+
+ * `"finished\n"'.
+
+ * `"exited abnormally with code EXITCODE\n"'.
+
+ * `"NAME-OF-SIGNAL\n"'.
+
+ * `"NAME-OF-SIGNAL (core dumped)\n"'.
+
+ A sentinel runs only while XEmacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output). This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs. A program can wait, so that
+sentinels will run, by calling `sit-for' or `sleep-for' (*note
+Waiting::.), or `accept-process-output' (*note Accepting Output::.).
+Emacs is also waiting when the command loop is reading input.
+
+ Quitting is normally inhibited within a sentinel--otherwise, the
+effect of typing `C-g' at command level or to quit a user command would
+be unpredictable. If you want to permit quitting inside a sentinel,
+bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive. If it tries to insert
+into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the sentinel.
+*Note Debugger::.
+
+ In earlier Emacs versions, every sentinel that did regexp searching
+or matching had to explicitly save and restore the match data. Now
+Emacs does this automatically; sentinels never need to do it explicitly.
+*Note Match Data::.
+
+ - Function: set-process-sentinel PROCESS SENTINEL
+ This function associates SENTINEL with PROCESS. If SENTINEL is
+ `nil', then the process will have no sentinel. The default
+ behavior when there is no sentinel is to insert a message in the
+ process's buffer when the process status changes.
+
+ (defun msg-me (process event)
+ (princ
+ (format "Process: %s had the event `%s'" process event)))
+ (set-process-sentinel (get-process "shell") 'msg-me)
+ => msg-me
+
+ (kill-process (get-process "shell"))
+ -| Process: #<process shell> had the event `killed'
+ => #<process shell>
+
+ - Function: process-sentinel PROCESS
+ This function returns the sentinel of PROCESS, or `nil' if it has
+ none.
+
+ - Function: waiting-for-user-input-p
+ While a sentinel or filter function is running, this function
+ returns non-`nil' if XEmacs was waiting for keyboard input from
+ the user at the time the sentinel or filter function was called,
+ `nil' if it was not.
+
+\1f
+File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
+
+Process Window Size
+===================
+
+ - Function: set-process-window-size PROCESS HEIGHT WIDTH
+ This function tells PROCESS that its logical window size is HEIGHT
+ by WIDTH characters. This is principally useful with pty's.
+
+\1f
+File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
+
+Transaction Queues
+==================
+
+ You can use a "transaction queue" for more convenient communication
+with subprocesses using transactions. First use `tq-create' to create
+a transaction queue communicating with a specified process. Then you
+can call `tq-enqueue' to send a transaction.
+
+ - Function: tq-create PROCESS
+ This function creates and returns a transaction queue
+ communicating with PROCESS. The argument PROCESS should be a
+ subprocess capable of sending and receiving streams of bytes. It
+ may be a child process, or it may be a TCP connection to a server,
+ possibly on another machine.
+
+ - Function: tq-enqueue QUEUE QUESTION REGEXP CLOSURE FN
+ This function sends a transaction to queue QUEUE. Specifying the
+ queue has the effect of specifying the subprocess to talk to.
+
+ The argument QUESTION is the outgoing message that starts the
+ transaction. The argument FN is the function to call when the
+ corresponding answer comes back; it is called with two arguments:
+ CLOSURE, and the answer received.
+
+ The argument REGEXP is a regular expression that should match the
+ entire answer, but nothing less; that's how `tq-enqueue' determines
+ where the answer ends.
+
+ The return value of `tq-enqueue' itself is not meaningful.
+
+ - Function: tq-close QUEUE
+ Shut down transaction queue QUEUE, waiting for all pending
+ transactions to complete, and then terminate the connection or
+ child process.
+
+ Transaction queues are implemented by means of a filter function.
+*Note Filter Functions::.
+
+\1f
+File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
+
+Network Connections
+===================
+
+ XEmacs Lisp programs can open TCP network connections to other
+processes on the same machine or other machines. A network connection
+is handled by Lisp much like a subprocess, and is represented by a
+process object. However, the process you are communicating with is not
+a child of the XEmacs process, so you can't kill it or send it signals.
+All you can do is send and receive data. `delete-process' closes the
+connection, but does not kill the process at the other end; that
+process must decide what to do about closure of the connection.
+
+ You can distinguish process objects representing network connections
+from those representing subprocesses with the `process-status'
+function. It always returns either `open' or `closed' for a network
+connection, and it never returns either of those values for a real
+subprocess. *Note Process Information::.
+
+ - Function: open-network-stream NAME BUFFER-OR-NAME HOST SERVICE
+ This function opens a TCP connection for a service to a host. It
+ returns a process object to represent the connection.
+
+ The NAME argument specifies the name for the process object. It
+ is modified as necessary to make it unique.
+
+ The BUFFER-OR-NAME argument is the buffer to associate with the
+ connection. Output from the connection is inserted in the buffer,
+ unless you specify a filter function to handle the output. If
+ BUFFER-OR-NAME is `nil', it means that the connection is not
+ associated with any buffer.
+
+ The arguments HOST and SERVICE specify where to connect to; HOST
+ is the host name or IP address (a string), and SERVICE is the name
+ of a defined network service (a string) or a port number (an
+ integer).
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
+
+Operating System Interface
+**************************
+
+ This chapter is about starting and getting out of Emacs, access to
+values in the operating system environment, and terminal input, output,
+and flow control.
+
+ *Note Building XEmacs::, for related information. See also *Note
+Display::, for additional operating system status information
+pertaining to the terminal and the screen.
+
+* Menu:
+
+* Starting Up:: Customizing XEmacs start-up processing.
+* Getting Out:: How exiting works (permanent or temporary).
+* System Environment:: Distinguish the name and kind of system.
+* User Identification:: Finding the name and user id of the user.
+* Time of Day:: Getting the current time.
+* Time Conversion:: Converting a time from numeric form to a string, or
+ to calendrical data (or vice versa).
+* Timers:: Setting a timer to call a function at a certain time.
+* Terminal Input:: Recording terminal input for debugging.
+* Terminal Output:: Recording terminal output for debugging.
+* Flow Control:: How to turn output flow control on or off.
+* Batch Mode:: Running XEmacs without terminal interaction.
+
+\1f
+File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
+
+Starting Up XEmacs
+==================
+
+ This section describes what XEmacs does when it is started, and how
+you can customize these actions.
+
+* Menu:
+
+* Start-up Summary:: Sequence of actions XEmacs performs at start-up.
+* Init File:: Details on reading the init file (`.emacs').
+* Terminal-Specific:: How the terminal-specific Lisp file is read.
+* Command Line Arguments:: How command line arguments are processed,
+ and how you can customize them.
+
+\1f
+File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
+
+Summary: Sequence of Actions at Start Up
+----------------------------------------
+
+ The order of operations performed (in `startup.el') by XEmacs when
+it is started up is as follows:
+
+ 1. It loads the initialization library for the window system, if you
+ are using a window system. This library's name is
+ `term/WINDOWSYSTEM-win.el'.
+
+ 2. It processes the initial options. (Some of them are handled even
+ earlier than this.)
+
+ 3. It initializes the X window frame and faces, if appropriate.
+
+ 4. It runs the normal hook `before-init-hook'.
+
+ 5. It loads the library `site-start', unless the option
+ `-no-site-file' was specified. The library's file name is usually
+ `site-start.el'.
+
+ 6. It loads the file `~/.emacs' unless `-q' was specified on the
+ command line. (This is not done in `-batch' mode.) The `-u'
+ option can specify the user name whose home directory should be
+ used instead of `~'.
+
+ 7. It loads the library `default' unless `inhibit-default-init' is
+ non-`nil'. (This is not done in `-batch' mode or if `-q' was
+ specified on the command line.) The library's file name is
+ usually `default.el'.
+
+ 8. It runs the normal hook `after-init-hook'.
+
+ 9. It sets the major mode according to `initial-major-mode', provided
+ the buffer `*scratch*' is still current and still in Fundamental
+ mode.
+
+ 10. It loads the terminal-specific Lisp file, if any, except when in
+ batch mode or using a window system.
+
+ 11. It displays the initial echo area message, unless you have
+ suppressed that with `inhibit-startup-echo-area-message'.
+
+ 12. It processes the action arguments from the command line.
+
+ 13. It runs `term-setup-hook'.
+
+ 14. It calls `frame-notice-user-settings', which modifies the
+ parameters of the selected frame according to whatever the init
+ files specify.
+
+ 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
+
+ 16. It displays copyleft, nonwarranty, and basic use information,
+ provided there were no remaining command line arguments (a few
+ steps above) and the value of `inhibit-startup-message' is `nil'.
+
+ - User Option: inhibit-startup-message
+ This variable inhibits the initial startup messages (the
+ nonwarranty, etc.). If it is non-`nil', then the messages are not
+ printed.
+
+ This variable exists so you can set it in your personal init file,
+ once you are familiar with the contents of the startup message.
+ Do not set this variable in the init file of a new user, or in a
+ way that affects more than one user, because that would prevent
+ new users from receiving the information they are supposed to see.
+
+ - User Option: inhibit-startup-echo-area-message
+ This variable controls the display of the startup echo area
+ message. You can suppress the startup echo area message by adding
+ text with this form to your `.emacs' file:
+
+ (setq inhibit-startup-echo-area-message
+ "YOUR-LOGIN-NAME")
+
+ Simply setting `inhibit-startup-echo-area-message' to your login
+ name is not sufficient to inhibit the message; Emacs explicitly
+ checks whether `.emacs' contains an expression as shown above.
+ Your login name must appear in the expression as a Lisp string
+ constant.
+
+ This way, you can easily inhibit the message for yourself if you
+ wish, but thoughtless copying of your `.emacs' file will not
+ inhibit the message for someone else.
+
+\1f
+File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
+
+The Init File: `.emacs'
+-----------------------
+
+ When you start XEmacs, it normally attempts to load the file
+`.emacs' from your home directory. This file, if it exists, must
+contain Lisp code. It is called your "init file". The command line
+switches `-q' and `-u' affect the use of the init file; `-q' says not
+to load an init file, and `-u' says to load a specified user's init
+file instead of yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
+
+ A site may have a "default init file", which is the library named
+`default.el'. XEmacs finds the `default.el' file through the standard
+search path for libraries (*note How Programs Do Loading::.). The
+XEmacs distribution does not come with this file; sites may provide one
+for local customizations. If the default init file exists, it is
+loaded whenever you start Emacs, except in batch mode or if `-q' is
+specified. But your own personal init file, if any, is loaded first; if
+it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
+not subsequently load the `default.el' file.
+
+ Another file for site-customization is `site-start.el'. Emacs loads
+this *before* the user's init file. You can inhibit the loading of
+this file with the option `-no-site-file'.
+
+ - Variable: site-run-file
+ This variable specifies the site-customization file to load before
+ the user's init file. Its normal value is `"site-start"'.
+
+ If there is a great deal of code in your `.emacs' file, you should
+move it into another file named `SOMETHING.el', byte-compile it (*note
+Byte Compilation::.), and make your `.emacs' file load the other file
+using `load' (*note Loading::.).
+
+ *Note Init File Examples: (xemacs)Init File Examples, for examples
+of how to make various commonly desired customizations in your `.emacs'
+file.
+
+ - User Option: inhibit-default-init
+ This variable prevents XEmacs from loading the default
+ initialization library file for your session of XEmacs. If its
+ value is non-`nil', then the default library is not loaded. The
+ default value is `nil'.
+
+ - Variable: before-init-hook
+ - Variable: after-init-hook
+ These two normal hooks are run just before, and just after,
+ loading of the user's init file, `default.el', and/or
+ `site-start.el'.
+
+\1f
+File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
+
+Terminal-Specific Initialization
+--------------------------------
+
+ Each terminal type can have its own Lisp library that XEmacs loads
+when run on that type of terminal. For a terminal type named TERMTYPE,
+the library is called `term/TERMTYPE'. XEmacs finds the file by
+searching the `load-path' directories as it does for other files, and
+trying the `.elc' and `.el' suffixes. Normally, terminal-specific Lisp
+library is located in `emacs/lisp/term', a subdirectory of the
+`emacs/lisp' directory in which most XEmacs Lisp libraries are kept.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Normally,
+`term-file-prefix' has the value `"term/"'; changing this is not
+recommended.
+
+ The usual function of a terminal-specific library is to enable
+special keys to send sequences that XEmacs can recognize. It may also
+need to set or add to `function-key-map' if the Termcap entry does not
+specify all the terminal's function keys. *Note Terminal Input::.
+
+ When the name of the terminal type contains a hyphen, only the part
+of the name before the first hyphen is significant in choosing the
+library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
+the `term/aaa' library. If necessary, the library can evaluate
+`(getenv "TERM")' to find the full name of the terminal type.
+
+ Your `.emacs' file can prevent the loading of the terminal-specific
+library by setting the variable `term-file-prefix' to `nil'. This
+feature is useful when experimenting with your own peculiar
+customizations.
+
+ You can also arrange to override some of the actions of the
+terminal-specific library by setting the variable `term-setup-hook'.
+This is a normal hook which XEmacs runs using `run-hooks' at the end of
+XEmacs initialization, after loading both your `.emacs' file and any
+terminal-specific libraries. You can use this variable to define
+initializations for terminals that do not have their own libraries.
+*Note Hooks::.
+
+ - Variable: term-file-prefix
+ If the `term-file-prefix' variable is non-`nil', XEmacs loads a
+ terminal-specific initialization file as follows:
+
+ (load (concat term-file-prefix (getenv "TERM")))
+
+ You may set the `term-file-prefix' variable to `nil' in your
+ `.emacs' file if you do not wish to load the
+ terminal-initialization file. To do this, put the following in
+ your `.emacs' file: `(setq term-file-prefix nil)'.
+
+ - Variable: term-setup-hook
+ This variable is a normal hook that XEmacs runs after loading your
+ `.emacs' file, the default initialization file (if any) and the
+ terminal-specific Lisp file.
+
+ You can use `term-setup-hook' to override the definitions made by a
+ terminal-specific file.
+
+ - Variable: window-setup-hook
+ This variable is a normal hook which XEmacs runs after loading your
+ `.emacs' file and the default initialization file (if any), after
+ loading terminal-specific Lisp code, and after running the hook
+ `term-setup-hook'.
+
+\1f
+File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
+
+Command Line Arguments
+----------------------
+
+ You can use command line arguments to request various actions when
+you start XEmacs. Since you do not need to start XEmacs more than once
+per day, and will often leave your XEmacs session running longer than
+that, command line arguments are hardly ever used. As a practical
+matter, it is best to avoid making the habit of using them, since this
+habit would encourage you to kill and restart XEmacs unnecessarily
+often. These options exist for two reasons: to be compatible with
+other editors (for invocation by other programs) and to enable shell
+scripts to run specific Lisp programs.
+
+ This section describes how Emacs processes command line arguments,
+and how you can customize them.
+
+ - Function: command-line
+ This function parses the command line that XEmacs was called with,
+ processes it, loads the user's `.emacs' file and displays the
+ startup messages.
+
+ - Variable: command-line-processed
+ The value of this variable is `t' once the command line has been
+ processed.
+
+ If you redump XEmacs by calling `dump-emacs', you may wish to set
+ this variable to `nil' first in order to cause the new dumped
+ XEmacs to process its new command line arguments.
+
+ - Variable: command-switch-alist
+ The value of this variable is an alist of user-defined command-line
+ options and associated handler functions. This variable exists so
+ you can add elements to it.
+
+ A "command line option" is an argument on the command line of the
+ form:
+
+ -OPTION
+
+ The elements of the `command-switch-alist' look like this:
+
+ (OPTION . HANDLER-FUNCTION)
+
+ The HANDLER-FUNCTION is called to handle OPTION and receives the
+ option name as its sole argument.
+
+ In some cases, the option is followed in the command line by an
+ argument. In these cases, the HANDLER-FUNCTION can find all the
+ remaining command-line arguments in the variable
+ `command-line-args-left'. (The entire list of command-line
+ arguments is in `command-line-args'.)
+
+ The command line arguments are parsed by the `command-line-1'
+ function in the `startup.el' file. See also *Note Command Line
+ Switches and Arguments: (xemacs)Command Switches.
+
+ - Variable: command-line-args
+ The value of this variable is the list of command line arguments
+ passed to XEmacs.
+
+ - Variable: command-line-functions
+ This variable's value is a list of functions for handling an
+ unrecognized command-line argument. Each time the next argument
+ to be processed has no special meaning, the functions in this list
+ are called, in order of appearance, until one of them returns a
+ non-`nil' value.
+
+ These functions are called with no arguments. They can access the
+ command-line argument under consideration through the variable
+ `argi'. The remaining arguments (not including the current one)
+ are in the variable `command-line-args-left'.
+
+ When a function recognizes and processes the argument in `argi', it
+ should return a non-`nil' value to say it has dealt with that
+ argument. If it has also dealt with some of the following
+ arguments, it can indicate that by deleting them from
+ `command-line-args-left'.
+
+ If all of these functions return `nil', then the argument is used
+ as a file name to visit.
+
+\1f
+File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
+
+Getting out of XEmacs
+=====================
+
+ There are two ways to get out of XEmacs: you can kill the XEmacs job,
+which exits permanently, or you can suspend it, which permits you to
+reenter the XEmacs process later. As a practical matter, you seldom
+kill XEmacs--only when you are about to log out. Suspending is much
+more common.
+
+* Menu:
+
+* Killing XEmacs:: Exiting XEmacs irreversibly.
+* Suspending XEmacs:: Exiting XEmacs reversibly.
+
+\1f
+File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
+
+Killing XEmacs
+--------------
+
+ Killing XEmacs means ending the execution of the XEmacs process. The
+parent process normally resumes control. The low-level primitive for
+killing XEmacs is `kill-emacs'.
+
+ - Function: 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
+ the XEmacs process. (This is useful primarily in batch operation;
+ see *Note Batch Mode::.)
+
+ If EXIT-DATA is a string, its contents are stuffed into the
+ terminal input buffer so that the shell (or whatever program next
+ reads input) can read them.
+
+ All the information in the XEmacs process, aside from files that have
+been saved, is lost when the XEmacs is killed. Because killing XEmacs
+inadvertently can lose a lot of work, XEmacs queries for confirmation
+before actually terminating if you have buffers that need saving or
+subprocesses that are running. This is done in the function
+`save-buffers-kill-emacs'.
+
+ - Variable: kill-emacs-query-functions
+ After asking the standard questions, `save-buffers-kill-emacs'
+ calls the functions in the list `kill-buffer-query-functions', in
+ order of appearance, with no arguments. These functions can ask
+ for additional confirmation from the user. If any of them returns
+ non-`nil', XEmacs is not killed.
+
+ - Variable: kill-emacs-hook
+ This variable is a normal hook; once `save-buffers-kill-emacs' is
+ finished with all file saving and confirmation, it runs the
+ functions in this hook.
+
+\1f
+File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
+
+Suspending XEmacs
+-----------------
+
+ "Suspending XEmacs" means stopping XEmacs temporarily and returning
+control to its superior process, which is usually the shell. This
+allows you to resume editing later in the same XEmacs process, with the
+same buffers, the same kill ring, the same undo history, and so on. To
+resume XEmacs, use the appropriate command in the parent shell--most
+likely `fg'.
+
+ Some operating systems do not support suspension of jobs; on these
+systems, "suspension" actually creates a new shell temporarily as a
+subprocess of XEmacs. Then you would exit the shell to return to
+XEmacs.
+
+ Suspension is not useful with window systems such as X, because the
+XEmacs job may not have a parent that can resume it again, and in any
+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
+ 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.
+
+ Before suspending, `suspend-emacs' runs the normal hook
+ `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
+ normal hook; its value was a single function, and if its value was
+ non-`nil', then `suspend-emacs' returned immediately without
+ actually suspending anything.
+
+ After the user resumes XEmacs, `suspend-emacs' runs the normal hook
+ `suspend-resume-hook'. *Note Hooks::.
+
+ The next redisplay after resumption will redraw the entire screen,
+ unless the variable `no-redraw-on-reenter' is non-`nil' (*note
+ Refresh Screen::.).
+
+ In the following example, note that `pwd' is not echoed after
+ XEmacs is suspended. But it is read and executed by the shell.
+
+ (suspend-emacs)
+ => nil
+
+ (add-hook 'suspend-hook
+ (function (lambda ()
+ (or (y-or-n-p
+ "Really suspend? ")
+ (error "Suspend cancelled")))))
+ => (lambda nil
+ (or (y-or-n-p "Really suspend? ")
+ (error "Suspend cancelled")))
+
+ (add-hook 'suspend-resume-hook
+ (function (lambda () (message "Resumed!"))))
+ => (lambda nil (message "Resumed!"))
+
+ (suspend-emacs "pwd")
+ => nil
+
+ ---------- Buffer: Minibuffer ----------
+ Really suspend? y
+ ---------- Buffer: Minibuffer ----------
+
+ ---------- Parent Shell ----------
+ lewis@slug[23] % /user/lewis/manual
+ lewis@slug[24] % fg
+
+ ---------- Echo Area ----------
+ Resumed!
+
+ - Variable: suspend-hook
+ This variable is a normal hook run before suspending.
+
+ - Variable: suspend-resume-hook
+ This variable is a normal hook run after suspending.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
+
+Time of Day
+===========
+
+ This section explains how to determine the current time and the time
+zone.
+
+ - Function: current-time-string &optional TIME-VALUE
+ This function returns the current time and date as a
+ humanly-readable string. The format of the string is unvarying;
+ the number of characters used for each part is always the same, so
+ you can reliably use `substring' to extract pieces of it. It is
+ wise to count the characters from the beginning of the string
+ rather than from the end, as additional information may be added
+ at the end.
+
+ The argument TIME-VALUE, if given, specifies a time to format
+ instead of the current time. The argument should be a list whose
+ first two elements are integers. Thus, you can use times obtained
+ from `current-time' (see below) and from `file-attributes' (*note
+ File Attributes::.).
+
+ (current-time-string)
+ => "Wed Oct 14 22:21:05 1987"
+
+ - Function: current-time
+ This function returns the system's time value as a list of three
+ integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
+ combine to give the number of seconds since 0:00 January 1, 1970,
+ which is HIGH * 2**16 + LOW.
+
+ The third element, MICROSEC, gives the microseconds since the
+ start of the current second (or 0 for systems that return time
+ only on the resolution of a second).
+
+ The first two elements can be compared with file time values such
+ as you get with the function `file-attributes'. *Note File
+ Attributes::.
+
+ - Function: current-time-zone &optional TIME-VALUE
+ This function returns a list describing the time zone that the
+ user is in.
+
+ The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
+ giving the number of seconds ahead of UTC (east of Greenwich). A
+ negative value means west of Greenwich. The second element, NAME
+ is a string giving the name of the time zone. Both elements
+ change when daylight savings time begins or ends; if the user has
+ specified a time zone that does not use a seasonal time
+ adjustment, then the value is constant through time.
+
+ If the operating system doesn't supply all the information
+ necessary to compute the value, both elements of the list are
+ `nil'.
+
+ The argument TIME-VALUE, if given, specifies a time to analyze
+ instead of the current time. The argument should be a cons cell
+ containing two integers, or a list whose first two elements are
+ integers. Thus, you can use times obtained from `current-time'
+ (see above) and from `file-attributes' (*note File Attributes::.).
+
+\1f
+File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
+
+Time Conversion
+===============
+
+ These functions convert time values (lists of two or three integers)
+to strings or to calendrical information. There is also a function to
+convert calendrical information to a time value. You can get time
+values from the functions `current-time' (*note Time of Day::.) and
+`file-attributes' (*note File Attributes::.).
+
+ - Function: format-time-string FORMAT-STRING &optional TIME
+ This function converts TIME to a string according to
+ FORMAT-STRING. If TIME is omitted, it defaults to the current
+ time. The argument FORMAT-STRING may contain `%'-sequences which
+ say to substitute parts of the time. Here is a table of what the
+ `%'-sequences mean:
+
+ `%a'
+ This stands for the abbreviated name of the day of week.
+
+ `%A'
+ This stands for the full name of the day of week.
+
+ `%b'
+ This stands for the abbreviated name of the month.
+
+ `%B'
+ This stands for the full name of the month.
+
+ `%c'
+ This is a synonym for `%x %X'.
+
+ `%C'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%A, %B %e, %Y'.
+
+ `%d'
+ This stands for the day of month, zero-padded.
+
+ `%D'
+ This is a synonym for `%m/%d/%y'.
+
+ `%e'
+ This stands for the day of month, blank-padded.
+
+ `%h'
+ This is a synonym for `%b'.
+
+ `%H'
+ This stands for the hour (00-23).
+
+ `%I'
+ This stands for the hour (00-12).
+
+ `%j'
+ This stands for the day of the year (001-366).
+
+ `%k'
+ This stands for the hour (0-23), blank padded.
+
+ `%l'
+ This stands for the hour (1-12), blank padded.
+
+ `%m'
+ This stands for the month (01-12).
+
+ `%M'
+ This stands for the minute (00-59).
+
+ `%n'
+ This stands for a newline.
+
+ `%p'
+ This stands for `AM' or `PM', as appropriate.
+
+ `%r'
+ This is a synonym for `%I:%M:%S %p'.
+
+ `%R'
+ This is a synonym for `%H:%M'.
+
+ `%S'
+ This stands for the seconds (00-60).
+
+ `%t'
+ This stands for a tab character.
+
+ `%T'
+ This is a synonym for `%H:%M:%S'.
+
+ `%U'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Sunday.
+
+ `%w'
+ This stands for the numeric day of week (0-6). Sunday is day
+ 0.
+
+ `%W'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Monday.
+
+ `%x'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%D'.
+
+ `%X'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%T'.
+
+ `%y'
+ This stands for the year without century (00-99).
+
+ `%Y'
+ This stands for the year with century.
+
+ `%Z'
+ This stands for the time zone abbreviation.
+
+ - Function: decode-time TIME
+ This function converts a time value into calendrical information.
+ The return value is a list of nine elements, as follows:
+
+ (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
+
+ Here is what the elements mean:
+
+ SEC
+ The number of seconds past the minute, as an integer between
+ 0 and 59.
+
+ MINUTE
+ The number of minutes past the hour, as an integer between 0
+ and 59.
+
+ HOUR
+ The hour of the day, as an integer between 0 and 23.
+
+ DAY
+ The day of the month, as an integer between 1 and 31.
+
+ MONTH
+ The month of the year, as an integer between 1 and 12.
+
+ YEAR
+ The year, an integer typically greater than 1900.
+
+ DOW
+ The day of week, as an integer between 0 and 6, where 0
+ stands for Sunday.
+
+ DST
+ `t' if daylight savings time is effect, otherwise `nil'.
+
+ ZONE
+ An integer indicating the time zone, as the number of seconds
+ east of Greenwich.
+
+ Note that Common Lisp has different meanings for DOW and ZONE.
+
+ - Function: encode-time SECONDS MINUTES HOUR DAY MONTH YEAR &optional
+ ZONE
+ This function is the inverse of `decode-time'. It converts seven
+ items of calendrical data into a time value. For the meanings of
+ the arguments, see the table above under `decode-time'.
+
+ Year numbers less than 100 are treated just like other year
+ numbers. If you want them to stand for years above 1900, you must
+ alter them yourself before you call `encode-time'.
+
+ The optional argument ZONE defaults to the current time zone and
+ its daylight savings time rules. If specified, it can be either a
+ list (as you would get from `current-time-zone') or an integer (as
+ you would get from `decode-time'). The specified zone is used
+ without any further alteration for daylight savings time.
+
+\1f
+File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
+
+Timers for Delayed Execution
+============================
+
+ You can set up a timer to call a function at a specified future time.
+
+ - Function: add-timeout SECS FUNCTION OBJECT &optional RESIGNAL
+ This function adds a timeout, to be signaled after the timeout
+ period has elapsed. SECS is a number of seconds, expressed as an
+ integer or a float. FUNCTION will be called after that many
+ seconds have elapsed, with one argument, the given OBJECT. If the
+ optional RESIGNAL argument is provided, then after this timeout
+ expires, `add-timeout' will automatically be called again with
+ RESIGNAL as the first argument.
+
+ This function returns an object which is the "id" of this
+ particular timeout. You can pass that object to `disable-timeout'
+ to turn off the timeout before it has been signalled.
+
+ The number of seconds may be expressed as a floating-point number,
+ in which case some fractional part of a second will be used.
+ Caveat: the usable timeout granularity will vary from system to
+ system.
+
+ Adding a timeout causes a timeout event to be returned by
+ `next-event', and the function will be invoked by
+ `dispatch-event', so if XEmacs is in a tight loop, the function
+ will not be invoked until the next call to sit-for or until the
+ return to top-level (the same is true of process filters).
+
+ WARNING: if you are thinking of calling add-timeout from inside of
+ a callback function as a way of resignalling a timeout, think
+ again. There is a race condition. That's why the RESIGNAL
+ argument exists.
+
+ (NOTE: In FSF Emacs, this function is called `run-at-time' and has
+ different semantics.)
+
+ - Function: disable-timeout ID
+ Cancel the requested action for ID, which should be a value
+ previously returned by `add-timeout'. This cancels the effect of
+ that call to `add-timeout'; the arrival of the specified time will
+ not cause anything special to happen. (NOTE: In FSF Emacs, this
+ function is called `cancel-timer'.)
+
+\1f
+File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
+
+Terminal Input
+==============
+
+ This section describes functions and variables for recording or
+manipulating terminal input. See *Note Display::, for related
+functions.
+
+* Menu:
+
+* Input Modes:: Options for how input is processed.
+* Translating Input:: Low level conversion of some characters or events
+ into others.
+* Recording Input:: Saving histories of recent or all input events.
+
+\1f
+File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
+
+Input Modes
+-----------
+
+ - Function: set-input-mode INTERRUPT FLOW META QUIT-CHAR
+ This function sets the mode for reading keyboard input. If
+ INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
+ `nil', then it uses CBREAK mode. When XEmacs communicates
+ directly with X, it ignores this argument and uses interrupts if
+ that is the way it knows how to communicate.
+
+ If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
+ flow control for output to the terminal. This has no effect except
+ in CBREAK mode. *Note Flow Control::.
+
+ The default setting is system dependent. Some systems always use
+ CBREAK mode regardless of what is specified.
+
+ The argument META controls support for input character codes above
+ 127. If META is `t', XEmacs converts characters with the 8th bit
+ set into Meta characters. If META is `nil', XEmacs disregards the
+ 8th bit; this is necessary when the terminal uses it as a parity
+ bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
+ input unchanged. This is good for terminals using European 8-bit
+ character sets.
+
+ If QUIT-CHAR is non-`nil', it specifies the character to use for
+ quitting. Normally this character is `C-g'. *Note Quitting::.
+
+ The `current-input-mode' function returns the input mode settings
+XEmacs is currently using.
+
+ - Function: current-input-mode
+ This function returns current mode for reading keyboard input. It
+ returns a list, corresponding to the arguments of `set-input-mode',
+ of the form `(INTERRUPT FLOW META QUIT)' in which:
+ INTERRUPT
+ is non-`nil' when XEmacs is using interrupt-driven input. If
+ `nil', Emacs is using CBREAK mode.
+
+ FLOW
+ is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
+ control for output to the terminal. This value has no effect
+ unless INTERRUPT is non-`nil'.
+
+ META
+ is `t' if XEmacs treats the eighth bit of input characters as
+ the meta bit; `nil' means XEmacs clears the eighth bit of
+ every input character; any other value means XEmacs uses all
+ eight bits as the basic character code.
+
+ QUIT
+ is the character XEmacs currently uses for quitting, usually
+ `C-g'.
+
+\1f
+File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
+
+Translating Input Events
+------------------------
+
+ This section describes features for translating input events into
+other input events before they become part of key sequences.
+
+ - Variable: function-key-map
+ This variable holds a keymap that describes the character sequences
+ sent by function keys on an ordinary character terminal. This
+ keymap uses the same data structure as other keymaps, but is used
+ differently: it specifies translations to make while reading
+ events.
+
+ If `function-key-map' "binds" a key sequence K to a vector V, then
+ when K appears as a subsequence *anywhere* in a key sequence, it
+ is replaced with the events in V.
+
+ For example, VT100 terminals send `<ESC> O P' when the keypad PF1
+ key is pressed. Therefore, we want XEmacs to translate that
+ sequence of events into the single event `pf1'. We accomplish
+ this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
+ when using a VT100.
+
+ Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+ P'; later the function `read-key-sequence' translates this back
+ into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
+
+ Entries in `function-key-map' are ignored if they conflict with
+ bindings made in the minor mode, local, or global keymaps. The
+ intent is that the character sequences that function keys send
+ should not have command bindings in their own right.
+
+ The value of `function-key-map' is usually set up automatically
+ according to the terminal's Terminfo or Termcap entry, but
+ sometimes those need help from terminal-specific Lisp files.
+ XEmacs comes with terminal-specific files for many common
+ terminals; their main purpose is to make entries in
+ `function-key-map' beyond those that can be deduced from Termcap
+ and Terminfo. *Note Terminal-Specific::.
+
+ Emacs versions 18 and earlier used totally different means of
+ detecting the character sequences that represent function keys.
+
+ - Variable: key-translation-map
+ This variable is another keymap used just like `function-key-map'
+ to translate input events into other events. It differs from
+ `function-key-map' in two ways:
+
+ * `key-translation-map' goes to work after `function-key-map' is
+ finished; it receives the results of translation by
+ `function-key-map'.
+
+ * `key-translation-map' overrides actual key bindings.
+
+ The intent of `key-translation-map' is for users to map one
+ character set to another, including ordinary characters normally
+ bound to `self-insert-command'.
+
+ You can use `function-key-map' or `key-translation-map' for more
+than simple aliases, by using a function, instead of a key sequence, as
+the "translation" of a key. Then this function is called to compute
+the translation of that key.
+
+ The key translation function receives one argument, which is the
+prompt that was specified in `read-key-sequence'--or `nil' if the key
+sequence is being read by the editor command loop. In most cases you
+can ignore the prompt value.
+
+ If the function reads input itself, it can have the effect of
+altering the event that follows. For example, here's how to define
+`C-c h' to turn the character that follows into a Hyper character:
+
+ (defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 20) e)
+ (if (memq 'hyper (event-modifiers e))
+ e
+ (add-event-modifier "H-" e))))))
+
+ (defun add-event-modifier (string e)
+ (let ((symbol (if (symbolp e) e (car e))))
+ (setq symbol (intern (concat string
+ (symbol-name symbol))))
+ (if (symbolp e)
+ symbol
+ (cons symbol (cdr e)))))
+
+ (define-key function-key-map "\C-ch" 'hyperify)
+
+ The `iso-transl' library uses this feature to provide a way of
+inputting non-ASCII Latin-1 characters.
+
+\1f
+File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
+
+Recording Input
+---------------
+
+ - Function: recent-keys &optional NUMBER
+ This function returns a vector containing recent input events from
+ the keyboard or mouse. By default, 100 events are recorded, which
+ is how many `recent-keys' returns.
+
+ All input events are included, whether or not they were used as
+ parts of key sequences. Thus, you always get the last 100 inputs,
+ not counting keyboard macros. (Events from keyboard macros are
+ excluded because they are less interesting for debugging; it
+ should be enough to see the events that invoked the macros.)
+
+ If NUMBER is specified, not more than NUMBER events will be
+ returned. You may change the number of stored events using
+ `set-recent-keys-ring-size'.
+
+ - Function: recent-keys-ring-size
+ This function returns the number of recent events stored
+ internally. This is also the maximum number of events
+ `recent-keys' can return. By default, 100 events are stored.
+
+ - Function: set-recent-keys-ring-size SIZE
+ This function changes the number of events stored by XEmacs and
+ returned by `recent-keys'.
+
+ For example, `(set-recent-keys-ring-size 250)' will make XEmacs
+ remember last 250 events and will make `recent-keys' return last
+ 250 events by default.
+
+ - Command: open-dribble-file FILENAME
+ This function opens a "dribble file" named FILENAME. When a
+ dribble file is open, each input event from the keyboard or mouse
+ (but not those from keyboard macros) is written in that file. A
+ non-character event is expressed using its printed representation
+ surrounded by `<...>'.
+
+ You close the dribble file by calling this function with an
+ argument of `nil'.
+
+ This function is normally used to record the input necessary to
+ trigger an XEmacs bug, for the sake of a bug report.
+
+ (open-dribble-file "~/dribble")
+ => nil
+
+ See also the `open-termscript' function (*note Terminal Output::.).
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types
+
+Specifier Type
+--------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types
+
+Font Instance Type
+------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types
+
+Color Instance Type
+-------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types
+
+Image Instance Type
+-------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types
+
+Toolbar Button Type
+-------------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types
+
+Subwindow Type
+--------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: X Resource Type, Prev: Subwindow Type, Up: Window-System Types
+
+X Resource Type
+---------------
+
+ (not yet documented)
+
+\1f
+File: lispref.info, Node: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types
+
+Type Predicates
+===============
+
+ The XEmacs Lisp interpreter itself does not perform type checking on
+the actual arguments passed to functions when they are called. It could
+not do so, since function arguments in Lisp do not have declared data
+types, as they do in other programming languages. It is therefore up to
+the individual function to test whether each actual argument belongs to
+a type that the function can use.
+
+ All built-in functions do check the types of their actual arguments
+when appropriate, and signal a `wrong-type-argument' error if an
+argument is of the wrong type. For example, here is what happens if you
+pass an argument to `+' that it cannot handle:
+
+ (+ 2 'a)
+ error--> Wrong type argument: integer-or-marker-p, a
+
+ If you want your program to handle different types differently, you
+must do explicit type checking. The most common way to check the type
+of an object is to call a "type predicate" function. Emacs has a type
+predicate for each type, as well as some predicates for combinations of
+types.
+
+ A type predicate function takes one argument; it returns `t' if the
+argument belongs to the appropriate type, and `nil' otherwise.
+Following a general Lisp convention for predicate functions, most type
+predicates' names end with `p'.
+
+ Here is an example which uses the predicates `listp' to check for a
+list and `symbolp' to check for a symbol.
+
+ (defun add-on (x)
+ (cond ((symbolp x)
+ ;; If X is a symbol, put it on LIST.
+ (setq list (cons x list)))
+ ((listp x)
+ ;; If X is a list, add its elements to LIST.
+ (setq list (append x list)))
+ (t
+ ;; We only handle symbols and lists.
+ (error "Invalid argument %s in add-on" x))))
+
+ Here is a table of predefined type predicates, in alphabetical order,
+with references to further information.
+
+`annotationp'
+ *Note annotationp: Annotation Primitives.
+
+`arrayp'
+ *Note arrayp: Array Functions.
+
+`atom'
+ *Note atom: List-related Predicates.
+
+`bit-vector-p'
+ *Note bit-vector-p: Bit Vector Functions.
+
+`bitp'
+ *Note bitp: Bit Vector Functions.
+
+`boolean-specifier-p'
+ *Note boolean-specifier-p: Specifier Types.
+
+`buffer-glyph-p'
+ *Note buffer-glyph-p: Glyph Types.
+
+`buffer-live-p'
+ *Note buffer-live-p: Killing Buffers.
+
+`bufferp'
+ *Note bufferp: Buffer Basics.
+
+`button-event-p'
+ *Note button-event-p: Event Predicates.
+
+`button-press-event-p'
+ *Note button-press-event-p: Event Predicates.
+
+`button-release-event-p'
+ *Note button-release-event-p: Event Predicates.
+
+`case-table-p'
+ *Note case-table-p: Case Tables.
+
+`char-int-p'
+ *Note char-int-p: Character Codes.
+
+`char-or-char-int-p'
+ *Note char-or-char-int-p: Character Codes.
+
+`char-or-string-p'
+ *Note char-or-string-p: Predicates for Strings.
+
+`char-table-p'
+ *Note char-table-p: Char Tables.
+
+`characterp'
+ *Note characterp: Predicates for Characters.
+
+`color-instance-p'
+ *Note color-instance-p: Colors.
+
+`color-pixmap-image-instance-p'
+ *Note color-pixmap-image-instance-p: Image Instance Types.
+
+`color-specifier-p'
+ *Note color-specifier-p: Specifier Types.
+
+`commandp'
+ *Note commandp: Interactive Call.
+
+`compiled-function-p'
+ *Note compiled-function-p: Compiled-Function Type.
+
+`console-live-p'
+ *Note console-live-p: Connecting to a Console or Device.
+
+`consolep'
+ *Note consolep: Consoles and Devices.
+
+`consp'
+ *Note consp: List-related Predicates.
+
+`database-live-p'
+ *Note database-live-p: Connecting to a Database.
+
+`databasep'
+ *Note databasep: Databases.
+
+`device-live-p'
+ *Note device-live-p: Connecting to a Console or Device.
+
+`device-or-frame-p'
+ *Note device-or-frame-p: Basic Device Functions.
+
+`devicep'
+ *Note devicep: Consoles and Devices.
+
+`eval-event-p'
+ *Note eval-event-p: Event Predicates.
+
+`event-live-p'
+ *Note event-live-p: Event Predicates.
+
+`eventp'
+ *Note eventp: Events.
+
+`extent-live-p'
+ *Note extent-live-p: Creating and Modifying Extents.
+
+`extentp'
+ *Note extentp: Extents.
+
+`face-boolean-specifier-p'
+ *Note face-boolean-specifier-p: Specifier Types.
+
+`facep'
+ *Note facep: Basic Face Functions.
+
+`floatp'
+ *Note floatp: Predicates on Numbers.
+
+`font-instance-p'
+ *Note font-instance-p: Fonts.
+
+`font-specifier-p'
+ *Note font-specifier-p: Specifier Types.
+
+`frame-live-p'
+ *Note frame-live-p: Deleting Frames.
+
+`framep'
+ *Note framep: Frames.
+
+`functionp'
+ (not yet documented)
+
+`generic-specifier-p'
+ *Note generic-specifier-p: Specifier Types.
+
+`glyphp'
+ *Note glyphp: Glyphs.
+
+`hash-table-p'
+ *Note hash-table-p: Hash Tables.
+
+`icon-glyph-p'
+ *Note icon-glyph-p: Glyph Types.
+
+`image-instance-p'
+ *Note image-instance-p: Images.
+
+`image-specifier-p'
+ *Note image-specifier-p: Specifier Types.
+
+`integer-char-or-marker-p'
+ *Note integer-char-or-marker-p: Predicates on Markers.
+
+`integer-or-char-p'
+ *Note integer-or-char-p: Predicates for Characters.
+
+`integer-or-marker-p'
+ *Note integer-or-marker-p: Predicates on Markers.
+
+`integer-specifier-p'
+ *Note integer-specifier-p: Specifier Types.
+
+`integerp'
+ *Note integerp: Predicates on Numbers.
+
+`itimerp'
+ (not yet documented)
+
+`key-press-event-p'
+ *Note key-press-event-p: Event Predicates.
+
+`keymapp'
+ *Note keymapp: Creating Keymaps.
+
+`keywordp'
+ (not yet documented)
+
+`listp'
+ *Note listp: List-related Predicates.
+
+`markerp'
+ *Note markerp: Predicates on Markers.
+
+`misc-user-event-p'
+ *Note misc-user-event-p: Event Predicates.
+
+`mono-pixmap-image-instance-p'
+ *Note mono-pixmap-image-instance-p: Image Instance Types.
+
+`motion-event-p'
+ *Note motion-event-p: Event Predicates.
+
+`mouse-event-p'
+ *Note mouse-event-p: Event Predicates.
+
+`natnum-specifier-p'
+ *Note natnum-specifier-p: Specifier Types.
+
+`natnump'
+ *Note natnump: Predicates on Numbers.
+
+`nlistp'
+ *Note nlistp: List-related Predicates.
+
+`nothing-image-instance-p'
+ *Note nothing-image-instance-p: Image Instance Types.
+
+`number-char-or-marker-p'
+ *Note number-char-or-marker-p: Predicates on Markers.
+
+`number-or-marker-p'
+ *Note number-or-marker-p: Predicates on Markers.
+
+`numberp'
+ *Note numberp: Predicates on Numbers.
+
+`pointer-glyph-p'
+ *Note pointer-glyph-p: Glyph Types.
+
+`pointer-image-instance-p'
+ *Note pointer-image-instance-p: Image Instance Types.
+
+`process-event-p'
+ *Note process-event-p: Event Predicates.
+
+`processp'
+ *Note processp: Processes.
+
+`range-table-p'
+ *Note range-table-p: Range Tables.
+
+`ringp'
+ (not yet documented)
+
+`sequencep'
+ *Note sequencep: Sequence Functions.
+
+`specifierp'
+ *Note specifierp: Specifiers.
+
+`stringp'
+ *Note stringp: Predicates for Strings.
+
+`subrp'
+ *Note subrp: Function Cells.
+
+`subwindow-image-instance-p'
+ *Note subwindow-image-instance-p: Image Instance Types.
+
+`subwindowp'
+ *Note subwindowp: Subwindows.
+
+`symbolp'
+ *Note symbolp: Symbols.
+
+`syntax-table-p'
+ *Note syntax-table-p: Syntax Tables.
+
+`text-image-instance-p'
+ *Note text-image-instance-p: Image Instance Types.
+
+`timeout-event-p'
+ *Note timeout-event-p: Event Predicates.
+
+`toolbar-button-p'
+ *Note toolbar-button-p: Toolbar.
+
+`toolbar-specifier-p'
+ *Note toolbar-specifier-p: Toolbar.
+
+`user-variable-p'
+ *Note user-variable-p: Defining Variables.
+
+`vectorp'
+ *Note vectorp: Vectors.
+
+`weak-list-p'
+ *Note weak-list-p: Weak Lists.
+
+`window-configuration-p'
+ *Note window-configuration-p: Window Configurations.
+
+`window-live-p'
+ *Note window-live-p: Deleting Windows.
+
+`windowp'
+ *Note windowp: Basic Windows.
+
+ The most general way to check the type of an object is to call the
+function `type-of'. Recall that each object belongs to one and only
+one primitive type; `type-of' tells you which one (*note Lisp Data
+Types::.). But `type-of' knows nothing about non-primitive types. In
+most cases, it is more convenient to use type predicates than `type-of'.
+
+ - Function: type-of OBJECT
+ This function returns a symbol naming the primitive type of
+ OBJECT. The value is one of `bit-vector', `buffer', `char-table',
+ `character', `charset', `coding-system', `cons', `color-instance',
+ `compiled-function', `console', `database', `device', `event',
+ `extent', `face', `float', `font-instance', `frame', `glyph',
+ `hash-table', `image-instance', `integer', `keymap', `marker',
+ `process', `range-table', `specifier', `string', `subr',
+ `subwindow', `symbol', `toolbar-button', `tooltalk-message',
+ `tooltalk-pattern', `vector', `weak-list', `window',
+ `window-configuration', or `x-resource'.
+
+ (type-of 1)
+ => integer
+ (type-of 'nil)
+ => symbol
+ (type-of '()) ; `()' is `nil'.
+ => symbol
+ (type-of '(x))
+ => cons
+
+\1f
+File: lispref.info, Node: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types
+
+Equality Predicates
+===================
+
+ Here we describe two functions that test for equality between any two
+objects. Other functions test equality between objects of specific
+types, e.g., strings. For these predicates, see the appropriate chapter
+describing the data type.
+
+ - Function: eq OBJECT1 OBJECT2
+ This function returns `t' if OBJECT1 and OBJECT2 are the same
+ object, `nil' otherwise. The "same object" means that a change in
+ one will be reflected by the same change in the other.
+
+ `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
+ value. Also, since symbol names are normally unique, if the
+ arguments are symbols with the same name, they are `eq'. For
+ other types (e.g., lists, vectors, strings), two arguments with
+ the same contents or elements are not necessarily `eq' to each
+ other: they are `eq' only if they are the same object.
+
+ (The `make-symbol' function returns an uninterned symbol that is
+ not interned in the standard `obarray'. When uninterned symbols
+ are in use, symbol names are no longer unique. Distinct symbols
+ with the same name are not `eq'. *Note Creating Symbols::.)
+
+ NOTE: Under XEmacs 19, characters are really just integers, and
+ thus characters and integers are `eq'. Under XEmacs 20, it was
+ necessary to preserve remnants of this in function such as `old-eq'
+ in order to maintain byte-code compatibility. Byte code compiled
+ under any Emacs 19 will automatically have calls to `eq' mapped to
+ `old-eq' when executed under XEmacs 20.
+
+ (eq 'foo 'foo)
+ => t
+
+ (eq 456 456)
+ => t
+
+ (eq "asdf" "asdf")
+ => nil
+
+ (eq '(1 (2 (3))) '(1 (2 (3))))
+ => nil
+
+ (setq foo '(1 (2 (3))))
+ => (1 (2 (3)))
+ (eq foo foo)
+ => t
+ (eq foo '(1 (2 (3))))
+ => nil
+
+ (eq [(1 2) 3] [(1 2) 3])
+ => nil
+
+ (eq (point-marker) (point-marker))
+ => nil
+
+
+ - Function: old-eq OBJ1 OBJ2
+ This function exists under XEmacs 20 and is exactly like `eq'
+ except that it suffers from the char-int confoundance disease. In
+ other words, it returns `t' if given a character and the
+ equivalent integer, even though the objects are of different types!
+ You should *not* ever call this function explicitly in your code.
+ However, be aware that all calls to `eq' in byte code compiled
+ under version 19 map to `old-eq' in XEmacs 20. (Likewise for
+ `old-equal', `old-memq', `old-member', `old-assq' and
+ `old-assoc'.)
+
+ ;; Remember, this does not apply under XEmacs 19.
+ ?A
+ => ?A
+ (char-int ?A)
+ => 65
+ (old-eq ?A 65)
+ => t ; Eek, we've been infected.
+ (eq ?A 65)
+ => nil ; We are still healthy.
+
+ - Function: equal OBJECT1 OBJECT2
+ This function returns `t' if OBJECT1 and OBJECT2 have equal
+ components, `nil' otherwise. Whereas `eq' tests if its arguments
+ are the same object, `equal' looks inside nonidentical arguments
+ to see if their elements are the same. So, if two objects are
+ `eq', they are `equal', but the converse is not always true.
+
+ (equal 'foo 'foo)
+ => t
+
+ (equal 456 456)
+ => t
+
+ (equal "asdf" "asdf")
+ => t
+ (eq "asdf" "asdf")
+ => nil
+
+ (equal '(1 (2 (3))) '(1 (2 (3))))
+ => t
+ (eq '(1 (2 (3))) '(1 (2 (3))))
+ => nil
+
+ (equal [(1 2) 3] [(1 2) 3])
+ => t
+ (eq [(1 2) 3] [(1 2) 3])
+ => nil
+
+ (equal (point-marker) (point-marker))
+ => t
+
+ (eq (point-marker) (point-marker))
+ => nil
+
+ Comparison of strings is case-sensitive.
+
+ Note that in FSF GNU Emacs, comparison of strings takes into
+ account their text properties, and you have to use `string-equal'
+ if you want only the strings themselves compared. This difference
+ does not exist in XEmacs; `equal' and `string-equal' always return
+ the same value on the same strings.
+
+ (equal "asdf" "ASDF")
+ => nil
+
+ Two distinct buffers are never `equal', even if their contents are
+ the same.
+
+ The test for equality is implemented recursively, and circular lists
+may therefore cause infinite recursion (leading to an error).
+
+\1f
+File: lispref.info, Node: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top
+
+Numbers
+*******
+
+ XEmacs supports two numeric data types: "integers" and "floating
+point numbers". Integers are whole numbers such as -3, 0, #b0111,
+#xFEED, #o744. Their values are exact. The number prefixes `#b',
+`#o', and `#x' are supported to represent numbers in binary, octal, and
+hexadecimal notation (or radix). Floating point numbers are numbers
+with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be
+expressed in exponential notation: 1.5e2 equals 150; in this example,
+`e2' stands for ten to the second power, and is multiplied by 1.5.
+Floating point values are not exact; they have a fixed, limited amount
+of precision.
+
+* Menu:
+
+* Integer Basics:: Representation and range of integers.
+* Float Basics:: Representation and range of floating point.
+* Predicates on Numbers:: Testing for numbers.
+* Comparison of Numbers:: Equality and inequality predicates.
+* Numeric Conversions:: Converting float to integer and vice versa.
+* Arithmetic Operations:: How to add, subtract, multiply and divide.
+* Rounding Operations:: Explicitly rounding floating point numbers.
+* Bitwise Operations:: Logical and, or, not, shifting.
+* Math Functions:: Trig, exponential and logarithmic functions.
+* Random Numbers:: Obtaining random integers, predictable or not.
+
+\1f
+File: lispref.info, Node: Integer Basics, Next: Float Basics, Up: Numbers
+
+Integer Basics
+==============
+
+ The range of values for an integer depends on the machine. The
+minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to
+2**27 - 1), but some machines may provide a wider range. Many examples
+in this chapter assume an integer has 28 bits.
+
+ The Lisp reader reads an integer as a sequence of digits with
+optional initial sign and optional final period.
+
+ 1 ; The integer 1.
+ 1. ; The integer 1.
+ +1 ; Also the integer 1.
+ -1 ; The integer -1.
+ 268435457 ; Also the integer 1, due to overflow.
+ 0 ; The integer 0.
+ -0 ; The integer 0.
+
+ To understand how various functions work on integers, especially the
+bitwise operators (*note Bitwise Operations::.), it is often helpful to
+view the numbers in their binary form.
+
+ In 28-bit binary, the decimal integer 5 looks like this:
+
+ 0000 0000 0000 0000 0000 0000 0101
+
+(We have inserted spaces between groups of 4 bits, and two spaces
+between groups of 8 bits, to make the binary integer easier to read.)
+
+ The integer -1 looks like this:
+
+ 1111 1111 1111 1111 1111 1111 1111
+
+-1 is represented as 28 ones. (This is called "two's complement"
+notation.)
+
+ The negative integer, -5, is creating by subtracting 4 from -1. In
+binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
+
+ 1111 1111 1111 1111 1111 1111 1011
+
+ In this implementation, the largest 28-bit binary integer is the
+decimal integer 134,217,727. In binary, it looks like this:
+
+ 0111 1111 1111 1111 1111 1111 1111
+
+ Since the arithmetic functions do not check whether integers go
+outside their range, when you add 1 to 134,217,727, the value is the
+negative integer -134,217,728:
+
+ (+ 1 134217727)
+ => -134217728
+ => 1000 0000 0000 0000 0000 0000 0000
+
+ Many of the following functions accept markers for arguments as well
+as integers. (*Note Markers::.) More precisely, the actual arguments
+to such functions may be either integers or markers, which is why we
+often give these arguments the name INT-OR-MARKER. When the argument
+value is a marker, its position value is used and its buffer is ignored.
+
+\1f
+File: lispref.info, Node: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers
+
+Floating Point Basics
+=====================
+
+ XEmacs supports floating point numbers. The precise range of
+floating point numbers is machine-specific; it is the same as the range
+of the C data type `double' on the machine in question.
+
+ The printed representation for floating point numbers requires either
+a decimal point (with at least one digit following), an exponent, or
+both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
+are five ways of writing a floating point number whose value is 1500.
+They are all equivalent. You can also use a minus sign to write
+negative floating point numbers, as in `-1.0'.
+
+ Most modern computers support the IEEE floating point standard, which
+provides for positive infinity and negative infinity as floating point
+values. It also provides for a class of values called NaN or
+"not-a-number"; numerical functions return such values in cases where
+there is no correct answer. For example, `(sqrt -1.0)' returns a NaN.
+For practical purposes, there's no significant difference between
+different NaN values in XEmacs Lisp, and there's no rule for precisely
+which NaN value should be used in a particular case, so this manual
+doesn't try to distinguish them. XEmacs Lisp has no read syntax for
+NaNs or infinities; perhaps we should create a syntax in the future.
+
+ You can use `logb' to extract the binary exponent of a floating
+point number (or estimate the logarithm of an integer):
+
+ - Function: logb NUMBER
+ This function returns the binary exponent of NUMBER. More
+ precisely, the value is the logarithm of NUMBER base 2, rounded
+ down to an integer.
+
+\1f
+File: lispref.info, Node: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers
+
+Type Predicates for Numbers
+===========================
+
+ The functions in this section test whether the argument is a number
+or whether it is a certain sort of number. The functions `integerp'
+and `floatp' can take any type of Lisp object as argument (the
+predicates would not be of much use otherwise); but the `zerop'
+predicate requires a number as its argument. See also
+`integer-or-marker-p', `integer-char-or-marker-p', `number-or-marker-p'
+and `number-char-or-marker-p', in *Note Predicates on Markers::.
+
+ - Function: floatp OBJECT
+ This predicate tests whether its argument is a floating point
+ number and returns `t' if so, `nil' otherwise.
+
+ `floatp' does not exist in Emacs versions 18 and earlier.
+
+ - Function: integerp OBJECT
+ This predicate tests whether its argument is an integer, and
+ returns `t' if so, `nil' otherwise.
+
+ - Function: numberp OBJECT
+ This predicate tests whether its argument is a number (either
+ integer or floating point), and returns `t' if so, `nil' otherwise.
+
+ - Function: natnump OBJECT
+ The `natnump' predicate (whose name comes from the phrase
+ "natural-number-p") tests to see whether its argument is a
+ nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is
+ considered non-negative.
+
+ - Function: zerop NUMBER
+ This predicate tests whether its argument is zero, and returns `t'
+ if so, `nil' otherwise. The argument must be a number.
+
+ These two forms are equivalent: `(zerop x)' == `(= x 0)'.
+
+\1f
+File: lispref.info, Node: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers
+
+Comparison of Numbers
+=====================
+
+ To test numbers for numerical equality, you should normally use `=',
+not `eq'. There can be many distinct floating point number objects
+with the same numeric value. If you use `eq' to compare them, then you
+test whether two values are the same *object*. By contrast, `='
+compares only the numeric values of the objects.
+
+ At present, each integer value has a unique Lisp object in XEmacs
+Lisp. Therefore, `eq' is equivalent to `=' where integers are
+concerned. It is sometimes convenient to use `eq' for comparing an
+unknown value with an integer, because `eq' does not report an error if
+the unknown value is not a number--it accepts arguments of any type.
+By contrast, `=' signals an error if the arguments are not numbers or
+markers. However, it is a good idea to use `=' if you can, even for
+comparing integers, just in case we change the representation of
+integers in a future XEmacs version.
+
+ There is another wrinkle: because floating point arithmetic is not
+exact, it is often a bad idea to check for equality of two floating
+point values. Usually it is better to test for approximate equality.
+Here's a function to do this:
+
+ (defconst fuzz-factor 1.0e-6)
+ (defun approx-equal (x y)
+ (or (and (= x 0) (= y 0))
+ (< (/ (abs (- x y))
+ (max (abs x) (abs y)))
+ fuzz-factor)))
+
+ Common Lisp note: Comparing numbers in Common Lisp always requires
+ `=' because Common Lisp implements multi-word integers, and two
+ distinct integer objects can have the same numeric value. XEmacs
+ Lisp can have just one integer object for any given value because
+ it has a limited range of integer values.
+
+ In addition to numbers, all of the following functions also accept
+characters and markers as arguments, and treat them as their number
+equivalents.
+
+ - Function: = NUMBER &rest MORE-NUMBERS
+ This function returns `t' if all of its arguments are numerically
+ equal, `nil' otherwise.
+
+ (= 5)
+ => t
+ (= 5 6)
+ => nil
+ (= 5 5.0)
+ => t
+ (= 5 5 6)
+ => nil
+
+ - Function: /= NUMBER &rest MORE-NUMBERS
+ This function returns `t' if no two arguments are numerically
+ equal, `nil' otherwise.
+
+ (/= 5 6)
+ => t
+ (/= 5 5 6)
+ => nil
+ (/= 5 6 1)
+ => t
+
+ - Function: < NUMBER &rest MORE-NUMBERS
+ This function returns `t' if the sequence of its arguments is
+ monotonically increasing, `nil' otherwise.
+
+ (< 5 6)
+ => t
+ (< 5 6 6)
+ => nil
+ (< 5 6 7)
+ => t
+
+ - Function: <= NUMBER &rest MORE-NUMBERS
+ This function returns `t' if the sequence of its arguments is
+ monotonically nondecreasing, `nil' otherwise.
+
+ (<= 5 6)
+ => t
+ (<= 5 6 6)
+ => t
+ (<= 5 6 5)
+ => nil
+
+ - Function: > NUMBER &rest MORE-NUMBERS
+ This function returns `t' if the sequence of its arguments is
+ monotonically decreasing, `nil' otherwise.
+
+ - Function: >= NUMBER &rest MORE-NUMBERS
+ This function returns `t' if the sequence of its arguments is
+ monotonically nonincreasing, `nil' otherwise.
+
+ - Function: max NUMBER &rest MORE-NUMBERS
+ This function returns the largest of its arguments.
+
+ (max 20)
+ => 20
+ (max 1 2.5)
+ => 2.5
+ (max 1 3 2.5)
+ => 3
+
+ - Function: min NUMBER &rest MORE-NUMBERS
+ This function returns the smallest of its arguments.
+
+ (min -4 1)
+ => -4
+
+\1f
+File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers
+
+Numeric Conversions
+===================
+
+ To convert an integer to floating point, use the function `float'.
+
+ - Function: float NUMBER
+ This returns NUMBER converted to floating point. If NUMBER is
+ already a floating point number, `float' returns it unchanged.
+
+ There are four functions to convert floating point numbers to
+integers; they differ in how they round. These functions accept
+integer arguments also, and return such arguments unchanged.
+
+ - Function: truncate NUMBER
+ This returns NUMBER, converted to an integer by rounding towards
+ zero.
+
+ - Function: floor NUMBER &optional DIVISOR
+ This returns NUMBER, converted to an integer by rounding downward
+ (towards negative infinity).
+
+ If DIVISOR is specified, NUMBER is divided by DIVISOR before the
+ floor is taken; this is the division operation that corresponds to
+ `mod'. An `arith-error' results if DIVISOR is 0.
+
+ - Function: ceiling NUMBER
+ This returns NUMBER, converted to an integer by rounding upward
+ (towards positive infinity).
+
+ - Function: round NUMBER
+ This returns NUMBER, converted to an integer by rounding towards
+ the nearest integer. Rounding a value equidistant between two
+ integers may choose the integer closer to zero, or it may prefer
+ an even integer, depending on your machine.
+
+\1f
+File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers
+
+Arithmetic Operations
+=====================
+
+ XEmacs Lisp provides the traditional four arithmetic operations:
+addition, subtraction, multiplication, and division. Remainder and
+modulus functions supplement the division functions. The functions to
+add or subtract 1 are provided because they are traditional in Lisp and
+commonly used.
+
+ All of these functions except `%' return a floating point value if
+any argument is floating.
+
+ It is important to note that in XEmacs Lisp, arithmetic functions do
+not check for overflow. Thus `(1+ 134217727)' may evaluate to
+-134217728, depending on your hardware.
+
+ - Function: 1+ NUMBER-OR-MARKER
+ This function returns NUMBER-OR-MARKER plus 1. For example,
+
+ (setq foo 4)
+ => 4
+ (1+ foo)
+ => 5
+
+ This function is not analogous to the C operator `++'--it does not
+ increment a variable. It just computes a sum. Thus, if we
+ continue,
+
+ foo
+ => 4
+
+ If you want to increment the variable, you must use `setq', like
+ this:
+
+ (setq foo (1+ foo))
+ => 5
+
+ Now that the `cl' package is always available from lisp code, a
+ more convenient and natural way to increment a variable is
+ `(incf foo)'.
+
+ - Function: 1- NUMBER-OR-MARKER
+ This function returns NUMBER-OR-MARKER minus 1.
+
+ - Function: abs NUMBER
+ This returns the absolute value of NUMBER.
+
+ - Function: + &rest NUMBERS-OR-MARKERS
+ This function adds its arguments together. When given no
+ arguments, `+' returns 0.
+
+ (+)
+ => 0
+ (+ 1)
+ => 1
+ (+ 1 2 3 4)
+ => 10
+
+ - Function: - &optional NUMBER-OR-MARKER &rest OTHER-NUMBERS-OR-MARKERS
+ The `-' function serves two purposes: negation and subtraction.
+ When `-' has a single argument, the value is the negative of the
+ argument. When there are multiple arguments, `-' subtracts each of
+ the OTHER-NUMBERS-OR-MARKERS from NUMBER-OR-MARKER, cumulatively.
+ If there are no arguments, the result is 0.
+
+ (- 10 1 2 3 4)
+ => 0
+ (- 10)
+ => -10
+ (-)
+ => 0
+
+ - Function: * &rest NUMBERS-OR-MARKERS
+ This function multiplies its arguments together, and returns the
+ product. When given no arguments, `*' returns 1.
+
+ (*)
+ => 1
+ (* 1)
+ => 1
+ (* 1 2 3 4)
+ => 24
+
+ - Function: / DIVIDEND DIVISOR &rest DIVISORS
+ This function divides DIVIDEND by DIVISOR and returns the
+ quotient. If there are additional arguments DIVISORS, then it
+ divides DIVIDEND by each divisor in turn. Each argument may be a
+ number or a marker.
+
+ If all the arguments are integers, then the result is an integer
+ too. This means the result has to be rounded. On most machines,
+ the result is rounded towards zero after each division, but some
+ machines may round differently with negative arguments. This is
+ because the Lisp function `/' is implemented using the C division
+ operator, which also permits machine-dependent rounding. As a
+ practical matter, all known machines round in the standard fashion.
+
+ If you divide by 0, an `arith-error' error is signaled. (*Note
+ Errors::.)
+
+ (/ 6 2)
+ => 3
+ (/ 5 2)
+ => 2
+ (/ 25 3 2)
+ => 4
+ (/ -17 6)
+ => -2
+
+ The result of `(/ -17 6)' could in principle be -3 on some
+ machines.
+
+ - Function: % DIVIDEND DIVISOR
+ This function returns the integer remainder after division of
+ DIVIDEND by DIVISOR. The arguments must be integers or markers.
+
+ For negative arguments, the remainder is in principle
+ machine-dependent since the quotient is; but in practice, all
+ known machines behave alike.
+
+ An `arith-error' results if DIVISOR is 0.
+
+ (% 9 4)
+ => 1
+ (% -9 4)
+ => -1
+ (% 9 -4)
+ => 1
+ (% -9 -4)
+ => -1
+
+ For any two integers DIVIDEND and DIVISOR,
+
+ (+ (% DIVIDEND DIVISOR)
+ (* (/ DIVIDEND DIVISOR) DIVISOR))
+
+ always equals DIVIDEND.
+
+ - Function: mod DIVIDEND DIVISOR
+ This function returns the value of DIVIDEND modulo DIVISOR; in
+ other words, the remainder after division of DIVIDEND by DIVISOR,
+ but with the same sign as DIVISOR. The arguments must be numbers
+ or markers.
+
+ Unlike `%', `mod' returns a well-defined result for negative
+ arguments. It also permits floating point arguments; it rounds the
+ quotient downward (towards minus infinity) to an integer, and uses
+ that quotient to compute the remainder.
+
+ An `arith-error' results if DIVISOR is 0.
+
+ (mod 9 4)
+ => 1
+ (mod -9 4)
+ => 3
+ (mod 9 -4)
+ => -3
+ (mod -9 -4)
+ => -1
+ (mod 5.5 2.5)
+ => .5
+
+ For any two numbers DIVIDEND and DIVISOR,
+
+ (+ (mod DIVIDEND DIVISOR)
+ (* (floor DIVIDEND DIVISOR) DIVISOR))
+
+ always equals DIVIDEND, subject to rounding error if either
+ argument is floating point. For `floor', see *Note Numeric
+ Conversions::.
+
+\1f
+File: lispref.info, Node: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers
+
+Rounding Operations
+===================
+
+ The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
+floating point argument and return a floating point result whose value
+is a nearby integer. `ffloor' returns the nearest integer below;
+`fceiling', the nearest integer above; `ftruncate', the nearest integer
+in the direction towards zero; `fround', the nearest integer.
+
+ - Function: ffloor FLOAT
+ This function rounds FLOAT to the next lower integral value, and
+ returns that value as a floating point number.
+
+ - Function: fceiling FLOAT
+ This function rounds FLOAT to the next higher integral value, and
+ returns that value as a floating point number.
+
+ - Function: ftruncate FLOAT
+ This function rounds FLOAT towards zero to an integral value, and
+ returns that value as a floating point number.
+
+ - Function: fround FLOAT
+ This function rounds FLOAT to the nearest integral value, and
+ returns that value as a floating point number.
+
+\1f
+File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers
+
+Bitwise Operations on Integers
+==============================
+
+ In a computer, an integer is represented as a binary number, a
+sequence of "bits" (digits which are either zero or one). A bitwise
+operation acts on the individual bits of such a sequence. For example,
+"shifting" moves the whole sequence left or right one or more places,
+reproducing the same pattern "moved over".
+
+ The bitwise operations in XEmacs Lisp apply only to integers.
+
+ - Function: lsh INTEGER1 COUNT
+ `lsh', which is an abbreviation for "logical shift", shifts the
+ bits in INTEGER1 to the left COUNT places, or to the right if
+ COUNT is negative, bringing zeros into the vacated bits. If COUNT
+ is negative, `lsh' shifts zeros into the leftmost
+ (most-significant) bit, producing a positive result even if
+ INTEGER1 is negative. Contrast this with `ash', below.
+
+ Here are two examples of `lsh', shifting a pattern of bits one
+ place to the left. We show only the low-order eight bits of the
+ binary pattern; the rest are all zero.
+
+ (lsh 5 1)
+ => 10
+ ;; Decimal 5 becomes decimal 10.
+ 00000101 => 00001010
+
+ (lsh 7 1)
+ => 14
+ ;; Decimal 7 becomes decimal 14.
+ 00000111 => 00001110
+
+ As the examples illustrate, shifting the pattern of bits one place
+ to the left produces a number that is twice the value of the
+ previous number.
+
+ Shifting a pattern of bits two places to the left produces results
+ like this (with 8-bit binary numbers):
+
+ (lsh 3 2)
+ => 12
+ ;; Decimal 3 becomes decimal 12.
+ 00000011 => 00001100
+
+ On the other hand, shifting one place to the right looks like this:
+
+ (lsh 6 -1)
+ => 3
+ ;; Decimal 6 becomes decimal 3.
+ 00000110 => 00000011
+
+ (lsh 5 -1)
+ => 2
+ ;; Decimal 5 becomes decimal 2.
+ 00000101 => 00000010
+
+ As the example illustrates, shifting one place to the right
+ divides the value of a positive integer by two, rounding downward.
+
+ The function `lsh', like all XEmacs Lisp arithmetic functions, does
+ not check for overflow, so shifting left can discard significant
+ bits and change the sign of the number. For example, left shifting
+ 134,217,727 produces -2 on a 28-bit machine:
+
+ (lsh 134217727 1) ; left shift
+ => -2
+
+ In binary, in the 28-bit implementation, the argument looks like
+ this:
+
+ ;; Decimal 134,217,727
+ 0111 1111 1111 1111 1111 1111 1111
+
+ which becomes the following when left shifted:
+
+ ;; Decimal -2
+ 1111 1111 1111 1111 1111 1111 1110
+
+ - Function: ash INTEGER1 COUNT
+ `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
+ COUNT places, or to the right if COUNT is negative.
+
+ `ash' gives the same results as `lsh' except when INTEGER1 and
+ COUNT are both negative. In that case, `ash' puts ones in the
+ empty bit positions on the left, while `lsh' puts zeros in those
+ bit positions.
+
+ Thus, with `ash', shifting the pattern of bits one place to the
+ right looks like this:
+
+ (ash -6 -1) => -3
+ ;; Decimal -6 becomes decimal -3.
+ 1111 1111 1111 1111 1111 1111 1010
+ =>
+ 1111 1111 1111 1111 1111 1111 1101
+
+ In contrast, shifting the pattern of bits one place to the right
+ with `lsh' looks like this:
+
+ (lsh -6 -1) => 134217725
+ ;; Decimal -6 becomes decimal 134,217,725.
+ 1111 1111 1111 1111 1111 1111 1010
+ =>
+ 0111 1111 1111 1111 1111 1111 1101
+
+ Here are other examples:
+
+ ; 28-bit binary values
+
+ (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 20 ; = 0000 0000 0000 0000 0000 0001 0100
+
+ (ash 5 2)
+ => 20
+ (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
+ => -20 ; = 1111 1111 1111 1111 1111 1110 1100
+ (ash -5 2)
+ => -20
+
+ (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 1 ; = 0000 0000 0000 0000 0000 0000 0001
+
+ (ash 5 -2)
+ => 1
+
+ (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
+ => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110
+
+ (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
+ => -2 ; = 1111 1111 1111 1111 1111 1111 1110
+
+ - Function: logand &rest INTS-OR-MARKERS
+ This function returns the "logical and" of the arguments: the Nth
+ bit is set in the result if, and only if, the Nth bit is set in
+ all the arguments. ("Set" means that the value of the bit is 1
+ rather than 0.)
+
+ For example, using 4-bit binary numbers, the "logical and" of 13
+ and 12 is 12: 1101 combined with 1100 produces 1100. In both the
+ binary numbers, the leftmost two bits are set (i.e., they are
+ 1's), so the leftmost two bits of the returned value are set.
+ However, for the rightmost two bits, each is zero in at least one
+ of the arguments, so the rightmost two bits of the returned value
+ are 0's.
+
+ Therefore,
+
+ (logand 13 12)
+ => 12
+
+ If `logand' is not passed any argument, it returns a value of -1.
+ This number is an identity element for `logand' because its binary
+ representation consists entirely of ones. If `logand' is passed
+ just one argument, it returns that argument.
+
+ ; 28-bit binary values
+
+ (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110
+ ; 13 = 0000 0000 0000 0000 0000 0000 1101
+ => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100
+
+ (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110
+ ; 13 = 0000 0000 0000 0000 0000 0000 1101
+ ; 4 = 0000 0000 0000 0000 0000 0000 0100
+ => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100
+
+ (logand)
+ => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111
+
+ - Function: logior &rest INTS-OR-MARKERS
+ This function returns the "inclusive or" of its arguments: the Nth
+ bit is set in the result if, and only if, the Nth bit is set in at
+ least one of the arguments. If there are no arguments, the result
+ is zero, which is an identity element for this operation. If
+ `logior' is passed just one argument, it returns that argument.
+
+ ; 28-bit binary values
+
+ (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101
+
+ (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ ; 7 = 0000 0000 0000 0000 0000 0000 0111
+ => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111
+
+ - Function: logxor &rest INTS-OR-MARKERS
+ This function returns the "exclusive or" of its arguments: the Nth
+ bit is set in the result if, and only if, the Nth bit is set in an
+ odd number of the arguments. If there are no arguments, the
+ result is 0, which is an identity element for this operation. If
+ `logxor' is passed just one argument, it returns that argument.
+
+ ; 28-bit binary values
+
+ (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001
+
+ (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ ; 7 = 0000 0000 0000 0000 0000 0000 0111
+ => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110
+
+ - Function: lognot INTEGER
+ This function returns the logical complement of its argument: the
+ Nth bit is one in the result if, and only if, the Nth bit is zero
+ in INTEGER, and vice-versa.
+
+ (lognot 5)
+ => -6
+ ;; 5 = 0000 0000 0000 0000 0000 0000 0101
+ ;; becomes
+ ;; -6 = 1111 1111 1111 1111 1111 1111 1010
+
+\1f
+File: lispref.info, Node: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers
+
+Standard Mathematical Functions
+===============================
+
+ These mathematical functions are available if floating point is
+supported (which is the normal state of affairs). They allow integers
+as well as floating point numbers as arguments.
+
+ - Function: sin ARG
+ - Function: cos ARG
+ - Function: tan ARG
+ These are the ordinary trigonometric functions, with argument
+ measured in radians.
+
+ - Function: asin ARG
+ The value of `(asin ARG)' is a number between -pi/2 and pi/2
+ (inclusive) whose sine is ARG; if, however, ARG is out of range
+ (outside [-1, 1]), then the result is a NaN.
+
+ - Function: acos ARG
+ The value of `(acos ARG)' is a number between 0 and pi (inclusive)
+ whose cosine is ARG; if, however, ARG is out of range (outside
+ [-1, 1]), then the result is a NaN.
+
+ - Function: atan ARG
+ The value of `(atan ARG)' is a number between -pi/2 and pi/2
+ (exclusive) whose tangent is ARG.
+
+ - Function: sinh ARG
+ - Function: cosh ARG
+ - Function: tanh ARG
+ These are the ordinary hyperbolic trigonometric functions.
+
+ - Function: asinh ARG
+ - Function: acosh ARG
+ - Function: atanh ARG
+ These are the inverse hyperbolic trigonometric functions.
+
+ - Function: exp ARG
+ This is the exponential function; it returns e to the power ARG.
+ e is a fundamental mathematical constant also called the base of
+ natural logarithms.
+
+ - Function: log ARG &optional BASE
+ This function returns the logarithm of ARG, with base BASE. If
+ you don't specify BASE, the base E is used. If ARG is negative,
+ the result is a NaN.
+
+ - Function: log10 ARG
+ This function returns the logarithm of ARG, with base 10. If ARG
+ is negative, the result is a NaN. `(log10 X)' == `(log X 10)', at
+ least approximately.
+
+ - Function: expt X Y
+ This function returns X raised to power Y. If both arguments are
+ integers and Y is positive, the result is an integer; in this
+ case, it is truncated to fit the range of possible integer values.
+
+ - Function: sqrt ARG
+ This returns the square root of ARG. If ARG is negative, the
+ value is a NaN.
+
+ - Function: cube-root ARG
+ This returns the cube root of ARG.
+
+\1f
+File: lispref.info, Node: Random Numbers, Prev: Math Functions, Up: Numbers
+
+Random Numbers
+==============
+
+ A deterministic computer program cannot generate true random numbers.
+For most purposes, "pseudo-random numbers" suffice. A series of
+pseudo-random numbers is generated in a deterministic fashion. The
+numbers are not truly random, but they have certain properties that
+mimic a random series. For example, all possible values occur equally
+often in a pseudo-random series.
+
+ In XEmacs, pseudo-random numbers are generated from a "seed" number.
+Starting from any given seed, the `random' function always generates
+the same sequence of numbers. XEmacs always starts with the same seed
+value, so the sequence of values of `random' is actually the same in
+each XEmacs run! For example, in one operating system, the first call
+to `(random)' after you start XEmacs always returns -1457731, and the
+second one always returns -7692030. This repeatability is helpful for
+debugging.
+
+ If you want truly unpredictable random numbers, execute `(random
+t)'. This chooses a new seed based on the current time of day and on
+XEmacs's process ID number.
+
+ - Function: random &optional LIMIT
+ This function returns a pseudo-random integer. Repeated calls
+ return a series of pseudo-random integers.
+
+ If LIMIT is a positive integer, the value is chosen to be
+ nonnegative and less than LIMIT.
+
+ If LIMIT is `t', it means to choose a new seed based on the
+ current time of day and on XEmacs's process ID number.
+
+ On some machines, any integer representable in Lisp may be the
+ result of `random'. On other machines, the result can never be
+ larger than a certain maximum or less than a certain (negative)
+ minimum.
+
+\1f
+File: lispref.info, Node: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top
+
+Strings and Characters
+**********************
+
+ A string in XEmacs Lisp is an array that contains an ordered sequence
+of characters. Strings are used as names of symbols, buffers, and
+files, to send messages to users, to hold text being copied between
+buffers, and for many other purposes. Because strings are so important,
+XEmacs Lisp has many functions expressly for manipulating them. XEmacs
+Lisp programs use strings more often than individual characters.
+
+* Menu:
+
+* Basics: String Basics. Basic properties of strings and characters.
+* Predicates for Strings:: Testing whether an object is a string or char.
+* Creating Strings:: Functions to allocate new strings.
+* Predicates for Characters:: Testing whether an object is a character.
+* Character Codes:: Each character has an equivalent integer.
+* Text Comparison:: Comparing characters or strings.
+* String Conversion:: Converting characters or strings and vice versa.
+* Modifying Strings:: Changing characters in a string.
+* String Properties:: Additional information attached to strings.
+* Formatting Strings:: `format': XEmacs's analog of `printf'.
+* Character Case:: Case conversion functions.
+* Case Tables:: Customizing case conversion.
+* Char Tables:: Mapping from characters to Lisp objects.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
+
+Terminal Output
+===============
+
+ The terminal output functions send output to the terminal or keep
+track of output sent to the terminal. The function `device-baud-rate'
+tells you what XEmacs thinks is the output speed of the terminal.
+
+ - Function: device-baud-rate &optional DEVICE
+ This function's value is the output speed of the terminal
+ associated with DEVICE, as far as XEmacs knows. DEVICE defaults
+ to the selected device (usually the only device) if omitted.
+ Changing this value does not change the speed of actual data
+ transmission, but the value is used for calculations such as
+ padding. This value has no effect for window-system devices.
+ (This is different in FSF Emacs, where the baud rate also affects
+ decisions about whether to scroll part of the screen or repaint,
+ even when using a window system.)
+
+ The value is measured in bits per second.
+
+ XEmacs attempts to automatically initialize the baud rate by querying
+the terminal. If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal. Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+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
+ This function sets the output speed of DEVICE. See
+ `device-baud-rate'. DEVICE defaults to the selected device
+ (usually the only device) if omitted.
+
+ - Function: send-string-to-terminal CHAR-OR-STRING &optional STDOUT-P
+ DEVICE
+ This function sends CHAR-OR-STRING to the terminal without
+ alteration. Control characters in CHAR-OR-STRING have
+ terminal-dependent effects.
+
+ If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+ stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
+ tty or stream device, and the function writes to the device's
+ normal or error output, according to STDOUT-P.
+
+ One use of this function is to define function keys on terminals
+ that have downloadable function key definitions. For example,
+ this is how on certain terminals to define function key 4 to move
+ forward four characters (by transmitting the characters `C-u C-f'
+ to the computer):
+
+ (send-string-to-terminal "\eF4\^U\^F")
+ => nil
+
+ - Command: open-termscript FILENAME
+ This function is used to open a "termscript file" that will record
+ all the characters sent by XEmacs to the terminal. (If there are
+ multiple tty or stream devices, all characters sent to all such
+ devices are recorded.) The function returns `nil'. Termscript
+ files are useful for investigating problems where XEmacs garbles
+ the screen, problems that are due to incorrect Termcap entries or
+ to undesirable settings of terminal options more often than to
+ actual XEmacs bugs. Once you are certain which characters were
+ actually output, you can determine reliably whether they
+ correspond to the Termcap specifications in use.
+
+ A `nil' value for FILENAME stops recording terminal output.
+
+ See also `open-dribble-file' in *Note Terminal Input::.
+
+ (open-termscript "../junk/termscript")
+ => nil
+
+\1f
+File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
+
+Flow Control
+============
+
+ This section attempts to answer the question "Why does XEmacs choose
+to use flow-control characters in its command character set?" For a
+second view on this issue, read the comments on flow control in the
+`emacs/INSTALL' file from the distribution; for help with Termcap
+entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
+
+ At one time, most terminals did not need flow control, and none used
+`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
+`C-q' as command characters was uncontroversial. XEmacs, for economy
+of keystrokes and portability, used nearly all the ASCII control
+characters, with mnemonic meanings when possible; thus, `C-s' for
+search and `C-q' for quote.
+
+ Later, some terminals were introduced which required these characters
+for flow control. They were not very good terminals for full-screen
+editing, so XEmacs maintainers did not pay attention. In later years,
+flow control with `C-s' and `C-q' became widespread among terminals,
+but by this time it was usually an option. And the majority of users,
+who can turn flow control off, were unwilling to switch to less
+mnemonic key bindings for the sake of flow control.
+
+ So which usage is "right", XEmacs's or that of some terminal and
+concentrator manufacturers? This question has no simple answer.
+
+ One reason why we are reluctant to cater to the problems caused by
+`C-s' and `C-q' is that they are gratuitous. There are other
+techniques (albeit less common in practice) for flow control that
+preserve transparency of the character stream. Note also that their use
+for flow control is not an official standard. Interestingly, on the
+model 33 teletype with a paper tape punch (which is very old), `C-s'
+and `C-q' were sent by the computer to turn the punch on and off!
+
+ As X servers and other window systems replace character-only
+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
+ 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::.).
+
+ You can use the function `enable-flow-control-on' in your `.emacs'
+file to enable flow control automatically on certain terminal types.
+
+ - Function: enable-flow-control-on &rest TERMTYPES
+ This function enables flow control, and the aliases `C-\' and
+ `C-^', if the terminal type is one of TERMTYPES. For example:
+
+ (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
+
+ Here is how `enable-flow-control' does its job:
+
+ 1. It sets CBREAK mode for terminal input, and tells the operating
+ system to handle flow control, with `(set-input-mode nil t)'.
+
+ 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
+ into `C-s' and `C-q'. Except at its very lowest level, XEmacs
+ never knows that the characters typed were anything but `C-s' and
+ `C-q', so you can in effect type them as `C-\' and `C-^' even when
+ they are input for other commands. *Note Translating Input::.
+
+ If the terminal is the source of the flow control characters, then
+once you enable kernel flow control handling, you probably can make do
+with less padding than normal for that terminal. You can reduce the
+amount of padding by customizing the Termcap entry. You can also
+reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
+a smaller speed when calculating the padding needed. *Note Terminal
+Output::.
+
+\1f
+File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
+
+Batch Mode
+==========
+
+ The command line option `-batch' causes XEmacs to run
+noninteractively. In this mode, XEmacs does not read commands from the
+terminal, it does not alter the terminal modes, and it does not expect
+to be outputting to an erasable screen. The idea is that you specify
+Lisp programs to run; when they are finished, XEmacs should exit. The
+way to specify the programs to run is with `-l FILE', which loads the
+library named FILE, and `-f FUNCTION', which calls FUNCTION with no
+arguments.
+
+ Any Lisp program output that would normally go to the echo area,
+either using `message' or using `prin1', etc., with `t' as the stream,
+goes instead to XEmacs's standard error descriptor when in batch mode.
+Thus, XEmacs behaves much like a noninteractive application program.
+(The echo area output that XEmacs itself normally generates, such as
+command echoing, is suppressed entirely.)
+
+ - Function: noninteractive
+ This function returns non-`nil' when XEmacs is running in batch
+ mode.
+
+ - Variable: noninteractive
+ This variable is non-`nil' when XEmacs is running in batch mode.
+ Setting this variable to `nil', however, will not change whether
+ XEmacs is running in batch mode, and will not change the return
+ value of the `noninteractive' function.
+
+\1f
+File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
+
+Functions Specific to the X Window System
+*****************************************
+
+ XEmacs provides the concept of "devices", which generalizes
+connections to an X server, a TTY device, etc. Most information about
+an X server that XEmacs is connected to can be determined through
+general console and device functions. *Note Consoles and Devices::.
+However, there are some features of the X Window System that do not
+generalize well, and they are covered specially here.
+
+* Menu:
+
+* X Selections:: Transferring text to and from other X clients.
+* X Server:: Information about the X server connected to
+ a particular device.
+* X Miscellaneous:: Other X-specific functions and variables.
+
+\1f
+File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
+
+X Selections
+============
+
+ The X server records a set of "selections" which permit transfer of
+data between application programs. The various selections are
+distinguished by "selection types", represented in XEmacs by symbols.
+X clients including XEmacs can read or set the selection for any given
+type.
+
+ - Function: x-own-selection DATA &optional TYPE
+ This function sets a "selection" in the X server. It takes two
+ arguments: a value, DATA, and the selection type TYPE to assign it
+ to. DATA may be a string, a cons of two markers, or an extent.
+ In the latter cases, the selection is considered to be the text
+ between the markers, or between the extent's endpoints.
+
+ Each possible TYPE has its own selection value, which changes
+ independently. The usual values of TYPE are `PRIMARY' and
+ `SECONDARY'; these are symbols with upper-case names, in accord
+ with X Windows conventions. The default is `PRIMARY'.
+
+ (In FSF Emacs, this function is called `x-set-selection' and takes
+ different arguments.)
+
+ - Function: x-get-selection
+ This function accesses selections set up by XEmacs or by other X
+ clients. It returns the value of the current primary selection.
+
+ - Function: x-disown-selection &optional SECONDARY-P
+ Assuming we own the selection, this function disowns it. If
+ SECONDARY-P is non-`nil', the secondary selection instead of the
+ primary selection is discarded.
+
+ The X server also has a set of numbered "cut buffers" which can
+store text or other data being moved between applications. Cut buffers
+are considered obsolete, but XEmacs supports them for the sake of X
+clients that still use them.
+
+ - Function: x-get-cutbuffer &optional N
+ 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
+ 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.)
+
+\1f
+File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
+
+X Server
+========
+
+ This section describes how to access and change the overall status of
+the X server XEmacs is using.
+
+* Menu:
+
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+* Grabs:: Restricting access to the server by other apps.
+
+\1f
+File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
+
+Resources
+---------
+
+ - Function: default-x-device
+ This function return the default X device for resourcing. This is
+ the first-created X device that still exists.
+
+ - Function: x-get-resource NAME CLASS TYPE &optional LOCALE DEVICE
+ NOERROR
+ This function retrieves a resource value from the X resource
+ manager.
+
+ * The first arg is the name of the resource to retrieve, such as
+ `"font"'.
+
+ * The second arg is the class of the resource to retrieve, like
+ `"Font"'.
+
+ * The third arg should be one of the symbols `string',
+ `integer', `natnum', or `boolean', specifying the type of
+ object that the database is searched for.
+
+ * The fourth arg is the locale to search for the resources on,
+ and can currently be a a buffer, a frame, a device, or the
+ symbol `global'. If omitted, it defaults to `global'.
+
+ * The fifth arg is the device to search for the resources on.
+ (The resource database for a particular device is constructed
+ by combining non-device- specific resources such any
+ command-line resources specified and any app-defaults files
+ found [or the fallback resources supplied by XEmacs, if no
+ app-defaults file is found] with device-specific resources
+ such as those supplied using `xrdb'.) If omitted, it defaults
+ to the device of LOCALE, if a device can be derived (i.e. if
+ LOCALE is a frame or device), and otherwise defaults to the
+ value of `default-x-device'.
+
+ * The sixth arg NOERROR, if non-`nil', means do not signal an
+ error if a bogus resource specification was retrieved (e.g.
+ if a non-integer was given when an integer was requested).
+ In this case, a warning is issued instead.
+
+ The resource names passed to this function are looked up relative
+ to the locale.
+
+ If you want to search for a subresource, you just need to specify
+ the resource levels in NAME and CLASS. For example, NAME could be
+ `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
+
+ Specifically,
+
+ 1. If LOCALE is a buffer, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
+ "String");'
+
+ 2. If LOCALE is a frame, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
+ "String");'
+
+ 3. If LOCALE is a device, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
+ "String");'
+
+ 4. If LOCALE is the symbol `global', a call
+
+ `(x-get-resource "foreground" "Foreground" 'string 'global)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.foreground",
+ "Emacs.Foreground",
+ "String");'
+
+ Note that for `global', no prefix is added other than that of the
+ application itself; thus, you can use this locale to retrieve
+ arbitrary application resources, if you really want to.
+
+ The returned value of this function is `nil' if the queried
+ resource is not found. If TYPE is `string', a string is returned,
+ and if it is `integer', an integer is returned. If TYPE is
+ `boolean', then the returned value is the list `(t)' for true,
+ `(nil)' for false, and is `nil' to mean "unspecified".
+
+ - Function: x-put-resource RESOURCE-LINE &optional DEVICE
+ This function adds a resource to the resource database for DEVICE.
+ RESOURCE-LINE specifies the resource to add and should be a
+ standard resource specification.
+
+ - Variable: x-emacs-application-class
+ This variable holds The X application class of the XEmacs process.
+ This controls, among other things, the name of the "app-defaults"
+ file that XEmacs will use. For changes to this variable to take
+ effect, they must be made before the connection to the X server is
+ initialized, that is, this variable may only be changed before
+ 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
+ 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".
+
+\1f
+File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
+
+Data about the X Server
+-----------------------
+
+ This section describes functions and a variable that you can use to
+get information about the capabilities and origin of the X server
+corresponding to a particular device. The device argument is generally
+optional and defaults to the selected device.
+
+ - Function: x-server-version &optional DEVICE
+ This function returns the list of version numbers of the X server
+ DEVICE is on. The returned value is a list of three integers: the
+ major and minor version numbers of the X protocol in use, and the
+ vendor-specific release number.
+
+ - Function: x-server-vendor &optional DEVICE
+ This function returns the vendor supporting the X server DEVICE is
+ on.
+
+ - Function: x-display-visual-class &optional DEVICE
+ This function returns the visual class of the display DEVICE is
+ on. The value is one of the symbols `static-gray', `gray-scale',
+ `static-color', `pseudo-color', `true-color', and `direct-color'.
+ (Note that this is different from previous versions of XEmacs,
+ which returned `StaticGray', `GrayScale', etc.)
+
+\1f
+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.
+
+\1f
+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
+
+\1f
+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::
+
+\1f
+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.
+
+\1f
+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::
+
+\1f
+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))
+
+\1f
+File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
+
+Elisp Interface for Sending Messages
+------------------------------------
+
+ - Function: make-tooltalk-message ATTRIBUTES
+ Create a ToolTalk message and initialize its attributes. The
+ value of ATTRIBUTES must be a list of alternating keyword/values,
+ where keywords are symbols that name valid message attributes.
+ For example:
+
+ (make-tooltalk-message
+ '(class TT_NOTICE
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "do-something"
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants. Attribute names are the same as those
+ supported by `set-tooltalk-message-attribute', plus `args'.
+
+ The value of `args' should be a list of message arguments where
+ each message argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk message arguments in chapter 4 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: send-tooltalk-message MSG
+ Send the message on its way. Once the message has been sent it's
+ almost always a good idea to get rid of it with
+ `destroy-tooltalk-message'.
+
+
+ - Function: return-tooltalk-message MSG &optional MODE
+ Send a reply to this message. The second argument can be `reply',
+ `reject' or `fail'; the default is `reply'. Before sending a
+ reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
+ should have been filled in - see `set-tooltalk-message-attribute'.
+
+
+ - Function: get-tooltalk-message-attribute MSG ATTRIBUTE &optional ARGN
+ Returns the indicated ToolTalk message attribute. Attributes are
+ identified by symbols with the same name (underscores and all) as
+ the suffix of the ToolTalk `tt_message_<attribute>' function that
+ extracts the value. String attribute values are copied and
+ enumerated type values (except disposition) are converted to
+ symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
+ represented by fixnums (small integers), `opnum' is converted to a
+ string, and `disposition' is converted to a fixnum. We convert
+ `opnum' (a C int) to a string (e.g. `123' => `"123"') because
+ there's no guarantee that opnums will fit within the range of
+ XEmacs Lisp integers.
+
+ [TBD] Use the `plist' attribute instead of C API `user' attribute
+ for user-defined message data. To retrieve the value of a message
+ property, specify the indicator for ARGN. For example, to get the
+ value of a property called `rflag', use
+
+ (get-tooltalk-message-attribute msg 'plist 'rflag)
+
+ To get the value of a message argument use one of the `arg_val'
+ (strings), `arg_ival' (integers), or `arg_bval' (strings with
+ embedded nulls), attributes. For example, to get the integer
+ value of the third argument:
+
+ (get-tooltalk-message-attribute msg 'arg_ival 2)
+
+ As you can see, argument numbers are zero-based. The type of each
+ arguments can be retrieved with the `arg_type' attribute; however
+ ToolTalk doesn't define any semantics for the string value of
+ `arg_type'. Conventionally `string' is used for strings and `int'
+ for 32 bit integers. Note that XEmacs Lisp stores the lengths of
+ strings explicitly (unlike C) so treating the value returned by
+ `arg_bval' like a string is fine.
+
+
+ - Function: set-tooltalk-message-attribute VALUE MSG ATTRIBUTE
+ &optional ARGN
+ Initialize one ToolTalk message attribute.
+
+ Attribute names and values are the same as for
+ `get-tooltalk-message-attribute'. A property list is provided for
+ user data (instead of the `user' message attribute); see
+ `get-tooltalk-message-attribute'.
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the state of the message
+ changes. This is usually used to notice when the message's state
+ has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
+ argument values can be used.
+
+ If one of the argument attributes is specified as `arg_val',
+ `arg_ival', or `arg_bval', then ARGN must be the number of an
+ already created argument. Arguments can be added to a message
+ with `add-tooltalk-message-arg'.
+
+
+ - Function: add-tooltalk-message-arg MSG MODE TYPE &optional VALUE
+ Append one new argument to the message. MODE must be one of
+ `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
+ can be a string or an integer. ToolTalk doesn't define any
+ semantics for TYPE, so only the participants in the protocol
+ you're using need to agree what types mean (if anything).
+ Conventionally `string' is used for strings and `int' for 32 bit
+ integers. Arguments can initialized by providing a value or with
+ `set-tooltalk-message-attribute'; the latter is necessary if you
+ want to initialize the argument with a string that can contain
+ embedded nulls (use `arg_bval').
+
+
+ - Function: create-tooltalk-message
+ Create a new ToolTalk message. The message's session attribute is
+ initialized to the default session. Other attributes can be
+ initialized with `set-tooltalk-message-attribute'.
+ `make-tooltalk-message' is the preferred way to create and
+ initialize a message.
+
+
+ - Function: destroy-tooltalk-message MSG
+ Apply `tt_message_destroy' to the message. It's not necessary to
+ destroy messages after they've been processed by a message or
+ pattern callback, the Lisp/ToolTalk callback machinery does this
+ for you.
+
+\1f
+File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
+
+Receiving Messages
+==================
+
+* Menu:
+
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
+
+\1f
+File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
+
+Example of Receiving Messages
+-----------------------------
+
+ Here's a simple example of a handler for a message that tells XEmacs
+to display a string in the mini-buffer area. The message operation is
+called `emacs-display-string'. Its first (0th) argument is the string
+to display.
+
+ (defun tooltalk-display-string-handler (msg)
+ (message (get-tooltalk-message-attribute msg 'arg_val 0)))
+
+ (defvar display-string-pattern
+ '(category TT_HANDLE
+ scope TT_SESSION
+ op "emacs-display-string"
+ callback tooltalk-display-string-handler))
+
+ (let ((p (make-tooltalk-pattern display-string-pattern)))
+ (register-tooltalk-pattern p))
+
+\1f
+File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
+
+Elisp Interface for Receiving Messages
+--------------------------------------
+
+ - Function: make-tooltalk-pattern ATTRIBUTES
+ Create a ToolTalk pattern and initialize its attributes. The
+ value of attributes must be a list of alternating keyword/values,
+ where keywords are symbols that name valid pattern attributes or
+ lists of valid attributes. For example:
+
+ (make-tooltalk-pattern
+ '(category TT_OBSERVE
+ scope TT_SESSION
+ op ("operation1" "operation2")
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Attribute names are the same as those supported by
+ `add-tooltalk-pattern-attribute', plus `'args'.
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants or lists of same. When a list of values is
+ provided all of the list elements are added to the attribute. In
+ the example above, messages whose `op' attribute is `"operation1"'
+ or `"operation2"' would match the pattern.
+
+ The value of ARGS should be a list of pattern arguments where each
+ pattern argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk pattern arguments in chapter 3 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: register-tooltalk-pattern PAT
+ XEmacs will begin receiving messages that match this pattern.
+
+ - Function: unregister-tooltalk-pattern PAT
+ XEmacs will stop receiving messages that match this pattern.
+
+ - Function: add-tooltalk-pattern-attribute VALUE PAT INDICATOR
+ Add one value to the indicated pattern attribute. The names of
+ attributes are the same as the ToolTalk accessors used to set them
+ less the `tooltalk_pattern_' prefix and the `_add' suffix. For
+ example, the name of the attribute for the
+ `tt_pattern_disposition_add' attribute is `disposition'. The
+ `category' attribute is handled specially, since a pattern can only
+ be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the pattern matches an
+ incoming message.
+
+ - Function: add-tooltalk-pattern-arg PAT MODE TYPE VALUE
+ Add one fully-specified argument to a ToolTalk pattern. MODE must
+ be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
+ string. VALUE can be an integer, string or `nil'. If VALUE is an
+ integer then an integer argument (`tt_pattern_iarg_add') is added;
+ otherwise a string argument is added. At present there's no way
+ to add a binary data argument.
+
+
+ - Function: create-tooltalk-pattern
+ Create a new ToolTalk pattern and initialize its session attribute
+ to be the default session.
+
+ - Function: destroy-tooltalk-pattern PAT
+ Apply `tt_pattern_destroy' to the pattern. This effectively
+ unregisters the pattern.
+
+ - Function: describe-tooltalk-message MSG &optional STREAM
+ Print the message's attributes and arguments to STREAM. This is
+ often useful for debugging.
+
+\1f
+File: lispref.info, Node: LDAP Support, Next: Internationalization, Prev: ToolTalk Support, Up: Top
+
+LDAP Support
+************
+
+ XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.
+
+* Menu:
+
+* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
+* XEmacs LDAP API:: Lisp access to LDAP functions
+* Syntax of Search Filters:: A brief summary of RFC 1558
+
+\1f
+File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
+
+Building XEmacs with LDAP support
+=================================
+
+ LDAP support must be added to XEmacs at build time since it requires
+linking to an external LDAP client library. As of 21.2, XEmacs has been
+successfully built and tested with
+
+ * OpenLDAP 1.0.3 (`http://www.openldap.org/')
+
+ * University of Michigan's LDAP 3.3
+ (`http://www.umich.edu/~dirsvcs/ldap/')
+
+ * LDAP SDK 1.0 from Netscape Corp. (`http://developer.netscape.com/')
+
+ Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
+
+ The standard XEmacs configure script autodetects an installed LDAP
+library provided the library itself and the corresponding header files
+can be found in the library and include paths. A successful detection
+will be signalled in the final output of the configure script.
+
+\1f
+File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
+
+XEmacs LDAP API
+===============
+
+ XEmacs LDAP API consists of two layers: a low-level layer which
+tries to stay as close as possible to the C API (where practical) and a
+higher-level layer which provides more convenient primitives to
+effectively use LDAP.
+
+ As of XEmacs 21.0, only interfaces to basic LDAP search functions are
+provided, broader support is planned in future versions.
+
+* Menu:
+
+* LDAP Variables:: Lisp variables related to LDAP
+* The High-Level LDAP API:: High-level LDAP lisp functions
+* The Low-Level LDAP API:: Low-level LDAP lisp primitives
+
+\1f
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
+
+LDAP Variables
+--------------
+
+ - Variable: ldap-default-host
+ The default LDAP server hostname. A TCP port number can be
+ appended to that name using a colon as a separator.
+
+ - Variable: ldap-default-port
+ Default TCP port for LDAP connections. Initialized from the LDAP
+ library. Default value is 389.
+
+ - Variable: ldap-default-base
+ Default base for LDAP searches. This is a string using the syntax
+ of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the
+ Acme organization in the United States.
+
+ - Variable: ldap-host-parameters-alist
+ An alist of per host options for LDAP transactions. The list
+ elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
+ name of an LDAP server. A TCP port number can be appended to that
+ name using a colon as a separator. PROPN and VALN are
+ property/value pairs describing parameters for the server. Valid
+ properties:
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
+
+ `passwd'
+ The password to use for authentication.
+
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
+
+ `base'
+ The base for the search. This may look like `cÿ, o¬me', see
+ RFC 1779 for syntax details.
+
+ `scope'
+ One of the symbols `base', `onelevel' or `subtree' indicating
+ the scope of the search limited to a base object, to a single
+ level or to the whole subtree.
+
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
+
+ `always'
+ Aliases are always dereferenced
+
+ `search'
+ Aliases are dereferenced when searching
+
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search
+
+ `timelimit'
+ The timeout limit for the connection in seconds.
+
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
+
+\1f
+File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
+
+The High-Level LDAP API
+-----------------------
+
+ As of this writing the high-level Lisp LDAP API only provides for
+LDAP searches. Further support is planned in the future.
+
+ The `ldap-search' function provides the most convenient interface to
+perform LDAP searches. It opens a connection to a host, performs the
+query and cleanly closes the connection thus insulating the user from
+all the details of the low-level interface such as LDAP Lisp objects
+*note The Low-Level LDAP API::.
+
+ - Function: ldap-search FILTER &optional HOST ATTRIBUTES ATTRSONLY
+ Perform an LDAP search. FILTER is the search filter *note Syntax
+ of Search Filters::. HOST is the LDAP host on which to perform
+ the search ATTRIBUTES is the specific attributes to retrieve,
+ `nil' means retrieve all ATTRSONLY if non-`nil' retrieves the
+ attributes only without their associated values. Additional
+ search parameters can be specified through
+ `ldap-host-parameters-alist'.
+
+\1f
+File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
+
+The Low-Level LDAP API
+----------------------
+
+* Menu:
+
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Searching on a LDAP Server (Low-level)::
+
+\1f
+File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
+
+The LDAP Lisp Object
+....................
+
+ An internal built-in `ldap' lisp object represents a LDAP connection.
+
+ - Function: ldapp OBJECT
+ This function returns non-`nil' if OBJECT is a `ldap' object.
+
+ - Function: ldap-host LDAP
+ Return the server host of the connection represented by LDAP
+
+ - Function: ldap-live-p LDAP
+ Return non-`nil' if LDAP is an active LDAP connection
+
+\1f
+File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searching on a LDAP Server (Low-level), Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
+
+Opening and Closing a LDAP Connection
+.....................................
+
+ - Function: ldap-open HOST &optional PLIST
+ Open a LDAP connection to HOST. PLIST is a property list
+ containing additional parameters for the connection. Valid keys
+ in that list are:
+ `port'
+ The TCP port to use for the connection if different from
+ `ldap-default-port' or the library builtin value
+
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
+
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
+
+ `passwd'
+ The password to use for authentication.
+
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
+
+ `always'
+ Aliases are always dereferenced
+
+ `search'
+ Aliases are dereferenced when searching
+
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search The default is `never'.
+
+ `timelimit'
+ The timeout limit for the connection in seconds.
+
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
+
+ - Function: ldap-close LDAP
+ Close the connection represented by LDAP
+
+\1f
+File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
+
+Searching on a LDAP Server (Low-level)
+......................................
+
+ `ldap-search-internal' is the low-level primitive to perform a
+search on a LDAP server. It works directly on an open LDAP connection
+thus requiring a preliminary call to `ldap-open'. Multiple searches
+can be made on the same connection, then the session must be closed
+with `ldap-close'.
+
+ - Function: ldap-search-internal LDAP FILTER BASE SCOPE ATTRS ATTRSONLY
+ Perform a search on an open connection LDAP created with
+ `ldap-open'. FILTER is a filter string for the search *note
+ Syntax of Search Filters::. BASE is the distinguished name at
+ which to start the search. SCOPE is one of the symbols `base',
+ `onelevel' or `subtree' indicating the scope of the search limited
+ to a base object, to a single level or to the whole subtree. The
+ default is `subtree'. `attrs' is a list of strings indicating
+ which attributes to retrieve for each matching entry. If `nil' all
+ available attributes are returned. If `attrsonly' is non-`nil'
+ then only the attributes are retrieved, not their associated values
+ The function returns a list of matching entries. Each entry being
+ itself an alist of attribute/values.
+
+\1f
+File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
+
+Syntax of Search Filters
+========================
+
+ LDAP search functions use RFC1558 syntax to describe the search
+filter. In that syntax simple filters have the form:
+
+ (<attr> <filtertype> <value>)
+
+ `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...
+
+ `<value>' is the corresponding value. This is generally an exact
+string but may also contain `*' characters as wildcards
+
+ `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.
+
+ Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.
+
+ A special case is the presence filter `(<attr>=*' which matches
+records containing a particular attribute. For instance `(mail=*)'
+matches all records containing a `mail' attribute.
+
+ Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.
+
+ `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
+matches records of class `Person' containing a `mail' attribute and
+corresponding to people whose last name is `Smith' or whose first name
+is `John'.
+
+\1f
+File: lispref.info, Node: Internationalization, Next: MULE, Prev: LDAP Support, Up: Top
+
+Internationalization
+********************
+
+* Menu:
+
+* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
+* I18N Level 3:: Support for localized messages.
+* I18N Level 4:: Support for Asian languages.
+
+\1f
+File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
+
+I18N Levels 1 and 2
+===================
+
+ XEmacs is now compliant with I18N levels 1 and 2. Specifically,
+this means that it is 8-bit clean and correctly handles time and date
+functions. XEmacs will correctly display the entire ISO-Latin 1
+character set.
+
+ The compose key may now be used to create any character in the
+ISO-Latin 1 character set not directly available via the keyboard.. In
+order for the compose key to work it is necessary to load the file
+`x-compose.el'. At any time while composing a character, `C-h' will
+display all valid completions and the character which would be produced.
+
+\1f
+File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
+
+I18N Level 3
+============
+
+* Menu:
+
+* Level 3 Basics::
+* Level 3 Primitives::
+* Dynamic Messaging::
+* Domain Specification::
+* Documentation String Extraction::
+
+\1f
+File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
+
+Level 3 Basics
+--------------
+
+ XEmacs now provides alpha-level functionality for I18N Level 3.
+This means that everything necessary for full messaging is available,
+but not every file has been converted.
+
+ The two message files which have been created are `src/emacs.po' and
+`lisp/packages/mh-e.po'. Both files need to be converted using
+`msgfmt', and the resulting `.mo' files placed in some locale's
+`LC_MESSAGES' directory. The test "translations" in these files are
+the original messages prefixed by `TRNSLT_'.
+
+ The domain for a variable is stored on the variable's property list
+under the property name VARIABLE-DOMAIN. The function
+`documentation-property' uses this information when translating a
+variable's documentation.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3
+
+Level 3 Primitives
+------------------
+
+ - Function: gettext STRING
+ This function looks up STRING in the default message domain and
+ returns its translation. If `I18N3' was not enabled when XEmacs
+ was compiled, it just returns STRING.
+
+ - Function: dgettext DOMAIN STRING
+ This function looks up STRING in the specified message domain and
+ returns its translation. If `I18N3' was not enabled when XEmacs
+ was compiled, it just returns STRING.
+
+ - Function: bind-text-domain DOMAIN PATHNAME
+ This function associates a pathname with a message domain. Here's
+ how the path to message file is constructed under SunOS 5.x:
+
+ `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
+
+ If `I18N3' was not enabled when XEmacs was compiled, this function
+ does nothing.
+
+ - Special Form: domain STRING
+ This function specifies the text domain used for translating
+ documentation strings and interactive prompts of a function. For
+ example, write:
+
+ (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
+
+ to specify `emacs-foo' as the text domain of the function `foo'.
+ The "call" to `domain' is actually a declaration rather than a
+ function; when actually called, `domain' just returns `nil'.
+
+ - Function: domain-of FUNCTION
+ This function returns the text domain of FUNCTION; it returns
+ `nil' if it is the default domain. If `I18N3' was not enabled
+ when XEmacs was compiled, it always returns `nil'.
+
+\1f
+File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3
+
+Dynamic Messaging
+-----------------
+
+ The `format' function has been extended to permit you to change the
+order of parameter insertion. For example, the conversion format
+`%1$s' inserts parameter one as a string, while `%2$s' inserts
+parameter two. This is useful when creating translations which require
+you to change the word order.
+
+\1f
+File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3
+
+Domain Specification
+--------------------
+
+ The default message domain of XEmacs is `emacs'. For add-on
+packages, it is best to use a different domain. For example, let us
+say we want to convert the "gorilla" package to use the domain
+`emacs-gorilla'. To translate the message "What gorilla?", use
+`dgettext' as follows:
+
+ (dgettext "emacs-gorilla" "What gorilla?")
+
+ A function (or macro) which has a documentation string or an
+interactive prompt needs to be associated with the domain in order for
+the documentation or prompt to be translated. This is done with the
+`domain' special form as follows:
+
+ (defun scratch (location)
+ "Scratch the specified location."
+ (domain "emacs-gorilla")
+ (interactive "sScratch: ")
+ ... )
+
+ It is most efficient to specify the domain in the first line of the
+function body, before the `interactive' form.
+
+ For variables and constants which have documentation strings,
+specify the domain after the documentation.
+
+ - Special Form: defvar SYMBOL [VALUE [DOC-STRING [DOMAIN]]]
+ Example:
+ (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
+
+ - Special Form: defconst SYMBOL [VALUE [DOC-STRING [DOMAIN]]]
+ 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:
+ (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
+
+\1f
+File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3
+
+Documentation String Extraction
+-------------------------------
+
+ The utility `etc/make-po' scans the file `DOC' to extract
+documentation strings and creates a message file `doc.po'. This file
+may then be inserted within `emacs.po'.
+
+ Currently, `make-po' is hard-coded to read from `DOC' and write to
+`doc.po'. In order to extract documentation strings from an add-on
+package, first run `make-docfile' on the package to produce the `DOC'
+file. Then run `make-po -p' with the `-p' argument to indicate that we
+are extracting documentation for an add-on package.
+
+ (The `-p' argument is a kludge to make up for a subtle difference
+between pre-loaded documentation and add-on documentation: For add-on
+packages, the final carriage returns in the strings produced by
+`make-docfile' must be ignored.)
+
+\1f
+File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization
+
+I18N Level 4
+============
+
+ The Asian-language support in XEmacs is called "MULE". *Note MULE::.
+
+\1f
+File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top
+
+MULE
+****
+
+ "MULE" is the name originally given to the version of GNU Emacs
+extended for multi-lingual (and in particular Asian-language) support.
+"MULE" is short for "MUlti-Lingual Emacs". It was originally called
+Nemacs ("Nihon Emacs" where "Nihon" is the Japanese word for "Japan"),
+when it only provided support for Japanese. XEmacs refers to its
+multi-lingual support as "MULE support" since it is based on "MULE".
+
+* Menu:
+
+* Internationalization Terminology::
+ Definition of various internationalization terms.
+* Charsets:: Sets of related characters.
+* MULE Characters:: Working with characters in XEmacs/MULE.
+* Composite Characters:: Making new characters by overstriking other ones.
+* ISO 2022:: An international standard for charsets and encodings.
+* Coding Systems:: Ways of representing a string of chars using integers.
+* CCL:: A special language for writing fast converters.
+* Category Tables:: Subdividing charsets into groups.
+
+\1f
+File: lispref.info, Node: Internationalization Terminology, Next: Charsets, Up: MULE
+
+Internationalization Terminology
+================================
+
+ In internationalization terminology, a string of text is divided up
+into "characters", which are the printable units that make up the text.
+A single character is (for example) a capital `A', the number `2', a
+Katakana character, a Kanji ideograph (an "ideograph" is a "picture"
+character, such as is used in Japanese Kanji, Chinese Hanzi, and Korean
+Hangul; typically there are thousands of such ideographs in each
+language), etc. The basic property of a character is its shape. Note
+that the same character may be drawn by two different people (or in two
+different fonts) in slightly different ways, although the basic shape
+will be the same.
+
+ In some cases, the differences will be significant enough that it is
+actually possible to identify two or more distinct shapes that both
+represent the same character. For example, the lowercase letters `a'
+and `g' each have two distinct possible shapes - the `a' can optionally
+have a curved tail projecting off the top, and the `g' can be formed
+either of two loops, or of one loop and a tail hanging off the bottom.
+Such distinct possible shapes of a character are called "glyphs". The
+important characteristic of two glyphs making up the same character is
+that the choice between one or the other is purely stylistic and has no
+linguistic effect on a word (this is the reason why a capital `A' and
+lowercase `a' are different characters rather than different glyphs -
+e.g. `Aspen' is a city while `aspen' is a kind of tree).
+
+ Note that "character" and "glyph" are used differently here than
+elsewhere in XEmacs.
+
+ A "character set" is simply a set of related characters. ASCII, for
+example, is a set of 94 characters (or 128, if you count non-printing
+characters). Other character sets are ISO8859-1 (ASCII plus various
+accented characters and other international symbols), JISX0201 (ASCII,
+more or less, plus half-width Katakana), JISX0208 (Japanese Kanji),
+JISX0212 (a second set of less-used Japanese Kanji), GB2312 (Mainland
+Chinese Hanzi), etc.
+
+ Every character set has one or more "orderings", which can be viewed
+as a way of assigning a number (or set of numbers) to each character in
+the set. For most character sets, there is a standard ordering, and in
+fact all of the character sets mentioned above define a particular
+ordering. ASCII, for example, places letters in their "natural" order,
+puts uppercase letters before lowercase letters, numbers before
+letters, etc. Note that for many of the Asian character sets, there is
+no natural ordering of the characters. The actual orderings are based
+on one or more salient characteristic, of which there are many to
+choose from - e.g. number of strokes, common radicals, phonetic
+ordering, etc.
+
+ The set of numbers assigned to any particular character are called
+the character's "position codes". The number of position codes
+required to index a particular character in a character set is called
+the "dimension" of the character set. ASCII, being a relatively small
+character set, is of dimension one, and each character in the set is
+indexed using a single position code, in the range 0 through 127 (if
+non-printing characters are included) or 33 through 126 (if only the
+printing characters are considered). JISX0208, i.e. Japanese Kanji,
+has thousands of characters, and is of dimension two - every character
+is indexed by two position codes, each in the range 33 through 126.
+(Note that the choice of the range here is somewhat arbitrary.
+Although a character set such as JISX0208 defines an *ordering* of all
+its characters, it does not define the actual mapping between numbers
+and characters. You could just as easily index the characters in
+JISX0208 using numbers in the range 0 through 93, 1 through 94, 2
+through 95, etc. The reason for the actual range chosen is so that the
+position codes match up with the actual values used in the common
+encodings.)
+
+ An "encoding" is a way of numerically representing characters from
+one or more character sets into a stream of like-sized numerical values
+called "words"; typically these are 8-bit, 16-bit, or 32-bit
+quantities. If an encoding encompasses only one character set, then the
+position codes for the characters in that character set could be used
+directly. (This is the case with ASCII, and as a result, most people do
+not understand the difference between a character set and an encoding.)
+This is not possible, however, if more than one character set is to be
+used in the encoding. For example, printed Japanese text typically
+requires characters from multiple character sets - ASCII, JISX0208, and
+JISX0212, to be specific. Each of these is indexed using one or more
+position codes in the range 33 through 126, so the position codes could
+not be used directly or there would be no way to tell which character
+was meant. Different Japanese encodings handle this differently - JIS
+uses special escape characters to denote different character sets; EUC
+sets the high bit of the position codes for JISX0208 and JISX0212, and
+puts a special extra byte before each JISX0212 character; etc. (JIS,
+EUC, and most of the other encodings you will encounter are 7-bit or
+8-bit encodings. There is one common 16-bit encoding, which is Unicode;
+this strives to represent all the world's characters in a single large
+character set. 32-bit encodings are generally used internally in
+programs to simplify the code that manipulates them; however, they are
+not much used externally because they are not very space-efficient.)
+
+ Encodings are classified as either "modal" or "non-modal". In a
+"modal encoding", there are multiple states that the encoding can be in,
+and the interpretation of the values in the stream depends on the
+current global state of the encoding. Special values in the encoding,
+called "escape sequences", are used to change the global state. JIS,
+for example, is a modal encoding. The bytes `ESC $ B' indicate that,
+from then on, bytes are to be interpreted as position codes for
+JISX0208, rather than as ASCII. This effect is cancelled using the
+bytes `ESC ( B', which mean "switch from whatever the current state is
+to ASCII". To switch to JISX0212, the escape sequence `ESC $ ( D'.
+(Note that here, as is common, the escape sequences do in fact begin
+with `ESC'. This is not necessarily the case, however.)
+
+ A "non-modal encoding" has no global state that extends past the
+character currently being interpreted. EUC, for example, is a
+non-modal encoding. Characters in JISX0208 are encoded by setting the
+high bit of the position codes, and characters in JISX0212 are encoded
+by doing the same but also prefixing the character with the byte 0x8F.
+
+ The advantage of a modal encoding is that it is generally more
+space-efficient, and is easily extendable because there are essentially
+an arbitrary number of escape sequences that can be created. The
+disadvantage, however, is that it is much more difficult to work with
+if it is not being processed in a sequential manner. In the non-modal
+EUC encoding, for example, the byte 0x41 always refers to the letter
+`A'; whereas in JIS, it could either be the letter `A', or one of the
+two position codes in a JISX0208 character, or one of the two position
+codes in a JISX0212 character. Determining exactly which one is meant
+could be difficult and time-consuming if the previous bytes in the
+string have not already been processed.
+
+ Non-modal encodings are further divided into "fixed-width" and
+"variable-width" formats. A fixed-width encoding always uses the same
+number of words per character, whereas a variable-width encoding does
+not. EUC is a good example of a variable-width encoding: one to three
+bytes are used per character, depending on the character set. 16-bit
+and 32-bit encodings are nearly always fixed-width, and this is in fact
+one of the main reasons for using an encoding with a larger word size.
+The advantages of fixed-width encodings should be obvious. The
+advantages of variable-width encodings are that they are generally more
+space-efficient and allow for compatibility with existing 8-bit
+encodings such as ASCII.
+
+ Note that the bytes in an 8-bit encoding are often referred to as
+"octets" rather than simply as bytes. This terminology dates back to
+the days before 8-bit bytes were universal, when some computers had
+9-bit bytes, others had 10-bit bytes, etc.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Charset Properties, Next: Basic Charset Functions, Up: Charsets
+
+Charset Properties
+------------------
+
+ Charsets have the following properties:
+
+`name'
+ A symbol naming the charset. Every charset must have a different
+ name; this allows a charset to be referred to using its name
+ rather than the actual charset object.
+
+`doc-string'
+ A documentation string describing the charset.
+
+`registry'
+ A regular expression matching the font registry field for this
+ character set. For example, both the `ascii' and `latin-iso8859-1'
+ charsets use the registry `"ISO8859-1"'. This field is used to
+ choose an appropriate font when the user gives a general font
+ specification such as `-*-courier-medium-r-*-140-*', i.e. a
+ 14-point upright medium-weight Courier font.
+
+`dimension'
+ Number of position codes used to index a character in the
+ character set. XEmacs/MULE can only handle character sets of
+ dimension 1 or 2. This property defaults to 1.
+
+`chars'
+ Number of characters in each dimension. In XEmacs/MULE, the only
+ allowed values are 94 or 96. (There are a couple of pre-defined
+ character sets, such as ASCII, that do not follow this, but you
+ cannot define new ones like this.) Defaults to 94. Note that if
+ the dimension is 2, the character set thus described is 94x94 or
+ 96x96.
+
+`columns'
+ Number of columns used to display a character in this charset.
+ Only used in TTY mode. (Under X, the actual width of a character
+ can be derived from the font used to display the characters.) If
+ unspecified, defaults to the dimension. (This is almost always the
+ correct value, because character sets with dimension 2 are usually
+ ideograph character sets, which need two columns to display the
+ intricate ideographs.)
+
+`direction'
+ A symbol, either `l2r' (left-to-right) or `r2l' (right-to-left).
+ Defaults to `l2r'. This specifies the direction that the text
+ should be displayed in, and will be left-to-right for most
+ charsets but right-to-left for Hebrew and Arabic. (Right-to-left
+ display is not currently implemented.)
+
+`final'
+ Final byte of the standard ISO 2022 escape sequence designating
+ this charset. Must be supplied. Each combination of (DIMENSION,
+ CHARS) defines a separate namespace for final bytes, and each
+ charset within a particular namespace must have a different final
+ byte. Note that ISO 2022 restricts the final byte to the range
+ 0x30 - 0x7E if dimension == 1, and 0x30 - 0x5F if dimension == 2.
+ Note also that final bytes in the range 0x30 - 0x3F are reserved
+ for user-defined (not official) character sets. For more
+ information on ISO 2022, see *Note Coding Systems::.
+
+`graphic'
+ 0 (use left half of font on output) or 1 (use right half of font on
+ output). Defaults to 0. This specifies how to convert the
+ position codes that index a character in a character set into an
+ index into the font used to display the character set. With
+ `graphic' set to 0, position codes 33 through 126 map to font
+ indices 33 through 126; with it set to 1, position codes 33
+ through 126 map to font indices 161 through 254 (i.e. the same
+ number but with the high bit set). For example, for a font whose
+ registry is ISO8859-1, the left half of the font (octets 0x20 -
+ 0x7F) is the `ascii' charset, while the right half (octets 0xA0 -
+ 0xFF) is the `latin-iso8859-1' charset.
+
+`ccl-program'
+ A compiled CCL program used to convert a character in this charset
+ into an index into the font. This is in addition to the `graphic'
+ property. If a CCL program is defined, the position codes of a
+ character will first be processed according to `graphic' and then
+ passed through the CCL program, with the resulting values used to
+ index the font.
+
+ This is used, for example, in the Big5 character set (used in
+ Taiwan). This character set is not ISO-2022-compliant, and its
+ size (94x157) does not fit within the maximum 96x96 size of
+ ISO-2022-compliant character sets. As a result, XEmacs/MULE
+ splits it (in a rather complex fashion, so as to group the most
+ commonly used characters together) into two charset objects
+ (`big5-1' and `big5-2'), each of size 94x94, and each charset
+ object uses a CCL program to convert the modified position codes
+ back into standard Big5 indices to retrieve a character from a
+ Big5 font.
+
+ Most of the above properties can only be changed when the charset is
+created. *Note Charset Property Functions::.
+
+\1f
+File: lispref.info, Node: Basic Charset Functions, Next: Charset Property Functions, Prev: Charset Properties, Up: Charsets
+
+Basic Charset Functions
+-----------------------
+
+ - Function: find-charset CHARSET-OR-NAME
+ This function retrieves the charset of the given name. If
+ CHARSET-OR-NAME is a charset object, it is simply returned.
+ Otherwise, CHARSET-OR-NAME should be a symbol. If there is no
+ such charset, `nil' is returned. Otherwise the associated charset
+ object is returned.
+
+ - Function: get-charset NAME
+ This function retrieves the charset of the given name. Same as
+ `find-charset' except an error is signalled if there is no such
+ charset instead of returning `nil'.
+
+ - Function: charset-list
+ This function returns a list of the names of all defined charsets.
+
+ - Function: make-charset NAME DOC-STRING PROPS
+ This function defines a new character set. This function is for
+ use with Mule support. NAME is a symbol, the name by which the
+ character set is normally referred. DOC-STRING is a string
+ describing the character set. PROPS is a property list,
+ describing the specific nature of the character set. The
+ recognized properties are `registry', `dimension', `columns',
+ `chars', `final', `graphic', `direction', and `ccl-program', as
+ previously described.
+
+ - Function: make-reverse-direction-charset CHARSET NEW-NAME
+ This function makes a charset equivalent to CHARSET but which goes
+ in the opposite direction. NEW-NAME is the name of the new
+ charset. The new charset is returned.
+
+ - Function: charset-from-attributes DIMENSION CHARS FINAL &optional
+ DIRECTION
+ This function returns a charset with the given DIMENSION, CHARS,
+ FINAL, and DIRECTION. If DIRECTION is omitted, both directions
+ will be checked (left-to-right will be returned if character sets
+ exist for both directions).
+
+ - Function: charset-reverse-direction-charset CHARSET
+ This function returns the charset (if any) with the same dimension,
+ number of characters, and final byte as CHARSET, but which is
+ displayed in the opposite direction.
+
+\1f
+File: lispref.info, Node: Charset Property Functions, Next: Predefined Charsets, Prev: Basic Charset Functions, Up: Charsets
+
+Charset Property Functions
+--------------------------
+
+ All of these functions accept either a charset name or charset
+object.
+
+ - Function: charset-property CHARSET PROP
+ This function returns property PROP of CHARSET. *Note Charset
+ Properties::.
+
+ Convenience functions are also provided for retrieving individual
+properties of a charset.
+
+ - Function: charset-name CHARSET
+ This function returns the name of CHARSET. This will be a symbol.
+
+ - Function: charset-doc-string CHARSET
+ This function returns the doc string of CHARSET.
+
+ - Function: charset-registry CHARSET
+ This function returns the registry of CHARSET.
+
+ - Function: charset-dimension CHARSET
+ This function returns the dimension of CHARSET.
+
+ - Function: charset-chars CHARSET
+ This function returns the number of characters per dimension of
+ CHARSET.
+
+ - Function: charset-columns CHARSET
+ This function returns the number of display columns per character
+ (in TTY mode) of CHARSET.
+
+ - Function: charset-direction CHARSET
+ This function returns the display direction of CHARSET - either
+ `l2r' or `r2l'.
+
+ - Function: charset-final CHARSET
+ This function returns the final byte of the ISO 2022 escape
+ sequence designating CHARSET.
+
+ - Function: charset-graphic CHARSET
+ This function returns either 0 or 1, depending on whether the
+ position codes of characters in CHARSET map to the left or right
+ half of their font, respectively.
+
+ - Function: charset-ccl-program CHARSET
+ This function returns the CCL program, if any, for converting
+ position codes of characters in CHARSET into font indices.
+
+ The only property of a charset that can currently be set after the
+charset has been created is the CCL program.
+
+ - Function: set-charset-ccl-program CHARSET CCL-PROGRAM
+ This function sets the `ccl-program' property of CHARSET to
+ CCL-PROGRAM.
+
+\1f
+File: lispref.info, Node: Predefined Charsets, Prev: Charset Property Functions, Up: Charsets
+
+Predefined Charsets
+-------------------
+
+ The following charsets are predefined in the C code.
+
+ Name Type Fi Gr Dir Registry
+ --------------------------------------------------------------
+ ascii 94 B 0 l2r ISO8859-1
+ control-1 94 0 l2r ---
+ latin-iso8859-1 94 A 1 l2r ISO8859-1
+ latin-iso8859-2 96 B 1 l2r ISO8859-2
+ latin-iso8859-3 96 C 1 l2r ISO8859-3
+ latin-iso8859-4 96 D 1 l2r ISO8859-4
+ cyrillic-iso8859-5 96 L 1 l2r ISO8859-5
+ arabic-iso8859-6 96 G 1 r2l ISO8859-6
+ greek-iso8859-7 96 F 1 l2r ISO8859-7
+ hebrew-iso8859-8 96 H 1 r2l ISO8859-8
+ latin-iso8859-9 96 M 1 l2r ISO8859-9
+ thai-tis620 96 T 1 l2r TIS620
+ katakana-jisx0201 94 I 1 l2r JISX0201.1976
+ latin-jisx0201 94 J 0 l2r JISX0201.1976
+ japanese-jisx0208-1978 94x94 @ 0 l2r JISX0208.1978
+ japanese-jisx0208 94x94 B 0 l2r JISX0208.19(83|90)
+ japanese-jisx0212 94x94 D 0 l2r JISX0212
+ chinese-gb2312 94x94 A 0 l2r GB2312
+ chinese-cns11643-1 94x94 G 0 l2r CNS11643.1
+ chinese-cns11643-2 94x94 H 0 l2r CNS11643.2
+ chinese-big5-1 94x94 0 0 l2r Big5
+ chinese-big5-2 94x94 1 0 l2r Big5
+ korean-ksc5601 94x94 C 0 l2r KSC5601
+ composite 96x96 0 l2r ---
+
+ The following charsets are predefined in the Lisp code.
+
+ Name Type Fi Gr Dir Registry
+ --------------------------------------------------------------
+ arabic-digit 94 2 0 l2r MuleArabic-0
+ arabic-1-column 94 3 0 r2l MuleArabic-1
+ arabic-2-column 94 4 0 r2l MuleArabic-2
+ sisheng 94 0 0 l2r sisheng_cwnn\|OMRON_UDC_ZH
+ chinese-cns11643-3 94x94 I 0 l2r CNS11643.1
+ chinese-cns11643-4 94x94 J 0 l2r CNS11643.1
+ chinese-cns11643-5 94x94 K 0 l2r CNS11643.1
+ chinese-cns11643-6 94x94 L 0 l2r CNS11643.1
+ chinese-cns11643-7 94x94 M 0 l2r CNS11643.1
+ ethiopic 94x94 2 0 l2r Ethio
+ ascii-r2l 94 B 0 r2l ISO8859-1
+ ipa 96 0 1 l2r MuleIPA
+ vietnamese-lower 96 1 1 l2r VISCII1.1
+ vietnamese-upper 96 2 1 l2r VISCII1.1
+
+ For all of the above charsets, the dimension and number of columns
+are the same.
+
+ Note that ASCII, Control-1, and Composite are handled specially.
+This is why some of the fields are blank; and some of the filled-in
+fields (e.g. the type) are not really accurate.
+
+\1f
+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.
+
+\1f
+File: lispref.info, Node: Composite Characters, Next: ISO 2022, 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.
+
+\1f
+File: lispref.info, Node: ISO 2022, Next: Coding Systems, Prev: Composite Characters, Up: MULE
+
+ISO 2022
+========
+
+ This section briefly describes the ISO 2022 encoding standard. For
+more thorough understanding, please refer to the original document of
+ISO 2022.
+
+ Character sets ("charsets") are classified into the following four
+categories, according to the number of characters of charset:
+94-charset, 96-charset, 94x94-charset, and 96x96-charset.
+
+94-charset
+ ASCII(B), left(J) and right(I) half of JISX0201, ...
+
+96-charset
+ Latin-1(A), Latin-2(B), Latin-3(C), ...
+
+94x94-charset
+ GB2312(A), JISX0208(B), KSC5601(C), ...
+
+96x96-charset
+ none for the moment
+
+ The character in parentheses after the name of each charset is the
+"final character" F, which can be regarded as the identifier of the
+charset. ECMA allocates F to each charset. F is in the range of
+0x30..0x7F, but 0x30..0x3F are only for private use.
+
+ Note: "ECMA" = European Computer Manufacturers Association
+
+ There are four "registers of charsets", called G0 thru G3. You can
+designate (or assign) any charset to one of these registers.
+
+ The code space contained within one octet (of size 256) is divided
+into 4 areas: C0, GL, C1, and GR. GL and GR are the areas into which a
+register of charset can be invoked into.
+
+ C0: 0x00 - 0x1F
+ GL: 0x20 - 0x7F
+ C1: 0x80 - 0x9F
+ GR: 0xA0 - 0xFF
+
+ Usually, in the initial state, G0 is invoked into GL, and G1 is
+invoked into GR.
+
+ ISO 2022 distinguishes 7-bit environments and 8-bit environments. In
+7-bit environments, only C0 and GL are used.
+
+ Charset designation is done by escape sequences of the form:
+
+ ESC [I] I F
+
+ where I is an intermediate character in the range 0x20 - 0x2F, and F
+is the final character identifying this charset.
+
+ The meaning of intermediate characters are:
+
+ $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96).
+ ( [0x28]: designate to G0 a 94-charset whose final byte is F.
+ ) [0x29]: designate to G1 a 94-charset whose final byte is F.
+ * [0x2A]: designate to G2 a 94-charset whose final byte is F.
+ + [0x2B]: designate to G3 a 94-charset whose final byte is F.
+ - [0x2D]: designate to G1 a 96-charset whose final byte is F.
+ . [0x2E]: designate to G2 a 96-charset whose final byte is F.
+ / [0x2F]: designate to G3 a 96-charset whose final byte is F.
+
+ The following rule is not allowed in ISO 2022 but can be used in
+Mule.
+
+ , [0x2C]: designate to G0 a 96-charset whose final byte is F.
+
+ Here are examples of designations:
+
+ ESC ( B : designate to G0 ASCII
+ ESC - A : designate to G1 Latin-1
+ ESC $ ( A or ESC $ A : designate to G0 GB2312
+ ESC $ ( B or ESC $ B : designate to G0 JISX0208
+ ESC $ ) C : designate to G1 KSC5601
+
+ To use a charset designated to G2 or G3, and to use a charset
+designated to G1 in a 7-bit environment, you must explicitly invoke G1,
+G2, or G3 into GL. There are two types of invocation, Locking Shift
+(forever) and Single Shift (one character only).
+
+ Locking Shift is done as follows:
+
+ LS0 or SI (0x0F): invoke G0 into GL
+ LS1 or SO (0x0E): invoke G1 into GL
+ LS2: invoke G2 into GL
+ LS3: invoke G3 into GL
+ LS1R: invoke G1 into GR
+ LS2R: invoke G2 into GR
+ LS3R: invoke G3 into GR
+
+ Single Shift is done as follows:
+
+ SS2 or ESC N: invoke G2 into GL
+ SS3 or ESC O: invoke G3 into GL
+
+ (#### Ben says: I think the above is slightly incorrect. It appears
+that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N
+and ESC O behave as indicated. The above definitions will not parse
+EUC-encoded text correctly, and it looks like the code in mule-coding.c
+has similar problems.)
+
+ You may realize that there are a lot of ISO-2022-compliant ways of
+encoding multilingual text. Now, in the world, there exist many coding
+systems such as X11's Compound Text, Japanese JUNET code, and so-called
+EUC (Extended UNIX Code); all of these are variants of ISO 2022.
+
+ In Mule, we characterize ISO 2022 by the following attributes:
+
+ 1. Initial designation to G0 thru G3.
+
+ 2. Allow designation of short form for Japanese and Chinese.
+
+ 3. Should we designate ASCII to G0 before control characters?
+
+ 4. Should we designate ASCII to G0 at the end of line?
+
+ 5. 7-bit environment or 8-bit environment.
+
+ 6. Use Locking Shift or not.
+
+ 7. Use ASCII or JIS0201-1976-Roman.
+
+ 8. Use JISX0208-1983 or JISX0208-1976.
+
+ (The last two are only for Japanese.)
+
+ By specifying these attributes, you can create any variant of ISO
+2022.
+
+ Here are several examples:
+
+ junet -- Coding system used in JUNET.
+ 1. G0 <- ASCII, G1..3 <- never used
+ 2. Yes.
+ 3. Yes.
+ 4. Yes.
+ 5. 7-bit environment
+ 6. No.
+ 7. Use ASCII
+ 8. Use JISX0208-1983
+
+ ctext -- Compound Text
+ 1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used
+ 2. No.
+ 3. No.
+ 4. Yes.
+ 5. 8-bit environment
+ 6. No.
+ 7. Use ASCII
+ 8. Use JISX0208-1983
+
+ euc-china -- Chinese EUC. Although many people call this
+ as "GB encoding", the name may cause misunderstanding.
+ 1. G0 <- ASCII, G1 <- GB2312, G2,3 <- never used
+ 2. No.
+ 3. Yes.
+ 4. Yes.
+ 5. 8-bit environment
+ 6. No.
+ 7. Use ASCII
+ 8. Use JISX0208-1983
+
+ korean-mail -- Coding system used in Korean network.
+ 1. G0 <- ASCII, G1 <- KSC5601, G2,3 <- never used
+ 2. No.
+ 3. Yes.
+ 4. Yes.
+ 5. 7-bit environment
+ 6. Yes.
+ 7. No.
+ 8. No.
+
+ Mule creates all these coding systems by default.
+
+\1f
+File: lispref.info, Node: Coding Systems, Next: CCL, Prev: ISO 2022, 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.
+* 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.
+
+\1f
+File: lispref.info, Node: Coding System Types, Next: EOL Conversion, Up: Coding Systems
+
+Coding System Types
+-------------------
+
+`nil'
+`autodetect'
+ Automatic conversion. XEmacs attempts to detect the coding system
+ used in the file.
+
+`no-conversion'
+ No conversion. Use this for binary files and such. On output,
+ graphic characters that are not in ASCII or Latin-1 will be
+ replaced by a `?'. (For a no-conversion-encoded buffer, these
+ characters will only be present if you explicitly insert them.)
+
+`shift-jis'
+ Shift-JIS (a Japanese encoding commonly used in PC operating
+ systems).
+
+`iso2022'
+ Any ISO-2022-compliant encoding. Among other things, this
+ includes JIS (the Japanese encoding commonly used for e-mail),
+ national variants of EUC (the standard Unix encoding for Japanese
+ and other languages), and Compound Text (an encoding used in X11).
+ You can specify more specific information about the conversion
+ with the FLAGS argument.
+
+`big5'
+ Big5 (the encoding commonly used for Taiwanese).
+
+`ccl'
+ The conversion is performed using a user-written pseudo-code
+ program. CCL (Code Conversion Language) is the name of this
+ pseudo-code.
+
+`internal'
+ Write out or read in the raw contents of the memory representing
+ the buffer's text. This is primarily useful for debugging
+ purposes, and is only enabled when XEmacs has been compiled with
+ `DEBUG_XEMACS' set (the `--debug' configure option). *Warning*:
+ Reading in a file using `internal' conversion can result in an
+ internal inconsistency in the memory representing a buffer's text,
+ which will produce unpredictable results and may cause XEmacs to
+ crash. Under normal circumstances you should never use `internal'
+ conversion.
+
+\1f
+File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: Coding System Types, Up: Coding Systems
+
+EOL Conversion
+--------------
+
+`nil'
+ Automatically detect the end-of-line type (LF, CRLF, or CR). Also
+ generate subsidiary coding systems named `NAME-unix', `NAME-dos',
+ and `NAME-mac', that are identical to this coding system but have
+ an EOL-TYPE value of `lf', `crlf', and `cr', respectively.
+
+`lf'
+ The end of a line is marked externally using ASCII LF. Since this
+ is also the way that XEmacs represents an end-of-line internally,
+ specifying this option results in no end-of-line conversion. This
+ is the standard format for Unix text files.
+
+`crlf'
+ The end of a line is marked externally using ASCII CRLF. This is
+ the standard format for MS-DOS text files.
+
+`cr'
+ The end of a line is marked externally using ASCII CR. This is the
+ standard format for Macintosh text files.
+
+`t'
+ Automatically detect the end-of-line type but do not generate
+ subsidiary coding systems. (This value is converted to `nil' when
+ stored internally, and `coding-system-property' will return `nil'.)
+
+\1f
+File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems
+
+Coding System Properties
+------------------------
+
+`mnemonic'
+ String to be displayed in the modeline when this coding system is
+ active.
+
+`eol-type'
+ End-of-line conversion to be used. It should be one of the types
+ listed in *Note EOL Conversion::.
+
+`post-read-conversion'
+ Function called after a file has been read in, to perform the
+ decoding. Called with two arguments, BEG and END, denoting a
+ region of the current buffer to be decoded.
+
+`pre-write-conversion'
+ Function called before a file is written out, to perform the
+ encoding. Called with two arguments, BEG and END, denoting a
+ region of the current buffer to be encoded.
+
+ The following additional properties are recognized if TYPE is
+`iso2022':
+
+`charset-g0'
+`charset-g1'
+`charset-g2'
+`charset-g3'
+ The character set initially designated to the G0 - G3 registers.
+ The value should be one of
+
+ * A charset object (designate that character set)
+
+ * `nil' (do not ever use this register)
+
+ * `t' (no character set is initially designated to the
+ register, but may be later on; this automatically sets the
+ corresponding `force-g*-on-output' property)
+
+`force-g0-on-output'
+`force-g1-on-output'
+`force-g2-on-output'
+`force-g3-on-output'
+ If non-`nil', send an explicit designation sequence on output
+ before using the specified register.
+
+`short'
+ If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $
+ B' on output in place of the full designation sequences `ESC $ (
+ @', `ESC $ ( A', and `ESC $ ( B'.
+
+`no-ascii-eol'
+ If non-`nil', don't designate ASCII to G0 at each end of line on
+ output. Setting this to non-`nil' also suppresses other
+ state-resetting that normally happens at the end of a line.
+
+`no-ascii-cntl'
+ If non-`nil', don't designate ASCII to G0 before control chars on
+ output.
+
+`seven'
+ If non-`nil', use 7-bit environment on output. Otherwise, use
+ 8-bit environment.
+
+`lock-shift'
+ If non-`nil', use locking-shift (SO/SI) instead of single-shift or
+ designation by escape sequence.
+
+`no-iso6429'
+ If non-`nil', don't use ISO6429's direction specification.
+
+`escape-quoted'
+ If non-nil, literal control characters that are the same as the
+ beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in
+ particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3
+ (0x8F), and CSI (0x9B)) are "quoted" with an escape character so
+ that they can be properly distinguished from an escape sequence.
+ (Note that doing this results in a non-portable encoding.) This
+ encoding flag is used for byte-compiled files. Note that ESC is a
+ good choice for a quoting character because there are no escape
+ sequences whose second byte is a character from the Control-0 or
+ Control-1 character sets; this is explicitly disallowed by the ISO
+ 2022 standard.
+
+`input-charset-conversion'
+ A list of conversion specifications, specifying conversion of
+ characters in one charset to another when decoding is performed.
+ Each specification is a list of two elements: the source charset,
+ and the destination charset.
+
+`output-charset-conversion'
+ A list of conversion specifications, specifying conversion of
+ characters in one charset to another when encoding is performed.
+ The form of each specification is the same as for
+ `input-charset-conversion'.
+
+ The following additional properties are recognized (and required) if
+TYPE is `ccl':
+
+`decode'
+ CCL program used for decoding (converting to internal format).
+
+`encode'
+ CCL program used for encoding (converting to external format).
+
+\1f
+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: 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.
+
+\1f
+File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems
+
+Coding System Property Functions
+--------------------------------
+
+ - 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.
+
+\1f
+File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems
+
+Encoding and Decoding Text
+--------------------------
+
+ - Function: decode-coding-region START END CODING-SYSTEM &optional
+ BUFFER
+ This function decodes the text between START and END which is
+ encoded in CODING-SYSTEM. This is useful if you've read in
+ encoded text from a file without decoding it (e.g. you read in a
+ JIS-formatted file but used the `binary' or `no-conversion' coding
+ system, so that it shows up as `^[$B!<!+^[(B'). The length of the
+ encoded text is returned. BUFFER defaults to the current buffer
+ if unspecified.
+
+ - Function: encode-coding-region START END CODING-SYSTEM &optional
+ BUFFER
+ This function encodes the text between START and END using
+ CODING-SYSTEM. This will, for example, convert Japanese
+ characters into stuff such as `^[$B!<!+^[(B' if you use the JIS
+ encoding. The length of the encoded text is returned. BUFFER
+ defaults to the current buffer if unspecified.
+
+\1f
+File: lispref.info, Node: Detection of Textual Encoding, Next: Big5 and Shift-JIS Functions, Prev: Encoding and Decoding Text, Up: Coding Systems
+
+Detection of Textual Encoding
+-----------------------------
+
+ - Function: coding-category-list
+ This function returns a list of all recognized coding categories.
+
+ - Function: set-coding-priority-list LIST
+ This function changes the priority order of the coding categories.
+ LIST should be a list of coding categories, in descending order of
+ priority. Unspecified coding categories will be lower in priority
+ than all specified ones, in the same relative order they were in
+ previously.
+
+ - Function: coding-priority-list
+ This function returns a list of coding categories in descending
+ order of priority.
+
+ - Function: set-coding-category-system CODING-CATEGORY CODING-SYSTEM
+ This function changes the coding system associated with a coding
+ category.
+
+ - Function: coding-category-system CODING-CATEGORY
+ This function returns the coding system associated with a coding
+ category.
+
+ - Function: detect-coding-region START END &optional BUFFER
+ This function detects coding system of the text in the region
+ between START and END. Returned value is a list of possible coding
+ systems ordered by priority. If only ASCII characters are found,
+ it returns `autodetect' or one of its subsidiary coding systems
+ according to a detected end-of-line type. Optional arg BUFFER
+ defaults to the current buffer.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Big5 and Shift-JIS Functions, Prev: Detection of Textual Encoding, Up: Coding Systems
+
+Big5 and Shift-JIS Functions
+----------------------------
+
+ These are special functions for working with the non-standard
+Shift-JIS and Big5 encodings.
+
+ - Function: decode-shift-jis-char CODE
+ This function decodes a JISX0208 character of Shift-JIS
+ coding-system. CODE is the character code in Shift-JIS as a cons
+ of type bytes. The corresponding character is returned.
+
+ - Function: encode-shift-jis-char CH
+ This function encodes a JISX0208 character CH to SHIFT-JIS
+ coding-system. The corresponding character code in SHIFT-JIS is
+ returned as a cons of two bytes.
+
+ - Function: decode-big5-char CODE
+ This function decodes a Big5 character CODE of BIG5 coding-system.
+ CODE is the character code in BIG5. The corresponding character
+ is returned.
+
+ - Function: encode-big5-char CH
+ This function encodes the Big5 character CHAR to BIG5
+ coding-system. The corresponding character code in Big5 is
+ returned.
+
+\1f
+File: lispref.info, Node: CCL, Next: Category Tables, Prev: Coding Systems, Up: MULE
+
+CCL
+===
+
+ CCL (Code Conversion Language) is a simple structured programming
+language designed for character coding conversions. A CCL program is
+compiled to CCL code (represented by a vector of integers) and executed
+by the CCL interpreter embedded in Emacs. The CCL interpreter
+implements a virtual machine with 8 registers called `r0', ..., `r7', a
+number of control structures, and some I/O operators. Take care when
+using registers `r0' (used in implicit "set" statements) and especially
+`r7' (used internally by several statements and operations, especially
+for multiple return values and I/O operations).
+
+ CCL is used for code conversion during process I/O and file I/O for
+non-ISO2022 coding systems. (It is the only way for a user to specify a
+code conversion function.) It is also used for calculating the code
+point of an X11 font from a character code. However, since CCL is
+designed as a powerful programming language, it can be used for more
+generic calculation where efficiency is demanded. A combination of
+three or more arithmetic operations can be calculated faster by CCL than
+by Emacs Lisp.
+
+ *Warning:* The code in `src/mule-ccl.c' and
+`$packages/lisp/mule-base/mule-ccl.el' is the definitive description of
+CCL's semantics. The previous version of this section contained
+several typos and obsolete names left from earlier versions of MULE,
+and many may remain. (I am not an experienced CCL programmer; the few
+who know CCL well find writing English painful.)
+
+ A CCL program transforms an input data stream into an output data
+stream. The input stream, held in a buffer of constant bytes, is left
+unchanged. The buffer may be filled by an external input operation,
+taken from an Emacs buffer, or taken from a Lisp string. The output
+buffer is a dynamic array of bytes, which can be written by an external
+output operation, inserted into an Emacs buffer, or returned as a Lisp
+string.
+
+ A CCL program is a (Lisp) list containing two or three members. The
+first member is the "buffer magnification", which indicates the
+required minimum size of the output buffer as a multiple of the input
+buffer. It is followed by the "main block" which executes while there
+is input remaining, and an optional "EOF block" which is executed when
+the input is exhausted. Both the main block and the EOF block are CCL
+blocks.
+
+ A "CCL block" is either a CCL statement or list of CCL statements.
+A "CCL statement" is either a "set statement" (either an integer or an
+"assignment", which is a list of a register to receive the assignment,
+an assignment operator, and an expression) or a "control statement" (a
+list starting with a keyword, whose allowable syntax depends on the
+keyword).
+
+* Menu:
+
+* CCL Syntax:: CCL program syntax in BNF notation.
+* CCL Statements:: Semantics of CCL statements.
+* CCL Expressions:: Operators and expressions in CCL.
+* Calling CCL:: Running CCL programs.
+* CCL Examples:: The encoding functions for Big5 and KOI-8.
+
+\1f
+File: lispref.info, Node: CCL Syntax, Next: CCL Statements, Prev: CCL, Up: CCL
+
+CCL Syntax
+----------
+
+ The full syntax of a CCL program in BNF notation:
+
+CCL_PROGRAM :=
+ (BUFFER_MAGNIFICATION
+ CCL_MAIN_BLOCK
+ [ CCL_EOF_BLOCK ])
+
+BUFFER_MAGNIFICATION := integer
+CCL_MAIN_BLOCK := CCL_BLOCK
+CCL_EOF_BLOCK := CCL_BLOCK
+
+CCL_BLOCK :=
+ STATEMENT | (STATEMENT [STATEMENT ...])
+STATEMENT :=
+ SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE
+ | CALL | END
+
+SET :=
+ (REG = EXPRESSION)
+ | (REG ASSIGNMENT_OPERATOR EXPRESSION)
+ | integer
+
+EXPRESSION := ARG | (EXPRESSION OPERATOR ARG)
+
+IF := (if EXPRESSION CCL_BLOCK [CCL_BLOCK])
+BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
+LOOP := (loop STATEMENT [STATEMENT ...])
+BREAK := (break)
+REPEAT :=
+ (repeat)
+ | (write-repeat [REG | integer | string])
+ | (write-read-repeat REG [integer | ARRAY])
+READ :=
+ (read REG ...)
+ | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK)
+ | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
+WRITE :=
+ (write REG ...)
+ | (write EXPRESSION)
+ | (write integer) | (write string) | (write REG ARRAY)
+ | string
+CALL := (call ccl-program-name)
+END := (end)
+
+REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
+ARG := REG | integer
+OPERATOR :=
+ + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
+ | < | > | == | <= | >= | != | de-sjis | en-sjis
+ASSIGNMENT_OPERATOR :=
+ += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
+ARRAY := '[' integer ... ']'
+
+\1f
+File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL
+
+CCL Statements
+--------------
+
+ The Emacs Code Conversion Language provides the following statement
+types: "set", "if", "branch", "loop", "repeat", "break", "read",
+"write", "call", and "end".
+
+Set statement:
+==============
+
+ The "set" statement has three variants with the syntaxes `(REG =
+EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'.
+The assignment operator variation of the "set" statement works the same
+way as the corresponding C expression statement does. The assignment
+operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=',
+and `>>=', and they have the same meanings as in C. A "naked integer"
+INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'.
+
+I/O statements:
+===============
+
+ The "read" statement takes one or more registers as arguments. It
+reads one byte (a C char) from the input into each register in turn.
+
+ The "write" takes several forms. In the form `(write REG ...)' it
+takes one or more registers as arguments and writes each in turn to the
+output. The integer in a register (interpreted as an Emchar) is
+encoded to multibyte form (ie, Bufbytes) and written to the current
+output buffer. If it is less than 256, it is written as is. The forms
+`(write EXPRESSION)' and `(write INTEGER)' are treated analogously.
+The form `(write STRING)' writes the constant string to the output. A
+"naked string" `STRING' is equivalent to the statement `(write
+STRING)'. The form `(write REG ARRAY)' writes the REGth element of the
+ARRAY to the output.
+
+Conditional statements:
+=======================
+
+ The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional
+SECOND CCL BLOCK as arguments. If the EXPRESSION evaluates to
+non-zero, the first CCL BLOCK is executed. Otherwise, if there is a
+SECOND CCL BLOCK, it is executed.
+
+ The "read-if" variant of the "if" statement takes an EXPRESSION, a
+CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. The
+EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is
+a register or an integer). The `read-if' statement first reads from
+the input into the first register operand in the EXPRESSION, then
+conditionally executes a CCL block just as the `if' statement does.
+
+ The "branch" statement takes an EXPRESSION and one or more CCL
+blocks as arguments. The CCL blocks are treated as a zero-indexed
+array, and the `branch' statement uses the EXPRESSION as the index of
+the CCL block to execute. Null CCL blocks may be used as no-ops,
+continuing execution with the statement following the `branch'
+statement in the containing CCL block. Out-of-range values for the
+EXPRESSION are also treated as no-ops.
+
+ The "read-branch" variant of the "branch" statement takes an
+REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments.
+The `read-branch' statement first reads from the input into the
+REGISTER, then conditionally executes a CCL block just as the `branch'
+statement does.
+
+Loop control statements:
+========================
+
+ The "loop" statement creates a block with an implied jump from the
+end of the block back to its head. The loop is exited on a `break'
+statement, and continued without executing the tail by a `repeat'
+statement.
+
+ The "break" statement, written `(break)', terminates the current
+loop and continues with the next statement in the current block.
+
+ The "repeat" statement has three variants, `repeat', `write-repeat',
+and `write-read-repeat'. Each continues the current loop from its
+head, possibly after performing I/O. `repeat' takes no arguments and
+does no I/O before jumping. `write-repeat' takes a single argument (a
+register, an integer, or a string), writes it to the output, then jumps.
+`write-read-repeat' takes one or two arguments. The first must be a
+register. The second may be an integer or an array; if absent, it is
+implicitly set to the first (register) argument. `write-read-repeat'
+writes its second argument to the output, then reads from the input
+into the register, and finally jumps. See the `write' and `read'
+statements for the semantics of the I/O operations for each type of
+argument.
+
+Other control statements:
+=========================
+
+ The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a
+CCL program as a subroutine. It does not return a value to the caller,
+but can modify the register status.
+
+ The "end" statement, written `(end)', terminates the CCL program
+successfully, and returns to caller (which may be a CCL program). It
+does not alter the status of the registers.
+
+\1f
+File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL
+
+CCL Expressions
+---------------
+
+ CCL, unlike Lisp, uses infix expressions. The simplest CCL
+expressions consist of a single OPERAND, either a register (one of `r0',
+..., `r0') or an integer. Complex expressions are lists of the form `(
+EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not
+expressions.
+
+ In the following table, X is the target resister for a "set". In
+subexpressions, this is implicitly `r7'. This means that `>8', `//',
+`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since
+they return parts of their values in `r7'. Y may be an expression,
+register, or integer, while Z must be a register or an integer.
+
+Name Operator Code C-like Description
+CCL_PLUS `+' 0x00 X = Y + Z
+CCL_MINUS `-' 0x01 X = Y - Z
+CCL_MUL `*' 0x02 X = Y * Z
+CCL_DIV `/' 0x03 X = Y / Z
+CCL_MOD `%' 0x04 X = Y % Z
+CCL_AND `&' 0x05 X = Y & Z
+CCL_OR `|' 0x06 X = Y | Z
+CCL_XOR `^' 0x07 X = Y ^ Z
+CCL_LSH `<<' 0x08 X = Y << Z
+CCL_RSH `>>' 0x09 X = Y >> Z
+CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
+CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
+CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
+CCL_LS `<' 0x10 X = (X < Y)
+CCL_GT `>' 0x11 X = (X > Y)
+CCL_EQ `==' 0x12 X = (X == Y)
+CCL_LE `<=' 0x13 X = (X <= Y)
+CCL_GE `>=' 0x14 X = (X >= Y)
+CCL_NE `!=' 0x15 X = (X != Y)
+CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
+ r[7] = LOWER_BYTE (SJIS (Y, Z)
+CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
+ r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
+
+ The CCL operators are as in C, with the addition of CCL_LSH8,
+CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The
+CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes
+as the high and low bytes of a two-byte character code. (SJIS stands
+for Shift JIS, an encoding of Japanese characters used by Microsoft.
+CCL_ENCODE_SJIS is a complicated transformation of the Japanese
+standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.)
+It is somewhat odd to represent the SJIS operations in infix form.
+
+\1f
+File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL
+
+Calling CCL
+-----------
+
+ CCL programs are called automatically during Emacs buffer I/O when
+the external representation has a coding system type of `shift-jis',
+`big5', or `ccl'. The program is specified by the coding system (*note
+Coding Systems::.). You can also call CCL programs from other CCL
+programs, and from Lisp using these functions:
+
+ - Function: ccl-execute CCL-PROGRAM STATUS
+ Execute CCL-PROGRAM with registers initialized by STATUS.
+ CCL-PROGRAM is a vector of compiled CCL code created by
+ `ccl-compile'. It is an error for the program to try to execute a
+ CCL I/O command. STATUS must be a vector of nine values,
+ specifying the initial value for the R0, R1 .. R7 registers and
+ for the instruction counter IC. A `nil' value for a register
+ initializer causes the register to be set to 0. A `nil' value for
+ the IC initializer causes execution to start at the beginning of
+ the program. When the program is done, STATUS is modified (by
+ side-effect) to contain the ending values for the corresponding
+ registers and IC.
+
+ - Function: ccl-execute-on-string CCL-PROGRAM STATUS STR &optional
+ CONTINUE
+ Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is
+ a vector of compiled CCL code created by `ccl-compile'. STATUS
+ must be a vector of nine values, specifying the initial value for
+ the R0, R1 .. R7 registers and for the instruction counter IC. A
+ `nil' value for a register initializer causes the register to be
+ set to 0. A `nil' value for the IC initializer causes execution
+ to start at the beginning of the program. An optional fourth
+ argument CONTINUE, if non-nil, causes the IC to remain on the
+ unsatisfied read operation if the program terminates due to
+ exhaustion of the input buffer. Otherwise the IC is set to the end
+ of the program. When the program is done, STATUS is modified (by
+ side-effect) to contain the ending values for the corresponding
+ registers and IC. Returns the resulting string.
+
+ To call a CCL program from another CCL program, it must first be
+registered:
+
+ - Function: register-ccl-program NAME CCL-PROGRAM
+ Register NAME for CCL program PROGRAM in `ccl-program-table'.
+ PROGRAM should be the compiled form of a CCL program, or nil.
+ Return index number of the registered CCL program.
+
+ Information about the processor time used by the CCL interpreter can
+be obtained using these functions:
+
+ - Function: ccl-elapsed-time
+ Returns the elapsed processor time of the CCL interpreter as cons
+ of user and system time, as floating point numbers measured in
+ seconds. If only one overall value can be determined, the return
+ value will be a cons of that value and 0.
+
+ - Function: ccl-reset-elapsed-time
+ Resets the CCL interpreter's internal elapsed time registers.
+
+\1f
+File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
+
+CCL Examples
+------------
+
+ This section is not yet written.
+
+\1f
+File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE
+
+Category Tables
+===============
+
+ A category table is a type of char table used for keeping track of
+categories. Categories are used for classifying characters for use in
+regexps - you can refer to a category rather than having to use a
+complicated [] expression (and category lookups are significantly
+faster).
+
+ There are 95 different categories available, one for each printable
+character (including space) in the ASCII charset. Each category is
+designated by one such character, called a "category designator". They
+are specified in a regexp using the syntax `\cX', where X is a category
+designator. (This is not yet implemented.)
+
+ A category table specifies, for each character, the categories that
+the character is in. Note that a character can be in more than one
+category. More specifically, a category table maps from a character to
+either the value `nil' (meaning the character is in no categories) or a
+95-element bit vector, specifying for each of the 95 categories whether
+the character is in that category.
+
+ Special Lisp functions are provided that abstract this, so you do not
+have to directly manipulate bit vectors.
+
+ - Function: category-table-p OBJ
+ This function returns `t' if ARG is a category table.
+
+ - Function: category-table &optional BUFFER
+ This function returns the current category table. This is the one
+ specified by the current buffer, or by BUFFER if it is non-`nil'.
+
+ - Function: standard-category-table
+ This function returns the standard category table. This is the
+ one used for new buffers.
+
+ - Function: copy-category-table &optional TABLE
+ This function constructs a new category table and return it. It
+ is a copy of the TABLE, which defaults to the standard category
+ table.
+
+ - Function: set-category-table TABLE &optional BUFFER
+ This function selects a new category table for BUFFER. One
+ argument, a category table. BUFFER defaults to the current buffer
+ if omitted.
+
+ - Function: category-designator-p OBJ
+ This function returns `t' if ARG is a category designator (a char
+ in the range `' '' to `'~'').
+
+ - Function: category-table-value-p OBJ
+ This function returns `t' if ARG is a category table value. Valid
+ values are `nil' or a bit vector of size 95.
+
+\1f
+File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top
+
+Tips and Standards
+******************
+
+ This chapter describes no additional features of XEmacs Lisp.
+Instead it gives advice on making effective use of the features
+described in the previous chapters.
+
+* Menu:
+
+* Style Tips:: Writing clean and robust programs.
+* Compilation Tips:: Making compiled code run fast.
+* Documentation Tips:: Writing readable documentation strings.
+* Comment Tips:: Conventions for writing comments.
+* Library Headers:: Standard headers for library packages.
+
+\1f
+File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
+
+Writing Clean Lisp Programs
+===========================
+
+ Here are some tips for avoiding common errors in writing Lisp code
+intended for widespread use:
+
+ * Since all global variables share the same name space, and all
+ functions share another name space, you should choose a short word
+ to distinguish your program from other Lisp programs. Then take
+ care to begin the names of all global variables, constants, and
+ functions with the chosen prefix. This helps avoid name conflicts.
+
+ This recommendation applies even to names for traditional Lisp
+ primitives that are not primitives in XEmacs Lisp--even to `cadr'.
+ Believe it or not, there is more than one plausible way to define
+ `cadr'. Play it safe; append your name prefix to produce a name
+ like `foo-cadr' or `mylib-cadr' instead.
+
+ If you write a function that you think ought to be added to Emacs
+ under a certain name, such as `twiddle-files', don't call it by
+ that name in your program. Call it `mylib-twiddle-files' in your
+ program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu'
+ suggesting we add it to Emacs. If and when we do, we can change
+ the name easily enough.
+
+ If one prefix is insufficient, your package may use two or three
+ alternative common prefixes, so long as they make sense.
+
+ Separate the prefix from the rest of the symbol name with a hyphen,
+ `-'. This will be consistent with XEmacs itself and with most
+ Emacs Lisp programs.
+
+ * It is often useful to put a call to `provide' in each separate
+ library program, at least if there is more than one entry point to
+ the program.
+
+ * If a file requires certain other library programs to be loaded
+ beforehand, then the comments at the beginning of the file should
+ say so. Also, use `require' to make sure they are loaded.
+
+ * If one file FOO uses a macro defined in another file BAR, FOO
+ should contain this expression before the first use of the macro:
+
+ (eval-when-compile (require 'BAR))
+
+ (And BAR should contain `(provide 'BAR)', to make the `require'
+ work.) This will cause BAR to be loaded when you byte-compile
+ FOO. Otherwise, you risk compiling FOO without the necessary
+ macro loaded, and that would produce compiled code that won't work
+ right. *Note Compiling Macros::.
+
+ Using `eval-when-compile' avoids loading BAR when the compiled
+ version of FOO is *used*.
+
+ * If you define a major mode, make sure to run a hook variable using
+ `run-hooks', just as the existing major modes do. *Note Hooks::.
+
+ * If the purpose of a function is to tell you whether a certain
+ condition is true or false, give the function a name that ends in
+ `p'. If the name is one word, add just `p'; if the name is
+ multiple words, add `-p'. Examples are `framep' and
+ `frame-live-p'.
+
+ * If a user option variable records a true-or-false condition, give
+ it a name that ends in `-flag'.
+
+ * Please do not define `C-c LETTER' as a key in your major modes.
+ These sequences are reserved for users; they are the *only*
+ sequences reserved for users, so we cannot do without them.
+
+ Instead, define sequences consisting of `C-c' followed by a
+ non-letter. These sequences are reserved for major modes.
+
+ Changing all the major modes in Emacs 18 so they would follow this
+ convention was a lot of work. Abandoning this convention would
+ make that work go to waste, and inconvenience users.
+
+ * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:'
+ or `;' are also reserved for major modes.
+
+ * Sequences consisting of `C-c' followed by any other punctuation
+ character are allocated for minor modes. Using them in a major
+ mode is not absolutely prohibited, but if you do that, the major
+ mode binding may be shadowed from time to time by minor modes.
+
+ * You should not bind `C-h' following any prefix character (including
+ `C-c'). If you don't bind `C-h', it is automatically available as
+ a help character for listing the subcommands of the prefix
+ character.
+
+ * You should not bind a key sequence ending in <ESC> except following
+ another <ESC>. (That is, it is ok to bind a sequence ending in
+ `<ESC> <ESC>'.)
+
+ The reason for this rule is that a non-prefix binding for <ESC> in
+ any context prevents recognition of escape sequences as function
+ keys in that context.
+
+ * Applications should not bind mouse events based on button 1 with
+ the shift key held down. These events include `S-mouse-1',
+ `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for
+ users.
+
+ * Modes should redefine `mouse-2' as a command to follow some sort of
+ reference in the text of a buffer, if users usually would not want
+ to alter the text in that buffer by hand. Modes such as Dired,
+ Info, Compilation, and Occur redefine it in this way.
+
+ * When a package provides a modification of ordinary Emacs behavior,
+ it is good to include a command to enable and disable the feature,
+ Provide a command named `WHATEVER-mode' which turns the feature on
+ or off, and make it autoload (*note Autoload::.). Design the
+ package so that simply loading it has no visible effect--that
+ should not enable the feature. Users will request the feature by
+ invoking the command.
+
+ * It is a bad idea to define aliases for the Emacs primitives. Use
+ the standard names instead.
+
+ * Redefining an Emacs primitive is an even worse idea. It may do
+ the right thing for a particular program, but there is no telling
+ what other programs might break as a result.
+
+ * If a file does replace any of the functions or library programs of
+ standard XEmacs, prominent comments at the beginning of the file
+ should say which functions are replaced, and how the behavior of
+ the replacements differs from that of the originals.
+
+ * Please keep the names of your XEmacs Lisp source files to 13
+ characters or less. This way, if the files are compiled, the
+ compiled files' names will be 14 characters or less, which is
+ short enough to fit on all kinds of Unix systems.
+
+ * Don't use `next-line' or `previous-line' in programs; nearly
+ always, `forward-line' is more convenient as well as more
+ predictable and robust. *Note Text Lines::.
+
+ * Don't call functions that set the mark, unless setting the mark is
+ one of the intended features of your program. The mark is a
+ user-level feature, so it is incorrect to change the mark except
+ to supply a value for the user's benefit. *Note The Mark::.
+
+ In particular, don't use these functions:
+
+ * `beginning-of-buffer', `end-of-buffer'
+
+ * `replace-string', `replace-regexp'
+
+ If you just want to move point, or replace a certain string,
+ without any of the other features intended for interactive users,
+ you can replace these functions with one or two lines of simple
+ Lisp code.
+
+ * Use lists rather than vectors, except when there is a particular
+ reason to use a vector. Lisp has more facilities for manipulating
+ lists than for vectors, and working with lists is usually more
+ convenient.
+
+ Vectors are advantageous for tables that are substantial in size
+ and are accessed in random order (not searched front to back),
+ provided there is no need to insert or delete elements (only lists
+ allow that).
+
+ * The recommended way to print a message in the echo area is with
+ the `message' function, not `princ'. *Note The Echo Area::.
+
+ * When you encounter an error condition, call the function `error'
+ (or `signal'). The function `error' does not return. *Note
+ Signaling Errors::.
+
+ Do not use `message', `throw', `sleep-for', or `beep' to report
+ errors.
+
+ * An error message should start with a capital letter but should not
+ end with a period.
+
+ * Try to avoid using recursive edits. Instead, do what the Rmail `e'
+ command does: use a new local keymap that contains one command
+ defined to switch back to the old local keymap. Or do what the
+ `edit-options' command does: switch to another buffer and let the
+ user switch back at will. *Note Recursive Editing::.
+
+ * In some other systems there is a convention of choosing variable
+ names that begin and end with `*'. We don't use that convention
+ in Emacs Lisp, so please don't use it in your programs. (Emacs
+ uses such names only for program-generated buffers.) The users
+ will find Emacs more coherent if all libraries use the same
+ conventions.
+
+ * Indent each function with `C-M-q' (`indent-sexp') using the
+ default indentation parameters.
+
+ * Don't make a habit of putting close-parentheses on lines by
+ themselves; Lisp programmers find this disconcerting. Once in a
+ while, when there is a sequence of many consecutive
+ close-parentheses, it may make sense to split them in one or two
+ significant places.
+
+ * Please put a copyright notice on the file if you give copies to
+ anyone. Use the same lines that appear at the top of the Lisp
+ files in XEmacs itself. If you have not signed papers to assign
+ the copyright to the Foundation, then place your name in the
+ copyright notice in place of the Foundation's name.
+
+\1f
+File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
+
+Tips for Making Compiled Code Fast
+==================================
+
+ Here are ways of improving the execution speed of byte-compiled Lisp
+programs.
+
+ * Use the `profile' library to profile your program. See the file
+ `profile.el' for instructions.
+
+ * Use iteration rather than recursion whenever possible. Function
+ calls are slow in XEmacs Lisp even when a compiled function is
+ calling another compiled function.
+
+ * Using the primitive list-searching functions `memq', `member',
+ `assq', or `assoc' is even faster than explicit iteration. It may
+ be worth rearranging a data structure so that one of these
+ primitive search functions can be used.
+
+ * Certain built-in functions are handled specially in byte-compiled
+ code, avoiding the need for an ordinary function call. It is a
+ good idea to use these functions rather than alternatives. To see
+ whether a function is handled specially by the compiler, examine
+ its `byte-compile' property. If the property is non-`nil', then
+ the function is handled specially.
+
+ For example, the following input will show you that `aref' is
+ compiled specially (*note Array Functions::.) while `elt' is not
+ (*note Sequence Functions::.):
+
+ (get 'aref 'byte-compile)
+ => byte-compile-two-args
+
+ (get 'elt 'byte-compile)
+ => nil
+
+ * If calling a small function accounts for a substantial part of
+ your program's running time, make the function inline. This
+ eliminates the function call overhead. Since making a function
+ inline reduces the flexibility of changing the program, don't do
+ it unless it gives a noticeable speedup in something slow enough
+ that users care about the speed. *Note Inline Functions::.
+
+\1f
+File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips
+
+Tips for Documentation Strings
+==============================
+
+ Here are some tips for the writing of documentation strings.
+
+ * Every command, function, or variable intended for users to know
+ about should have a documentation string.
+
+ * An internal variable or subroutine of a Lisp program might as well
+ have a documentation string. In earlier Emacs versions, you could
+ save space by using a comment instead of a documentation string,
+ but that is no longer the case.
+
+ * The first line of the documentation string should consist of one
+ or two complete sentences that stand on their own as a summary.
+ `M-x apropos' displays just the first line, and if it doesn't
+ stand on its own, the result looks bad. In particular, start the
+ first line with a capital letter and end with a period.
+
+ The documentation string can have additional lines that expand on
+ the details of how to use the function or variable. The
+ additional lines should be made up of complete sentences also, but
+ they may be filled if that looks good.
+
+ * For consistency, phrase the verb in the first sentence of a
+ documentation string as an infinitive with "to" omitted. For
+ instance, use "Return the cons of A and B." in preference to
+ "Returns the cons of A and B." Usually it looks good to do
+ likewise for the rest of the first paragraph. Subsequent
+ paragraphs usually look better if they have proper subjects.
+
+ * Write documentation strings in the active voice, not the passive,
+ and in the present tense, not the future. For instance, use
+ "Return a list containing A and B." instead of "A list containing
+ A and B will be returned."
+
+ * Avoid using the word "cause" (or its equivalents) unnecessarily.
+ Instead of, "Cause Emacs to display text in boldface," write just
+ "Display text in boldface."
+
+ * Do not start or end a documentation string with whitespace.
+
+ * Format the documentation string so that it fits in an Emacs window
+ on an 80-column screen. It is a good idea for most lines to be no
+ wider than 60 characters. The first line can be wider if
+ necessary to fit the information that ought to be there.
+
+ However, rather than simply filling the entire documentation
+ string, you can make it much more readable by choosing line breaks
+ with care. Use blank lines between topics if the documentation
+ string is long.
+
+ * *Do not* indent subsequent lines of a documentation string so that
+ the text is lined up in the source code with the text of the first
+ line. This looks nice in the source code, but looks bizarre when
+ users view the documentation. Remember that the indentation
+ before the starting double-quote is not part of the string!
+
+ * A variable's documentation string should start with `*' if the
+ variable is one that users would often want to set interactively.
+ If the value is a long list, or a function, or if the variable
+ would be set only in init files, then don't start the
+ documentation string with `*'. *Note Defining Variables::.
+
+ * The documentation string for a variable that is a yes-or-no flag
+ should start with words such as "Non-nil means...", to make it
+ clear that all non-`nil' values are equivalent and indicate
+ explicitly what `nil' and non-`nil' mean.
+
+ * When a function's documentation string mentions the value of an
+ argument of the function, use the argument name in capital letters
+ as if it were a name for that value. Thus, the documentation
+ string of the function `/' refers to its second argument as
+ `DIVISOR', because the actual argument name is `divisor'.
+
+ Also use all caps for meta-syntactic variables, such as when you
+ show the decomposition of a list or vector into subunits, some of
+ which may vary.
+
+ * When a documentation string refers to a Lisp symbol, write it as it
+ would be printed (which usually means in lower case), with
+ single-quotes around it. For example: `lambda'. There are two
+ exceptions: write t and nil without single-quotes. (In this
+ manual, we normally do use single-quotes for those symbols.)
+
+ * Don't write key sequences directly in documentation strings.
+ Instead, use the `\\[...]' construct to stand for them. For
+ example, instead of writing `C-f', write `\\[forward-char]'. When
+ Emacs displays the documentation string, it substitutes whatever
+ key is currently bound to `forward-char'. (This is normally `C-f',
+ but it may be some other character if the user has moved key
+ bindings.) *Note Keys in Documentation::.
+
+ * In documentation strings for a major mode, you will want to refer
+ to the key bindings of that mode's local map, rather than global
+ ones. Therefore, use the construct `\\<...>' once in the
+ documentation string to specify which key map to use. Do this
+ before the first use of `\\[...]'. The text inside the `\\<...>'
+ should be the name of the variable containing the local keymap for
+ the major mode.
+
+ It is not practical to use `\\[...]' very many times, because
+ display of the documentation string will become slow. So use this
+ to describe the most important commands in your major mode, and
+ then use `\\{...}' to display the rest of the mode's keymap.
+
+\1f
+File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
+
+Tips on Writing Comments
+========================
+
+ We recommend these conventions for where to put comments and how to
+indent them:
+
+`;'
+ Comments that start with a single semicolon, `;', should all be
+ aligned to the same column on the right of the source code. Such
+ comments usually explain how the code on the same line does its
+ job. In Lisp mode and related modes, the `M-;'
+ (`indent-for-comment') command automatically inserts such a `;' in
+ the right place, or aligns such a comment if it is already present.
+
+ This and following examples are taken from the Emacs sources.
+
+ (setq base-version-list ; there was a base
+ (assoc (substring fn 0 start-vn) ; version to which
+ file-version-assoc-list)) ; this looks like
+ ; a subversion
+
+`;;'
+ Comments that start with two semicolons, `;;', should be aligned to
+ the same level of indentation as the code. Such comments usually
+ describe the purpose of the following lines or the state of the
+ program at that point. For example:
+
+ (prog1 (setq auto-fill-function
+ ...
+ ...
+ ;; update modeline
+ (redraw-modeline)))
+
+ Every function that has no documentation string (because it is use
+ only internally within the package it belongs to), should have
+ instead a two-semicolon comment right before the function,
+ explaining what the function does and how to call it properly.
+ Explain precisely what each argument means and how the function
+ interprets its possible values.
+
+`;;;'
+ Comments that start with three semicolons, `;;;', should start at
+ the left margin. Such comments are used outside function
+ definitions to make general statements explaining the design
+ principles of the program. For example:
+
+ ;;; This Lisp code is run in XEmacs
+ ;;; when it is to operate as a server
+ ;;; for other processes.
+
+ Another use for triple-semicolon comments is for commenting out
+ lines within a function. We use triple-semicolons for this
+ precisely so that they remain at the left margin.
+
+ (defun foo (a)
+ ;;; This is no longer necessary.
+ ;;; (force-mode-line-update)
+ (message "Finished with %s" a))
+
+`;;;;'
+ Comments that start with four semicolons, `;;;;', should be aligned
+ to the left margin and are used for headings of major sections of a
+ program. For example:
+
+ ;;;; The kill ring
+
+The indentation commands of the Lisp modes in XEmacs, such as `M-;'
+(`indent-for-comment') and <TAB> (`lisp-indent-line') automatically
+indent comments according to these conventions, depending on the number
+of semicolons. *Note Manipulating Comments: (emacs)Comments.
+
+\1f
+File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips
+
+Conventional Headers for XEmacs Libraries
+=========================================
+
+ XEmacs has conventions for using special comments in Lisp libraries
+to divide them into sections and give information such as who wrote
+them. This section explains these conventions. First, an example:
+
+ ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+
+ ;; Copyright (C) 1992 Free Software Foundation, Inc.
+
+ ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
+ ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
+ ;; Created: 14 Jul 1992
+ ;; Version: 1.2
+ ;; Keywords: docs
+
+ ;; This file is part of XEmacs.
+ COPYING PERMISSIONS...
+
+ The very first line should have this format:
+
+ ;;; FILENAME --- DESCRIPTION
+
+The description should be complete in one line.
+
+ After the copyright notice come several "header comment" lines, each
+beginning with `;; HEADER-NAME:'. Here is a table of the conventional
+possibilities for HEADER-NAME:
+
+`Author'
+ This line states the name and net address of at least the principal
+ author of the library.
+
+ If there are multiple authors, you can list them on continuation
+ lines led by `;;' and a tab character, like this:
+
+ ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
+ ;; Dave Sill <de5@ornl.gov>
+ ;; Dave Brennan <brennan@hal.com>
+ ;; Eric Raymond <esr@snark.thyrsus.com>
+
+`Maintainer'
+ This line should contain a single name/address as in the Author
+ line, or an address only, or the string `FSF'. If there is no
+ maintainer line, the person(s) in the Author field are presumed to
+ be the maintainers. The example above is mildly bogus because the
+ maintainer line is redundant.
+
+ The idea behind the `Author' and `Maintainer' lines is to make
+ possible a Lisp function to "send mail to the maintainer" without
+ having to mine the name out by hand.
+
+ Be sure to surround the network address with `<...>' if you
+ include the person's full name as well as the network address.
+
+`Created'
+ This optional line gives the original creation date of the file.
+ For historical interest only.
+
+`Version'
+ If you wish to record version numbers for the individual Lisp
+ program, put them in this line.
+
+`Adapted-By'
+ In this header line, place the name of the person who adapted the
+ library for installation (to make it fit the style conventions, for
+ example).
+
+`Keywords'
+ This line lists keywords for the `finder-by-keyword' help command.
+ This field is important; it's how people will find your package
+ when they're looking for things by topic area. To separate the
+ keywords, you can use spaces, commas, or both.
+
+ Just about every Lisp library ought to have the `Author' and
+`Keywords' header comment lines. Use the others if they are
+appropriate. You can also put in header lines with other header
+names--they have no standard meanings, so they can't do any harm.
+
+ We use additional stylized comments to subdivide the contents of the
+library file. Here is a table of them:
+
+`;;; Commentary:'
+ This begins introductory comments that explain how the library
+ works. It should come right after the copying permissions.
+
+`;;; Change log:'
+ This begins change log information stored in the library file (if
+ you store the change history there). For most of the Lisp files
+ distributed with XEmacs, the change history is kept in the file
+ `ChangeLog' and not in the source file at all; these files do not
+ have a `;;; Change log:' line.
+
+`;;; Code:'
+ This begins the actual code of the program.
+
+`;;; FILENAME ends here'
+ This is the "footer line"; it appears at the very end of the file.
+ Its purpose is to enable people to detect truncated versions of
+ the file from the lack of a footer line.
+
+\1f
+File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top
+
+Building XEmacs; Allocation of Objects
+**************************************
+
+ This chapter describes how the runnable XEmacs executable is dumped
+with the preloaded Lisp libraries in it and how storage is allocated.
+
+ There is an entire separate document, the `XEmacs Internals Manual',
+devoted to the internals of XEmacs from the perspective of the C
+programmer. It contains much more detailed information about the build
+process, the allocation and garbage-collection process, and other
+aspects related to the internals of XEmacs.
+
+* Menu:
+
+* 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.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation
+
+Building XEmacs
+===============
+
+ This section explains the steps involved in building the XEmacs
+executable. You don't have to know this material to build and install
+XEmacs, since the makefiles do all these things automatically. This
+information is pertinent to XEmacs maintenance.
+
+ The `XEmacs Internals Manual' contains more information about this.
+
+ Compilation of the C source files in the `src' directory produces an
+executable file called `temacs', also called a "bare impure XEmacs".
+It contains the XEmacs Lisp interpreter and I/O routines, but not the
+editing commands.
+
+ Before XEmacs is actually usable, a number of Lisp files need to be
+loaded. These define all the editing commands, plus most of the startup
+code and many very basic Lisp primitives. This is accomplished by
+loading the file `loadup.el', which in turn loads all of the other
+standardly-loaded Lisp files.
+
+ It takes a substantial time to load the standard Lisp files.
+Luckily, you don't have to do this each time you run XEmacs; `temacs'
+can dump out an executable program called `xemacs' that has these files
+preloaded. `xemacs' starts more quickly because it does not need to
+load the files. This is the XEmacs executable that is normally
+installed.
+
+ To create `xemacs', use the command `temacs -batch -l loadup dump'.
+The purpose of `-batch' here is to tell `temacs' to run in
+non-interactive, command-line mode. (`temacs' can *only* run in this
+fashion. Part of the code required to initialize frames and faces is
+in Lisp, and must be loaded before XEmacs is able to create any frames.)
+The argument `dump' tells `loadup.el' to dump a new executable named
+`xemacs'.
+
+ The dumping process is highly system-specific, and some operating
+systems don't support dumping. On those systems, you must start XEmacs
+with the `temacs -batch -l loadup run-temacs' command each time you use
+it. This takes a substantial time, but since you need to start Emacs
+once a day at most--or once a week if you never log out--the extra time
+is not too severe a problem. (In older versions of Emacs, you started
+Emacs from `temacs' using `temacs -l loadup'.)
+
+ You are free to start XEmacs directly from `temacs' if you want,
+even if there is already a dumped `xemacs'. Normally you wouldn't want
+to do that; but the Makefiles do this when you rebuild XEmacs using
+`make all-elc', which builds XEmacs and simultaneously compiles any
+out-of-date Lisp files. (You need `xemacs' in order to compile Lisp
+files. However, you also need the compiled Lisp files in order to dump
+out `xemacs'. If both of these are missing or corrupted, you are out
+of luck unless you're able to bootstrap `xemacs' from `temacs'. Note
+that `make all-elc' actually loads the alternative loadup file
+`loadup-el.el', which works like `loadup.el' but disables the
+pure-copying process and forces XEmacs to ignore any compiled Lisp
+files even if they exist.)
+
+ You can specify additional files to preload by writing a library
+named `site-load.el' that loads them. You may need to increase the
+value of `PURESIZE', in `src/puresize.h', to make room for the
+additional files. You should *not* modify this file directly, however;
+instead, use the `--puresize' configuration option. (If you run out of
+pure space while dumping `xemacs', you will be told how much pure space
+you actually will need.) However, the advantage of preloading
+additional files decreases as machines get faster. On modern machines,
+it is often not advisable, especially if the Lisp code is on a file
+system local to the machine running XEmacs.
+
+ You can specify other Lisp expressions to execute just before dumping
+by putting them in a library named `site-init.el'. However, if they
+might alter the behavior that users expect from an ordinary unmodified
+XEmacs, it is better to put them in `default.el', so that users can
+override them if they wish. *Note Start-up Summary::.
+
+ Before `loadup.el' dumps the new executable, it finds the
+documentation strings for primitive and preloaded functions (and
+variables) in the file where they are stored, by calling
+`Snarf-documentation' (*note Accessing Documentation::.). These
+strings were moved out of the `xemacs' executable to make it smaller.
+*Note Documentation Basics::.
+
+ - Function: dump-emacs TO-FILE FROM-FILE
+ This function dumps the current state of XEmacs into an executable
+ file TO-FILE. It takes symbols from FROM-FILE (this is normally
+ the executable file `temacs').
+
+ If you use this function in an XEmacs that was already dumped, you
+ must set `command-line-processed' to `nil' first for good results.
+ *Note Command Line Arguments::.
+
+ - Function: run-emacs-from-temacs &rest ARGS
+ This is the function that implements the `run-temacs' command-line
+ argument. It is called from `loadup.el' as appropriate. You
+ should most emphatically *not* call this yourself; it will
+ reinitialize your XEmacs process and you'll be sorry.
+
+ - Command: emacs-version
+ This function returns a string describing the version of XEmacs
+ that is running. It is useful to include this string in bug
+ reports.
+
+ (emacs-version)
+ => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
+ of Mon Apr 7 1997 on altair.xemacs.org"
+
+ Called interactively, the function prints the same information in
+ the echo area.
+
+ - Variable: emacs-build-time
+ The value of this variable is the time at which XEmacs was built
+ at the local site.
+
+ emacs-build-time "Mon Apr 7 20:28:52 1997"
+ =>
+
+ - Variable: emacs-version
+ The value of this variable is the version of Emacs being run. It
+ is a string, e.g. `"20.1 XEmacs Lucid"'.
+
+ The following two variables did not exist before FSF GNU Emacs
+version 19.23 and XEmacs version 19.10, which reduces their usefulness
+at present, but we hope they will be convenient in the future.
+
+ - Variable: emacs-major-version
+ The major version number of Emacs, as an integer. For XEmacs
+ version 20.1, the value is 20.
+
+ - Variable: emacs-minor-version
+ The minor version number of Emacs, as an integer. For XEmacs
+ version 20.1, the value is 1.
+
+\1f
+File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation
+
+Pure Storage
+============
+
+ XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
+"normal storage" and "pure storage". Normal storage is where all the
+new data created during an XEmacs session is kept; see the following
+section for information on normal storage. Pure storage is used for
+certain data in the preloaded standard Lisp files--data that should
+never change during actual use of XEmacs.
+
+ Pure storage is allocated only while `temacs' is loading the
+standard preloaded Lisp libraries. In the file `xemacs', it is marked
+as read-only (on operating systems that permit this), so that the
+memory space can be shared by all the XEmacs jobs running on the machine
+at once. Pure storage is not expandable; a fixed amount is allocated
+when XEmacs is compiled, and if that is not sufficient for the preloaded
+libraries, `temacs' aborts with an error message. If that happens, you
+must increase the compilation parameter `PURESIZE' using the
+`--puresize' option to `configure'. This normally won't happen unless
+you try to preload additional libraries or add features to the standard
+ones.
+
+ - Function: purecopy OBJECT
+ This function makes a copy of OBJECT in pure storage and returns
+ it. It copies strings by simply making a new string with the same
+ characters in pure storage. It recursively copies the contents of
+ vectors and cons cells. It does not make copies of other objects
+ such as symbols, but just returns them unchanged. It signals an
+ error if asked to copy markers.
+
+ This function is a no-op except while XEmacs is being built and
+ dumped; it is usually called only in the file
+ `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in
+ case you decide to preload them.
+
+ - Variable: pure-bytes-used
+ The value of this variable is the number of bytes of pure storage
+ allocated so far. Typically, in a dumped XEmacs, this number is
+ very close to the total amount of pure storage available--if it
+ were not, we would preallocate less.
+
+ - Variable: purify-flag
+ This variable determines whether `defun' should make a copy of the
+ function definition in pure storage. If it is non-`nil', then the
+ function definition is copied into pure storage.
+
+ This flag is `t' while loading all of the basic functions for
+ building XEmacs initially (allowing those functions to be sharable
+ and non-collectible). Dumping XEmacs as an executable always
+ writes `nil' in this variable, regardless of the value it actually
+ has before and after dumping.
+
+ You should not change this flag in a running XEmacs.
+
+\1f
+File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation
+
+Garbage Collection
+==================
+
+ When a program creates a list or the user defines a new function
+(such as by loading a library), that data is placed in normal storage.
+If normal storage runs low, then XEmacs asks the operating system to
+allocate more memory in blocks of 2k bytes. Each block is used for one
+type of Lisp object, so symbols, cons cells, markers, etc., are
+segregated in distinct blocks in memory. (Vectors, long strings,
+buffers and certain other editing types, which are fairly large, are
+allocated in individual blocks, one per object, while small strings are
+packed into blocks of 8k bytes. [More correctly, a string is allocated
+in two sections: a fixed size chunk containing the length, list of
+extents, etc.; and a chunk containing the actual characters in the
+string. It is this latter chunk that is either allocated individually
+or packed into 8k blocks. The fixed size chunk is packed into 2k
+blocks, as for conses, markers, etc.])
+
+ It is quite common to use some storage for a while, then release it
+by (for example) killing a buffer or deleting the last pointer to an
+object. XEmacs provides a "garbage collector" to reclaim this
+abandoned storage. (This name is traditional, but "garbage recycler"
+might be a more intuitive metaphor for this facility.)
+
+ The garbage collector operates by finding and marking all Lisp
+objects that are still accessible to Lisp programs. To begin with, it
+assumes all the symbols, their values and associated function
+definitions, and any data presently on the stack, are accessible. Any
+objects that can be reached indirectly through other accessible objects
+are also accessible.
+
+ When marking is finished, all objects still unmarked are garbage. No
+matter what the Lisp program or the user does, it is impossible to refer
+to them, since there is no longer a way to reach them. Their space
+might as well be reused, since no one will miss them. The second
+("sweep") phase of the garbage collector arranges to reuse them.
+
+ The sweep phase puts unused cons cells onto a "free list" for future
+allocation; likewise for symbols, markers, extents, events, floats,
+compiled-function objects, and the fixed-size portion of strings. It
+compacts the accessible small string-chars chunks so they occupy fewer
+8k blocks; then it frees the other 8k blocks. Vectors, buffers,
+windows, and other large objects are individually allocated and freed
+using `malloc' and `free'.
+
+ Common Lisp note: unlike other Lisps, XEmacs Lisp does not call
+ the garbage collector when the free list is empty. Instead, it
+ simply requests the operating system to allocate more storage, and
+ processing continues until `gc-cons-threshold' bytes have been
+ used.
+
+ This means that you can make sure that the garbage collector will
+ not run during a certain portion of a Lisp program by calling the
+ garbage collector explicitly just before it (provided that portion
+ of the program does not use so much space as to force a second
+ garbage collection).
+
+ - Command: garbage-collect
+ This command runs a garbage collection, and returns information on
+ the amount of space in use. (Garbage collection can also occur
+ spontaneously if you use more than `gc-cons-threshold' bytes of
+ Lisp data since the previous garbage collection.)
+
+ `garbage-collect' returns a list containing the following
+ information:
+
+ ((USED-CONSES . FREE-CONSES)
+ (USED-SYMS . FREE-SYMS)
+ (USED-MARKERS . FREE-MARKERS)
+ USED-STRING-CHARS
+ USED-VECTOR-SLOTS
+ (PLIST))
+
+ => ((73362 . 8325) (13718 . 164)
+ (5089 . 5098) 949121 118677
+ (conses-used 73362 conses-free 8329 cons-storage 658168
+ symbols-used 13718 symbols-free 164 symbol-storage 335216
+ bit-vectors-used 0 bit-vectors-total-length 0
+ bit-vector-storage 0 vectors-used 7882
+ vectors-total-length 118677 vector-storage 537764
+ compiled-functions-used 1336 compiled-functions-free 37
+ compiled-function-storage 44440 short-strings-used 28829
+ long-strings-used 2 strings-free 7722
+ short-strings-total-length 916657 short-string-storage 1179648
+ long-strings-total-length 32464 string-header-storage 441504
+ floats-used 3 floats-free 43 float-storage 2044 markers-used 5089
+ markers-free 5098 marker-storage 245280 events-used 103
+ events-free 835 event-storage 110656 extents-used 10519
+ extents-free 2718 extent-storage 372736
+ extent-auxiliarys-used 111 extent-auxiliarys-freed 3
+ extent-auxiliary-storage 4440 window-configurations-used 39
+ window-configurations-on-free-list 5
+ window-configurations-freed 10 window-configuration-storage 9492
+ popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62
+ toolbar-button-storage 4960 toolbar-datas-used 12
+ toolbar-data-storage 240 symbol-value-buffer-locals-used 182
+ symbol-value-buffer-local-storage 5824
+ symbol-value-lisp-magics-used 22
+ symbol-value-lisp-magic-storage 1496
+ symbol-value-varaliases-used 43
+ symbol-value-varalias-storage 1032 opaque-lists-used 2
+ opaque-list-storage 48 color-instances-used 12
+ color-instance-storage 288 font-instances-used 5
+ font-instance-storage 180 opaques-used 11 opaque-storage 312
+ range-tables-used 1 range-table-storage 16 faces-used 34
+ face-storage 2584 glyphs-used 124 glyph-storage 4464
+ specifiers-used 775 specifier-storage 43869 weak-lists-used 786
+ weak-list-storage 18864 char-tables-used 40
+ char-table-storage 41920 buffers-used 25 buffer-storage 7000
+ extent-infos-used 457 extent-infos-freed 73
+ extent-info-storage 9140 keymaps-used 275 keymap-storage 12100
+ consoles-used 4 console-storage 384 command-builders-used 2
+ command-builder-storage 120 devices-used 2 device-storage 344
+ frames-used 3 frame-storage 624 image-instances-used 47
+ image-instance-storage 3008 windows-used 27 windows-freed 2
+ window-storage 9180 lcrecord-lists-used 15
+ lcrecord-list-storage 360 hash-tables-used 631
+ hash-table-storage 25240 streams-used 1 streams-on-free-list 3
+ streams-freed 12 stream-storage 91))
+
+ Here is a table explaining each element:
+
+ USED-CONSES
+ The number of cons cells in use.
+
+ FREE-CONSES
+ The number of cons cells for which space has been obtained
+ from the operating system, but that are not currently being
+ used.
+
+ USED-SYMS
+ The number of symbols in use.
+
+ FREE-SYMS
+ The number of symbols for which space has been obtained from
+ the operating system, but that are not currently being used.
+
+ USED-MARKERS
+ The number of markers in use.
+
+ FREE-MARKERS
+ The number of markers for which space has been obtained from
+ the operating system, but that are not currently being used.
+
+ USED-STRING-CHARS
+ The total size of all strings, in characters.
+
+ USED-VECTOR-SLOTS
+ The total number of elements of existing vectors.
+
+ PLIST
+ A list of alternating keyword/value pairs providing more
+ detailed information. (As you can see above, quite a lot of
+ information is provided.)
+
+ - User Option: gc-cons-threshold
+ The value of this variable is the number of bytes of storage that
+ must be allocated for Lisp objects after one garbage collection in
+ order to trigger another garbage collection. A cons cell counts
+ as eight bytes, a string as one byte per character plus a few
+ bytes of overhead, and so on; space allocated to the contents of
+ buffers does not count. Note that the subsequent garbage
+ collection does not happen immediately when the threshold is
+ exhausted, but only the next time the Lisp evaluator is called.
+
+ The initial threshold value is 500,000. If you specify a larger
+ value, garbage collection will happen less often. This reduces the
+ amount of time spent garbage collecting, but increases total
+ memory use. You may want to do this when running a program that
+ creates lots of Lisp data.
+
+ You can make collections more frequent by specifying a smaller
+ value, down to 10,000. A value less than 10,000 will remain in
+ effect only until the subsequent garbage collection, at which time
+ `garbage-collect' will set the threshold back to 10,000. (This does
+ not apply if XEmacs was configured with `--debug'. Therefore, be
+ careful when setting `gc-cons-threshold' in that case!)
+
+ - Function: memory-limit
+ This function returns the address of the last byte XEmacs has
+ allocated, divided by 1024. We divide the value by 1024 to make
+ sure it fits in a Lisp integer.
+
+ You can use this to get a general idea of how your actions affect
+ the memory usage.
+
+ - Variable: pre-gc-hook
+ This is a normal hook to be run just before each garbage
+ collection. Interrupts, garbage collection, and errors are
+ inhibited while this hook runs, so be extremely careful in what
+ you add here. In particular, avoid consing, and do not interact
+ with the user.
+
+ - Variable: post-gc-hook
+ This is a normal hook to be run just after each garbage collection.
+ Interrupts, garbage collection, and errors are inhibited while
+ this hook runs, so be extremely careful in what you add here. In
+ particular, avoid consing, and do not interact with the user.
+
+ - Variable: gc-message
+ This is a string to print to indicate that a garbage collection is
+ in progress. This is printed in the echo area. If the selected
+ frame is on a window system and `gc-pointer-glyph' specifies a
+ value (i.e. a pointer image instance) in the domain of the
+ selected frame, the mouse cursor will change instead of this
+ message being printed.
+
+ - Glyph: gc-pointer-glyph
+ This holds the pointer glyph used to indicate that a garbage
+ collection is in progress. If the selected window is on a window
+ system and this glyph specifies a value (i.e. a pointer image
+ instance) in the domain of the selected window, the cursor will be
+ changed as specified during garbage collection. Otherwise, a
+ message will be printed in the echo area, as controlled by
+ `gc-message'. *Note Glyphs::.
+
+ If XEmacs was configured with `--debug', you can set the following
+two variables to get direct information about all the allocation that
+is happening in a segment of Lisp code.
+
+ - Variable: debug-allocation
+ If non-zero, print out information to stderr about all objects
+ allocated.
+
+ - Variable: debug-allocation-backtrace
+ Length (in stack frames) of short backtrace printed out by
+ `debug-allocation'.
+
+\1f
+File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top
+
+Standard Errors
+***************
+
+ Here is the complete list of the error symbols in standard Emacs,
+grouped by concept. The list includes each symbol's message (on the
+`error-message' property of the symbol) and a cross reference to a
+description of how the error can occur.
+
+ Each error symbol has an `error-conditions' property that is a list
+of symbols. Normally this list includes the error symbol itself and
+the symbol `error'. Occasionally it includes additional symbols, which
+are intermediate classifications, narrower than `error' but broader
+than a single error symbol. For example, all the errors in accessing
+files have the condition `file-error'.
+
+ As a special exception, the error symbol `quit' does not have the
+condition `error', because quitting is not considered an error.
+
+ *Note Errors::, for an explanation of how errors are generated and
+handled.
+
+`SYMBOL'
+ STRING; REFERENCE.
+
+`error'
+ `"error"'
+ *Note Errors::.
+
+`quit'
+ `"Quit"'
+ *Note Quitting::.
+
+`args-out-of-range'
+ `"Args out of range"'
+ *Note Sequences Arrays Vectors::.
+
+`arith-error'
+ `"Arithmetic error"'
+ See `/' and `%' in *Note Numbers::.
+
+`beginning-of-buffer'
+ `"Beginning of buffer"'
+ *Note Motion::.
+
+`buffer-read-only'
+ `"Buffer is read-only"'
+ *Note Read Only Buffers::.
+
+`cyclic-function-indirection'
+ `"Symbol's chain of function indirections contains a loop"'
+ *Note Function Indirection::.
+
+`domain-error'
+ `"Arithmetic domain error"'
+`end-of-buffer'
+ `"End of buffer"'
+ *Note Motion::.
+
+`end-of-file'
+ `"End of file during parsing"'
+ This is not a `file-error'.
+ *Note Input Functions::.
+
+`file-error'
+ This error and its subcategories do not have error-strings,
+ because the error message is constructed from the data items alone
+ when the error condition `file-error' is present.
+ *Note Files::.
+
+`file-locked'
+ This is a `file-error'.
+ *Note File Locks::.
+
+`file-already-exists'
+ This is a `file-error'.
+ *Note Writing to Files::.
+
+`file-supersession'
+ This is a `file-error'.
+ *Note Modification Time::.
+
+`invalid-byte-code'
+ `"Invalid byte code"'
+ *Note Byte Compilation::.
+
+`invalid-function'
+ `"Invalid function"'
+ *Note Classifying Lists::.
+
+`invalid-read-syntax'
+ `"Invalid read syntax"'
+ *Note Input Functions::.
+
+`invalid-regexp'
+ `"Invalid regexp"'
+ *Note Regular Expressions::.
+
+`mark-inactive'
+ `"The mark is not active now"'
+`no-catch'
+ `"No catch for tag"'
+ *Note Catch and Throw::.
+
+`overflow-error'
+ `"Arithmetic overflow error"'
+`protected-field'
+ `"Attempt to modify a protected field"'
+`range-error'
+ `"Arithmetic range error"'
+`search-failed'
+ `"Search failed"'
+ *Note Searching and Matching::.
+
+`setting-constant'
+ `"Attempt to set a constant symbol"'
+ *Note Variables that Never Change: Constant Variables.
+
+`singularity-error'
+ `"Arithmetic singularity error"'
+`tooltalk-error'
+ `"ToolTalk error"'
+ *Note ToolTalk Support::.
+
+`undefined-keystroke-sequence'
+ `"Undefined keystroke sequence"'
+`void-function'
+ `"Symbol's function definition is void"'
+ *Note Function Cells::.
+
+`void-variable'
+ `"Symbol's value as variable is void"'
+ *Note Accessing Variables::.
+
+`wrong-number-of-arguments'
+ `"Wrong number of arguments"'
+ *Note Classifying Lists::.
+
+`wrong-type-argument'
+ `"Wrong type argument"'
+ *Note Type Predicates::.
+
+ These error types, which are all classified as special cases of
+`arith-error', can occur on certain systems for invalid use of
+mathematical functions.
+
+`domain-error'
+ `"Arithmetic domain error"'
+ *Note Math Functions::.
+
+`overflow-error'
+ `"Arithmetic overflow error"'
+ *Note Math Functions::.
+
+`range-error'
+ `"Arithmetic range error"'
+ *Note Math Functions::.
+
+`singularity-error'
+ `"Arithmetic singularity error"'
+ *Note Math Functions::.
+
+`underflow-error'
+ `"Arithmetic underflow error"'
+ *Note Math Functions::.
+
+\1f
+File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top
+
+Buffer-Local Variables
+**********************
+
+ The table below lists the general-purpose Emacs variables that are
+automatically local (when set) in each buffer. Many Lisp packages
+define such variables for their internal use; we don't list them here.
+
+`abbrev-mode'
+ *note Abbrevs::.
+
+`auto-fill-function'
+ *note Auto Filling::.
+
+`buffer-auto-save-file-name'
+ *note Auto-Saving::.
+
+`buffer-backed-up'
+ *note Backup Files::.
+
+`buffer-display-table'
+ *note Display Tables::.
+
+`buffer-file-format'
+ *note Format Conversion::.
+
+`buffer-file-name'
+ *note Buffer File Name::.
+
+`buffer-file-number'
+ *note Buffer File Name::.
+
+`buffer-file-truename'
+ *note Buffer File Name::.
+
+`buffer-file-type'
+ *note Files and MS-DOS::.
+
+`buffer-invisibility-spec'
+ *note Invisible Text::.
+
+`buffer-offer-save'
+ *note Saving Buffers::.
+
+`buffer-read-only'
+ *note Read Only Buffers::.
+
+`buffer-saved-size'
+ *note Point::.
+
+`buffer-undo-list'
+ *note Undo::.
+
+`cache-long-line-scans'
+ *note Text Lines::.
+
+`case-fold-search'
+ *note Searching and Case::.
+
+`ctl-arrow'
+ *note Usual Display::.
+
+`comment-column'
+ *note Comments: (emacs)Comments.
+
+`default-directory'
+ *note System Environment::.
+
+`defun-prompt-regexp'
+ *note List Motion::.
+
+`fill-column'
+ *note Auto Filling::.
+
+`goal-column'
+ *note Moving Point: (emacs)Moving Point.
+
+`left-margin'
+ *note Indentation::.
+
+`local-abbrev-table'
+ *note Abbrevs::.
+
+`local-write-file-hooks'
+ *note Saving Buffers::.
+
+`major-mode'
+ *note Mode Help::.
+
+`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::.
+
+\1f
+File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top
+
+Standard Keymaps
+****************
+
+ The following symbols are used as the names for various keymaps.
+Some of these exist when XEmacs is first started, others are loaded
+only when their respective mode is used. This is not an exhaustive
+list.
+
+ Almost all of these maps are used as local maps. Indeed, of the
+modes that presently exist, only Vip mode and Terminal mode ever change
+the global keymap.
+
+`bookmark-map'
+ A keymap containing bindings to bookmark functions.
+
+`Buffer-menu-mode-map'
+ A keymap used by Buffer Menu mode.
+
+`c++-mode-map'
+ A keymap used by C++ mode.
+
+`c-mode-map'
+ A keymap used by C mode. A sparse keymap used by C mode.
+
+`command-history-map'
+ A keymap used by Command History mode.
+
+`ctl-x-4-map'
+ A keymap for subcommands of the prefix `C-x 4'.
+
+`ctl-x-5-map'
+ A keymap for subcommands of the prefix `C-x 5'.
+
+`ctl-x-map'
+ A keymap for `C-x' commands.
+
+`debugger-mode-map'
+ A keymap used by Debugger mode.
+
+`dired-mode-map'
+ A keymap for `dired-mode' buffers.
+
+`edit-abbrevs-map'
+ A keymap used in `edit-abbrevs'.
+
+`edit-tab-stops-map'
+ A keymap used in `edit-tab-stops'.
+
+`electric-buffer-menu-mode-map'
+ A keymap used by Electric Buffer Menu mode.
+
+`electric-history-map'
+ A keymap used by Electric Command History mode.
+
+`emacs-lisp-mode-map'
+ A keymap used by Emacs Lisp mode.
+
+`help-map'
+ A keymap for characters following the Help key.
+
+`Helper-help-map'
+ A keymap used by the help utility package.
+ It has the same keymap in its value cell and in its function cell.
+
+`Info-edit-map'
+ A keymap used by the `e' command of Info.
+
+`Info-mode-map'
+ A keymap containing Info commands.
+
+`isearch-mode-map'
+ A keymap that defines the characters you can type within
+ incremental search.
+
+`itimer-edit-map'
+ A keymap used when in Itimer Edit mode.
+
+`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.
+
+\1f
+File: lispref.info, Node: Standard Hooks, Next: Index, Prev: Standard Keymaps, Up: Top
+
+Standard Hooks
+**************
+
+ The following is a list of hook variables that let you provide
+functions to be called from within Emacs on suitable occasions.
+
+ Most of these variables have names ending with `-hook'. They are
+"normal hooks", run by means of `run-hooks'. The value of such a hook
+is a list of functions. The recommended way to put a new function on
+such a hook is to call `add-hook'. *Note Hooks::, for more information
+about using hooks.
+
+ The variables whose names end in `-function' have single functions
+as their values. Usually there is a specific reason why the variable is
+not a normal hook, such as the need to pass arguments to the function.
+(In older Emacs versions, some of these variables had names ending in
+`-hook' even though they were not normal hooks.)
+
+ The variables whose names end in `-hooks' or `-functions' have lists
+of functions as their values, but these functions are called in a
+special way (they are passed arguments, or else their values are used).
+
+`activate-menubar-hook'
+
+`activate-popup-menu-hook'
+
+`ad-definition-hooks'
+
+`adaptive-fill-function'
+
+`add-log-current-defun-function'
+
+`after-change-functions'
+
+`after-delete-annotation-hook'
+
+`after-init-hook'
+
+`after-insert-file-functions'
+
+`after-revert-hook'
+
+`after-save-hook'
+
+`after-set-visited-file-name-hooks'
+
+`after-write-file-hooks'
+
+`auto-fill-function'
+
+`auto-save-hook'
+
+`before-change-functions'
+
+`before-delete-annotation-hook'
+
+`before-init-hook'
+
+`before-revert-hook'
+
+`blink-paren-function'
+
+`buffers-menu-switch-to-buffer-function'
+
+`c++-mode-hook'
+
+`c-delete-function'
+
+`c-mode-common-hook'
+
+`c-mode-hook'
+
+`c-special-indent-hook'
+
+`calendar-load-hook'
+
+`change-major-mode-hook'
+
+`command-history-hook'
+
+`comment-indent-function'
+
+`compilation-buffer-name-function'
+
+`compilation-exit-message-function'
+
+`compilation-finish-function'
+
+`compilation-parse-errors-function'
+
+`compilation-mode-hook'
+
+`create-console-hook'
+
+`create-device-hook'
+
+`create-frame-hook'
+
+`dabbrev-friend-buffer-function'
+
+`dabbrev-select-buffers-function'
+
+`delete-console-hook'
+
+`delete-device-hook'
+
+`delete-frame-hook'
+
+`deselect-frame-hook'
+
+`diary-display-hook'
+
+`diary-hook'
+
+`dired-after-readin-hook'
+
+`dired-before-readin-hook'
+
+`dired-load-hook'
+
+`dired-mode-hook'
+
+`disabled-command-hook'
+
+`display-buffer-function'
+
+`ediff-after-setup-control-frame-hook'
+
+`ediff-after-setup-windows-hook'
+
+`ediff-before-setup-control-frame-hook'
+
+`ediff-before-setup-windows-hook'
+
+`ediff-brief-help-message-function'
+
+`ediff-cleanup-hook'
+
+`ediff-control-frame-position-function'
+
+`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'
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: 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.
+* *scratch*: Auto Major Mode.
+* +: Arithmetic Operations.
+* + in regexp: Syntax of Regexps.
+* +? in regexp: Syntax of Regexps.
+* , (with Backquote): Backquote.
+* ,@ (with Backquote): Backquote.
+* -: Arithmetic Operations.
+* . in lists: Dotted Pair Notation.
+* . in regexp: Syntax of Regexps.
+* .emacs: Init File.
+* .emacs customization: Major Mode Conventions.
+* /: Arithmetic Operations.
+* /=: Comparison of Numbers.
+* 1+: Arithmetic Operations.
+* 1-: Arithmetic Operations.
+* ; in comment: Comments.
+* <: Comparison of Numbers.
+* <=: Comparison of Numbers.
+* <ESC>: Functions for Key Lookup.
+* <SPC> in minibuffer: Text from Minibuffer.
+* <TAB> in minibuffer: Text from Minibuffer.
+* =: Comparison of Numbers.
+* >: Comparison of Numbers.
+* >=: Comparison of Numbers.
+* ? in character constant: Character Type.
+* ? in minibuffer: Text from Minibuffer.
+* ? 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>: Cons Cell Type.
+* atom: List-related Predicates.
+* atomic extent: Atomic Extents.
+* atoms: List-related Predicates.
+* attributes of text: Text Properties.
+* Auto Fill mode: Auto Filling.
+* auto-fill-function: Auto Filling.
+* auto-lower-frame: Raising and Lowering.
+* auto-mode-alist: Auto Major Mode.
+* auto-raise-frame: Raising and Lowering.
+* auto-save-default: Auto-Saving.
+* auto-save-file-format: Format Conversion.
+* auto-save-file-name-p: Auto-Saving.
+* auto-save-hook: Auto-Saving.
+* auto-save-interval: Auto-Saving.
+* auto-save-list-file-name: Auto-Saving.
+* auto-save-mode: Auto-Saving.
+* auto-save-timeout: Auto-Saving.
+* auto-save-visited-file-name: Auto-Saving.
+* auto-saving: Auto-Saving.
+* autoload <1>: Domain Specification.
+* autoload: Autoload.
+* autoload errors: Autoload.
+* automatically buffer-local: Intro to Buffer-Local.
+* available fonts: Font Instance Names.
+* back-to-indentation: Motion by Indent.
+* background pixmap: Merging Faces.
+* backquote (Edebug): Debugging Backquote.
+* backquote (list substitution): Backquote.
+* backslash in character constant: Character Type.
+* backslash in strings: String Type.
+* backslash in symbols: Symbol Type.
+* backspace: Character Type.
+* backtrace: Internals of Debugger.
+* backtrace-debug: Internals of Debugger.
+* backtrace-frame: Internals of Debugger.
+* backtracking: Backtracking.
+* backup file: Backup Files.
+* backup files, how to make them: Rename or Copy.
+* backup-buffer: Making Backups.
+* backup-by-copying: Rename or Copy.
+* backup-by-copying-when-linked: Rename or Copy.
+* backup-by-copying-when-mismatch: Rename or Copy.
+* backup-enable-predicate: Making Backups.
+* backup-file-name-p: Backup Names.
+* backup-inhibited: Making Backups.
+* backward-char: Character Motion.
+* backward-delete-char-untabify: Deletion.
+* backward-list: List Motion.
+* backward-prefix-chars: Motion and Syntax.
+* backward-sexp: List Motion.
+* backward-to-indentation: Motion by Indent.
+* backward-word: Word Motion.
+* balancing parentheses: Blinking.
+* barf-if-buffer-read-only: Read Only Buffers.
+* base buffer: Indirect Buffers.
+* base64: Transformations.
+* base64-decode-region: Transformations.
+* base64-decode-string: Transformations.
+* base64-encode-region: Transformations.
+* base64-encode-string: Transformations.
+* batch mode: Batch Mode.
+* batch-byte-compile: Compilation Functions.
+* batch-byte-recompile-directory: Compilation Functions.
+* beep: Beeping.
+* beeping: Beeping.
+* before point, insertion: Insertion.
+* before-change-function: Change Hooks.
+* before-change-functions: Change Hooks.
+* before-init-hook: Init File.
+* before-revert-hook: Reverting.
+* beginning of line: Text Lines.
+* beginning of line in regexp: Syntax of Regexps.
+* beginning-of-buffer: Buffer End Motion.
+* beginning-of-defun: List Motion.
+* beginning-of-line: Text Lines.
+* bell: Beeping.
+* bell character: Character Type.
+* bell-volume: Beeping.
+* binary files and text files: Files and MS-DOS.
+* binary-process-input: MS-DOS Subprocesses.
+* binary-process-output: MS-DOS Subprocesses.
+* bind-text-domain: Level 3 Primitives.
+* binding arguments: Argument List.
+* binding local variables: Local Variables.
+* binding of a key: Keymap Terminology.
+* bit vector: Bit Vectors.
+* bit vector length: Sequence Functions.
+* bit-vector: Bit Vector Functions.
+* bit-vector-p: Bit Vector Functions.
+* bitp: Bit Vector Functions.
+* bitwise and: Bitwise Operations.
+* bitwise exclusive or: Bitwise Operations.
+* bitwise not: Bitwise Operations.
+* bitwise or: Bitwise Operations.
+* blink-matching-open: Blinking.
+* blink-matching-paren: Blinking.
+* blink-matching-paren-delay: Blinking.
+* blink-matching-paren-distance: Blinking.
+* blink-paren-function: Blinking.
+* blink-paren-hook: Blinking.
+* blinking: Blinking.
+* bobp: Near Point.
+* body of function: Lambda Components.
+* bold: Font Instance Characteristics.
+* bolp: Near Point.
+* bookmark-map: Standard Keymaps.
+* boolean: nil and t.
+* boolean-specifier-p: Specifier Types.
+* bootstrapping XEmacs from temacs: Building XEmacs.
+* bottom-toolbar: Specifying the Toolbar.
+* bottom-toolbar-height: Other Toolbar Variables.
+* bottom-toolbar-visible-p: Other Toolbar Variables.
+* boundp: Void Variables.
+* box diagrams, for lists: Cons Cell Type.
+* box representation for lists: Lists as Boxes.
+* break: Debugger.
+* breakpoints: Breakpoints.
+* bucket (in obarray): Creating Symbols.
+* buffer: Buffers.
+* buffer contents: Text.
+* buffer file name: Buffer File Name.
+* buffer input stream: Input Streams.
+* buffer list: The Buffer List.
+* buffer modification: Buffer Modification.
+* buffer names: Buffer Names.
+* buffer output stream: Output Streams.
+* buffer text notation: Buffer Text Notation.
+* buffer, read-only: Read Only Buffers.
+* buffer-auto-save-file-name: Auto-Saving.
+* buffer-backed-up: Making Backups.
+* buffer-base-buffer: Indirect Buffers.
+* buffer-disable-undo: Maintaining Undo.
+* buffer-enable-undo: Maintaining Undo.
+* buffer-end: Point.
+* buffer-file-format: Format Conversion.
+* buffer-file-name: Buffer File Name.
+* buffer-file-number: Buffer File Name.
+* buffer-file-truename: Buffer File Name.
+* buffer-file-type: Files and MS-DOS.
+* buffer-flush-undo: Maintaining Undo.
+* buffer-glyph-p: Glyph Types.
+* buffer-indirect-children: Indirect Buffers.
+* buffer-invisibility-spec: Invisible Text.
+* buffer-list: The Buffer List.
+* buffer-live-p: Killing Buffers.
+* buffer-local variables: Buffer-Local Variables.
+* buffer-local variables in modes: Major Mode Conventions.
+* buffer-local-variables: Creating Buffer-Local.
+* Buffer-menu-mode-map: Standard Keymaps.
+* buffer-modified-p: Buffer Modification.
+* buffer-modified-tick: Buffer Modification.
+* buffer-name: Buffer Names.
+* buffer-offer-save <1>: Killing Buffers.
+* buffer-offer-save: Saving Buffers.
+* buffer-read-only: Read Only Buffers.
+* buffer-saved-size <1>: Auto-Saving.
+* buffer-saved-size: Point.
+* 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.
+* 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-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 quote: Syntax Class Table.
+* 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.
+* 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-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---no continuable errors: Signaling Errors.
+* 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 parenthesis character: Syntax Class Table.
+* close-database: Connecting to a Database.
+* closures not available: Extent.
+* clrhash: Working With Hash Tables.
+* codes, interactive, description of: Interactive Codes.
+* coding standards: Tips.
+* coding system type: Coding System Type.
+* coding-category-list: Detection of Textual Encoding.
+* coding-category-system: Detection of Textual Encoding.
+* coding-priority-list: Detection of Textual Encoding.
+* coding-system-doc-string: Coding System Property Functions.
+* coding-system-list: Basic Coding System Functions.
+* coding-system-name: Basic Coding System Functions.
+* coding-system-p: Coding Systems.
+* coding-system-property: Coding System Property Functions.
+* coding-system-type: Coding System Property Functions.
+* color instance type: Color Instance Type.
+* color instances: Color Instances.
+* color-instance-name: Color Instance Properties.
+* color-instance-p: Color Instances.
+* color-instance-rgb-components: Color Instance Properties.
+* color-name: Color Convenience Functions.
+* color-pixmap-image-instance-p: Image Instance Types.
+* color-rgb-components: Color Convenience Functions.
+* color-specifier-p <1>: Color Specifiers.
+* color-specifier-p: Specifier Types.
+* colorize-image-instance: Image Instance Functions.
+* colors: Colors.
+* columns: Columns.
+* command: What Is a Function.
+* command descriptions: A Sample Function Description.
+* command history: Command History.
+* command in keymap: Key Lookup.
+* command line arguments: Command Line Arguments.
+* command line options: Command Line Arguments.
+* command loop: Command Loop.
+* command loop, recursive: Recursive Editing.
+* command-debug-status: Internals of Debugger.
+* command-execute: Interactive Call.
+* command-history: Command History.
+* command-history-map: Standard Keymaps.
+* command-line: Command Line Arguments.
+* command-line-args: Command Line Arguments.
+* command-line-functions: Command Line Arguments.
+* command-line-processed: Command Line Arguments.
+* command-switch-alist: Command Line Arguments.
+* commandp: Interactive Call.
+* commandp example: High-Level Completion.
+* commands, defining: Defining Commands.
+* comment ender: Syntax Class Table.
+* comment starter: Syntax Class Table.
+* comment syntax: Syntax Class Table.
+* comments: Comments.
+* 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>: Prefix Keys.
+* ctl-x-4-map: Standard Keymaps.
+* ctl-x-5-map <1>: Prefix Keys.
+* ctl-x-5-map: Standard Keymaps.
+* ctl-x-map <1>: Standard Keymaps.
+* ctl-x-map: Prefix Keys.
+* cube-root: Math Functions.
+* current binding: Local Variables.
+* current buffer: Current Buffer.
+* current buffer excursion: Excursions.
+* current buffer mark: The Mark.
+* current buffer point and mark (Edebug): Edebug Display Update.
+* current buffer position: Point.
+* current command: Command Loop Info.
+* current stack frame: Using Debugger.
+* current-buffer: Current Buffer.
+* current-case-table: Case Tables.
+* current-column: Columns.
+* current-fill-column: Margins.
+* current-frame-configuration: Frame Configurations.
+* current-global-map: Active Keymaps.
+* current-indentation: Primitive Indent.
+* current-input-mode: Input Modes.
+* current-justification: Filling.
+* current-keymaps: Active Keymaps.
+* current-kill: Low-Level Kill Ring.
+* current-left-margin: Margins.
+* current-local-map: Active Keymaps.
+* current-menubar: Menubar.
+* current-message: The Echo Area.
+* current-minor-mode-maps: Active Keymaps.
+* current-mouse-event: Command Loop Info.
+* current-prefix-arg: Prefix Command Arguments.
+* current-time: Time of Day.
+* current-time-string: Time of Day.
+* current-time-zone: Time of Day.
+* current-window-configuration: Window Configurations.
+* cursor (mouse): Mouse Pointer.
+* cursor-in-echo-area: The Echo Area.
+* cust-print: Printing in Edebug.
+* cut buffer: X Selections.
+* cyclic ordering of windows: Cyclic Window Ordering.
+* data type: Lisp Data Types.
+* data-directory: Accessing Documentation.
+* database: Databases.
+* database type: Database Type.
+* database-file-name: Other Database Functions.
+* database-last-error: Other Database Functions.
+* database-live-p: Connecting to a Database.
+* database-subtype: Other Database Functions.
+* database-type: Other Database Functions.
+* databasep: Databases.
+* deallocate-event: Working With Events.
+* debug: Invoking the Debugger.
+* debug-allocation: Garbage Collection.
+* debug-allocation-backtrace: Garbage Collection.
+* debug-ignored-errors: Error Debugging.
+* debug-on-entry: Function Debugging.
+* debug-on-error: Error Debugging.
+* debug-on-error use: Processing of Errors.
+* debug-on-next-call: Internals of Debugger.
+* debug-on-quit: Infinite Loops.
+* debug-on-signal: Error Debugging.
+* debugger <1>: Debugger.
+* debugger: Internals of Debugger.
+* debugger command list: Debugger Commands.
+* debugger-mode-map: Standard Keymaps.
+* debugging errors: Error Debugging.
+* debugging specific functions: Function Debugging.
+* decode-big5-char: Big5 and Shift-JIS Functions.
+* decode-coding-region: Encoding and Decoding Text.
+* decode-shift-jis-char: Big5 and Shift-JIS Functions.
+* decode-time: Time Conversion.
+* decoding file formats: Format Conversion.
+* decompose-region: Composite Characters.
+* decrement field of register: Cons Cell Type.
+* dedicated window: Choosing Window.
+* deep binding: Impl of Scope.
+* def-edebug-spec: Instrumenting Macro Calls.
+* defalias: Defining Functions.
+* default argument string: Interactive Codes.
+* default init file: Init File.
+* default value: Default Value.
+* default-abbrev-mode: Abbrev Mode.
+* default-boundp: Default Value.
+* default-buffer-file-type: Files and MS-DOS.
+* default-case-fold-search: Searching and Case.
+* default-ctl-arrow: Usual Display.
+* default-deselect-frame-hook: Raising and Lowering.
+* default-directory: File Name Expansion.
+* default-file-modes: Changing File Attributes.
+* default-fill-column: Margins.
+* default-frame-name: Frame Name.
+* default-frame-plist: Initial Properties.
+* default-justification: Filling.
+* default-major-mode: Auto Major Mode.
+* default-menubar: Menubar.
+* default-minibuffer-frame: Minibuffers and Frames.
+* default-modeline-format: Modeline Variables.
+* default-popup-menu: Pop-Up Menus.
+* default-select-frame-hook: Raising and Lowering.
+* default-text-properties: Examining Properties.
+* default-toolbar: Specifying the Toolbar.
+* default-toolbar-height: Other Toolbar Variables.
+* default-toolbar-position: Specifying the Toolbar.
+* default-toolbar-visible-p: Other Toolbar Variables.
+* default-toolbar-width: Other Toolbar Variables.
+* default-truncate-lines: Truncation.
+* default-value: Default Value.
+* default-x-device: Resources.
+* default.el: Start-up Summary.
+* defconst <1>: Domain Specification.
+* defconst: Defining Variables.
+* defcustom: Variable Definitions.
+* defgroup: Group Definitions.
+* define-abbrev: Defining Abbrevs.
+* define-abbrev-table: Abbrev Tables.
+* define-derived-mode: Derived Modes.
+* define-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>: Defining Variables.
+* defvar: Domain Specification.
+* 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-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>: Console and Device I/O.
+* device-baud-rate: Terminal Output.
+* device-class: Console Types and Device Classes.
+* device-frame-list <1>: Finding All Frames.
+* device-frame-list: Basic Device Functions.
+* 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-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: Edebug.
+* edebug: Embedded Breakpoints.
+* 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>: Instrumenting.
+* edebug-all-forms: Edebug Options.
+* edebug-continue-kbd-macro: Edebug Options.
+* edebug-display-freq-count: Coverage Testing.
+* edebug-eval-top-level-form: Instrumenting.
+* edebug-global-break-condition <1>: Global Break Condition.
+* edebug-global-break-condition: Edebug Options.
+* 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>: Printing in Edebug.
+* edebug-print-circle: Edebug Options.
+* edebug-print-length <1>: Printing in Edebug.
+* edebug-print-length: Edebug Options.
+* edebug-print-level <1>: Printing in Edebug.
+* edebug-print-level: Edebug Options.
+* edebug-print-trace-after <1>: Tracing.
+* edebug-print-trace-after: Edebug Options.
+* edebug-print-trace-before <1>: Tracing.
+* edebug-print-trace-before: Edebug Options.
+* 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>: Debugging Backquote.
+* edebug-unwrap-results: Edebug Options.
+* 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.
+* errors: Errors.
+* esc-map: Prefix Keys.
+* ESC-prefix: Prefix Keys.
+* escape <1>: Character Type.
+* escape: Syntax Class Table.
+* 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>: Variable Scoping.
+* extent: Extents.
+* 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>: What Is a Function.
+* function: Anonymous Functions.
+* 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>: Mouse Pointer.
+* gc-pointer-glyph: Garbage Collection.
+* generate-new-buffer: Creating Buffers.
+* generate-new-buffer-name: Buffer Names.
+* generic-specifier-p: Specifier Types.
+* get: Symbol Plists.
+* get-buffer: Buffer Names.
+* get-buffer-create: Creating Buffers.
+* get-buffer-process: Process Buffers.
+* get-buffer-window: Buffers and Windows.
+* get-char-property: Examining Properties.
+* get-char-table: Working With Char Tables.
+* get-charset: Basic Charset Functions.
+* get-coding-system: Basic Coding System Functions.
+* get-database: Working With a Database.
+* get-file-buffer: Buffer File Name.
+* get-largest-window: Selecting Windows.
+* get-lru-window: Selecting Windows.
+* get-process: Process Information.
+* get-range-char-table: Working With Char Tables.
+* get-range-table: Working With Range Tables.
+* get-register: Registers.
+* get-text-property: Examining Properties.
+* get-tooltalk-message-attribute: Elisp Interface for Sending Messages.
+* getenv: System Environment.
+* getf: Other Plists.
+* gethash: Working With Hash Tables.
+* gettext: Level 3 Primitives.
+* global binding: Local Variables.
+* global break condition: Global Break Condition.
+* global keymap: Active Keymaps.
+* global mark ring: The Mark.
+* global variable: Global Variables.
+* global-abbrev-table: Standard Abbrev Tables.
+* global-key-binding: Functions for Key Lookup.
+* global-map: Active Keymaps.
+* global-mark-ring: The Mark.
+* global-mode-string: Modeline Variables.
+* global-popup-menu: Pop-Up Menus.
+* global-set-key: Key Binding Commands.
+* global-unset-key: Key Binding Commands.
+* glyph type: Glyph Type.
+* glyph-ascent: Glyph Dimensions.
+* glyph-baseline: Glyph Convenience Functions.
+* glyph-baseline-instance: Glyph Convenience Functions.
+* glyph-contrib-p: Glyph Convenience Functions.
+* glyph-contrib-p-instance: Glyph Convenience Functions.
+* glyph-descent: Glyph Dimensions.
+* glyph-face: Glyph Convenience Functions.
+* glyph-height: Glyph Dimensions.
+* glyph-image: Glyph Convenience Functions.
+* glyph-image-instance: Glyph Convenience Functions.
+* glyph-property: Glyph Properties.
+* glyph-property-instance: Glyph Properties.
+* glyph-type: Glyph Types.
+* glyph-type-list: Glyph Types.
+* glyph-width: Glyph Dimensions.
+* glyphp: Glyphs.
+* glyphs: Glyphs.
+* goto-char: Character Motion.
+* goto-line: Text Lines.
+* hack-local-variables: Auto Major Mode.
+* handling errors: Handling Errors.
+* hash notation: Printed Representation.
+* hash table: Hash Tables.
+* hash table type: Hash Table Type.
+* hash table, weak: Weak Hash Tables.
+* hash-table-count: Introduction to Hash Tables.
+* hash-table-p: Hash Tables.
+* hash-table-rehash-size: Introduction to Hash Tables.
+* hash-table-rehash-threshold: Introduction to Hash Tables.
+* hash-table-size: Introduction to Hash Tables.
+* hash-table-test: Introduction to Hash Tables.
+* hash-table-weakness: Introduction to Hash Tables.
+* hashing: Creating Symbols.
+* header comments: Library Headers.
+* help for major mode: Mode Help.
+* help-char: Help Functions.
+* help-command: Help Functions.
+* help-form: Help Functions.
+* help-map <1>: Help Functions.
+* help-map: Standard Keymaps.
+* Helper-describe-bindings: Help Functions.
+* Helper-help: Help Functions.
+* Helper-help-map: Standard Keymaps.
+* hide-annotation: Annotation Properties.
+* highlight-extent: Extents and Events.
+* history list: Minibuffer History.
+* history of commands: Command History.
+* HOME environment variable: Subprocess Creation.
+* hooks: Hooks.
+* hooks for loading: Hooks for Loading.
+* hooks for text changes: Change Hooks.
+* horizontal position: Columns.
+* horizontal scrolling: Horizontal Scrolling.
+* hscroll-glyph: Redisplay Glyphs.
+* icon-glyph-p: Glyph Types.
+* iconified frame: Visibility of Frames.
+* iconify-frame: Visibility of Frames.
+* identity: Calling Functions.
+* IEEE floating point: Float Basics.
+* if: Conditionals.
+* ignore: Calling Functions.
+* ignored-local-variables: Auto Major Mode.
+* image instance type: Image Instance Type.
+* image instance types: Image Instance Types.
+* image instances: Image Instances.
+* image instantiator conversion: Image Instantiator Conversion.
+* image specifiers: Image Specifiers.
+* image-instance-background: Image Instance Functions.
+* image-instance-depth: Image Instance Functions.
+* image-instance-file-name: Image Instance Functions.
+* image-instance-foreground: Image Instance Functions.
+* image-instance-height: Image Instance Functions.
+* image-instance-hotspot-x: Image Instance Functions.
+* image-instance-hotspot-y: Image Instance Functions.
+* image-instance-mask-file-name: Image Instance Functions.
+* image-instance-name: Image Instance Functions.
+* image-instance-p: Image Instances.
+* image-instance-string: Image Instance Functions.
+* image-instance-type: Image Instance Types.
+* image-instance-type-list: Image Instance Types.
+* image-instance-width: Image Instance Functions.
+* image-instantiator-format-list: Image Specifiers.
+* image-specifier-p <1>: Specifier Types.
+* image-specifier-p: Image Specifiers.
+* implicit progn: Sequencing.
+* inc: Simple Macro.
+* indent-according-to-mode: Mode-Specific Indent.
+* indent-code-rigidly: Region Indent.
+* indent-for-tab-command: Mode-Specific Indent.
+* indent-line-function: Mode-Specific Indent.
+* indent-region: Region Indent.
+* indent-region-function: Region Indent.
+* indent-relative: Relative Indent.
+* indent-relative-maybe: Relative Indent.
+* indent-rigidly: Region Indent.
+* indent-tabs-mode: Primitive Indent.
+* indent-to: Primitive Indent.
+* indent-to-left-margin: Margins.
+* indentation: Indentation.
+* indenting with parentheses: Parsing Expressions.
+* indirect buffers: Indirect Buffers.
+* indirect specifications: Specification List.
+* indirect variables: Variable Aliases.
+* indirect-function: Function Indirection.
+* indirect-variable: Variable Aliases.
+* indirection: Function Indirection.
+* infinite loops: Infinite Loops.
+* infinite recursion: Local Variables.
+* infinity: Float Basics.
+* Info-edit-map: Standard Keymaps.
+* Info-minibuffer-history: Minibuffer History.
+* Info-mode-map: Standard Keymaps.
+* inherit: Syntax Class Table.
+* inheriting a keymap's bindings: Inheritance and Keymaps.
+* inhibit-default-init: Init File.
+* inhibit-file-name-handlers: Magic File Names.
+* inhibit-file-name-operation: Magic File Names.
+* inhibit-quit: Quitting.
+* inhibit-read-only: Read Only Buffers.
+* inhibit-startup-echo-area-message: Start-up Summary.
+* inhibit-startup-message: Start-up Summary.
+* init file: Init File.
+* initial-frame-plist: Initial Properties.
+* initial-major-mode: Auto Major Mode.
+* initial-toolbar-spec: Other Toolbar Variables.
+* initialization: Start-up Summary.
+* inline functions: Inline Functions.
+* innermost containing parentheses: Parsing Expressions.
+* input events: Events.
+* input focus: Input Focus.
+* input modes: Input Modes.
+* input stream: Input Streams.
+* input-pending-p: Peeking and Discarding.
+* insert: Insertion.
+* insert-abbrev-table-description: Abbrev Tables.
+* insert-before-markers: Insertion.
+* insert-buffer: Commands for Insertion.
+* insert-buffer-substring: Insertion.
+* insert-char: Insertion.
+* insert-default-directory: Reading File Names.
+* insert-directory: Contents of Directories.
+* insert-directory-program: Contents of Directories.
+* insert-extent: Detached Extents.
+* insert-file-contents: Reading from Files.
+* insert-register: Registers.
+* insert-string: Insertion.
+* inserting killed text: Yank Commands.
+* insertion before point: Insertion.
+* insertion of text: Insertion.
+* inside comment: Parsing Expressions.
+* inside margin: Annotation Basics.
+* inside string: Parsing Expressions.
+* inst-list (in a specifier): Specifiers In-Depth.
+* inst-pair (in a specifier): Specifiers In-Depth.
+* installation-directory: System Environment.
+* instance (in a specifier): Specifiers In-Depth.
+* instancing (in a specifier): Specifiers In-Depth.
+* instantiator (in a specifier): Specifiers In-Depth.
+* int-char: Character Codes.
+* int-to-string: String Conversion.
+* integer to decimal: String Conversion.
+* integer to hexadecimal: Formatting Strings.
+* integer to octal: Formatting Strings.
+* integer to string: String Conversion.
+* integer-char-or-marker-p: Predicates on Markers.
+* integer-or-char-p: Predicates for Characters.
+* integer-or-marker-p: Predicates on Markers.
+* integer-specifier-p: Specifier Types.
+* integerp: Predicates on Numbers.
+* integers: Numbers.
+* interactive: Using Interactive.
+* interactive call: Interactive Call.
+* interactive code description: Interactive Codes.
+* interactive commands (Edebug): Instrumenting.
+* interactive completion: Interactive Codes.
+* interactive function: Defining Commands.
+* interactive, examples of using: Interactive Examples.
+* interactive-p: Interactive Call.
+* intern: Creating Symbols.
+* intern-soft: Creating Symbols.
+* internal-doc-file-name: Accessing Documentation.
+* interning: Creating Symbols.
+* interpreter: Evaluation.
+* interpreter-mode-alist: Auto Major Mode.
+* interprogram-cut-function: Low-Level Kill Ring.
+* interprogram-paste-function: Low-Level Kill Ring.
+* interrupt-process: Signals to Processes.
+* invalid function: Function Indirection.
+* invalid prefix key error: Changing Key Bindings.
+* invalid-function: Function Indirection.
+* invalid-read-syntax: Printed Representation.
+* invalid-regexp: Syntax of Regexps.
+* invert-face: Other Face Display Functions.
+* invisible frame: Visibility of Frames.
+* invisible text: Invisible Text.
+* invisible-text-glyph: Redisplay Glyphs.
+* invocation-directory: System Environment.
+* invocation-name: System Environment.
+* isearch-mode-map: Standard Keymaps.
+* ISO Latin 1: Case Tables.
+* ISO Latin-1 characters (input): Translating Input.
+* iso-syntax: Case Tables.
+* iso-transl: Translating Input.
+* italic: Font Instance Characteristics.
+* iteration: Iteration.
+* itimer-edit-map: Standard Keymaps.
+* joining lists: Rearrangement.
+* just-one-space: User-Level Deletion.
+* justify-current-line: Filling.
+* kept-new-versions: Numbered Backups.
+* kept-old-versions: Numbered Backups.
+* key: Keymap Terminology.
+* key binding: Keymap Terminology.
+* key lookup: Key Lookup.
+* key sequence: Key Sequence Input.
+* key sequence error: Changing Key Bindings.
+* key sequence input: Key Sequence Input.
+* key sequences: Key Sequences.
+* key translation function: Translating Input.
+* key-binding: Functions for Key Lookup.
+* key-description: Describing Characters.
+* key-press-event-p: Event Predicates.
+* key-translation-map: Translating Input.
+* keyboard macro execution: Interactive Call.
+* keyboard macro termination: Beeping.
+* keyboard macros: Keyboard Macros.
+* keyboard macros (Edebug): Edebug Execution Modes.
+* keyboard menu accelerators: Menu Accelerators.
+* keyboard-quit: Quitting.
+* keymap: Keymaps.
+* keymap entry: Key Lookup.
+* keymap format: Format of Keymaps.
+* keymap in keymap: Key Lookup.
+* keymap inheritance: Inheritance and Keymaps.
+* keymap parent: Inheritance and Keymaps.
+* keymap-default-binding: Inheritance and Keymaps.
+* keymap-fullness: Scanning Keymaps.
+* keymap-name: Creating Keymaps.
+* keymap-parents: Inheritance and Keymaps.
+* keymap-prompt: Other Keymap Functions.
+* keymapp: Format of Keymaps.
+* keymaps in modes: Major Mode Conventions.
+* keys in documentation strings: Keys in Documentation.
+* keystroke: Keymap Terminology.
+* keystroke command: What Is a Function.
+* keywordp: Specification List.
+* kill command repetition: Command Loop Info.
+* kill ring: The Kill Ring.
+* kill-all-local-variables: Creating Buffer-Local.
+* kill-append: Low-Level Kill Ring.
+* kill-buffer: Killing Buffers.
+* kill-buffer-hook: Killing Buffers.
+* kill-buffer-query-functions: Killing Buffers.
+* kill-emacs: Killing XEmacs.
+* kill-emacs-hook: Killing XEmacs.
+* kill-emacs-query-functions: Killing XEmacs.
+* kill-local-variable: Creating Buffer-Local.
+* kill-new: Low-Level Kill Ring.
+* kill-process: Signals to Processes.
+* kill-region: Kill Functions.
+* kill-ring: Internals of Kill Ring.
+* kill-ring-max: Internals of Kill Ring.
+* kill-ring-yank-pointer: Internals of Kill Ring.
+* killing buffers: Killing Buffers.
+* killing XEmacs: Killing XEmacs.
+* lambda expression: Lambda Expressions.
+* lambda expression in hook: Hooks.
+* lambda in debug: Invoking the Debugger.
+* lambda in keymap: Key Lookup.
+* lambda list: Lambda Components.
+* lambda-list (Edebug): Specification List.
+* lambda-list-keywordp: Specification List.
+* last-abbrev: Abbrev Expansion.
+* last-abbrev-location: Abbrev Expansion.
+* last-abbrev-text: Abbrev Expansion.
+* last-command: Command Loop Info.
+* last-command-char: Command Loop Info.
+* last-command-event: Command Loop Info.
+* last-input-char: Peeking and Discarding.
+* last-input-event: Peeking and Discarding.
+* last-kbd-macro: Keyboard Macros.
+* Latin-1 character set (input): Translating Input.
+* lax-plist-get: Working With Lax Plists.
+* lax-plist-member: Working With Lax Plists.
+* lax-plist-put: Working With Lax Plists.
+* lax-plist-remprop: Working With Lax Plists.
+* lax-plists-eq: Working With Lax Plists.
+* lax-plists-equal: Working With Lax Plists.
+* layout policy: Annotation Basics.
+* layout types: Annotation Basics.
+* lazy loading: Dynamic Loading.
+* LDAP: LDAP Support.
+* ldap-close: Opening and Closing a LDAP Connection.
+* ldap-default-base: LDAP Variables.
+* ldap-default-host: LDAP Variables.
+* ldap-default-port: LDAP Variables.
+* ldap-host: The LDAP Lisp Object.
+* ldap-host-parameters-alist: LDAP Variables.
+* ldap-live-p: The LDAP Lisp Object.
+* ldap-open: Opening and Closing a LDAP Connection.
+* ldap-search: The High-Level LDAP API.
+* ldap-search-internal: Searching on a LDAP Server (Low-level).
+* ldapp: The LDAP Lisp Object.
+* left-margin: Margins.
+* left-margin-width: Margin Primitives.
+* left-toolbar: Specifying the Toolbar.
+* left-toolbar-visible-p: Other Toolbar Variables.
+* left-toolbar-width: Other Toolbar Variables.
+* length: Sequence Functions.
+* let: Local Variables.
+* let*: Local Variables.
+* let-specifier: Adding Specifications.
+* lexical binding (Edebug): Edebug Eval.
+* lexical comparison: Text Comparison.
+* library: Loading.
+* library compilation: Compilation Functions.
+* library header comments: Library Headers.
+* line wrapping: Truncation.
+* lines: Text Lines.
+* lines in region: Text Lines.
+* linking files: Changing File Attributes.
+* Lisp debugger: Debugger.
+* Lisp expression motion: List Motion.
+* Lisp history: Lisp History.
+* Lisp library: Loading.
+* Lisp nesting error: Eval.
+* Lisp object: Lisp Data Types.
+* Lisp printer: Output Functions.
+* Lisp reader: Streams Intro.
+* lisp-interaction-mode-map: Standard Keymaps.
+* lisp-mode-abbrev-table: Standard Abbrev Tables.
+* lisp-mode-map: Standard Keymaps.
+* lisp-mode.el: Example Major Modes.
+* list <1>: Lists.
+* list: Building Lists.
+* list elements: List Elements.
+* list form evaluation: Classifying Lists.
+* list in keymap: Key Lookup.
+* list length: Sequence Functions.
+* list motion: List Motion.
+* list structure: Cons Cells.
+* list-buffers: The Buffer List.
+* list-buffers-directory: Buffer File Name.
+* list-fonts: Font Instance Names.
+* list-processes: Process Information.
+* listp: List-related Predicates.
+* lists and cons cells: Cons Cells.
+* lists as sets: Sets And Lists.
+* lists represented as boxes: Lists as Boxes.
+* literal evaluation: Self-Evaluating Forms.
+* lmessage: The Echo Area.
+* ln: Changing File Attributes.
+* load: How Programs Do Loading.
+* load error with require: Named Features.
+* load errors: How Programs Do Loading.
+* load-average: System Environment.
+* load-default-sounds: Beeping.
+* load-history: Unloading.
+* load-ignore-elc-files: How Programs Do Loading.
+* load-in-progress: How Programs Do Loading.
+* load-path: How Programs Do Loading.
+* load-read-function: How Programs Do Loading.
+* load-sound-file: Beeping.
+* load-warn-when-source-newer: How Programs Do Loading.
+* load-warn-when-source-only: How Programs Do Loading.
+* loading: Loading.
+* loading hooks: Hooks for Loading.
+* loadup.el: Building XEmacs.
+* local binding: Local Variables.
+* local keymap: Active Keymaps.
+* local variables: Local Variables.
+* local-abbrev-table: Standard Abbrev Tables.
+* local-key-binding: Functions for Key Lookup.
+* local-set-key: Key Binding Commands.
+* local-unset-key: Key Binding Commands.
+* local-variable-p: Creating Buffer-Local.
+* local-write-file-hooks: Saving Buffers.
+* locale (in a specifier): Specifiers In-Depth.
+* locate-file: How Programs Do Loading.
+* locate-file-clear-hashing: How Programs Do Loading.
+* lock-buffer: File Locks.
+* log: Math Functions.
+* log-message-ignore-labels: The Echo Area.
+* log-message-ignore-regexps: The Echo Area.
+* log-message-max-size: The Echo Area.
+* log-warning-minimum-level: Warnings.
+* log-warning-suppressed-classes: Warnings.
+* log10: Math Functions.
+* logand: Bitwise Operations.
+* logb: Float Basics.
+* logical and: Bitwise Operations.
+* logical exclusive or: Bitwise Operations.
+* logical inclusive or: Bitwise Operations.
+* logical not: Bitwise Operations.
+* logical shift: Bitwise Operations.
+* logior: Bitwise Operations.
+* lognot: Bitwise Operations.
+* logxor: Bitwise Operations.
+* looking-at: Regexp Search.
+* lookup-key: Functions for Key Lookup.
+* loops, infinite: Infinite Loops.
+* lower case: Character Case.
+* lower-frame: Raising and Lowering.
+* lowering a frame: Raising and Lowering.
+* lsh: Bitwise Operations.
+* lwarn: Warnings.
+* M-x: Interactive Call.
+* Maclisp: Lisp History.
+* macro: What Is a Function.
+* macro argument evaluation: Argument Evaluation.
+* macro call: Expansion.
+* macro call evaluation: Macro Forms.
+* macro compilation: Compilation Functions.
+* macro descriptions: A Sample Function Description.
+* macro expansion: Expansion.
+* macroexpand: Expansion.
+* macros: Macros.
+* magic file names: Magic File Names.
+* mail-host-address: System Environment.
+* major mode: Major Modes.
+* major mode hook: Major Mode Conventions.
+* major mode keymap: Active Keymaps.
+* major-mode: Mode Help.
+* make-abbrev-table: Abbrev Tables.
+* make-annotation: Annotation Primitives.
+* make-auto-save-file-name: Auto-Saving.
+* make-backup-file-name: Backup Names.
+* make-backup-files: Making Backups.
+* make-bit-vector: Bit Vector Functions.
+* make-byte-code: Compiled-Function Objects.
+* make-char: MULE Characters.
+* make-char-table: Working With Char Tables.
+* make-charset: Basic Charset Functions.
+* make-coding-system: Basic Coding System Functions.
+* make-composite-char: Composite Characters.
+* make-device: Connecting to a Console or Device.
+* make-directory: Create/Delete Dirs.
+* make-display-table: Display Table Format.
+* make-event: Working With Events.
+* make-extent: Creating and Modifying Extents.
+* make-face: Basic Face Functions.
+* make-file-part: Creating a Partial File.
+* make-font-instance: Font Instances.
+* make-frame: Creating Frames.
+* make-frame-invisible: Visibility of Frames.
+* make-frame-visible: Visibility of Frames.
+* make-glyph: Creating Glyphs.
+* make-glyph-internal: Creating Glyphs.
+* make-hash-table: Introduction to Hash Tables.
+* make-icon-glyph: Creating Glyphs.
+* make-image-instance: Image Instance Functions.
+* make-image-specifier: Image Specifiers.
+* make-indirect-buffer: Indirect Buffers.
+* make-keymap: Creating Keymaps.
+* make-list: Building Lists.
+* make-local-hook: Hooks.
+* make-local-variable: Creating Buffer-Local.
+* make-marker: Creating Markers.
+* make-obsolete: Obsoleteness.
+* make-obsolete-variable: Obsoleteness.
+* make-pointer-glyph: Creating Glyphs.
+* make-range-table: Introduction to Range Tables.
+* make-reverse-direction-charset: Basic Charset Functions.
+* make-sparse-keymap: Creating Keymaps.
+* make-specifier: Creating Specifiers.
+* make-specifier-and-init: Creating Specifiers.
+* make-string: Creating Strings.
+* make-symbol: Creating Symbols.
+* make-symbolic-link: Changing File Attributes.
+* make-syntax-table: Syntax Table Functions.
+* make-temp-name: Unique File Names.
+* make-tooltalk-message: Elisp Interface for Sending Messages.
+* make-tooltalk-pattern: Elisp Interface for Receiving Messages.
+* make-tty-device: Connecting to a Console or Device.
+* make-variable-buffer-local: Creating Buffer-Local.
+* make-vector: Vector Functions.
+* make-weak-list: Weak Lists.
+* make-x-device: Connecting to a Console or Device.
+* makunbound: Void Variables.
+* Manual-page-minibuffer-history: Minibuffer History.
+* map-char-table: Working With Char Tables.
+* map-database: Working With a Database.
+* map-extent-children: Mapping Over Extents.
+* map-extents: Mapping Over Extents.
+* map-frame-hook: Frame Hooks.
+* map-keymap: Scanning Keymaps.
+* map-range-table: Working With Range Tables.
+* map-specifier: Other Specification Functions.
+* map-y-or-n-p: Multiple Queries.
+* mapatoms: Creating Symbols.
+* mapcar: Mapping Functions.
+* mapcar-extents: Mapping Over Extents.
+* mapconcat: Mapping Functions.
+* maphash: Working With Hash Tables.
+* mapping functions: Mapping Functions.
+* margin: Annotation Basics.
+* margin width: Margin Primitives.
+* mark: The Mark.
+* mark excursion: Excursions.
+* mark ring: The Mark.
+* mark, the: The Mark.
+* mark-marker: The Mark.
+* mark-ring: The Mark.
+* mark-ring-max: The Mark.
+* marker argument: Interactive Codes.
+* marker garbage collection: Overview of Markers.
+* marker input stream: Input Streams.
+* marker output stream: Output Streams.
+* marker relocation: Overview of Markers.
+* marker-buffer: Information from Markers.
+* marker-position: Information from Markers.
+* markerp: Predicates on Markers.
+* markers: Markers.
+* markers as numbers: Overview of Markers.
+* markers vs. extents: Overview of Markers.
+* match data: Match Data.
+* match-beginning: Simple Match Data.
+* match-data: Entire Match Data.
+* match-end: Simple Match Data.
+* match-string: Simple Match Data.
+* mathematical functions: Math Functions.
+* max: Comparison of Numbers.
+* max-lisp-eval-depth: Eval.
+* max-specpdl-size: Local Variables.
+* md5: Transformations.
+* MD5 digests: Transformations.
+* member: Sets And Lists.
+* membership in a list: Sets And Lists.
+* memory allocation: Garbage Collection.
+* memory-limit: Garbage Collection.
+* memq: Sets And Lists.
+* menu: Menus.
+* menu accelerators: Menu Accelerators.
+* menu filters: Menu Filters.
+* menu format: Menu Format.
+* menu-accelerator-enabled: Menu Accelerator Functions.
+* menu-accelerator-map: Menu Accelerator Functions.
+* menu-accelerator-modifiers: Menu Accelerator Functions.
+* menu-accelerator-prefix: Menu Accelerator Functions.
+* menu-no-selection-hook: Menubar.
+* menubar: Menubar.
+* menubar format: Menubar Format.
+* menubar-configuration: Menu Format.
+* menubar-pointer-glyph: Mouse Pointer.
+* menubar-show-keybindings: Menubar.
+* message: The Echo Area.
+* meta character printing: Describing Characters.
+* meta-prefix-char: Functions for Key Lookup.
+* min: Comparison of Numbers.
+* minibuffer: Minibuffers.
+* minibuffer history: Minibuffer History.
+* minibuffer input: Recursive Editing.
+* minibuffer window: Cyclic Window Ordering.
+* minibuffer-complete: Completion Commands.
+* minibuffer-complete-and-exit: Completion Commands.
+* minibuffer-complete-word: Completion Commands.
+* minibuffer-completion-confirm: Completion Commands.
+* minibuffer-completion-help: Completion Commands.
+* minibuffer-completion-predicate: Completion Commands.
+* minibuffer-completion-table: Completion Commands.
+* minibuffer-depth: Minibuffer Misc.
+* minibuffer-exit-hook: Minibuffer Misc.
+* minibuffer-frame-plist: Initial Properties.
+* minibuffer-help-form: Minibuffer Misc.
+* minibuffer-history: Minibuffer History.
+* minibuffer-local-completion-map <1>: Completion Commands.
+* minibuffer-local-completion-map: Standard Keymaps.
+* minibuffer-local-isearch-map: Standard Keymaps.
+* minibuffer-local-map <1>: Standard Keymaps.
+* minibuffer-local-map: Text from Minibuffer.
+* minibuffer-local-must-match-map <1>: Completion Commands.
+* minibuffer-local-must-match-map: Standard Keymaps.
+* minibuffer-local-ns-map: Text from Minibuffer.
+* 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>: Active Keymaps.
+* modeline-map: Standard 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>: Character Type.
+* newline: Commands for Insertion.
+* 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.
+* 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 parenthesis character: Syntax Class Table.
+* open-database: Connecting to a Database.
+* open-dribble-file: Recording Input.
+* open-network-stream: Network.
+* open-termscript: Terminal Output.
+* 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.
+* PATH environment variable: Subprocess Creation.
+* path-separator: System Environment.
+* pausing: Waiting.
+* peculiar error: Error Symbols.
+* peeking at input: Peeking and Discarding.
+* percent symbol in modeline: Modeline Data.
+* perform-replace: Search and Replace.
+* performance analysis: Coverage Testing.
+* permanent local variable: Creating Buffer-Local.
+* permission: File Attributes.
+* pipes: Asynchronous Processes.
+* play-sound: Beeping.
+* play-sound-file: Beeping.
+* plist: Property Lists.
+* plist, symbol: Symbol Properties.
+* plist-get: Working With Normal Plists.
+* plist-member: Working With Normal Plists.
+* plist-put: Working With Normal Plists.
+* plist-remprop: Working With Normal Plists.
+* plist-to-alist: Converting Plists To/From Alists.
+* plists-eq <1>: Working With Normal Plists.
+* plists-eq: Other Plists.
+* plists-equal <1>: Working With Normal Plists.
+* plists-equal: Other Plists.
+* point: Point.
+* point excursion: Excursions.
+* point in window: Window Point.
+* point with narrowing: Point.
+* point-marker: Creating Markers.
+* point-max: Point.
+* point-max-marker: Creating Markers.
+* point-min: Point.
+* point-min-marker: Creating Markers.
+* pointer (mouse): Mouse Pointer.
+* pointer-glyph-p: Glyph Types.
+* pointer-image-instance-p: Image Instance Types.
+* pop-global-mark: The Mark.
+* pop-mark: The Mark.
+* pop-to-buffer: Displaying Buffers.
+* pop-up menu: Pop-Up Menus.
+* pop-up-frame-function: Choosing Window.
+* pop-up-frame-plist: Choosing Window.
+* pop-up-frames: Choosing Window.
+* pop-up-windows: Choosing Window.
+* popup-buffer-menu: Pop-Up Menus.
+* popup-dialog-box: Dialog Box Functions.
+* popup-menu: Pop-Up Menus.
+* popup-menu-titles: Pop-Up Menus.
+* popup-menu-up-p: Pop-Up Menus.
+* popup-menubar-menu: Pop-Up Menus.
+* popup-mode-menu: Pop-Up Menus.
+* pos-visible-in-window-p: Window Start.
+* position (in buffer): Positions.
+* position argument: Interactive Codes.
+* position in window: Window Point.
+* position of frame: Size and Position.
+* position of window: Position of Window.
+* positive infinity: Float Basics.
+* posix-looking-at: POSIX Regexps.
+* posix-search-backward: POSIX Regexps.
+* posix-search-forward: POSIX Regexps.
+* posix-string-match: POSIX Regexps.
+* post-command-hook: Command Overview.
+* post-gc-hook: Garbage Collection.
+* pre-abbrev-expand-hook: Abbrev Expansion.
+* pre-command-hook: Command Overview.
+* pre-gc-hook: Garbage Collection.
+* preceding-char: Near Point.
+* precision of formatted numbers: Formatting Strings.
+* predicates: Type Predicates.
+* prefix argument: Prefix Command Arguments.
+* prefix argument unreading: Peeking and Discarding.
+* prefix command: Prefix Keys.
+* prefix key: Prefix Keys.
+* prefix-arg: Prefix Command Arguments.
+* prefix-help-command: Help Functions.
+* prefix-numeric-value: Prefix Command Arguments.
+* preventing backtracking: Specification List.
+* preventing prefix key: Key Lookup.
+* previous complete subexpression: Parsing Expressions.
+* previous-extent: Finding Extents.
+* previous-frame: Finding All Frames.
+* previous-history-element: Minibuffer Misc.
+* previous-matching-history-element: Minibuffer Misc.
+* previous-property-change: Property Search.
+* previous-single-property-change: Property Search.
+* previous-window: Cyclic Window Ordering.
+* primitive: What Is a Function.
+* primitive type: Lisp Data Types.
+* primitive types: Primitive Types.
+* primitive-undo: Undo.
+* prin1: Output Functions.
+* prin1-to-string: Output Functions.
+* princ: Output Functions.
+* print: Output Functions.
+* print example: Output Streams.
+* print name cell: Symbol Components.
+* print-escape-newlines: Output Variables.
+* print-gensym: Output Variables.
+* print-help-return-message: Help Functions.
+* print-length: Output Variables.
+* print-level: Output Variables.
+* print-readably <1>: Output Variables.
+* print-readably: Printing in Edebug.
+* print-string-length: Output Variables.
+* printed representation: Printed Representation.
+* printed representation for characters: Character Type.
+* printing: Streams Intro.
+* printing (Edebug): Printing in Edebug.
+* printing circular structures: Printing in Edebug.
+* printing floating-point numbers: Output Variables.
+* printing limits: Output Variables.
+* printing notation: Printing Notation.
+* printing readably: Output Variables.
+* printing uninterned symbols: Output Variables.
+* priority of an extent: Intro to Extents.
+* process: Processes.
+* process filter: Filter Functions.
+* process input: Input to Processes.
+* process output: Output from Processes.
+* process sentinel: Sentinels.
+* process signals: Signals to Processes.
+* process window size: Process Window Size.
+* process-buffer: Process Buffers.
+* process-command: Process Information.
+* process-connection-type: Asynchronous Processes.
+* process-environment: System Environment.
+* process-event-p: Event Predicates.
+* process-exit-status: Process Information.
+* process-filter: Filter Functions.
+* process-id: Process Information.
+* process-kill-without-query: Deleting Processes.
+* process-kill-without-query-p: Process Information.
+* process-list: Process Information.
+* process-mark: Process Buffers.
+* process-name: Process Information.
+* process-send-eof: Input to Processes.
+* process-send-region: Input to Processes.
+* process-send-string: Input to Processes.
+* process-sentinel: Sentinels.
+* process-status: Process Information.
+* process-tty-name: Process Information.
+* processp: Processes.
+* profile.el: Compilation Tips.
+* profiling: Compilation Tips.
+* prog1: Sequencing.
+* prog2: Sequencing.
+* progn: Sequencing.
+* program arguments: Subprocess Creation.
+* program directories: Subprocess Creation.
+* programmed completion: Programmed Completion.
+* programming types: Programming Types.
+* properties of strings: String Properties.
+* properties of text: Text Properties.
+* property list: Property Lists.
+* property list cell (symbol): Symbol Components.
+* property list, symbol: Symbol Properties.
+* property lists vs association lists: Plists and Alists.
+* property of an extent: Extent Properties.
+* protected forms: Cleanups.
+* provide: Named Features.
+* providing features: Named Features.
+* PTYs: Asynchronous Processes.
+* punctuation character: Syntax Class Table.
+* pure storage: Pure Storage.
+* pure-bytes-used: Pure Storage.
+* purecopy: Pure Storage.
+* purify-flag: Pure Storage.
+* push-mark: The Mark.
+* put: Symbol 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>: Search and Replace.
+* query-replace-map: Standard Keymaps.
+* querying the user: Yes-or-No Queries.
+* question mark in character constant: Character Type.
+* quietly-read-abbrev-file: Abbrev Files.
+* quit-flag: Quitting.
+* quit-process: Signals to Processes.
+* quitting: Quitting.
+* quitting from infinite loop: Infinite Loops.
+* quote: Quoting.
+* quote character: Parsing Expressions.
+* quoted character input: Quoted Character Input.
+* quoted-insert suppression: Changing Key Bindings.
+* quoting: Quoting.
+* quoting characters in printing: Output Functions.
+* quoting using apostrophe: Quoting.
+* raise-frame: Raising and Lowering.
+* raising a frame: Raising and Lowering.
+* random: Random Numbers.
+* random numbers: Random Numbers.
+* range table type: Range Table Type.
+* Range Tables: Range Tables.
+* range-table-p: Range Tables.
+* rassoc: Association Lists.
+* rassq: Association Lists.
+* raw prefix argument: Prefix Command Arguments.
+* raw prefix argument usage: Interactive Codes.
+* re-search-backward: Regexp Search.
+* re-search-forward: Regexp Search.
+* read: Input Functions.
+* read command name: Interactive Call.
+* read syntax: Printed Representation.
+* read syntax for characters: Character Type.
+* read-buffer: High-Level Completion.
+* read-char: Reading One Event.
+* read-command: High-Level Completion.
+* read-expression-history: Minibuffer History.
+* read-expression-map: Standard Keymaps.
+* read-file-name: Reading File Names.
+* read-from-minibuffer: Text from Minibuffer.
+* read-from-string: Input Functions.
+* read-key-sequence: Key Sequence Input.
+* read-minibuffer: Object from Minibuffer.
+* read-no-blanks-input: Text from Minibuffer.
+* read-only buffer: Read Only Buffers.
+* read-only buffers in interactive: Using Interactive.
+* 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-glyph-property: Glyph Properties.
+* remove-hook: Hooks.
+* remove-range-table: Working With Range Tables.
+* remove-specifier: Other Specification Functions.
+* remove-text-properties: Changing Properties.
+* remrassoc: Association Lists.
+* remrassq: Association Lists.
+* rename-auto-save-file: Auto-Saving.
+* rename-buffer: Buffer Names.
+* rename-file: Changing File Attributes.
+* renaming files: Changing File Attributes.
+* repeated loading: Repeated Loading.
+* replace bindings: Changing Key Bindings.
+* replace characters: Substitution.
+* replace-buffer-in-windows: Displaying Buffers.
+* replace-match: Replacing Match.
+* replacement: Search and Replace.
+* repositioning format arguments: Formatting Strings.
+* require: Named Features.
+* require-final-newline: Saving Buffers.
+* requiring features: Named Features.
+* reset-char-table: Working With Char Tables.
+* resize redisplay: Size and Position.
+* rest arguments: Argument List.
+* restriction (in a buffer): Narrowing.
+* resume (cf. no-redraw-on-reenter): Refresh Screen.
+* return: Character Type.
+* return-tooltalk-message: Elisp Interface for Sending Messages.
+* reveal-annotation: Annotation Properties.
+* reverse: Building Lists.
+* reversing a list: Rearrangement.
+* revert-buffer: Reverting.
+* revert-buffer-function: Reverting.
+* revert-buffer-insert-file-contents-function: Reverting.
+* right-margin-width: Margin Primitives.
+* right-toolbar: Specifying the Toolbar.
+* right-toolbar-visible-p: Other Toolbar Variables.
+* right-toolbar-width: Other Toolbar Variables.
+* rm: Changing File Attributes.
+* round: Numeric Conversions.
+* rounding in conversions: Numeric Conversions.
+* rounding without conversion: Rounding Operations.
+* rplaca: Modifying Lists.
+* rplacd: Modifying Lists.
+* run time stack: Internals of Debugger.
+* run-emacs-from-temacs: Building XEmacs.
+* run-hooks: Hooks.
+* runnable temacs: Building XEmacs.
+* same-window-buffer-names: Choosing Window.
+* same-window-regexps: Choosing Window.
+* save-abbrevs: Abbrev Files.
+* save-buffer: Saving Buffers.
+* save-current-buffer: Excursions.
+* save-excursion: Excursions.
+* save-excursion (Edebug): Edebug Display Update.
+* save-match-data: Saving Match Data.
+* save-restriction: Narrowing.
+* save-selected-frame: Input Focus.
+* save-selected-window <1>: Excursions.
+* save-selected-window: Selecting Windows.
+* save-some-buffers: Saving Buffers.
+* save-window-excursion: Window Configurations.
+* saving text properties: Saving Properties.
+* saving window information: Window Configurations.
+* scan-lists: Parsing Expressions.
+* scan-sexps: Parsing Expressions.
+* scope: Variable Scoping.
+* screen layout: Window Configuration Type.
+* scroll-conservatively: Vertical Scrolling.
+* scroll-down: Vertical Scrolling.
+* scroll-left: Horizontal Scrolling.
+* scroll-other-window: Vertical Scrolling.
+* scroll-right: Horizontal Scrolling.
+* scroll-step: Vertical Scrolling.
+* scroll-up: Vertical Scrolling.
+* scrollbar-pointer-glyph: Mouse Pointer.
+* scrollbars: Scrollbars.
+* scrolling vertically: Vertical Scrolling.
+* search-backward: String Search.
+* search-failed: String Search.
+* search-forward: String Search.
+* searching: Searching and Matching.
+* searching and case: Searching and Case.
+* searching for regexp: Regexp Search.
+* second: List Elements.
+* select-console: The Selected Console and Device.
+* select-device: The Selected Console and Device.
+* select-frame: Input Focus.
+* select-frame-hook: Frame Hooks.
+* select-window: Selecting Windows.
+* selected frame: Input Focus.
+* selected window: Basic Windows.
+* selected-console: The Selected Console and Device.
+* selected-device: The Selected Console and Device.
+* selected-frame: Input Focus.
+* selected-window: Selecting Windows.
+* selecting a buffer: Current Buffer.
+* selecting windows: Selecting Windows.
+* selection (for X windows): X Selections.
+* selection-pointer-glyph: Mouse Pointer.
+* selective display: Selective Display.
+* selective-display: Selective Display.
+* selective-display-ellipses: Selective Display.
+* self-evaluating form: Self-Evaluating Forms.
+* self-insert-and-exit: Minibuffer Misc.
+* self-insert-command: Commands for Insertion.
+* self-insert-command override: Changing Key Bindings.
+* self-insert-command, minor modes: Keymaps and Minor Modes.
+* self-insertion: Commands for Insertion.
+* send-string-to-terminal: Terminal Output.
+* send-tooltalk-message: Elisp Interface for Sending Messages.
+* sending signals: Signals to Processes.
+* sending ToolTalk messages: Sending Messages.
+* sentence-end: Standard Regexps.
+* sentinel: Sentinels.
+* sequence: Sequences Arrays Vectors.
+* sequence length: Sequence Functions.
+* sequencep: Sequence Functions.
+* set: Setting Variables.
+* set-annotation-action: Annotation Properties.
+* set-annotation-data: Annotation Properties.
+* set-annotation-down-glyph: Annotation Properties.
+* set-annotation-face: Annotation Properties.
+* set-annotation-glyph: Annotation Properties.
+* set-annotation-layout: Annotation Properties.
+* set-annotation-menu: Annotation Properties.
+* set-auto-mode: Auto Major Mode.
+* set-buffer: Current Buffer.
+* set-buffer-auto-saved: Auto-Saving.
+* set-buffer-major-mode: Auto Major Mode.
+* set-buffer-menubar: Menubar.
+* set-buffer-modified-p: Buffer Modification.
+* set-case-syntax: Case Tables.
+* set-case-syntax-delims: Case Tables.
+* set-case-syntax-pair: Case Tables.
+* set-case-table: Case Tables.
+* set-category-table: Category Tables.
+* set-charset-ccl-program: Charset Property Functions.
+* set-coding-category-system: Detection of Textual Encoding.
+* set-coding-priority-list: Detection of Textual Encoding.
+* set-console-type-image-conversion-list: Image Instantiator Conversion.
+* set-default: Default Value.
+* set-default-file-modes: Changing File Attributes.
+* set-default-toolbar-position: Specifying the Toolbar.
+* set-device-baud-rate <1>: Terminal Output.
+* set-device-baud-rate: Console and Device I/O.
+* set-extent-begin-glyph: Extent Properties.
+* set-extent-begin-glyph-layout: Extent Properties.
+* set-extent-end-glyph: Extent Properties.
+* set-extent-end-glyph-layout: Extent Properties.
+* set-extent-endpoints: Extent Endpoints.
+* set-extent-face: Extent Properties.
+* set-extent-initial-redisplay-function: Extent Properties.
+* set-extent-keymap: Extent Properties.
+* set-extent-mouse-face: Extent Properties.
+* set-extent-parent: Extent Parents.
+* set-extent-priority: Extent Properties.
+* set-extent-properties: Extent Properties.
+* set-extent-property: Extent Properties.
+* set-face-background: Face Convenience Functions.
+* set-face-background-pixmap: Face Convenience Functions.
+* set-face-font: Face Convenience Functions.
+* set-face-foreground: Face Convenience Functions.
+* set-face-property: Face Properties.
+* set-face-underline-p: Face Convenience Functions.
+* set-file-modes: Changing File Attributes.
+* set-frame-configuration: Frame Configurations.
+* set-frame-pointer: Mouse Pointer.
+* set-frame-position: Size and Position.
+* set-frame-properties: Property Access.
+* set-frame-property: Property Access.
+* set-frame-size: Size and Position.
+* set-glyph-baseline: Glyph Convenience Functions.
+* set-glyph-contrib-p: Glyph Convenience Functions.
+* set-glyph-face: Glyph Convenience Functions.
+* set-glyph-image: Glyph Convenience Functions.
+* set-glyph-property: Glyph Properties.
+* set-input-mode: Input Modes.
+* set-keymap-default-binding: Inheritance and Keymaps.
+* set-keymap-name: Creating Keymaps.
+* set-keymap-parents: Inheritance and Keymaps.
+* set-keymap-prompt: Other Keymap Functions.
+* set-left-margin: Margins.
+* set-mark: The Mark.
+* set-marker: Changing Markers.
+* set-match-data: Entire Match Data.
+* set-menubar: Menubar.
+* set-menubar-dirty-flag: Menubar.
+* set-process-buffer: Process Buffers.
+* set-process-filter: Filter Functions.
+* set-process-sentinel: Sentinels.
+* set-process-window-size: Process Window Size.
+* set-recent-keys-ring-size: Recording Input.
+* set-register: Registers.
+* set-right-margin: Margins.
+* set-specifier: Adding Specifications.
+* set-standard-case-table: Case Tables.
+* set-syntax-table: Syntax Table Functions.
+* set-text-properties: Changing Properties.
+* set-tooltalk-message-attribute: Elisp Interface for Sending Messages.
+* set-visited-file-modtime: Modification Time.
+* set-visited-file-name: Buffer File Name.
+* set-weak-list-list: Weak Lists.
+* set-window-buffer: Buffers and Windows.
+* set-window-buffer-dedicated: Choosing Window.
+* set-window-configuration: Window Configurations.
+* set-window-dedicated-p: Choosing Window.
+* set-window-hscroll: Horizontal Scrolling.
+* set-window-point: Window Point.
+* set-window-start: Window Start.
+* setcar: Setcar.
+* setcdr: Setcdr.
+* setenv: System Environment.
+* setplist: Symbol 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-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 quote: Syntax Class Table.
+* 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.
+* 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 constituent: Syntax Class Table.
+* 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: Symbol Plists.
+* symbol-value: Accessing Variables.
+* symbolp: Symbols.
+* 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>: Active Keymaps.
+* toolbar-map: Standard Keymaps.
+* toolbar-pointer-glyph: Mouse Pointer.
+* toolbar-specifier-p <1>: Specifier Types.
+* toolbar-specifier-p: Specifying the Toolbar.
+* ToolTalk: ToolTalk Support.
+* ToolTalk message: Sending Messages.
+* ToolTalk pattern: Receiving Messages.
+* top-level: Recursive Editing.
+* top-level form: Loading.
+* top-toolbar: Specifying the Toolbar.
+* top-toolbar-height: Other Toolbar Variables.
+* top-toolbar-visible-p: Other Toolbar Variables.
+* tq-close: Transaction Queues.
+* tq-create: Transaction Queues.
+* tq-enqueue: Transaction Queues.
+* tracing: Tracing.
+* transaction queue: Transaction Queues.
+* transcendental functions: Math Functions.
+* translate-region: Substitution.
+* translating input events: Translating Input.
+* transpose-regions: Transposition.
+* trim-versions-without-asking: Numbered Backups.
+* 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 Tag Functions.
+* valid-specifier-tag-p: Specifier Validation Functions.
+* valid-specifier-tag-set-p: Specifier Tag Functions.
+* valid-specifier-type-p: Specifier Validation Functions.
+* value cell: Symbol Components.
+* value of expression: Evaluation.
+* values: Eval.
+* variable: Variables.
+* variable aliases: Variable Aliases.
+* variable definition: Defining Variables.
+* variable descriptions: A Sample Variable Description.
+* variable limit error: Local Variables.
+* variable-alias: Variable Aliases.
+* variable-documentation: Documentation Basics.
+* variable-obsoleteness-doc: Obsoleteness.
+* variables, buffer-local: Buffer-Local Variables.
+* variables, indirect: Variable Aliases.
+* vc-mode: Modeline Variables.
+* vconcat: Vector Functions.
+* vector <1>: Vector Functions.
+* vector: Vectors.
+* vector evaluation: Self-Evaluating Forms.
+* vector length: Sequence Functions.
+* vectorp: Vector Functions.
+* verify-visited-file-modtime: Modification Time.
+* version number (in file name): File Name Components.
+* version-control: Numbered Backups.
+* vertical scrolling: Vertical Scrolling.
+* vertical tab: Character Type.
+* vertical-motion: Screen Lines.
+* vertical-motion-pixels: Screen Lines.
+* view-file: Visiting Functions.
+* view-mode-map: Standard Keymaps.
+* view-register: Registers.
+* visible frame: Visibility of Frames.
+* visible-bell: Beeping.
+* visible-frame-list: Finding All Frames.
+* visited file: Buffer File Name.
+* visited file mode: Auto Major Mode.
+* visited-file-modtime: Modification Time.
+* visiting files: Visiting Files.
+* void function: Function Indirection.
+* void function cell: Function Cells.
+* void variable: Void Variables.
+* void-function: Function Cells.
+* void-variable: Void Variables.
+* waiting: Waiting.
+* waiting for command key input: Peeking and Discarding.
+* waiting-for-user-input-p: Sentinels.
+* wakeup: Subprocess Creation.
+* walk-windows: Cyclic Window Ordering.
+* weak hash table: Weak Hash Tables.
+* weak list: Weak Lists.
+* weak list type: Weak List Type.
+* weak-list-list: Weak Lists.
+* weak-list-p: Weak Lists.
+* weak-list-type: Weak Lists.
+* where-is-internal: Scanning Keymaps.
+* while: Iteration.
+* whitespace: Character Type.
+* whitespace character: Syntax Class Table.
+* widen: Narrowing.
+* widening: Narrowing.
+* window: Basic Windows.
+* window configuration (Edebug): Edebug Display Update.
+* window configurations: Window Configurations.
+* window excursions: Excursions.
+* window ordering, cyclic: Cyclic Window Ordering.
+* window point: Window Point.
+* window position <1>: Window Point.
+* window position: Position of Window.
+* 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 constituent: Syntax Class Table.
+* word search: String Search.
+* word-search-backward: String Search.
+* word-search-forward: String Search.
+* words-include-escapes: Word Motion.
+* 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.
+
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: String Basics, Next: Predicates for Strings, Up: Strings and Characters
+
+String and Character Basics
+===========================
+
+ Strings in XEmacs Lisp are arrays that contain an ordered sequence of
+characters. Characters are their own primitive object type in XEmacs
+20. However, in XEmacs 19, characters are represented in XEmacs Lisp as
+integers; whether an integer was intended as a character or not is
+determined only by how it is used. *Note Character Type::.
+
+ The length of a string (like any array) is fixed and independent of
+the string contents, and cannot be altered. Strings in Lisp are *not*
+terminated by a distinguished character code. (By contrast, strings in
+C are terminated by a character with ASCII code 0.) This means that
+any character, including the null character (ASCII code 0), is a valid
+element of a string.
+
+ Since strings are considered arrays, you can operate on them with the
+general array functions. (*Note Sequences Arrays Vectors::.) For
+example, you can access or change individual characters in a string
+using the functions `aref' and `aset' (*note Array Functions::.).
+
+ Strings use an efficient representation for storing the characters
+in them, and thus take up much less memory than a vector of the same
+length.
+
+ Sometimes you will see strings used to hold key sequences. This
+exists for backward compatibility with Emacs 18, but should *not* be
+used in new code, since many key chords can't be represented at all and
+others (in particular meta key chords) are confused with accented
+characters.
+
+ Strings are useful for holding regular expressions. You can also
+match regular expressions against strings (*note Regexp Search::.). The
+functions `match-string' (*note Simple Match Data::.) and
+`replace-match' (*note Replacing Match::.) are useful for decomposing
+and modifying strings based on regular expression matching.
+
+ Like a buffer, a string can contain extents in it. These extents are
+created when a function such as `buffer-substring' is called on a
+region with duplicable extents in it. When the string is inserted into
+a buffer, the extents are inserted along with it. *Note Duplicable
+Extents::.
+
+ *Note Text::, for information about functions that display strings or
+copy them into buffers. *Note Character Type::, and *Note String
+Type::, for information about the syntax of characters and strings.
+
+\1f
+File: lispref.info, Node: Predicates for Strings, Next: Creating Strings, Prev: String Basics, Up: Strings and Characters
+
+The Predicates for Strings
+==========================
+
+ For more information about general sequence and array predicates,
+see *Note Sequences Arrays Vectors::, and *Note Arrays::.
+
+ - Function: stringp OBJECT
+ This function returns `t' if OBJECT is a string, `nil' otherwise.
+
+ - Function: char-or-string-p OBJECT
+ This function returns `t' if OBJECT is a string or a character,
+ `nil' otherwise.
+
+ In XEmacs addition, this function also returns `t' if OBJECT is an
+ integer that can be represented as a character. This is because
+ of compatibility with previous XEmacs and should not be depended
+ on.
+
+\1f
+File: lispref.info, Node: Creating Strings, Next: Predicates for Characters, Prev: Predicates for Strings, Up: Strings and Characters
+
+Creating Strings
+================
+
+ The following functions create strings, either from scratch, or by
+putting strings together, or by taking them apart.
+
+ - Function: string &rest CHARACTERS
+ This function returns a new string made up of CHARACTERS.
+
+ (string ?X ?E ?m ?a ?c ?s)
+ => "XEmacs"
+ (string)
+ => ""
+
+ Analogous functions operating on other data types include `list',
+ `cons' (*note Building Lists::.), `vector' (*note Vectors::.) and
+ `bit-vector' (*note Bit Vectors::.). This function has not been
+ available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
+
+ - Function: make-string COUNT CHARACTER
+ This function returns a string made up of COUNT repetitions of
+ CHARACTER. If COUNT is negative, an error is signaled.
+
+ (make-string 5 ?x)
+ => "xxxxx"
+ (make-string 0 ?x)
+ => ""
+
+ Other functions to compare with this one include `char-to-string'
+ (*note String Conversion::.), `make-vector' (*note Vectors::.), and
+ `make-list' (*note Building Lists::.).
+
+ - Function: substring STRING START &optional END
+ This function returns a new string which consists of those
+ characters from STRING in the range from (and including) the
+ character at the index START up to (but excluding) the character
+ at the index END. The first character is at index zero.
+
+ (substring "abcdefg" 0 3)
+ => "abc"
+
+ Here the index for `a' is 0, the index for `b' is 1, and the index
+ for `c' is 2. Thus, three letters, `abc', are copied from the
+ string `"abcdefg"'. The index 3 marks the character position up
+ to which the substring is copied. The character whose index is 3
+ is actually the fourth character in the string.
+
+ A negative number counts from the end of the string, so that -1
+ signifies the index of the last character of the string. For
+ example:
+
+ (substring "abcdefg" -3 -1)
+ => "ef"
+
+ In this example, the index for `e' is -3, the index for `f' is -2,
+ and the index for `g' is -1. Therefore, `e' and `f' are included,
+ and `g' is excluded.
+
+ When `nil' is used as an index, it stands for the length of the
+ string. Thus,
+
+ (substring "abcdefg" -3 nil)
+ => "efg"
+
+ Omitting the argument END is equivalent to specifying `nil'. It
+ follows that `(substring STRING 0)' returns a copy of all of
+ STRING.
+
+ (substring "abcdefg" 0)
+ => "abcdefg"
+
+ But we recommend `copy-sequence' for this purpose (*note Sequence
+ Functions::.).
+
+ If the characters copied from STRING have duplicable extents or
+ text properties, those are copied into the new string also. *Note
+ Duplicable Extents::.
+
+ A `wrong-type-argument' error is signaled if either START or END
+ is not an integer or `nil'. An `args-out-of-range' error is
+ signaled if START indicates a character following END, or if
+ either integer is out of range for STRING.
+
+ Contrast this function with `buffer-substring' (*note Buffer
+ Contents::.), which returns a string containing a portion of the
+ text in the current buffer. The beginning of a string is at index
+ 0, but the beginning of a buffer is at index 1.
+
+ - Function: concat &rest SEQUENCES
+ This function returns a new string consisting of the characters in
+ the arguments passed to it (along with their text properties, if
+ any). The arguments may be strings, lists of numbers, or vectors
+ of numbers; they are not themselves changed. If `concat' receives
+ no arguments, it returns an empty string.
+
+ (concat "abc" "-def")
+ => "abc-def"
+ (concat "abc" (list 120 (+ 256 121)) [122])
+ => "abcxyz"
+ ;; `nil' is an empty sequence.
+ (concat "abc" nil "-def")
+ => "abc-def"
+ (concat "The " "quick brown " "fox.")
+ => "The quick brown fox."
+ (concat)
+ => ""
+
+ The second example above shows how characters stored in strings are
+ taken modulo 256. In other words, each character in the string is
+ stored in one byte.
+
+ The `concat' function always constructs a new string that is not
+ `eq' to any existing string.
+
+ When an argument is an integer (not a sequence of integers), it is
+ converted to a string of digits making up the decimal printed
+ representation of the integer. *Don't use this feature; we plan
+ to eliminate it. If you already use this feature, change your
+ programs now!* The proper way to convert an integer to a decimal
+ number in this way is with `format' (*note Formatting Strings::.)
+ or `number-to-string' (*note String Conversion::.).
+
+ (concat 137)
+ => "137"
+ (concat 54 321)
+ => "54321"
+
+ For information about other concatenation functions, see the
+ description of `mapconcat' in *Note Mapping Functions::, `vconcat'
+ in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
+ in *Note Building Lists::.
+
+\1f
+File: lispref.info, Node: Predicates for Characters, Next: Character Codes, Prev: Creating Strings, Up: Strings and Characters
+
+The Predicates for Characters
+=============================
+
+ - Function: characterp OBJECT
+ This function returns `t' if OBJECT is a character.
+
+ Some functions that work on integers (e.g. the comparison functions
+ <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
+ accept characters and implicitly convert them into integers. In
+ general, functions that work on characters also accept char-ints
+ and implicitly convert them into characters. WARNING: Neither of
+ these behaviors is very desirable, and they are maintained for
+ backward compatibility with old E-Lisp programs that confounded
+ characters and integers willy-nilly. These behaviors may change
+ in the future; therefore, do not rely on them. Instead, convert
+ the characters explicitly using `char-int'.
+
+ - Function: integer-or-char-p OBJECT
+ This function returns `t' if OBJECT is an integer or character.
+
+\1f
+File: lispref.info, Node: Character Codes, Next: Text Comparison, Prev: Predicates for Characters, Up: Strings and Characters
+
+Character Codes
+===============
+
+ - Function: char-int CH
+ This function converts a character into an equivalent integer.
+ The resulting integer will always be non-negative. The integers in
+ the range 0 - 255 map to characters as follows:
+
+ 0 - 31
+ Control set 0
+
+ 32 - 127
+ ASCII
+
+ 128 - 159
+ Control set 1
+
+ 160 - 255
+ Right half of ISO-8859-1
+
+ If support for MULE does not exist, these are the only valid
+ character values. When MULE support exists, the values assigned to
+ other characters may vary depending on the particular version of
+ XEmacs, the order in which character sets were loaded, etc., and
+ you should not depend on them.
+
+ - Function: int-char INTEGER
+ This function converts an integer into the equivalent character.
+ Not all integers correspond to valid characters; use `char-int-p'
+ to determine whether this is the case. If the integer cannot be
+ converted, `nil' is returned.
+
+ - Function: char-int-p OBJECT
+ This function returns `t' if OBJECT is an integer that can be
+ converted into a character.
+
+ - Function: char-or-char-int-p OBJECT
+ This function returns `t' if OBJECT is a character or an integer
+ that can be converted into one.
+
+\1f
+File: lispref.info, Node: Text Comparison, Next: String Conversion, Prev: Character Codes, Up: Strings and Characters
+
+Comparison of Characters and Strings
+====================================
+
+ - Function: char-equal CHARACTER1 CHARACTER2
+ This function returns `t' if the arguments represent the same
+ character, `nil' otherwise. This function ignores differences in
+ case if `case-fold-search' is non-`nil'.
+
+ (char-equal ?x ?x)
+ => t
+ (let ((case-fold-search t))
+ (char-equal ?x ?X))
+ => t
+ (let ((case-fold-search nil))
+ (char-equal ?x ?X))
+ => nil
+
+ - Function: char= CHARACTER1 CHARACTER2
+ This function returns `t' if the arguments represent the same
+ character, `nil' otherwise. Case is significant.
+
+ (char= ?x ?x)
+ => t
+ (char= ?x ?X)
+ => nil
+ (let ((case-fold-search t))
+ (char-equal ?x ?X))
+ => nil
+ (let ((case-fold-search nil))
+ (char-equal ?x ?X))
+ => nil
+
+ - Function: string= STRING1 STRING2
+ This function returns `t' if the characters of the two strings
+ match exactly; case is significant.
+
+ (string= "abc" "abc")
+ => t
+ (string= "abc" "ABC")
+ => nil
+ (string= "ab" "ABC")
+ => nil
+
+
+ - Function: string-equal STRING1 STRING2
+ `string-equal' is another name for `string='.
+
+ - Function: string< STRING1 STRING2
+ This function compares two strings a character at a time. First it
+ scans both the strings at once to find the first pair of
+ corresponding characters that do not match. If the lesser
+ character of those two is the character from STRING1, then STRING1
+ is less, and this function returns `t'. If the lesser character
+ is the one from STRING2, then STRING1 is greater, and this
+ function returns `nil'. If the two strings match entirely, the
+ value is `nil'.
+
+ Pairs of characters are compared by their ASCII codes. Keep in
+ mind that lower case letters have higher numeric values in the
+ ASCII character set than their upper case counterparts; numbers and
+ many punctuation characters have a lower numeric value than upper
+ case letters.
+
+ (string< "abc" "abd")
+ => t
+ (string< "abd" "abc")
+ => nil
+ (string< "123" "abc")
+ => t
+
+ When the strings have different lengths, and they match up to the
+ length of STRING1, then the result is `t'. If they match up to
+ the length of STRING2, the result is `nil'. A string of no
+ characters is less than any other string.
+
+ (string< "" "abc")
+ => t
+ (string< "ab" "abc")
+ => t
+ (string< "abc" "")
+ => nil
+ (string< "abc" "ab")
+ => nil
+ (string< "" "")
+ => nil
+
+ - Function: string-lessp STRING1 STRING2
+ `string-lessp' is another name for `string<'.
+
+ See also `compare-buffer-substrings' in *Note Comparing Text::, for
+a way to compare text in buffers. The function `string-match', which
+matches a regular expression against a string, can be used for a kind
+of string comparison; see *Note Regexp Search::.
+
+\1f
+File: lispref.info, Node: String Conversion, Next: Modifying Strings, Prev: Text Comparison, Up: Strings and Characters
+
+Conversion of Characters and Strings
+====================================
+
+ This section describes functions for conversions between characters,
+strings and integers. `format' and `prin1-to-string' (*note Output
+Functions::.) can also convert Lisp objects into strings.
+`read-from-string' (*note Input Functions::.) can "convert" a string
+representation of a Lisp object into an object.
+
+ *Note Documentation::, for functions that produce textual
+descriptions of text characters and general input events
+(`single-key-description' and `text-char-description'). These
+functions are used primarily for making help messages.
+
+ - Function: char-to-string CHARACTER
+ This function returns a new string with a length of one character.
+ The value of CHARACTER, modulo 256, is used to initialize the
+ element of the string.
+
+ This function is similar to `make-string' with an integer argument
+ of 1. (*Note Creating Strings::.) This conversion can also be
+ done with `format' using the `%c' format specification. (*Note
+ Formatting Strings::.)
+
+ (char-to-string ?x)
+ => "x"
+ (char-to-string (+ 256 ?x))
+ => "x"
+ (make-string 1 ?x)
+ => "x"
+
+ - Function: string-to-char STRING
+ This function returns the first character in STRING. If the
+ string is empty, the function returns 0. (Under XEmacs 19, the
+ value is also 0 when the first character of STRING is the null
+ character, ASCII code 0.)
+
+ (string-to-char "ABC")
+ => ?A ;; Under XEmacs 20.
+ => 65 ;; Under XEmacs 19.
+ (string-to-char "xyz")
+ => ?x ;; Under XEmacs 20.
+ => 120 ;; Under XEmacs 19.
+ (string-to-char "")
+ => 0
+ (string-to-char "\000")
+ => ?\^ ;; Under XEmacs 20.
+ => 0 ;; Under XEmacs 20.
+
+ This function may be eliminated in the future if it does not seem
+ useful enough to retain.
+
+ - Function: number-to-string NUMBER
+ This function returns a string consisting of the printed
+ representation of NUMBER, which may be an integer or a floating
+ point number. The value starts with a sign if the argument is
+ negative.
+
+ (number-to-string 256)
+ => "256"
+ (number-to-string -23)
+ => "-23"
+ (number-to-string -23.5)
+ => "-23.5"
+
+ `int-to-string' is a semi-obsolete alias for this function.
+
+ See also the function `format' in *Note Formatting Strings::.
+
+ - Function: string-to-number STRING &optional BASE
+ This function returns the numeric value of the characters in
+ STRING, read in BASE. It skips spaces and tabs at the beginning
+ of STRING, then reads as much of STRING as it can interpret as a
+ number. (On some systems it ignores other whitespace at the
+ beginning, not just spaces and tabs.) If the first character after
+ the ignored whitespace is not a digit or a minus sign, this
+ function returns 0.
+
+ If BASE is not specified, it defaults to ten. With BASE other
+ than ten, only integers can be read.
+
+ (string-to-number "256")
+ => 256
+ (string-to-number "25 is a perfect square.")
+ => 25
+ (string-to-number "X256")
+ => 0
+ (string-to-number "-4.5")
+ => -4.5
+ (string-to-number "ffff" 16)
+ => 65535
+
+ `string-to-int' is an obsolete alias for this function.
+
+\1f
+File: lispref.info, Node: Modifying Strings, Next: String Properties, Prev: String Conversion, Up: Strings and Characters
+
+Modifying Strings
+=================
+
+ You can modify a string using the general array-modifying primitives.
+*Note Arrays::. The function `aset' modifies a single character; the
+function `fillarray' sets all characters in the string to a specified
+character.
+
+ Each string has a tick counter that starts out at zero (when the
+string is created) and is incremented each time a change is made to that
+string.
+
+ - Function: string-modified-tick STRING
+ This function returns the tick counter for `string'.
+
+\1f
+File: lispref.info, Node: String Properties, Next: Formatting Strings, Prev: Modifying Strings, Up: Strings and Characters
+
+String Properties
+=================
+
+ Similar to symbols, extents, faces, and glyphs, you can attach
+additional information to strings in the form of "string properties".
+These differ from text properties, which are logically attached to
+particular characters in the string.
+
+ To attach a property to a string, use `put'. To retrieve a property
+from a string, use `get'. You can also use `remprop' to remove a
+property from a string and `object-props' to retrieve a list of all the
+properties in a string.
+
+\1f
+File: lispref.info, Node: Formatting Strings, Next: Character Case, Prev: String Properties, Up: Strings and Characters
+
+Formatting Strings
+==================
+
+ "Formatting" means constructing a string by substitution of computed
+values at various places in a constant string. This string controls
+how the other values are printed as well as where they appear; it is
+called a "format string".
+
+ Formatting is often useful for computing messages to be displayed.
+In fact, the functions `message' and `error' provide the same
+formatting feature described here; they differ from `format' only in
+how they use the result of formatting.
+
+ - Function: format STRING &rest OBJECTS
+ This function returns a new string that is made by copying STRING
+ and then replacing any format specification in the copy with
+ encodings of the corresponding OBJECTS. The arguments OBJECTS are
+ the computed values to be formatted.
+
+ A format specification is a sequence of characters beginning with a
+`%'. Thus, if there is a `%d' in STRING, the `format' function
+replaces it with the printed representation of one of the values to be
+formatted (one of the arguments OBJECTS). For example:
+
+ (format "The value of fill-column is %d." fill-column)
+ => "The value of fill-column is 72."
+
+ If STRING contains more than one format specification, the format
+specifications correspond with successive values from OBJECTS. Thus,
+the first format specification in STRING uses the first such value, the
+second format specification uses the second such value, and so on. Any
+extra format specifications (those for which there are no corresponding
+values) cause unpredictable behavior. Any extra values to be formatted
+are ignored.
+
+ Certain format specifications require values of particular types.
+However, no error is signaled if the value actually supplied fails to
+have the expected type. Instead, the output is likely to be
+meaningless.
+
+ Here is a table of valid format specifications:
+
+`%s'
+ Replace the specification with the printed representation of the
+ object, made without quoting. Thus, strings are represented by
+ their contents alone, with no `"' characters, and symbols appear
+ without `\' characters. This is equivalent to printing the object
+ with `princ'.
+
+ If there is no corresponding object, the empty string is used.
+
+`%S'
+ Replace the specification with the printed representation of the
+ object, made with quoting. Thus, strings are enclosed in `"'
+ characters, and `\' characters appear where necessary before
+ special characters. This is equivalent to printing the object
+ with `prin1'.
+
+ If there is no corresponding object, the empty string is used.
+
+`%o'
+ Replace the specification with the base-eight representation of an
+ integer.
+
+`%d'
+`%i'
+ Replace the specification with the base-ten representation of an
+ integer.
+
+`%x'
+ Replace the specification with the base-sixteen representation of
+ an integer, using lowercase letters.
+
+`%X'
+ Replace the specification with the base-sixteen representation of
+ an integer, using uppercase letters.
+
+`%c'
+ Replace the specification with the character which is the value
+ given.
+
+`%e'
+ Replace the specification with the exponential notation for a
+ floating point number (e.g. `7.85200e+03').
+
+`%f'
+ Replace the specification with the decimal-point notation for a
+ floating point number.
+
+`%g'
+ Replace the specification with notation for a floating point
+ number, using a "pretty format". Either exponential notation or
+ decimal-point notation will be used (usually whichever is
+ shorter), and trailing zeroes are removed from the fractional part.
+
+`%%'
+ A single `%' is placed in the string. This format specification is
+ unusual in that it does not use a value. For example, `(format "%%
+ %d" 30)' returns `"% 30"'.
+
+ Any other format character results in an `Invalid format operation'
+error.
+
+ Here are several examples:
+
+ (format "The name of this buffer is %s." (buffer-name))
+ => "The name of this buffer is strings.texi."
+
+ (format "The buffer object prints as %s." (current-buffer))
+ => "The buffer object prints as #<buffer strings.texi>."
+
+ (format "The octal value of %d is %o,
+ and the hex value is %x." 18 18 18)
+ => "The octal value of 18 is 22,
+ and the hex value is 12."
+
+ There are many additional flags and specifications that can occur
+between the `%' and the format character, in the following order:
+
+ 1. An optional repositioning specification, which is a positive
+ integer followed by a `$'.
+
+ 2. Zero or more of the optional flag characters `-', `+', ` ', `0',
+ and `#'.
+
+ 3. An asterisk (`*', meaning that the field width is now assumed to
+ have been specified as an argument.
+
+ 4. An optional minimum field width.
+
+ 5. An optional precision, preceded by a `.' character.
+
+ A "repositioning" specification changes which argument to `format'
+is used by the current and all following format specifications.
+Normally the first specification uses the first argument, the second
+specification uses the second argument, etc. Using a repositioning
+specification, you can change this. By placing a number N followed by
+a `$' between the `%' and the format character, you cause the
+specification to use the Nth argument. The next specification will use
+the N+1'th argument, etc.
+
+ For example:
+
+ (format "Can't find file `%s' in directory `%s'."
+ "ignatius.c" "loyola/")
+ => "Can't find file `ignatius.c' in directory `loyola/'."
+
+ (format "In directory `%2$s', the file `%1$s' was not found."
+ "ignatius.c" "loyola/")
+ => "In directory `loyola/', the file `ignatius.c' was not found."
+
+ (format
+ "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
+ 37 12)
+ => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
+
+ As you can see, this lets you reprocess arguments more than once or
+reword a format specification (thereby moving the arguments around)
+without having to actually reorder the arguments. This is especially
+useful in translating messages from one language to another: Different
+languages use different word orders, and this sometimes entails changing
+the order of the arguments. By using repositioning specifications,
+this can be accomplished without having to embed knowledge of particular
+languages into the location in the program's code where the message is
+displayed.
+
+ All the specification characters allow an optional numeric prefix
+between the `%' and the character, and following any repositioning
+specification or flag. The optional numeric prefix defines the minimum
+width for the object. If the printed representation of the object
+contains fewer characters than this, then it is padded. The padding is
+normally on the left, but will be on the right if the `-' flag
+character is given. The padding character is normally a space, but if
+the `0' flag character is given, zeros are used for padding.
+
+ (format "%06d is padded on the left with zeros" 123)
+ => "000123 is padded on the left with zeros"
+
+ (format "%-6d is padded on the right" 123)
+ => "123 is padded on the right"
+
+ `format' never truncates an object's printed representation, no
+matter what width you specify. Thus, you can use a numeric prefix to
+specify a minimum spacing between columns with no risk of losing
+information.
+
+ In the following three examples, `%7s' specifies a minimum width of
+7. In the first case, the string inserted in place of `%7s' has only 3
+letters, so 4 blank spaces are inserted for padding. In the second
+case, the string `"specification"' is 13 letters wide but is not
+truncated. In the third case, the padding is on the right.
+
+ (format "The word `%7s' actually has %d letters in it."
+ "foo" (length "foo"))
+ => "The word ` foo' actually has 3 letters in it."
+
+ (format "The word `%7s' actually has %d letters in it."
+ "specification" (length "specification"))
+ => "The word `specification' actually has 13 letters in it."
+
+ (format "The word `%-7s' actually has %d letters in it."
+ "foo" (length "foo"))
+ => "The word `foo ' actually has 3 letters in it."
+
+ After any minimum field width, a precision may be specified by
+preceding it with a `.' character. The precision specifies the minimum
+number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
+conversions (the number is padded on the left with zeroes as
+necessary); the number of digits printed after the decimal point for
+`%f', `%e', and `%E' conversions; the number of significant digits
+printed in `%g' and `%G' conversions; and the maximum number of
+non-padding characters printed in `%s' and `%S' conversions. The
+default precision for floating-point conversions is six.
+
+ The other flag characters have the following meanings:
+
+ * The ` ' flag means prefix non-negative numbers with a space.
+
+ * The `+' flag means prefix non-negative numbers with a plus sign.
+
+ * The `#' flag means print numbers in an alternate, more verbose
+ format: octal numbers begin with zero; hex numbers begin with a
+ `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
+ conversions even if no numbers are printed after it; and trailing
+ zeroes are not omitted in `%g' and `%G' conversions.
+
+\1f
+File: lispref.info, Node: Character Case, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters
+
+Character Case
+==============
+
+ The character case functions change the case of single characters or
+of the contents of strings. The functions convert only alphabetic
+characters (the letters `A' through `Z' and `a' through `z'); other
+characters are not altered. The functions do not modify the strings
+that are passed to them as arguments.
+
+ The examples below use the characters `X' and `x' which have ASCII
+codes 88 and 120 respectively.
+
+ - Function: downcase STRING-OR-CHAR
+ This function converts a character or a string to lower case.
+
+ When the argument to `downcase' is a string, the function creates
+ and returns a new string in which each letter in the argument that
+ is upper case is converted to lower case. When the argument to
+ `downcase' is a character, `downcase' returns the corresponding
+ lower case character. (This value is actually an integer under
+ XEmacs 19.) If the original character is lower case, or is not a
+ letter, then the value equals the original character.
+
+ (downcase "The cat in the hat")
+ => "the cat in the hat"
+
+ (downcase ?X)
+ => ?x ;; Under XEmacs 20.
+ => 120 ;; Under XEmacs 19.
+
+ - Function: upcase STRING-OR-CHAR
+ This function converts a character or a string to upper case.
+
+ When the argument to `upcase' is a string, the function creates
+ and returns a new string in which each letter in the argument that
+ is lower case is converted to upper case.
+
+ When the argument to `upcase' is a character, `upcase' returns the
+ corresponding upper case character. (This value is actually an
+ integer under XEmacs 19.) If the original character is upper
+ case, or is not a letter, then the value equals the original
+ character.
+
+ (upcase "The cat in the hat")
+ => "THE CAT IN THE HAT"
+
+ (upcase ?x)
+ => ?X ;; Under XEmacs 20.
+ => 88 ;; Under XEmacs 19.
+
+ - Function: capitalize STRING-OR-CHAR
+ This function capitalizes strings or characters. If
+ STRING-OR-CHAR is a string, the function creates and returns a new
+ string, whose contents are a copy of STRING-OR-CHAR in which each
+ word has been capitalized. This means that the first character of
+ each word is converted to upper case, and the rest are converted
+ to lower case.
+
+ The definition of a word is any sequence of consecutive characters
+ that are assigned to the word constituent syntax class in the
+ current syntax table (*note Syntax Class Table::.).
+
+ When the argument to `capitalize' is a character, `capitalize' has
+ the same result as `upcase'.
+
+ (capitalize "The cat in the hat")
+ => "The Cat In The Hat"
+
+ (capitalize "THE 77TH-HATTED CAT")
+ => "The 77th-Hatted Cat"
+
+ (capitalize ?x)
+ => ?X ;; Under XEmacs 20.
+ => 88 ;; Under XEmacs 19.
+
+\1f
+File: lispref.info, Node: Case Tables, Next: Char Tables, Prev: Character Case, Up: Strings and Characters
+
+The Case Table
+==============
+
+ You can customize case conversion by installing a special "case
+table". A case table specifies the mapping between upper case and lower
+case letters. It affects both the string and character case conversion
+functions (see the previous section) and those that apply to text in the
+buffer (*note Case Changes::.). You need a case table if you are using
+a language which has letters other than the standard ASCII letters.
+
+ A case table is a list of this form:
+
+ (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
+
+where each element is either `nil' or a string of length 256. The
+element DOWNCASE says how to map each character to its lower-case
+equivalent. The element UPCASE maps each character to its upper-case
+equivalent. If lower and upper case characters are in one-to-one
+correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
+table from DOWNCASE.
+
+ For some languages, upper and lower case letters are not in
+one-to-one correspondence. There may be two different lower case
+letters with the same upper case equivalent. In these cases, you need
+to specify the maps for both directions.
+
+ The element CANONICALIZE maps each character to a canonical
+equivalent; any two characters that are related by case-conversion have
+the same canonical equivalent character.
+
+ The element EQUIVALENCES is a map that cyclicly permutes each
+equivalence class (of characters with the same canonical equivalent).
+(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
+likewise for each set of equivalent characters.)
+
+ When you construct a case table, you can provide `nil' for
+CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
+You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
+string from CANONICALIZE. In a case table that is actually in use,
+those components are non-`nil'. Do not try to specify EQUIVALENCES
+without also specifying CANONICALIZE.
+
+ Each buffer has a case table. XEmacs also has a "standard case
+table" which is copied into each buffer when you create the buffer.
+Changing the standard case table doesn't affect any existing buffers.
+
+ Here are the functions for working with case tables:
+
+ - Function: case-table-p OBJECT
+ This predicate returns non-`nil' if OBJECT is a valid case table.
+
+ - Function: set-standard-case-table TABLE
+ This function makes TABLE the standard case table, so that it will
+ apply to any buffers created subsequently.
+
+ - Function: standard-case-table
+ This returns the standard case table.
+
+ - Function: current-case-table
+ This function returns the current buffer's case table.
+
+ - Function: set-case-table TABLE
+ This sets the current buffer's case table to TABLE.
+
+ The following three functions are convenient subroutines for packages
+that define non-ASCII character sets. They modify a string
+DOWNCASE-TABLE provided as an argument; this should be a string to be
+used as the DOWNCASE part of a case table. They also modify the
+standard syntax table. *Note Syntax Tables::.
+
+ - Function: set-case-syntax-pair UC LC DOWNCASE-TABLE
+ This function specifies a pair of corresponding letters, one upper
+ case and one lower case.
+
+ - Function: set-case-syntax-delims L R DOWNCASE-TABLE
+ This function makes characters L and R a matching pair of
+ case-invariant delimiters.
+
+ - Function: set-case-syntax CHAR SYNTAX DOWNCASE-TABLE
+ This function makes CHAR case-invariant, with syntax SYNTAX.
+
+ - Command: describe-buffer-case-table
+ This command displays a description of the contents of the current
+ buffer's case table.
+
+ You can load the library `iso-syntax' to set up the standard syntax
+table and define a case table for the 8-bit ISO Latin 1 character set.
+
+\1f
+File: lispref.info, Node: Char Tables, Prev: Case Tables, Up: Strings and Characters
+
+The Char Table
+==============
+
+ A char table is a table that maps characters (or ranges of
+characters) to values. Char tables are specialized for characters,
+only allowing particular sorts of ranges to be assigned values.
+Although this loses in generality, it makes for extremely fast
+(constant-time) lookups, and thus is feasible for applications that do
+an extremely large number of lookups (e.g. scanning a buffer for a
+character in a particular syntax, where a lookup in the syntax table
+must occur once per character).
+
+ Note that char tables as a primitive type, and all of the functions
+in this section, exist only in XEmacs 20. In XEmacs 19, char tables are
+generally implemented using a vector of 256 elements.
+
+ When MULE support exists, the types of ranges that can be assigned
+values are
+
+ * all characters
+
+ * an entire charset
+
+ * a single row in a two-octet charset
+
+ * a single character
+
+ When MULE support is not present, the types of ranges that can be
+assigned values are
+
+ * all characters
+
+ * a single character
+
+ - Function: char-table-p OBJECT
+ This function returns non-`nil' if OBJECT is a char table.
+
+* Menu:
+
+* Char Table Types:: Char tables have different uses.
+* Working With Char Tables:: Creating and working with char tables.
+
+\1f
+File: lispref.info, Node: Char Table Types, Next: Working With Char Tables, Up: Char Tables
+
+Char Table Types
+----------------
+
+ Each char table type is used for a different purpose and allows
+different sorts of values. The different char table types are
+
+`category'
+ Used for category tables, which specify the regexp categories that
+ a character is in. The valid values are `nil' or a bit vector of
+ 95 elements. Higher-level Lisp functions are provided for working
+ with category tables. Currently categories and category tables
+ only exist when MULE support is present.
+
+`char'
+ A generalized char table, for mapping from one character to
+ another. Used for case tables, syntax matching tables,
+ `keyboard-translate-table', etc. The valid values are characters.
+
+`generic'
+ An even more generalized char table, for mapping from a character
+ to anything.
+
+`display'
+ Used for display tables, which specify how a particular character
+ is to appear when displayed. #### Not yet implemented.
+
+`syntax'
+ Used for syntax tables, which specify the syntax of a particular
+ character. Higher-level Lisp functions are provided for working
+ with syntax tables. The valid values are integers.
+
+ - Function: char-table-type TABLE
+ This function returns the type of char table TABLE.
+
+ - Function: char-table-type-list
+ This function returns a list of the recognized char table types.
+
+ - Function: valid-char-table-type-p TYPE
+ This function returns `t' if TYPE if a recognized char table type.
+
+\1f
+File: lispref.info, Node: Working With Char Tables, Prev: Char Table Types, Up: Char Tables
+
+Working With Char Tables
+------------------------
+
+ - Function: make-char-table TYPE
+ This function makes a new, empty char table of type TYPE. TYPE
+ should be a symbol, one of `char', `category', `display',
+ `generic', or `syntax'.
+
+ - Function: put-char-table RANGE VAL TABLE
+ This function sets the value for chars in RANGE to be VAL in TABLE.
+
+ RANGE specifies one or more characters to be affected and should be
+ one of the following:
+
+ * `t' (all characters are affected)
+
+ * A charset (only allowed when MULE support is present)
+
+ * A vector of two elements: a two-octet charset and a row number
+ (only allowed when MULE support is present)
+
+ * A single character
+
+ VAL must be a value appropriate for the type of TABLE.
+
+ - Function: get-char-table CH TABLE
+ This function finds the value for char CH in TABLE.
+
+ - Function: get-range-char-table RANGE TABLE &optional MULTI
+ This function finds the value for a range in TABLE. If there is
+ more than one value, MULTI is returned (defaults to `nil').
+
+ - Function: reset-char-table TABLE
+ This function resets a char table to its default state.
+
+ - Function: map-char-table FUNCTION TABLE &optional RANGE
+ This function maps FUNCTION over entries in TABLE, calling it with
+ two args, each key and value in the table.
+
+ RANGE specifies a subrange to map over and is in the same format
+ as the RANGE argument to `put-range-table'. If omitted or `t', it
+ defaults to the entire table.
+
+ - Function: valid-char-table-value-p VALUE CHAR-TABLE-TYPE
+ This function returns non-`nil' if VALUE is a valid value for
+ CHAR-TABLE-TYPE.
+
+ - Function: check-valid-char-table-value VALUE CHAR-TABLE-TYPE
+ This function signals an error if VALUE is not a valid value for
+ CHAR-TABLE-TYPE.
+
+\1f
+File: lispref.info, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top
+
+Lists
+*****
+
+ A "list" represents a sequence of zero or more elements (which may
+be any Lisp objects). The important difference between lists and
+vectors is that two or more lists can share part of their structure; in
+addition, you can insert or delete elements in a list without copying
+the whole list.
+
+* Menu:
+
+* Cons Cells:: How lists are made out of cons cells.
+* Lists as Boxes:: Graphical notation to explain lists.
+* List-related Predicates:: Is this object a list? Comparing two lists.
+* List Elements:: Extracting the pieces of a list.
+* Building Lists:: Creating list structure.
+* Modifying Lists:: Storing new pieces into an existing list.
+* Sets And Lists:: A list can represent a finite mathematical set.
+* Association Lists:: A list can represent a finite relation or mapping.
+* Property Lists:: A different way to represent a finite mapping.
+* Weak Lists:: A list with special garbage-collection behavior.
+
+\1f
+File: lispref.info, Node: Cons Cells, Next: Lists as Boxes, Up: Lists
+
+Lists and Cons Cells
+====================
+
+ Lists in Lisp are not a primitive data type; they are built up from
+"cons cells". A cons cell is a data object that represents an ordered
+pair. It records two Lisp objects, one labeled as the CAR, and the
+other labeled as the CDR. These names are traditional; see *Note Cons
+Cell Type::. CDR is pronounced "could-er."
+
+ A list is a series of cons cells chained together, one cons cell per
+element of the list. By convention, the CARs of the cons cells are the
+elements of the list, and the CDRs are used to chain the list: the CDR
+of each cons cell is the following cons cell. The CDR of the last cons
+cell is `nil'. This asymmetry between the CAR and the CDR is entirely
+a matter of convention; at the level of cons cells, the CAR and CDR
+slots have the same characteristics.
+
+ Because most cons cells are used as part of lists, the phrase "list
+structure" has come to mean any structure made out of cons cells.
+
+ The symbol `nil' is considered a list as well as a symbol; it is the
+list with no elements. For convenience, the symbol `nil' is considered
+to have `nil' as its CDR (and also as its CAR).
+
+ The CDR of any nonempty list L is a list containing all the elements
+of L except the first.
+
+\1f
+File: lispref.info, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists
+
+Lists as Linked Pairs of Boxes
+==============================
+
+ A cons cell can be illustrated as a pair of boxes. The first box
+represents the CAR and the second box represents the CDR. Here is an
+illustration of the two-element list, `(tulip lily)', made from two
+cons cells:
+
+ --------------- ---------------
+ | car | cdr | | car | cdr |
+ | tulip | o---------->| lily | nil |
+ | | | | | |
+ --------------- ---------------
+
+ Each pair of boxes represents a cons cell. Each box "refers to",
+"points to" or "contains" a Lisp object. (These terms are synonymous.)
+The first box, which is the CAR of the first cons cell, contains the
+symbol `tulip'. The arrow from the CDR of the first cons cell to the
+second cons cell indicates that the CDR of the first cons cell points
+to the second cons cell.
+
+ The same list can be illustrated in a different sort of box notation
+like this:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> tulip --> lily
+
+ Here is a more complex illustration, showing the three-element list,
+`((pine needles) oak maple)', the first element of which is a
+two-element list:
+
+ ___ ___ ___ ___ ___ ___
+ |___|___|--> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ | --> oak --> maple
+ |
+ | ___ ___ ___ ___
+ --> |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> pine --> needles
+
+ The same list represented in the first box notation looks like this:
+
+ -------------- -------------- --------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | o | o------->| oak | o------->| maple | nil |
+ | | | | | | | | | |
+ -- | --------- -------------- --------------
+ |
+ |
+ | -------------- ----------------
+ | | car | cdr | | car | cdr |
+ ------>| pine | o------->| needles | nil |
+ | | | | | |
+ -------------- ----------------
+
+ *Note Cons Cell Type::, for the read and print syntax of cons cells
+and lists, and for more "box and arrow" illustrations of lists.
+
+\1f
+File: lispref.info, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists
+
+Predicates on Lists
+===================
+
+ The following predicates test whether a Lisp object is an atom, is a
+cons cell or is a list, or whether it is the distinguished object
+`nil'. (Many of these predicates can be defined in terms of the
+others, but they are used so often that it is worth having all of them.)
+
+ - Function: consp OBJECT
+ This function returns `t' if OBJECT is a cons cell, `nil'
+ otherwise. `nil' is not a cons cell, although it *is* a list.
+
+ - Function: atom OBJECT
+ This function returns `t' if OBJECT is an atom, `nil' otherwise.
+ All objects except cons cells are atoms. The symbol `nil' is an
+ atom and is also a list; it is the only Lisp object that is both.
+
+ (atom OBJECT) == (not (consp OBJECT))
+
+ - Function: listp OBJECT
+ This function returns `t' if OBJECT is a cons cell or `nil'.
+ Otherwise, it returns `nil'.
+
+ (listp '(1))
+ => t
+ (listp '())
+ => t
+
+ - Function: nlistp OBJECT
+ This function is the opposite of `listp': it returns `t' if OBJECT
+ is not a list. Otherwise, it returns `nil'.
+
+ (listp OBJECT) == (not (nlistp OBJECT))
+
+ - Function: null OBJECT
+ This function returns `t' if OBJECT is `nil', and returns `nil'
+ otherwise. This function is identical to `not', but as a matter
+ of clarity we use `null' when OBJECT is considered a list and
+ `not' when it is considered a truth value (see `not' in *Note
+ Combining Conditions::).
+
+ (null '(1))
+ => nil
+ (null '())
+ => t
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: List Elements, Next: Building Lists, Prev: List-related Predicates, Up: Lists
+
+Accessing Elements of Lists
+===========================
+
+ - Function: car CONS-CELL
+ This function returns the value pointed to by the first pointer of
+ the cons cell CONS-CELL. Expressed another way, this function
+ returns the CAR of CONS-CELL.
+
+ As a special case, if CONS-CELL is `nil', then `car' is defined to
+ return `nil'; therefore, any list is a valid argument for `car'.
+ An error is signaled if the argument is not a cons cell or `nil'.
+
+ (car '(a b c))
+ => a
+ (car '())
+ => nil
+
+ - Function: cdr CONS-CELL
+ This function returns the value pointed to by the second pointer of
+ the cons cell CONS-CELL. Expressed another way, this function
+ returns the CDR of CONS-CELL.
+
+ As a special case, if CONS-CELL is `nil', then `cdr' is defined to
+ return `nil'; therefore, any list is a valid argument for `cdr'.
+ An error is signaled if the argument is not a cons cell or `nil'.
+
+ (cdr '(a b c))
+ => (b c)
+ (cdr '())
+ => nil
+
+ - Function: car-safe OBJECT
+ This function lets you take the CAR of a cons cell while avoiding
+ errors for other data types. It returns the CAR of OBJECT if
+ OBJECT is a cons cell, `nil' otherwise. This is in contrast to
+ `car', which signals an error if OBJECT is not a list.
+
+ (car-safe OBJECT)
+ ==
+ (let ((x OBJECT))
+ (if (consp x)
+ (car x)
+ nil))
+
+ - Function: cdr-safe OBJECT
+ This function lets you take the CDR of a cons cell while avoiding
+ errors for other data types. It returns the CDR of OBJECT if
+ OBJECT is a cons cell, `nil' otherwise. This is in contrast to
+ `cdr', which signals an error if OBJECT is not a list.
+
+ (cdr-safe OBJECT)
+ ==
+ (let ((x OBJECT))
+ (if (consp x)
+ (cdr x)
+ nil))
+
+ - Function: nth N LIST
+ This function returns the Nth element of LIST. Elements are
+ numbered starting with zero, so the CAR of LIST is element number
+ zero. If the length of LIST is N or less, the value is `nil'.
+
+ If N is negative, `nth' returns the first element of LIST.
+
+ (nth 2 '(1 2 3 4))
+ => 3
+ (nth 10 '(1 2 3 4))
+ => nil
+ (nth -3 '(1 2 3 4))
+ => 1
+
+ (nth n x) == (car (nthcdr n x))
+
+ - Function: nthcdr N LIST
+ This function returns the Nth CDR of LIST. In other words, it
+ removes the first N links of LIST and returns what follows.
+
+ If N is zero or negative, `nthcdr' returns all of LIST. If the
+ length of LIST is N or less, `nthcdr' returns `nil'.
+
+ (nthcdr 1 '(1 2 3 4))
+ => (2 3 4)
+ (nthcdr 10 '(1 2 3 4))
+ => nil
+ (nthcdr -3 '(1 2 3 4))
+ => (1 2 3 4)
+
+ Many convenience functions are provided to make it easier for you to
+access particular elements in a nested list. All of these can be
+rewritten in terms of the functions just described.
+
+ - Function: caar CONS-CELL
+ - Function: cadr CONS-CELL
+ - Function: cdar CONS-CELL
+ - Function: cddr CONS-CELL
+ - Function: caaar CONS-CELL
+ - Function: caadr CONS-CELL
+ - Function: cadar CONS-CELL
+ - Function: caddr CONS-CELL
+ - Function: cdaar CONS-CELL
+ - Function: cdadr CONS-CELL
+ - Function: cddar CONS-CELL
+ - Function: cdddr CONS-CELL
+ - Function: caaaar CONS-CELL
+ - Function: caaadr CONS-CELL
+ - Function: caadar CONS-CELL
+ - Function: caaddr CONS-CELL
+ - Function: cadaar CONS-CELL
+ - Function: cadadr CONS-CELL
+ - Function: caddar CONS-CELL
+ - Function: cadddr CONS-CELL
+ - Function: cdaaar CONS-CELL
+ - Function: cdaadr CONS-CELL
+ - Function: cdadar CONS-CELL
+ - Function: cdaddr CONS-CELL
+ - Function: cddaar CONS-CELL
+ - Function: cddadr CONS-CELL
+ - Function: cdddar CONS-CELL
+ - Function: cddddr CONS-CELL
+ Each of these functions is equivalent to one or more applications
+ of `car' and/or `cdr'. For example,
+
+ (cadr x)
+
+ is equivalent to
+
+ (car (cdr x))
+
+ and
+
+ (cdaddr x)
+
+ is equivalent to
+
+ (cdr (car (cdr (cdr x))))
+
+ That is to say, read the a's and d's from right to left and apply
+ a `car' or `cdr' for each a or d found, respectively.
+
+ - Function: first LIST
+ This is equivalent to `(nth 0 LIST)', i.e. the first element of
+ LIST. (Note that this is also equivalent to `car'.)
+
+ - Function: second LIST
+ This is equivalent to `(nth 1 LIST)', i.e. the second element of
+ LIST.
+
+ - Function: third LIST
+ - Function: fourth LIST
+ - Function: fifth LIST
+ - Function: sixth LIST
+ - Function: seventh LIST
+ - Function: eighth LIST
+ - Function: ninth LIST
+ - Function: tenth LIST
+ These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
+ respectively, i.e. the third through tenth elements of LIST.
+
+\1f
+File: lispref.info, Node: Building Lists, Next: Modifying Lists, Prev: List Elements, Up: Lists
+
+Building Cons Cells and Lists
+=============================
+
+ Many functions build lists, as lists reside at the very heart of
+Lisp. `cons' is the fundamental list-building function; however, it is
+interesting to note that `list' is used more times in the source code
+for Emacs than `cons'.
+
+ - Function: cons OBJECT1 OBJECT2
+ This function is the fundamental function used to build new list
+ structure. It creates a new cons cell, making OBJECT1 the CAR,
+ and OBJECT2 the CDR. It then returns the new cons cell. The
+ arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
+ often OBJECT2 is a list.
+
+ (cons 1 '(2))
+ => (1 2)
+ (cons 1 '())
+ => (1)
+ (cons 1 2)
+ => (1 . 2)
+
+ `cons' is often used to add a single element to the front of a
+ list. This is called "consing the element onto the list". For
+ example:
+
+ (setq list (cons newelt list))
+
+ Note that there is no conflict between the variable named `list'
+ used in this example and the function named `list' described below;
+ any symbol can serve both purposes.
+
+ - Function: list &rest OBJECTS
+ This function creates a list with OBJECTS as its elements. The
+ resulting list is always `nil'-terminated. If no OBJECTS are
+ given, the empty list is returned.
+
+ (list 1 2 3 4 5)
+ => (1 2 3 4 5)
+ (list 1 2 '(3 4 5) 'foo)
+ => (1 2 (3 4 5) foo)
+ (list)
+ => nil
+
+ - Function: make-list LENGTH OBJECT
+ This function creates a list of length LENGTH, in which all the
+ elements have the identical value OBJECT. Compare `make-list'
+ with `make-string' (*note Creating Strings::.).
+
+ (make-list 3 'pigs)
+ => (pigs pigs pigs)
+ (make-list 0 'pigs)
+ => nil
+
+ - Function: append &rest SEQUENCES
+ This function returns a list containing all the elements of
+ SEQUENCES. The SEQUENCES may be lists, vectors, or strings, but
+ the last one should be a list. All arguments except the last one
+ are copied, so none of them are altered.
+
+ More generally, the final argument to `append' may be any Lisp
+ object. The final argument is not copied or converted; it becomes
+ the CDR of the last cons cell in the new list. If the final
+ argument is itself a list, then its elements become in effect
+ elements of the result list. If the final element is not a list,
+ the result is a "dotted list" since its final CDR is not `nil' as
+ required in a true list.
+
+ See `nconc' in *Note Rearrangement::, for a way to join lists with
+ no copying.
+
+ Here is an example of using `append':
+
+ (setq trees '(pine oak))
+ => (pine oak)
+ (setq more-trees (append '(maple birch) trees))
+ => (maple birch pine oak)
+
+ trees
+ => (pine oak)
+ more-trees
+ => (maple birch pine oak)
+ (eq trees (cdr (cdr more-trees)))
+ => t
+
+ You can see how `append' works by looking at a box diagram. The
+ variable `trees' is set to the list `(pine oak)' and then the
+ variable `more-trees' is set to the list `(maple birch pine oak)'.
+ However, the variable `trees' continues to refer to the original
+ list:
+
+ more-trees trees
+ | |
+ | ___ ___ ___ ___ -> ___ ___ ___ ___
+ --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
+ | | | |
+ | | | |
+ --> maple -->birch --> pine --> oak
+
+ An empty sequence contributes nothing to the value returned by
+ `append'. As a consequence of this, a final `nil' argument forces
+ a copy of the previous argument.
+
+ trees
+ => (pine oak)
+ (setq wood (append trees ()))
+ => (pine oak)
+ wood
+ => (pine oak)
+ (eq wood trees)
+ => nil
+
+ This once was the usual way to copy a list, before the function
+ `copy-sequence' was invented. *Note Sequences Arrays Vectors::.
+
+ With the help of `apply', we can append all the lists in a list of
+ lists:
+
+ (apply 'append '((a b c) nil (x y z) nil))
+ => (a b c x y z)
+
+ If no SEQUENCES are given, `nil' is returned:
+
+ (append)
+ => nil
+
+ Here are some examples where the final argument is not a list:
+
+ (append '(x y) 'z)
+ => (x y . z)
+ (append '(x y) [z])
+ => (x y . [z])
+
+ The second example shows that when the final argument is a
+ sequence but not a list, the sequence's elements do not become
+ elements of the resulting list. Instead, the sequence becomes the
+ final CDR, like any other non-list final argument.
+
+ The `append' function also allows integers as arguments. It
+ converts them to strings of digits, making up the decimal print
+ representation of the integer, and then uses the strings instead
+ of the original integers. *Don't use this feature; we plan to
+ eliminate it. If you already use this feature, change your
+ programs now!* The proper way to convert an integer to a decimal
+ number in this way is with `format' (*note Formatting Strings::.)
+ or `number-to-string' (*note String Conversion::.).
+
+ - Function: reverse LIST
+ This function creates a new list whose elements are the elements of
+ LIST, but in reverse order. The original argument LIST is *not*
+ altered.
+
+ (setq x '(1 2 3 4))
+ => (1 2 3 4)
+ (reverse x)
+ => (4 3 2 1)
+ x
+ => (1 2 3 4)
+
+\1f
+File: lispref.info, Node: Modifying Lists, Next: Sets And Lists, Prev: Building Lists, Up: Lists
+
+Modifying Existing List Structure
+=================================
+
+ You can modify the CAR and CDR contents of a cons cell with the
+primitives `setcar' and `setcdr'.
+
+ Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
+ to alter list structure; they change structure the same way as
+ `setcar' and `setcdr', but the Common Lisp functions return the
+ cons cell while `setcar' and `setcdr' return the new CAR or CDR.
+
+* Menu:
+
+* Setcar:: Replacing an element in a list.
+* Setcdr:: Replacing part of the list backbone.
+ This can be used to remove or add elements.
+* Rearrangement:: Reordering the elements in a list; combining lists.
+
+\1f
+File: lispref.info, Node: Setcar, Next: Setcdr, Up: Modifying Lists
+
+Altering List Elements with `setcar'
+------------------------------------
+
+ Changing the CAR of a cons cell is done with `setcar'. When used on
+a list, `setcar' replaces one element of a list with a different
+element.
+
+ - Function: setcar CONS OBJECT
+ This function stores OBJECT as the new CAR of CONS, replacing its
+ previous CAR. It returns the value OBJECT. For example:
+
+ (setq x '(1 2))
+ => (1 2)
+ (setcar x 4)
+ => 4
+ x
+ => (4 2)
+
+ When a cons cell is part of the shared structure of several lists,
+storing a new CAR into the cons changes one element of each of these
+lists. Here is an example:
+
+ ;; Create two lists that are partly shared.
+ (setq x1 '(a b c))
+ => (a b c)
+ (setq x2 (cons 'z (cdr x1)))
+ => (z b c)
+
+ ;; Replace the CAR of a shared link.
+ (setcar (cdr x1) 'foo)
+ => foo
+ x1 ; Both lists are changed.
+ => (a foo c)
+ x2
+ => (z foo c)
+
+ ;; Replace the CAR of a link that is not shared.
+ (setcar x1 'baz)
+ => baz
+ x1 ; Only one list is changed.
+ => (baz foo c)
+ x2
+ => (z foo c)
+
+ Here is a graphical depiction of the shared structure of the two
+lists in the variables `x1' and `x2', showing why replacing `b' changes
+them both:
+
+ ___ ___ ___ ___ ___ ___
+ x1---> |___|___|----> |___|___|--> |___|___|--> nil
+ | --> | |
+ | | | |
+ --> a | --> b --> c
+ |
+ ___ ___ |
+ x2--> |___|___|--
+ |
+ |
+ --> z
+
+ Here is an alternative form of box diagram, showing the same
+relationship:
+
+ x1:
+ -------------- -------------- --------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | a | o------->| b | o------->| c | nil |
+ | | | -->| | | | | |
+ -------------- | -------------- --------------
+ |
+ x2: |
+ -------------- |
+ | car | cdr | |
+ | z | o----
+ | | |
+ --------------
+
+\1f
+File: lispref.info, Node: Setcdr, Next: Rearrangement, Prev: Setcar, Up: Modifying Lists
+
+Altering the CDR of a List
+--------------------------
+
+ The lowest-level primitive for modifying a CDR is `setcdr':
+
+ - Function: setcdr CONS OBJECT
+ This function stores OBJECT as the new CDR of CONS, replacing its
+ previous CDR. It returns the value OBJECT.
+
+ Here is an example of replacing the CDR of a list with a different
+list. All but the first element of the list are removed in favor of a
+different sequence of elements. The first element is unchanged,
+because it resides in the CAR of the list, and is not reached via the
+CDR.
+
+ (setq x '(1 2 3))
+ => (1 2 3)
+ (setcdr x '(4))
+ => (4)
+ x
+ => (1 4)
+
+ You can delete elements from the middle of a list by altering the
+CDRs of the cons cells in the list. For example, here we delete the
+second element, `b', from the list `(a b c)', by changing the CDR of
+the first cell:
+
+ (setq x1 '(a b c))
+ => (a b c)
+ (setcdr x1 (cdr (cdr x1)))
+ => (c)
+ x1
+ => (a c)
+
+ Here is the result in box notation:
+
+ --------------------
+ | |
+ -------------- | -------------- | --------------
+ | car | cdr | | | car | cdr | -->| car | cdr |
+ | a | o----- | b | o-------->| c | nil |
+ | | | | | | | | |
+ -------------- -------------- --------------
+
+The second cons cell, which previously held the element `b', still
+exists and its CAR is still `b', but it no longer forms part of this
+list.
+
+ It is equally easy to insert a new element by changing CDRs:
+
+ (setq x1 '(a b c))
+ => (a b c)
+ (setcdr x1 (cons 'd (cdr x1)))
+ => (d b c)
+ x1
+ => (a d b c)
+
+ Here is this result in box notation:
+
+ -------------- ------------- -------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | a | o | -->| b | o------->| c | nil |
+ | | | | | | | | | | |
+ --------- | -- | ------------- -------------
+ | |
+ ----- --------
+ | |
+ | --------------- |
+ | | car | cdr | |
+ -->| d | o------
+ | | |
+ ---------------
+
+\1f
+File: lispref.info, Node: Rearrangement, Prev: Setcdr, Up: Modifying Lists
+
+Functions that Rearrange Lists
+------------------------------
+
+ Here are some functions that rearrange lists "destructively" by
+modifying the CDRs of their component cons cells. We call these
+functions "destructive" because they chew up the original lists passed
+to them as arguments, to produce a new list that is the returned value.
+
+ See `delq', in *Note Sets And Lists::, for another function that
+modifies cons cells.
+
+ - Function: nconc &rest LISTS
+ This function returns a list containing all the elements of LISTS.
+ Unlike `append' (*note Building Lists::.), the LISTS are *not*
+ copied. Instead, the last CDR of each of the LISTS is changed to
+ refer to the following list. The last of the LISTS is not
+ altered. For example:
+
+ (setq x '(1 2 3))
+ => (1 2 3)
+ (nconc x '(4 5))
+ => (1 2 3 4 5)
+ x
+ => (1 2 3 4 5)
+
+ Since the last argument of `nconc' is not itself modified, it is
+ reasonable to use a constant list, such as `'(4 5)', as in the
+ above example. For the same reason, the last argument need not be
+ a list:
+
+ (setq x '(1 2 3))
+ => (1 2 3)
+ (nconc x 'z)
+ => (1 2 3 . z)
+ x
+ => (1 2 3 . z)
+
+ A common pitfall is to use a quoted constant list as a non-last
+ argument to `nconc'. If you do this, your program will change
+ each time you run it! Here is what happens:
+
+ (defun add-foo (x) ; We want this function to add
+ (nconc '(foo) x)) ; `foo' to the front of its arg.
+
+ (symbol-function 'add-foo)
+ => (lambda (x) (nconc (quote (foo)) x))
+
+ (setq xx (add-foo '(1 2))) ; It seems to work.
+ => (foo 1 2)
+
+ (setq xy (add-foo '(3 4))) ; What happened?
+ => (foo 1 2 3 4)
+
+ (eq xx xy)
+ => t
+
+ (symbol-function 'add-foo)
+ => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
+
+ - Function: nreverse LIST
+ This function reverses the order of the elements of LIST. Unlike
+ `reverse', `nreverse' alters its argument by reversing the CDRs in
+ the cons cells forming the list. The cons cell that used to be
+ the last one in LIST becomes the first cell of the value.
+
+ For example:
+
+ (setq x '(1 2 3 4))
+ => (1 2 3 4)
+ x
+ => (1 2 3 4)
+ (nreverse x)
+ => (4 3 2 1)
+ ;; The cell that was first is now last.
+ x
+ => (1)
+
+ To avoid confusion, we usually store the result of `nreverse' back
+ in the same variable which held the original list:
+
+ (setq x (nreverse x))
+
+ Here is the `nreverse' of our favorite example, `(a b c)',
+ presented graphically:
+
+ Original list head: Reversed list:
+ ------------- ------------- ------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | a | nil |<-- | b | o |<-- | c | o |
+ | | | | | | | | | | | | |
+ ------------- | --------- | - | -------- | -
+ | | | |
+ ------------- ------------
+
+ - Function: sort LIST PREDICATE
+ This function sorts LIST stably, though destructively, and returns
+ the sorted list. It compares elements using PREDICATE. A stable
+ sort is one in which elements with equal sort keys maintain their
+ relative order before and after the sort. Stability is important
+ when successive sorts are used to order elements according to
+ different criteria.
+
+ The argument PREDICATE must be a function that accepts two
+ arguments. It is called with two elements of LIST. To get an
+ increasing order sort, the PREDICATE should return `t' if the
+ first element is "less than" the second, or `nil' if not.
+
+ The destructive aspect of `sort' is that it rearranges the cons
+ cells forming LIST by changing CDRs. A nondestructive sort
+ function would create new cons cells to store the elements in their
+ sorted order. If you wish to make a sorted copy without
+ destroying the original, copy it first with `copy-sequence' and
+ then sort.
+
+ Sorting does not change the CARs of the cons cells in LIST; the
+ cons cell that originally contained the element `a' in LIST still
+ has `a' in its CAR after sorting, but it now appears in a
+ different position in the list due to the change of CDRs. For
+ example:
+
+ (setq nums '(1 3 2 6 5 4 0))
+ => (1 3 2 6 5 4 0)
+ (sort nums '<)
+ => (0 1 2 3 4 5 6)
+ nums
+ => (1 2 3 4 5 6)
+
+ Note that the list in `nums' no longer contains 0; this is the same
+ cons cell that it was before, but it is no longer the first one in
+ the list. Don't assume a variable that formerly held the argument
+ now holds the entire sorted list! Instead, save the result of
+ `sort' and use that. Most often we store the result back into the
+ variable that held the original list:
+
+ (setq nums (sort nums '<))
+
+ *Note Sorting::, for more functions that perform sorting. See
+ `documentation' in *Note Accessing Documentation::, for a useful
+ example of `sort'.
+
+\1f
+File: lispref.info, Node: Sets And Lists, Next: Association Lists, Prev: Modifying Lists, Up: Lists
+
+Using Lists as Sets
+===================
+
+ A list can represent an unordered mathematical set--simply consider a
+value an element of a set if it appears in the list, and ignore the
+order of the list. To form the union of two sets, use `append' (as
+long as you don't mind having duplicate elements). Other useful
+functions for sets include `memq' and `delq', and their `equal'
+versions, `member' and `delete'.
+
+ Common Lisp note: Common Lisp has functions `union' (which avoids
+ duplicate elements) and `intersection' for set operations, but
+ XEmacs Lisp does not have them. You can write them in Lisp if you
+ wish.
+
+ - Function: memq OBJECT LIST
+ This function tests to see whether OBJECT is a member of LIST. If
+ it is, `memq' returns a list starting with the first occurrence of
+ OBJECT. Otherwise, it returns `nil'. The letter `q' in `memq'
+ says that it uses `eq' to compare OBJECT against the elements of
+ the list. For example:
+
+ (memq 'b '(a b c b a))
+ => (b c b a)
+ (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
+ => nil
+
+ - Function: delq OBJECT LIST
+ This function destructively removes all elements `eq' to OBJECT
+ from LIST. The letter `q' in `delq' says that it uses `eq' to
+ compare OBJECT against the elements of the list, like `memq'.
+
+ When `delq' deletes elements from the front of the list, it does so
+simply by advancing down the list and returning a sublist that starts
+after those elements:
+
+ (delq 'a '(a b c)) == (cdr '(a b c))
+
+ When an element to be deleted appears in the middle of the list,
+removing it involves changing the CDRs (*note Setcdr::.).
+
+ (setq sample-list '(a b c (4)))
+ => (a b c (4))
+ (delq 'a sample-list)
+ => (b c (4))
+ sample-list
+ => (a b c (4))
+ (delq 'c sample-list)
+ => (a b (4))
+ sample-list
+ => (a b (4))
+
+ Note that `(delq 'c sample-list)' modifies `sample-list' to splice
+out the third element, but `(delq 'a sample-list)' does not splice
+anything--it just returns a shorter list. Don't assume that a variable
+which formerly held the argument LIST now has fewer elements, or that
+it still holds the original list! Instead, save the result of `delq'
+and use that. Most often we store the result back into the variable
+that held the original list:
+
+ (setq flowers (delq 'rose flowers))
+
+ In the following example, the `(4)' that `delq' attempts to match
+and the `(4)' in the `sample-list' are not `eq':
+
+ (delq '(4) sample-list)
+ => (a c (4))
+
+ The following two functions are like `memq' and `delq' but use
+`equal' rather than `eq' to compare elements. They are new in Emacs 19.
+
+ - Function: member OBJECT LIST
+ The function `member' tests to see whether OBJECT is a member of
+ LIST, comparing members with OBJECT using `equal'. If OBJECT is a
+ member, `member' returns a list starting with its first occurrence
+ in LIST. Otherwise, it returns `nil'.
+
+ Compare this with `memq':
+
+ (member '(2) '((1) (2))) ; `(2)' and `(2)' are `equal'.
+ => ((2))
+ (memq '(2) '((1) (2))) ; `(2)' and `(2)' are not `eq'.
+ => nil
+ ;; Two strings with the same contents are `equal'.
+ (member "foo" '("foo" "bar"))
+ => ("foo" "bar")
+
+ - Function: delete OBJECT LIST
+ This function destructively removes all elements `equal' to OBJECT
+ from LIST. It is to `delq' as `member' is to `memq': it uses
+ `equal' to compare elements with OBJECT, like `member'; when it
+ finds an element that matches, it removes the element just as
+ `delq' would. For example:
+
+ (delete '(2) '((2) (1) (2)))
+ => '((1))
+
+ Common Lisp note: The functions `member' and `delete' in XEmacs
+ Lisp are derived from Maclisp, not Common Lisp. The Common Lisp
+ versions do not use `equal' to compare elements.
+
+ See also the function `add-to-list', in *Note Setting Variables::,
+for another way to add an element to a list stored in a variable.
+
+\1f
+File: lispref.info, Node: Association Lists, Next: Property Lists, Prev: Sets And Lists, Up: Lists
+
+Association Lists
+=================
+
+ An "association list", or "alist" for short, records a mapping from
+keys to values. It is a list of cons cells called "associations": the
+CAR of each cell is the "key", and the CDR is the "associated value".(1)
+
+ Here is an example of an alist. The key `pine' is associated with
+the value `cones'; the key `oak' is associated with `acorns'; and the
+key `maple' is associated with `seeds'.
+
+ '((pine . cones)
+ (oak . acorns)
+ (maple . seeds))
+
+ The associated values in an alist may be any Lisp objects; so may the
+keys. For example, in the following alist, the symbol `a' is
+associated with the number `1', and the string `"b"' is associated with
+the *list* `(2 3)', which is the CDR of the alist element:
+
+ ((a . 1) ("b" 2 3))
+
+ Sometimes it is better to design an alist to store the associated
+value in the CAR of the CDR of the element. Here is an example:
+
+ '((rose red) (lily white) (buttercup yellow))
+
+Here we regard `red' as the value associated with `rose'. One
+advantage of this method is that you can store other related
+information--even a list of other items--in the CDR of the CDR. One
+disadvantage is that you cannot use `rassq' (see below) to find the
+element containing a given value. When neither of these considerations
+is important, the choice is a matter of taste, as long as you are
+consistent about it for any given alist.
+
+ Note that the same alist shown above could be regarded as having the
+associated value in the CDR of the element; the value associated with
+`rose' would be the list `(red)'.
+
+ Association lists are often used to record information that you might
+otherwise keep on a stack, since new associations may be added easily to
+the front of the list. When searching an association list for an
+association with a given key, the first one found is returned, if there
+is more than one.
+
+ In XEmacs Lisp, it is *not* an error if an element of an association
+list is not a cons cell. The alist search functions simply ignore such
+elements. Many other versions of Lisp signal errors in such cases.
+
+ Note that property lists are similar to association lists in several
+respects. A property list behaves like an association list in which
+each key can occur only once. *Note Property Lists::, for a comparison
+of property lists and association lists.
+
+ - Function: assoc KEY ALIST
+ This function returns the first association for KEY in ALIST. It
+ compares KEY against the alist elements using `equal' (*note
+ Equality Predicates::.). It returns `nil' if no association in
+ ALIST has a CAR `equal' to KEY. For example:
+
+ (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+ => ((pine . cones) (oak . acorns) (maple . seeds))
+ (assoc 'oak trees)
+ => (oak . acorns)
+ (cdr (assoc 'oak trees))
+ => acorns
+ (assoc 'birch trees)
+ => nil
+
+ Here is another example, in which the keys and values are not
+ symbols:
+
+ (setq needles-per-cluster
+ '((2 "Austrian Pine" "Red Pine")
+ (3 "Pitch Pine")
+ (5 "White Pine")))
+
+ (cdr (assoc 3 needles-per-cluster))
+ => ("Pitch Pine")
+ (cdr (assoc 2 needles-per-cluster))
+ => ("Austrian Pine" "Red Pine")
+
+ - Function: rassoc VALUE ALIST
+ This function returns the first association with value VALUE in
+ ALIST. It returns `nil' if no association in ALIST has a CDR
+ `equal' to VALUE.
+
+ `rassoc' is like `assoc' except that it compares the CDR of each
+ ALIST association instead of the CAR. You can think of this as
+ "reverse `assoc'", finding the key for a given value.
+
+ - Function: assq KEY ALIST
+ This function is like `assoc' in that it returns the first
+ association for KEY in ALIST, but it makes the comparison using
+ `eq' instead of `equal'. `assq' returns `nil' if no association
+ in ALIST has a CAR `eq' to KEY. This function is used more often
+ than `assoc', since `eq' is faster than `equal' and most alists
+ use symbols as keys. *Note Equality Predicates::.
+
+ (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+ => ((pine . cones) (oak . acorns) (maple . seeds))
+ (assq 'pine trees)
+ => (pine . cones)
+
+ On the other hand, `assq' is not usually useful in alists where the
+ keys may not be symbols:
+
+ (setq leaves
+ '(("simple leaves" . oak)
+ ("compound leaves" . horsechestnut)))
+
+ (assq "simple leaves" leaves)
+ => nil
+ (assoc "simple leaves" leaves)
+ => ("simple leaves" . oak)
+
+ - Function: rassq VALUE ALIST
+ This function returns the first association with value VALUE in
+ ALIST. It returns `nil' if no association in ALIST has a CDR `eq'
+ to VALUE.
+
+ `rassq' is like `assq' except that it compares the CDR of each
+ ALIST association instead of the CAR. You can think of this as
+ "reverse `assq'", finding the key for a given value.
+
+ For example:
+
+ (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
+
+ (rassq 'acorns trees)
+ => (oak . acorns)
+ (rassq 'spores trees)
+ => nil
+
+ Note that `rassq' cannot search for a value stored in the CAR of
+ the CDR of an element:
+
+ (setq colors '((rose red) (lily white) (buttercup yellow)))
+
+ (rassq 'white colors)
+ => nil
+
+ In this case, the CDR of the association `(lily white)' is not the
+ symbol `white', but rather the list `(white)'. This becomes
+ clearer if the association is written in dotted pair notation:
+
+ (lily white) == (lily . (white))
+
+ - Function: remassoc KEY ALIST
+ This function deletes by side effect any associations with key KEY
+ in ALIST - i.e. it removes any elements from ALIST whose `car' is
+ `equal' to KEY. The modified ALIST is returned.
+
+ If the first member of ALIST has a `car' that is `equal' to KEY,
+ there is no way to remove it by side effect; therefore, write
+ `(setq foo (remassoc key foo))' to be sure of changing the value
+ of `foo'.
+
+ - Function: remassq KEY ALIST
+ This function deletes by side effect any associations with key KEY
+ in ALIST - i.e. it removes any elements from ALIST whose `car' is
+ `eq' to KEY. The modified ALIST is returned.
+
+ This function is exactly like `remassoc', but comparisons between
+ KEY and keys in ALIST are done using `eq' instead of `equal'.
+
+ - Function: remrassoc VALUE ALIST
+ This function deletes by side effect any associations with value
+ VALUE in ALIST - i.e. it removes any elements from ALIST whose
+ `cdr' is `equal' to VALUE. The modified ALIST is returned.
+
+ If the first member of ALIST has a `car' that is `equal' to VALUE,
+ there is no way to remove it by side effect; therefore, write
+ `(setq foo (remassoc value foo))' to be sure of changing the value
+ of `foo'.
+
+ `remrassoc' is like `remassoc' except that it compares the CDR of
+ each ALIST association instead of the CAR. You can think of this
+ as "reverse `remassoc'", removing an association based on its
+ value instead of its key.
+
+ - Function: remrassq VALUE ALIST
+ This function deletes by side effect any associations with value
+ VALUE in ALIST - i.e. it removes any elements from ALIST whose
+ `cdr' is `eq' to VALUE. The modified ALIST is returned.
+
+ This function is exactly like `remrassoc', but comparisons between
+ VALUE and values in ALIST are done using `eq' instead of `equal'.
+
+ - Function: copy-alist ALIST
+ This function returns a two-level deep copy of ALIST: it creates a
+ new copy of each association, so that you can alter the
+ associations of the new alist without changing the old one.
+
+ (setq needles-per-cluster
+ '((2 . ("Austrian Pine" "Red Pine"))
+ (3 . ("Pitch Pine"))
+ (5 . ("White Pine"))))
+ =>
+ ((2 "Austrian Pine" "Red Pine")
+ (3 "Pitch Pine")
+ (5 "White Pine"))
+
+ (setq copy (copy-alist needles-per-cluster))
+ =>
+ ((2 "Austrian Pine" "Red Pine")
+ (3 "Pitch Pine")
+ (5 "White Pine"))
+
+ (eq needles-per-cluster copy)
+ => nil
+ (equal needles-per-cluster copy)
+ => t
+ (eq (car needles-per-cluster) (car copy))
+ => nil
+ (cdr (car (cdr needles-per-cluster)))
+ => ("Pitch Pine")
+ (eq (cdr (car (cdr needles-per-cluster)))
+ (cdr (car (cdr copy))))
+ => t
+
+ This example shows how `copy-alist' makes it possible to change
+ the associations of one copy without affecting the other:
+
+ (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
+ (cdr (assq 3 needles-per-cluster))
+ => ("Pitch Pine")
+
+ ---------- Footnotes ----------
+
+ (1) This usage of "key" is not related to the term "key sequence";
+it means a value used to look up an item in a table. In this case, the
+table is the alist, and the alist associations are the items.
+
+\1f
+File: lispref.info, Node: Property Lists, Next: Weak Lists, Prev: Association Lists, Up: Lists
+
+Property Lists
+==============
+
+ A "property list" (or "plist") is another way of representing a
+mapping from keys to values. Instead of the list consisting of conses
+of a key and a value, the keys and values alternate as successive
+entries in the list. Thus, the association list
+
+ ((a . 1) (b . 2) (c . 3))
+
+ has the equivalent property list form
+
+ (a 1 b 2 c 3)
+
+ Property lists are used to represent the properties associated with
+various sorts of objects, such as symbols, strings, frames, etc. The
+convention is that property lists can be modified in-place, while
+association lists generally are not.
+
+ Plists come in two varieties: "normal" plists, whose keys are
+compared with `eq', and "lax" plists, whose keys are compared with
+`equal',
+
+ - Function: valid-plist-p PLIST
+ Given a plist, this function returns non-`nil' if its format is
+ correct. If it returns `nil', `check-valid-plist' will signal an
+ error when given the plist; that means it's a malformed or circular
+ plist or has non-symbols as keywords.
+
+ - Function: check-valid-plist PLIST
+ Given a plist, this function signals an error if there is anything
+ wrong with it. This means that it's a malformed or circular plist.
+
+* Menu:
+
+* Working With Normal Plists:: Functions for normal plists.
+* Working With Lax Plists:: Functions for lax plists.
+* Converting Plists To/From Alists:: Alist to plist and vice-versa.
+
+\1f
+File: lispref.info, Node: Working With Normal Plists, Next: Working With Lax Plists, Up: Property Lists
+
+Working With Normal Plists
+--------------------------
+
+ - Function: plist-get PLIST PROP &optional DEFAULT
+ This function extracts a value from a property list. The function
+ returns the value corresponding to the given PROP, or DEFAULT if
+ PROP is not one of the properties on the list.
+
+ - Function: plist-put PLIST PROP VAL
+ This function changes the value in PLIST of PROP to VAL. If PROP
+ is already a property on the list, its value is set to VAL,
+ otherwise the new PROP VAL pair is added. The new plist is
+ returned; use `(setq x (plist-put x prop val))' to be sure to use
+ the new value. The PLIST is modified by side effects.
+
+ - Function: plist-remprop PLIST PROP
+ This function removes from PLIST the property PROP and its value.
+ The new plist is returned; use `(setq x (plist-remprop x prop
+ val))' to be sure to use the new value. The PLIST is modified by
+ side effects.
+
+ - Function: plist-member PLIST PROP
+ This function returns `t' if PROP has a value specified in PLIST.
+
+ In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
+non-`nil', then a property with a `nil' value is ignored or removed.
+This feature is a virus that has infected old Lisp implementations (and
+thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
+used except for backward compatibility.
+
+ - Function: plists-eq A B &optional NIL-MEANS-NOT-PRESENT
+ This function returns non-`nil' if property lists A and B are `eq'
+ (i.e. their values are `eq').
+
+ - Function: plists-equal A B &optional NIL-MEANS-NOT-PRESENT
+ This function returns non-`nil' if property lists A and B are
+ `equal' (i.e. their values are `equal'; their keys are still
+ compared using `eq').
+
+ - Function: canonicalize-plist PLIST &optional NIL-MEANS-NOT-PRESENT
+ This function destructively removes any duplicate entries from a
+ plist. In such cases, the first entry applies.
+
+ The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
+ return value may not be `eq' to the passed-in value, so make sure
+ to `setq' the value back into where it came from.
+
+\1f
+File: lispref.info, Node: Working With Lax Plists, Next: Converting Plists To/From Alists, Prev: Working With Normal Plists, Up: Property Lists
+
+Working With Lax Plists
+-----------------------
+
+ Recall that a "lax plist" is a property list whose keys are compared
+using `equal' instead of `eq'.
+
+ - Function: lax-plist-get LAX-PLIST PROP &optional DEFAULT
+ This function extracts a value from a lax property list. The
+ function returns the value corresponding to the given PROP, or
+ DEFAULT if PROP is not one of the properties on the list.
+
+ - Function: lax-plist-put LAX-PLIST PROP VAL
+ This function changes the value in LAX-PLIST of PROP to VAL.
+
+ - Function: lax-plist-remprop LAX-PLIST PROP
+ This function removes from LAX-PLIST the property PROP and its
+ value. The new plist is returned; use `(setq x (lax-plist-remprop
+ x prop val))' to be sure to use the new value. The LAX-PLIST is
+ modified by side effects.
+
+ - Function: lax-plist-member LAX-PLIST PROP
+ This function returns `t' if PROP has a value specified in
+ LAX-PLIST.
+
+ In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
+non-`nil', then a property with a `nil' value is ignored or removed.
+This feature is a virus that has infected old Lisp implementations (and
+thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
+used except for backward compatibility.
+
+ - Function: lax-plists-eq A B &optional NIL-MEANS-NOT-PRESENT
+ This function returns non-`nil' if lax property lists A and B are
+ `eq' (i.e. their values are `eq'; their keys are still compared
+ using `equal').
+
+ - Function: lax-plists-equal A B &optional NIL-MEANS-NOT-PRESENT
+ This function returns non-`nil' if lax property lists A and B are
+ `equal' (i.e. their values are `equal').
+
+ - Function: canonicalize-lax-plist LAX-PLIST &optional
+ NIL-MEANS-NOT-PRESENT
+ This function destructively removes any duplicate entries from a
+ lax plist. In such cases, the first entry applies.
+
+ The new plist is returned. If NIL-MEANS-NOT-PRESENT is given, the
+ return value may not be `eq' to the passed-in value, so make sure
+ to `setq' the value back into where it came from.
+
+\1f
+File: lispref.info, Node: Converting Plists To/From Alists, Prev: Working With Lax Plists, Up: Property Lists
+
+Converting Plists To/From Alists
+--------------------------------
+
+ - Function: alist-to-plist ALIST
+ This function converts association list ALIST into the equivalent
+ property-list form. The plist is returned. This converts from
+
+ ((a . 1) (b . 2) (c . 3))
+
+ into
+
+ (a 1 b 2 c 3)
+
+ The original alist is not modified.
+
+ - Function: plist-to-alist PLIST
+ This function converts property list PLIST into the equivalent
+ association-list form. The alist is returned. This converts from
+
+ (a 1 b 2 c 3)
+
+ into
+
+ ((a . 1) (b . 2) (c . 3))
+
+ The original plist is not modified.
+
+ The following two functions are equivalent to the preceding two
+except that they destructively modify their arguments, using cons cells
+from the original list to form the new list rather than allocating new
+cons cells.
+
+ - Function: destructive-alist-to-plist ALIST
+ This function destructively converts association list ALIST into
+ the equivalent property-list form. The plist is returned.
+
+ - Function: destructive-plist-to-alist PLIST
+ This function destructively converts property list PLIST into the
+ equivalent association-list form. The alist is returned.
+
+\1f
+File: lispref.info, Node: Weak Lists, Prev: Property Lists, Up: Lists
+
+Weak Lists
+==========
+
+ A "weak list" is a special sort of list whose members are not counted
+as references for the purpose of garbage collection. This means that,
+for any object in the list, if there are no references to the object
+anywhere outside of the list (or other weak list or weak hash table),
+that object will disappear the next time a garbage collection happens.
+Weak lists can be useful for keeping track of things such as unobtrusive
+lists of another function's buffers or markers. When that function is
+done with the elements, they will automatically disappear from the list.
+
+ Weak lists are used internally, for example, to manage the list
+holding the children of an extent - an extent that is unused but has a
+parent will still be reclaimed, and will automatically be removed from
+its parent's list of children.
+
+ Weak lists are similar to weak hash tables (*note Weak Hash
+Tables::.).
+
+ - Function: weak-list-p OBJECT
+ This function returns non-`nil' if OBJECT is a weak list.
+
+ Weak lists come in one of four types:
+
+`simple'
+ Objects in the list disappear if not referenced outside of the
+ list.
+
+`assoc'
+ Objects in the list disappear if they are conses and either the
+ car or the cdr of the cons is not referenced outside of the list.
+
+`key-assoc'
+ Objects in the list disappear if they are conses and the car is not
+ referenced outside of the list.
+
+`value-assoc'
+ Objects in the list disappear if they are conses and the cdr is not
+ referenced outside of the list.
+
+ - Function: make-weak-list &optional TYPE
+ This function creates a new weak list of type TYPE. TYPE is a
+ symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
+ as described above) and defaults to `simple'.
+
+ - Function: weak-list-type WEAK
+ This function returns the type of the given weak-list object.
+
+ - Function: weak-list-list WEAK
+ This function returns the list contained in a weak-list object.
+
+ - Function: set-weak-list-list WEAK NEW-LIST
+ This function changes the list contained in a weak-list object.
+
+\1f
+File: lispref.info, Node: Sequences Arrays Vectors, Next: Symbols, Prev: Lists, Up: Top
+
+Sequences, Arrays, and Vectors
+******************************
+
+ Recall that the "sequence" type is the union of four other Lisp
+types: lists, vectors, bit vectors, and strings. In other words, any
+list is a sequence, any vector is a sequence, any bit vector is a
+sequence, and any string is a sequence. The common property that all
+sequences have is that each is an ordered collection of elements.
+
+ An "array" is a single primitive object that has a slot for each
+elements. All the elements are accessible in constant time, but the
+length of an existing array cannot be changed. Strings, vectors, and
+bit vectors are the three types of arrays.
+
+ A list is a sequence of elements, but it is not a single primitive
+object; it is made of cons cells, one cell per element. Finding the
+Nth element requires looking through N cons cells, so elements farther
+from the beginning of the list take longer to access. But it is
+possible to add elements to the list, or remove elements.
+
+ The following diagram shows the relationship between these types:
+
+ ___________________________________
+ | |
+ | Sequence |
+ | ______ ______________________ |
+ | | | | | |
+ | | List | | Array | |
+ | | | | ________ _______ | |
+ | |______| | | | | | | |
+ | | | Vector | | String| | |
+ | | |________| |_______| | |
+ | | __________________ | |
+ | | | | | |
+ | | | Bit Vector | | |
+ | | |__________________| | |
+ | |______________________| |
+ |___________________________________|
+
+ The elements of vectors and lists may be any Lisp objects. The
+elements of strings are all characters. The elements of bit vectors
+are the numbers 0 and 1.
+
+* Menu:
+
+* Sequence Functions:: Functions that accept any kind of sequence.
+* Arrays:: Characteristics of arrays in XEmacs Lisp.
+* Array Functions:: Functions specifically for arrays.
+* Vectors:: Special characteristics of XEmacs Lisp vectors.
+* Vector Functions:: Functions specifically for vectors.
+* Bit Vectors:: Special characteristics of XEmacs Lisp bit vectors.
+* Bit Vector Functions:: Functions specifically for bit vectors.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors
+
+Sequences
+=========
+
+ In XEmacs Lisp, a "sequence" is either a list, a vector, a bit
+vector, or a string. The common property that all sequences have is
+that each is an ordered collection of elements. This section describes
+functions that accept any kind of sequence.
+
+ - Function: sequencep OBJECT
+ Returns `t' if OBJECT is a list, vector, bit vector, or string,
+ `nil' otherwise.
+
+ - Function: copy-sequence SEQUENCE
+ Returns a copy of SEQUENCE. The copy is the same type of object
+ as the original sequence, and it has the same elements in the same
+ order.
+
+ Storing a new element into the copy does not affect the original
+ SEQUENCE, and vice versa. However, the elements of the new
+ sequence are not copies; they are identical (`eq') to the elements
+ of the original. Therefore, changes made within these elements, as
+ found via the copied sequence, are also visible in the original
+ sequence.
+
+ If the sequence is a string with extents or text properties, the
+ extents and text properties in the copy are also copied, not
+ shared with the original. (This means that modifying the extents
+ or text properties of the original will not affect the copy.)
+ However, the actual values of the properties are shared. *Note
+ Extents::, *Note Text Properties::.
+
+ See also `append' in *Note Building Lists::, `concat' in *Note
+ Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
+ in *Note Bit Vectors::, for other ways to copy sequences.
+
+ (setq bar '(1 2))
+ => (1 2)
+ (setq x (vector 'foo bar))
+ => [foo (1 2)]
+ (setq y (copy-sequence x))
+ => [foo (1 2)]
+
+ (eq x y)
+ => nil
+ (equal x y)
+ => t
+ (eq (elt x 1) (elt y 1))
+ => t
+
+ ;; Replacing an element of one sequence.
+ (aset x 0 'quux)
+ x => [quux (1 2)]
+ y => [foo (1 2)]
+
+ ;; Modifying the inside of a shared element.
+ (setcar (aref x 1) 69)
+ x => [quux (69 2)]
+ y => [foo (69 2)]
+
+ ;; Creating a bit vector.
+ (bit-vector 1 0 1 1 0 1 0 0)
+ => #*10110100
+
+ - Function: length SEQUENCE
+ Returns the number of elements in SEQUENCE. If SEQUENCE is a cons
+ cell that is not a list (because the final CDR is not `nil'), a
+ `wrong-type-argument' error is signaled.
+
+ (length '(1 2 3))
+ => 3
+ (length ())
+ => 0
+ (length "foobar")
+ => 6
+ (length [1 2 3])
+ => 3
+ (length #*01101)
+ => 5
+
+ - Function: elt SEQUENCE INDEX
+ This function returns the element of SEQUENCE indexed by INDEX.
+ Legitimate values of INDEX are integers ranging from 0 up to one
+ less than the length of SEQUENCE. If SEQUENCE is a list, then
+ out-of-range values of INDEX return `nil'; otherwise, they trigger
+ an `args-out-of-range' error.
+
+ (elt [1 2 3 4] 2)
+ => 3
+ (elt '(1 2 3 4) 2)
+ => 3
+ (char-to-string (elt "1234" 2))
+ => "3"
+ (elt #*00010000 3)
+ => 1
+ (elt [1 2 3 4] 4)
+ error-->Args out of range: [1 2 3 4], 4
+ (elt [1 2 3 4] -1)
+ error-->Args out of range: [1 2 3 4], -1
+
+ This function generalizes `aref' (*note Array Functions::.) and
+ `nth' (*note List Elements::.).
+
+\1f
+File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors
+
+Arrays
+======
+
+ An "array" object has slots that hold a number of other Lisp
+objects, called the elements of the array. Any element of an array may
+be accessed in constant time. In contrast, an element of a list
+requires access time that is proportional to the position of the element
+in the list.
+
+ When you create an array, you must specify how many elements it has.
+The amount of space allocated depends on the number of elements.
+Therefore, it is impossible to change the size of an array once it is
+created; you cannot add or remove elements. However, you can replace an
+element with a different value.
+
+ XEmacs defines three types of array, all of which are
+one-dimensional: "strings", "vectors", and "bit vectors". A vector is a
+general array; its elements can be any Lisp objects. A string is a
+specialized array; its elements must be characters. A bit vector is
+another specialized array; its elements must be bits (an integer, either
+0 or 1). Each type of array has its own read syntax. *Note String
+Type::, *Note Vector Type::, and *Note Bit Vector Type::.
+
+ All kinds of array share these characteristics:
+
+ * The first element of an array has index zero, the second element
+ has index 1, and so on. This is called "zero-origin" indexing.
+ For example, an array of four elements has indices 0, 1, 2, and 3.
+
+ * The elements of an array may be referenced or changed with the
+ functions `aref' and `aset', respectively (*note Array
+ Functions::.).
+
+ In principle, if you wish to have an array of text characters, you
+could use either a string or a vector. In practice, we always choose
+strings for such applications, for four reasons:
+
+ * They usually occupy one-fourth the space of a vector of the same
+ elements. (This is one-eighth the space for 64-bit machines such
+ as the DEC Alpha, and may also be different when MULE support is
+ compiled into XEmacs.)
+
+ * Strings are printed in a way that shows the contents more clearly
+ as characters.
+
+ * Strings can hold extent and text properties. *Note Extents::,
+ *Note Text Properties::.
+
+ * Many of the specialized editing and I/O facilities of XEmacs
+ accept only strings. For example, you cannot insert a vector of
+ characters into a buffer the way you can insert a string. *Note
+ Strings and Characters::.
+
+ By contrast, for an array of keyboard input characters (such as a key
+sequence), a vector may be necessary, because many keyboard input
+characters are non-printable and are represented with symbols rather
+than with characters. *Note Key Sequence Input::.
+
+ Similarly, when representing an array of bits, a bit vector has the
+following advantages over a regular vector:
+
+ * They occupy 1/32nd the space of a vector of the same elements.
+ (1/64th on 64-bit machines such as the DEC Alpha.)
+
+ * Bit vectors are printed in a way that shows the contents more
+ clearly as bits.
+
+\1f
+File: lispref.info, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors
+
+Functions that Operate on Arrays
+================================
+
+ In this section, we describe the functions that accept strings,
+vectors, and bit vectors.
+
+ - Function: arrayp OBJECT
+ This function returns `t' if OBJECT is an array (i.e., a string,
+ vector, or bit vector).
+
+ (arrayp "asdf")
+ => t
+ (arrayp [a])
+ => t
+ (arrayp #*101)
+ => t
+
+ - Function: aref ARRAY INDEX
+ This function returns the INDEXth element of ARRAY. The first
+ element is at index zero.
+
+ (setq primes [2 3 5 7 11 13])
+ => [2 3 5 7 11 13]
+ (aref primes 4)
+ => 11
+ (elt primes 4)
+ => 11
+
+ (aref "abcdefg" 1)
+ => ?b
+
+ (aref #*1101 2)
+ => 0
+
+ See also the function `elt', in *Note Sequence Functions::.
+
+ - Function: aset ARRAY INDEX OBJECT
+ This function sets the INDEXth element of ARRAY to be OBJECT. It
+ returns OBJECT.
+
+ (setq w [foo bar baz])
+ => [foo bar baz]
+ (aset w 0 'fu)
+ => fu
+ w
+ => [fu bar baz]
+
+ (setq x "asdfasfd")
+ => "asdfasfd"
+ (aset x 3 ?Z)
+ => ?Z
+ x
+ => "asdZasfd"
+
+ (setq bv #*1111)
+ => #*1111
+ (aset bv 2 0)
+ => 0
+ bv
+ => #*1101
+
+ If ARRAY is a string and OBJECT is not a character, a
+ `wrong-type-argument' error results.
+
+ - Function: fillarray ARRAY OBJECT
+ This function fills the array ARRAY with OBJECT, so that each
+ element of ARRAY is OBJECT. It returns ARRAY.
+
+ (setq a [a b c d e f g])
+ => [a b c d e f g]
+ (fillarray a 0)
+ => [0 0 0 0 0 0 0]
+ a
+ => [0 0 0 0 0 0 0]
+
+ (setq s "When in the course")
+ => "When in the course"
+ (fillarray s ?-)
+ => "------------------"
+
+ (setq bv #*1101)
+ => #*1101
+ (fillarray bv 0)
+ => #*0000
+
+ If ARRAY is a string and OBJECT is not a character, a
+ `wrong-type-argument' error results.
+
+ The general sequence functions `copy-sequence' and `length' are
+often useful for objects known to be arrays. *Note Sequence
+Functions::.
+
+\1f
+File: lispref.info, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors
+
+Vectors
+=======
+
+ Arrays in Lisp, like arrays in most languages, are blocks of memory
+whose elements can be accessed in constant time. A "vector" is a
+general-purpose array; its elements can be any Lisp objects. (The other
+kind of array in XEmacs Lisp is the "string", whose elements must be
+characters.) Vectors in XEmacs serve as obarrays (vectors of symbols),
+although this is a shortcoming that should be fixed. They are also used
+internally as part of the representation of a byte-compiled function; if
+you print such a function, you will see a vector in it.
+
+ In XEmacs Lisp, the indices of the elements of a vector start from
+zero and count up from there.
+
+ Vectors are printed with square brackets surrounding the elements.
+Thus, a vector whose elements are the symbols `a', `b' and `a' is
+printed as `[a b a]'. You can write vectors in the same way in Lisp
+input.
+
+ A vector, like a string or a number, is considered a constant for
+evaluation: the result of evaluating it is the same vector. This does
+not evaluate or even examine the elements of the vector. *Note
+Self-Evaluating Forms::.
+
+ Here are examples of these principles:
+
+ (setq avector [1 two '(three) "four" [five]])
+ => [1 two (quote (three)) "four" [five]]
+ (eval avector)
+ => [1 two (quote (three)) "four" [five]]
+ (eq avector (eval avector))
+ => t
+
+\1f
+File: lispref.info, Node: Vector Functions, Next: Bit Vectors, Prev: Vectors, Up: Sequences Arrays Vectors
+
+Functions That Operate on Vectors
+=================================
+
+ Here are some functions that relate to vectors:
+
+ - Function: vectorp OBJECT
+ This function returns `t' if OBJECT is a vector.
+
+ (vectorp [a])
+ => t
+ (vectorp "asdf")
+ => nil
+
+ - Function: vector &rest OBJECTS
+ This function creates and returns a vector whose elements are the
+ arguments, OBJECTS.
+
+ (vector 'foo 23 [bar baz] "rats")
+ => [foo 23 [bar baz] "rats"]
+ (vector)
+ => []
+
+ - Function: make-vector LENGTH OBJECT
+ This function returns a new vector consisting of LENGTH elements,
+ each initialized to OBJECT.
+
+ (setq sleepy (make-vector 9 'Z))
+ => [Z Z Z Z Z Z Z Z Z]
+
+ - Function: vconcat &rest SEQUENCES
+ This function returns a new vector containing all the elements of
+ the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or
+ strings. If no SEQUENCES are given, an empty vector is returned.
+
+ The value is a newly constructed vector that is not `eq' to any
+ existing vector.
+
+ (setq a (vconcat '(A B C) '(D E F)))
+ => [A B C D E F]
+ (eq a (vconcat a))
+ => nil
+ (vconcat)
+ => []
+ (vconcat [A B C] "aa" '(foo (6 7)))
+ => [A B C 97 97 foo (6 7)]
+
+ The `vconcat' function also allows integers as arguments. It
+ converts them to strings of digits, making up the decimal print
+ representation of the integer, and then uses the strings instead
+ of the original integers. *Don't use this feature; we plan to
+ eliminate it. If you already use this feature, change your
+ programs now!* The proper way to convert an integer to a decimal
+ number in this way is with `format' (*note Formatting Strings::.)
+ or `number-to-string' (*note String Conversion::.).
+
+ For other concatenation functions, see `mapconcat' in *Note
+ Mapping Functions::, `concat' in *Note Creating Strings::, `append'
+ in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
+ Functions::.
+
+ The `append' function provides a way to convert a vector into a list
+with the same elements (*note Building Lists::.):
+
+ (setq avector [1 two (quote (three)) "four" [five]])
+ => [1 two (quote (three)) "four" [five]]
+ (append avector nil)
+ => (1 two (quote (three)) "four" [five])
+
+\1f
+File: lispref.info, Node: Bit Vectors, Next: Bit Vector Functions, Prev: Vector Functions, Up: Sequences Arrays Vectors
+
+Bit Vectors
+===========
+
+ Bit vectors are specialized vectors that can only represent arrays
+of 1's and 0's. Bit vectors have a very efficient representation and
+are useful for representing sets of boolean (true or false) values.
+
+ There is no limit on the size of a bit vector. You could, for
+example, create a bit vector with 100,000 elements if you really wanted
+to.
+
+ Bit vectors have a special printed representation consisting of `#*'
+followed by the bits of the vector. For example, a bit vector whose
+elements are 0, 1, 1, 0, and 1, respectively, is printed as
+
+ #*01101
+
+ Bit vectors are considered constants for evaluation, like vectors,
+strings, and numbers. *Note Self-Evaluating Forms::.
+
+\1f
+File: lispref.info, Node: Bit Vector Functions, Prev: Bit Vectors, Up: Sequences Arrays Vectors
+
+Functions That Operate on Bit Vectors
+=====================================
+
+ Here are some functions that relate to bit vectors:
+
+ - Function: bit-vector-p OBJECT
+ This function returns `t' if OBJECT is a bit vector.
+
+ (bit-vector-p #*01)
+ => t
+ (bit-vector-p [0 1])
+ => nil
+ (bit-vector-p "01")
+ => nil
+
+ - Function: bitp OBJECT
+ This function returns `t' if OBJECT is either 0 or 1.
+
+ - Function: bit-vector &rest OBJECTS
+ This function creates and returns a bit vector whose elements are
+ the arguments OBJECTS. The elements must be either of the two
+ integers 0 or 1.
+
+ (bit-vector 0 0 0 1 0 0 0 0 1 0)
+ => #*0001000010
+ (bit-vector)
+ => #*
+
+ - Function: make-bit-vector LENGTH OBJECT
+ This function creates and returns a bit vector consisting of
+ LENGTH elements, each initialized to OBJECT.
+
+ (setq picket-fence (make-bit-vector 9 1))
+ => #*111111111
+
+ - Function: bvconcat &rest SEQUENCES
+ This function returns a new bit vector containing all the elements
+ of the SEQUENCES. The arguments SEQUENCES may be lists, vectors,
+ or bit vectors, all of whose elements are the integers 0 or 1. If
+ no SEQUENCES are given, an empty bit vector is returned.
+
+ The value is a newly constructed bit vector that is not `eq' to any
+ existing bit vector.
+
+ (setq a (bvconcat '(1 1 0) '(0 0 1)))
+ => #*110001
+ (eq a (bvconcat a))
+ => nil
+ (bvconcat)
+ => #*
+ (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
+ => #*1000011100001
+
+ For other concatenation functions, see `mapconcat' in *Note
+ Mapping Functions::, `concat' in *Note Creating Strings::,
+ `vconcat' in *Note Vector Functions::, and `append' in *Note
+ Building Lists::.
+
+ The `append' function provides a way to convert a bit vector into a
+list with the same elements (*note Building Lists::.):
+
+ (setq bv #*00001110)
+ => #*00001110
+ (append bv nil)
+ => (0 0 0 0 1 1 1 0)
+
+\1f
+File: lispref.info, Node: Symbols, Next: Evaluation, Prev: Sequences Arrays Vectors, Up: Top
+
+Symbols
+*******
+
+ A "symbol" is an object with a unique name. This chapter describes
+symbols, their components, their property lists, and how they are
+created and interned. Separate chapters describe the use of symbols as
+variables and as function names; see *Note Variables::, and *Note
+Functions::. For the precise read syntax for symbols, see *Note Symbol
+Type::.
+
+ You can test whether an arbitrary Lisp object is a symbol with
+`symbolp':
+
+ - Function: symbolp OBJECT
+ This function returns `t' if OBJECT is a symbol, `nil' otherwise.
+
+* Menu:
+
+* Symbol Components:: Symbols have names, values, function definitions
+ and property lists.
+* Definitions:: A definition says how a symbol will be used.
+* Creating Symbols:: How symbols are kept unique.
+* Symbol Properties:: Each symbol has a property list
+ for recording miscellaneous information.
+
+\1f
+File: lispref.info, Node: Symbol Components, Next: Definitions, Up: Symbols
+
+Symbol Components
+=================
+
+ Each symbol has four components (or "cells"), each of which
+references another object:
+
+Print name
+ The "print name cell" holds a string that names the symbol for
+ reading and printing. See `symbol-name' in *Note Creating
+ Symbols::.
+
+Value
+ The "value cell" holds the current value of the symbol as a
+ variable. When a symbol is used as a form, the value of the form
+ is the contents of the symbol's value cell. See `symbol-value' in
+ *Note Accessing Variables::.
+
+Function
+ The "function cell" holds the function definition of the symbol.
+ When a symbol is used as a function, its function definition is
+ used in its place. This cell is also used to make a symbol stand
+ for a keymap or a keyboard macro, for editor command execution.
+ Because each symbol has separate value and function cells,
+ variables and function names do not conflict. See
+ `symbol-function' in *Note Function Cells::.
+
+Property list
+ The "property list cell" holds the property list of the symbol.
+ See `symbol-plist' in *Note Symbol Properties::.
+
+ The print name cell always holds a string, and cannot be changed.
+The other three cells can be set individually to any specified Lisp
+object.
+
+ The print name cell holds the string that is the name of the symbol.
+Since symbols are represented textually by their names, it is important
+not to have two symbols with the same name. The Lisp reader ensures
+this: every time it reads a symbol, it looks for an existing symbol with
+the specified name before it creates a new one. (In XEmacs Lisp, this
+lookup uses a hashing algorithm and an obarray; see *Note Creating
+Symbols::.)
+
+ In normal usage, the function cell usually contains a function or
+macro, as that is what the Lisp interpreter expects to see there (*note
+Evaluation::.). Keyboard macros (*note Keyboard Macros::.), keymaps
+(*note Keymaps::.) and autoload objects (*note Autoloading::.) are also
+sometimes stored in the function cell of symbols. We often refer to
+"the function `foo'" when we really mean the function stored in the
+function cell of the symbol `foo'. We make the distinction only when
+necessary.
+
+ The property list cell normally should hold a correctly formatted
+property list (*note Property Lists::.), as a number of functions expect
+to see a property list there.
+
+ The function cell or the value cell may be "void", which means that
+the cell does not reference any object. (This is not the same thing as
+holding the symbol `void', nor the same as holding the symbol `nil'.)
+Examining a cell that is void results in an error, such as `Symbol's
+value as variable is void'.
+
+ The four functions `symbol-name', `symbol-value', `symbol-plist',
+and `symbol-function' return the contents of the four cells of a
+symbol. Here as an example we show the contents of the four cells of
+the symbol `buffer-file-name':
+
+ (symbol-name 'buffer-file-name)
+ => "buffer-file-name"
+ (symbol-value 'buffer-file-name)
+ => "/gnu/elisp/symbols.texi"
+ (symbol-plist 'buffer-file-name)
+ => (variable-documentation 29529)
+ (symbol-function 'buffer-file-name)
+ => #<subr buffer-file-name>
+
+Because this symbol is the variable which holds the name of the file
+being visited in the current buffer, the value cell contents we see are
+the name of the source file of this chapter of the XEmacs Lisp Manual.
+The property list cell contains the list `(variable-documentation
+29529)' which tells the documentation functions where to find the
+documentation string for the variable `buffer-file-name' in the `DOC'
+file. (29529 is the offset from the beginning of the `DOC' file to
+where that documentation string begins.) The function cell contains
+the function for returning the name of the file. `buffer-file-name'
+names a primitive function, which has no read syntax and prints in hash
+notation (*note Primitive Function Type::.). A symbol naming a
+function written in Lisp would have a lambda expression (or a byte-code
+object) in this cell.
+
+\1f
+File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols
+
+Defining Symbols
+================
+
+ A "definition" in Lisp is a special form that announces your
+intention to use a certain symbol in a particular way. In XEmacs Lisp,
+you can define a symbol as a variable, or define it as a function (or
+macro), or both independently.
+
+ A definition construct typically specifies a value or meaning for the
+symbol for one kind of use, plus documentation for its meaning when used
+in this way. Thus, when you define a symbol as a variable, you can
+supply an initial value for the variable, plus documentation for the
+variable.
+
+ `defvar' and `defconst' are special forms that define a symbol as a
+global variable. They are documented in detail in *Note Defining
+Variables::.
+
+ `defun' defines a symbol as a function, creating a lambda expression
+and storing it in the function cell of the symbol. This lambda
+expression thus becomes the function definition of the symbol. (The
+term "function definition", meaning the contents of the function cell,
+is derived from the idea that `defun' gives the symbol its definition
+as a function.) `defsubst', `define-function' and `defalias' are other
+ways of defining a function. *Note Functions::.
+
+ `defmacro' defines a symbol as a macro. It creates a macro object
+and stores it in the function cell of the symbol. Note that a given
+symbol can be a macro or a function, but not both at once, because both
+macro and function definitions are kept in the function cell, and that
+cell can hold only one Lisp object at any given time. *Note Macros::.
+
+ In XEmacs Lisp, a definition is not required in order to use a symbol
+as a variable or function. Thus, you can make a symbol a global
+variable with `setq', whether you define it first or not. The real
+purpose of definitions is to guide programmers and programming tools.
+They inform programmers who read the code that certain symbols are
+*intended* to be used as variables, or as functions. In addition,
+utilities such as `etags' and `make-docfile' recognize definitions, and
+add appropriate information to tag tables and the `DOC' file. *Note
+Accessing Documentation::.
+
+\1f
+File: lispref.info, Node: Creating Symbols, Next: Symbol Properties, Prev: Definitions, Up: Symbols
+
+Creating and Interning Symbols
+==============================
+
+ To understand how symbols are created in XEmacs Lisp, you must know
+how Lisp reads them. Lisp must ensure that it finds the same symbol
+every time it reads the same set of characters. Failure to do so would
+cause complete confusion.
+
+ When the Lisp reader encounters a symbol, it reads all the characters
+of the name. Then it "hashes" those characters to find an index in a
+table called an "obarray". Hashing is an efficient method of looking
+something up. For example, instead of searching a telephone book cover
+to cover when looking up Jan Jones, you start with the J's and go from
+there. That is a simple version of hashing. Each element of the
+obarray is a "bucket" which holds all the symbols with a given hash
+code; to look for a given name, it is sufficient to look through all
+the symbols in the bucket for that name's hash code.
+
+ If a symbol with the desired name is found, the reader uses that
+symbol. If the obarray does not contain a symbol with that name, the
+reader makes a new symbol and adds it to the obarray. Finding or adding
+a symbol with a certain name is called "interning" it, and the symbol
+is then called an "interned symbol".
+
+ Interning ensures that each obarray has just one symbol with any
+particular name. Other like-named symbols may exist, but not in the
+same obarray. Thus, the reader gets the same symbols for the same
+names, as long as you keep reading with the same obarray.
+
+ No obarray contains all symbols; in fact, some symbols are not in any
+obarray. They are called "uninterned symbols". An uninterned symbol
+has the same four cells as other symbols; however, the only way to gain
+access to it is by finding it in some other object or as the value of a
+variable.
+
+ In XEmacs Lisp, an obarray is actually a vector. Each element of the
+vector is a bucket; its value is either an interned symbol whose name
+hashes to that bucket, or 0 if the bucket is empty. Each interned
+symbol has an internal link (invisible to the user) to the next symbol
+in the bucket. Because these links are invisible, there is no way to
+find all the symbols in an obarray except using `mapatoms' (below).
+The order of symbols in a bucket is not significant.
+
+ In an empty obarray, every element is 0, and you can create an
+obarray with `(make-vector LENGTH 0)'. *This is the only valid way to
+create an obarray.* Prime numbers as lengths tend to result in good
+hashing; lengths one less than a power of two are also good.
+
+ *Do not try to put symbols in an obarray yourself.* This does not
+work--only `intern' can enter a symbol in an obarray properly. *Do not
+try to intern one symbol in two obarrays.* This would garble both
+obarrays, because a symbol has just one slot to hold the following
+symbol in the obarray bucket. The results would be unpredictable.
+
+ It is possible for two different symbols to have the same name in
+different obarrays; these symbols are not `eq' or `equal'. However,
+this normally happens only as part of the abbrev mechanism (*note
+Abbrevs::.).
+
+ Common Lisp note: In Common Lisp, a single symbol may be interned
+ in several obarrays.
+
+ Most of the functions below take a name and sometimes an obarray as
+arguments. A `wrong-type-argument' error is signaled if the name is
+not a string, or if the obarray is not a vector.
+
+ - Function: symbol-name SYMBOL
+ This function returns the string that is SYMBOL's name. For
+ example:
+
+ (symbol-name 'foo)
+ => "foo"
+
+ Changing the string by substituting characters, etc, does change
+ the name of the symbol, but fails to update the obarray, so don't
+ do it!
+
+ - Function: make-symbol NAME
+ This function returns a newly-allocated, uninterned symbol whose
+ name is NAME (which must be a string). Its value and function
+ definition are void, and its property list is `nil'. In the
+ example below, the value of `sym' is not `eq' to `foo' because it
+ is a distinct uninterned symbol whose name is also `foo'.
+
+ (setq sym (make-symbol "foo"))
+ => foo
+ (eq sym 'foo)
+ => nil
+
+ - Function: intern NAME &optional OBARRAY
+ This function returns the interned symbol whose name is NAME. If
+ there is no such symbol in the obarray OBARRAY, `intern' creates a
+ new one, adds it to the obarray, and returns it. If OBARRAY is
+ omitted, the value of the global variable `obarray' is used.
+
+ (setq sym (intern "foo"))
+ => foo
+ (eq sym 'foo)
+ => t
+
+ (setq sym1 (intern "foo" other-obarray))
+ => foo
+ (eq sym 'foo)
+ => nil
+
+ - Function: intern-soft NAME &optional OBARRAY
+ This function returns the symbol in OBARRAY whose name is NAME, or
+ `nil' if OBARRAY has no symbol with that name. Therefore, you can
+ use `intern-soft' to test whether a symbol with a given name is
+ already interned. If OBARRAY is omitted, the value of the global
+ variable `obarray' is used.
+
+ (intern-soft "frazzle") ; No such symbol exists.
+ => nil
+ (make-symbol "frazzle") ; Create an uninterned one.
+ => frazzle
+ (intern-soft "frazzle") ; That one cannot be found.
+ => nil
+
+ (setq sym (intern "frazzle")) ; Create an interned one.
+ => frazzle
+
+ (intern-soft "frazzle") ; That one can be found!
+ => frazzle
+
+ (eq sym 'frazzle) ; And it is the same one.
+ => t
+
+ - Variable: obarray
+ This variable is the standard obarray for use by `intern' and
+ `read'.
+
+ - Function: mapatoms FUNCTION &optional OBARRAY
+ This function calls FUNCTION for each symbol in the obarray
+ OBARRAY. It returns `nil'. If OBARRAY is omitted, it defaults to
+ the value of `obarray', the standard obarray for ordinary symbols.
+
+ (setq count 0)
+ => 0
+ (defun count-syms (s)
+ (setq count (1+ count)))
+ => count-syms
+ (mapatoms 'count-syms)
+ => nil
+ count
+ => 1871
+
+ See `documentation' in *Note Accessing Documentation::, for another
+ example using `mapatoms'.
+
+ - Function: unintern SYMBOL &optional OBARRAY
+ This function deletes SYMBOL from the obarray OBARRAY. If
+ `symbol' is not actually in the obarray, `unintern' does nothing.
+ If OBARRAY is `nil', the current obarray is used.
+
+ If you provide a string instead of a symbol as SYMBOL, it stands
+ for a symbol name. Then `unintern' deletes the symbol (if any) in
+ the obarray which has that name. If there is no such symbol,
+ `unintern' does nothing.
+
+ If `unintern' does delete a symbol, it returns `t'. Otherwise it
+ returns `nil'.
+
+\1f
+File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symbols
+
+Symbol Properties
+=================
+
+ A "property list" ("plist" for short) is a list of paired elements
+stored in the property list cell of a symbol. Each of the pairs
+associates a property name (usually a symbol) with a property or value.
+Property lists are generally used to record information about a
+symbol, such as its documentation as a variable, the name of the file
+where it was defined, or perhaps even the grammatical class of the
+symbol (representing a word) in a language-understanding system.
+
+ Many objects other than symbols can have property lists associated
+with them, and XEmacs provides a full complement of functions for
+working with property lists. *Note Property Lists::.
+
+ The property names and values in a property list can be any Lisp
+objects, but the names are usually symbols. They are compared using
+`eq'. Here is an example of a property list, found on the symbol
+`progn' when the compiler is loaded:
+
+ (lisp-indent-function 0 byte-compile byte-compile-progn)
+
+Here `lisp-indent-function' and `byte-compile' are property names, and
+the other two elements are the corresponding values.
+
+* Menu:
+
+* Plists and Alists:: Comparison of the advantages of property
+ lists and association lists.
+* Symbol Plists:: Functions to access symbols' property lists.
+* Other Plists:: Accessing property lists stored elsewhere.
+
+\1f
+File: lispref.info, Node: Plists and Alists, Next: Symbol Plists, Up: Symbol Properties
+
+Property Lists and Association Lists
+------------------------------------
+
+ Association lists (*note Association Lists::.) are very similar to
+property lists. In contrast to association lists, the order of the
+pairs in the property list is not significant since the property names
+must be distinct.
+
+ Property lists are better than association lists for attaching
+information to various Lisp function names or variables. If all the
+associations are recorded in one association list, the program will need
+to search that entire list each time a function or variable is to be
+operated on. By contrast, if the information is recorded in the
+property lists of the function names or variables themselves, each
+search will scan only the length of one property list, which is usually
+short. This is why the documentation for a variable is recorded in a
+property named `variable-documentation'. The byte compiler likewise
+uses properties to record those functions needing special treatment.
+
+ However, association lists have their own advantages. Depending on
+your application, it may be faster to add an association to the front of
+an association list than to update a property. All properties for a
+symbol are stored in the same property list, so there is a possibility
+of a conflict between different uses of a property name. (For this
+reason, it is a good idea to choose property names that are probably
+unique, such as by including the name of the library in the property
+name.) An association list may be used like a stack where associations
+are pushed on the front of the list and later discarded; this is not
+possible with a property list.
+
+\1f
+File: lispref.info, Node: Symbol Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
+
+Property List Functions for Symbols
+-----------------------------------
+
+ - Function: symbol-plist SYMBOL
+ This function returns the property list of SYMBOL.
+
+ - Function: setplist SYMBOL PLIST
+ This function sets SYMBOL's property list to PLIST. Normally,
+ PLIST should be a well-formed property list, but this is not
+ enforced.
+
+ (setplist 'foo '(a 1 b (2 3) c nil))
+ => (a 1 b (2 3) c nil)
+ (symbol-plist 'foo)
+ => (a 1 b (2 3) c nil)
+
+ For symbols in special obarrays, which are not used for ordinary
+ purposes, it may make sense to use the property list cell in a
+ nonstandard fashion; in fact, the abbrev mechanism does so (*note
+ Abbrevs::.).
+
+ - Function: get SYMBOL PROPERTY
+ This function finds the value of the property named PROPERTY in
+ SYMBOL's property list. If there is no such property, `nil' is
+ returned. Thus, there is no distinction between a value of `nil'
+ and the absence of the property.
+
+ The name PROPERTY is compared with the existing property names
+ using `eq', so any object is a legitimate property.
+
+ See `put' for an example.
+
+ - Function: put SYMBOL PROPERTY VALUE
+ This function puts VALUE onto SYMBOL's property list under the
+ property name PROPERTY, replacing any previous property value.
+ The `put' function returns VALUE.
+
+ (put 'fly 'verb 'transitive)
+ =>'transitive
+ (put 'fly 'noun '(a buzzing little bug))
+ => (a buzzing little bug)
+ (get 'fly 'verb)
+ => transitive
+ (symbol-plist 'fly)
+ => (verb transitive noun (a buzzing little bug))
+
+\1f
+File: lispref.info, Node: Other Plists, Prev: Symbol Plists, Up: Symbol Properties
+
+Property Lists Outside Symbols
+------------------------------
+
+ These functions are useful for manipulating property lists that are
+stored in places other than symbols:
+
+ - Function: getf PLIST PROPERTY &optional DEFAULT
+ This returns the value of the PROPERTY property stored in the
+ property list PLIST. For example,
+
+ (getf '(foo 4) 'foo)
+ => 4
+
+ - Function: putf PLIST PROPERTY VALUE
+ This stores VALUE as the value of the PROPERTY property in the
+ property list PLIST. It may modify PLIST destructively, or it may
+ construct a new list structure without altering the old. The
+ function returns the modified property list, so you can store that
+ back in the place where you got PLIST. For example,
+
+ (setq my-plist '(bar t foo 4))
+ => (bar t foo 4)
+ (setq my-plist (putf my-plist 'foo 69))
+ => (bar t foo 69)
+ (setq my-plist (putf my-plist 'quux '(a)))
+ => (quux (a) bar t foo 5)
+
+ - Function: plists-eq A B
+ This function returns non-`nil' if property lists A and B are
+ `eq'. This means that the property lists have the same values for
+ all the same properties, where comparison between values is done
+ using `eq'.
+
+ - Function: plists-equal A B
+ This function returns non-`nil' if property lists A and B are
+ `equal'.
+
+ Both of the above functions do order-insensitive comparisons.
+
+ (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
+ => t
+ (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+ => nil
+ (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+ => t
+
+\1f
+File: lispref.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top
+
+Evaluation
+**********
+
+ The "evaluation" of expressions in XEmacs Lisp is performed by the
+"Lisp interpreter"--a program that receives a Lisp object as input and
+computes its "value as an expression". How it does this depends on the
+data type of the object, according to rules described in this chapter.
+The interpreter runs automatically to evaluate portions of your
+program, but can also be called explicitly via the Lisp primitive
+function `eval'.
+
+* Menu:
+
+* Intro Eval:: Evaluation in the scheme of things.
+* Eval:: How to invoke the Lisp interpreter explicitly.
+* Forms:: How various sorts of objects are evaluated.
+* Quoting:: Avoiding evaluation (to put constants in the program).
+
+\1f
+File: lispref.info, Node: Intro Eval, Next: Eval, Up: Evaluation
+
+Introduction to Evaluation
+==========================
+
+ The Lisp interpreter, or evaluator, is the program that computes the
+value of an expression that is given to it. When a function written in
+Lisp is called, the evaluator computes the value of the function by
+evaluating the expressions in the function body. Thus, running any
+Lisp program really means running the Lisp interpreter.
+
+ How the evaluator handles an object depends primarily on the data
+type of the object.
+
+ A Lisp object that is intended for evaluation is called an
+"expression" or a "form". The fact that expressions are data objects
+and not merely text is one of the fundamental differences between
+Lisp-like languages and typical programming languages. Any object can
+be evaluated, but in practice only numbers, symbols, lists and strings
+are evaluated very often.
+
+ It is very common to read a Lisp expression and then evaluate the
+expression, but reading and evaluation are separate activities, and
+either can be performed alone. Reading per se does not evaluate
+anything; it converts the printed representation of a Lisp object to the
+object itself. It is up to the caller of `read' whether this object is
+a form to be evaluated, or serves some entirely different purpose.
+*Note Input Functions::.
+
+ Do not confuse evaluation with command key interpretation. The
+editor command loop translates keyboard input into a command (an
+interactively callable function) using the active keymaps, and then
+uses `call-interactively' to invoke the command. The execution of the
+command itself involves evaluation if the command is written in Lisp,
+but that is not a part of command key interpretation itself. *Note
+Command Loop::.
+
+ Evaluation is a recursive process. That is, evaluation of a form may
+call `eval' to evaluate parts of the form. For example, evaluation of
+a function call first evaluates each argument of the function call, and
+then evaluates each form in the function body. Consider evaluation of
+the form `(car x)': the subform `x' must first be evaluated
+recursively, so that its value can be passed as an argument to the
+function `car'.
+
+ Evaluation of a function call ultimately calls the function specified
+in it. *Note Functions::. The execution of the function may itself
+work by evaluating the function definition; or the function may be a
+Lisp primitive implemented in C, or it may be a byte-compiled function
+(*note Byte Compilation::.).
+
+ The evaluation of forms takes place in a context called the
+"environment", which consists of the current values and bindings of all
+Lisp variables.(1) Whenever the form refers to a variable without
+creating a new binding for it, the value of the binding in the current
+environment is used. *Note Variables::.
+
+ Evaluation of a form may create new environments for recursive
+evaluation by binding variables (*note Local Variables::.). These
+environments are temporary and vanish by the time evaluation of the form
+is complete. The form may also make changes that persist; these changes
+are called "side effects". An example of a form that produces side
+effects is `(setq foo 1)'.
+
+ The details of what evaluation means for each kind of form are
+described below (*note Forms::.).
+
+ ---------- Footnotes ----------
+
+ (1) This definition of "environment" is specifically not intended to
+include all the data that can affect the result of a program.
+
+\1f
+File: lispref.info, Node: Eval, Next: Forms, Prev: Intro Eval, Up: Evaluation
+
+Eval
+====
+
+ Most often, forms are evaluated automatically, by virtue of their
+occurrence in a program being run. On rare occasions, you may need to
+write code that evaluates a form that is computed at run time, such as
+after reading a form from text being edited or getting one from a
+property list. On these occasions, use the `eval' function.
+
+ *Please note:* it is generally cleaner and more flexible to call
+functions that are stored in data structures, rather than to evaluate
+expressions stored in data structures. Using functions provides the
+ability to pass information to them as arguments.
+
+ The functions and variables described in this section evaluate forms,
+specify limits to the evaluation process, or record recently returned
+values. Loading a file also does evaluation (*note Loading::.).
+
+ - Function: eval FORM
+ This is the basic function for performing evaluation. It evaluates
+ FORM in the current environment and returns the result. How the
+ evaluation proceeds depends on the type of the object (*note
+ Forms::.).
+
+ Since `eval' is a function, the argument expression that appears
+ in a call to `eval' is evaluated twice: once as preparation before
+ `eval' is called, and again by the `eval' function itself. Here
+ is an example:
+
+ (setq foo 'bar)
+ => bar
+ (setq bar 'baz)
+ => baz
+ ;; `eval' receives argument `bar', which is the value of `foo'
+ (eval foo)
+ => baz
+ (eval 'foo)
+ => bar
+
+ The number of currently active calls to `eval' is limited to
+ `max-lisp-eval-depth' (see below).
+
+ - Command: eval-region START END &optional STREAM
+ This function evaluates the forms in the current buffer in the
+ region defined by the positions START and END. It reads forms from
+ the region and calls `eval' on them until the end of the region is
+ reached, or until an error is signaled and not handled.
+
+ If STREAM is supplied, `standard-output' is bound to it during the
+ evaluation.
+
+ You can use the variable `load-read-function' to specify a function
+ for `eval-region' to use instead of `read' for reading
+ expressions. *Note How Programs Do Loading::.
+
+ `eval-region' always returns `nil'.
+
+ - Command: eval-buffer BUFFER &optional STREAM
+ This is like `eval-region' except that it operates on the whole
+ contents of BUFFER.
+
+ - Variable: max-lisp-eval-depth
+ This variable defines the maximum depth allowed in calls to `eval',
+ `apply', and `funcall' before an error is signaled (with error
+ message `"Lisp nesting exceeds max-lisp-eval-depth"'). This counts
+ internal uses of those functions, such as for calling the functions
+ mentioned in Lisp expressions, and recursive evaluation of
+ function call arguments and function body forms.
+
+ This limit, with the associated error when it is exceeded, is one
+ way that Lisp avoids infinite recursion on an ill-defined function.
+
+ The default value of this variable is 500. If you set it to a
+ value less than 100, Lisp will reset it to 100 if the given value
+ is reached.
+
+ `max-specpdl-size' provides another limit on nesting. *Note Local
+ Variables::.
+
+ - Variable: values
+ The value of this variable is a list of the values returned by all
+ the expressions that were read from buffers (including the
+ minibuffer), evaluated, and printed. The elements are ordered
+ most recent first.
+
+ (setq x 1)
+ => 1
+ (list 'A (1+ 2) auto-save-default)
+ => (A 3 t)
+ values
+ => ((A 3 t) 1 ...)
+
+ This variable is useful for referring back to values of forms
+ recently evaluated. It is generally a bad idea to print the value
+ of `values' itself, since this may be very long. Instead, examine
+ particular elements, like this:
+
+ ;; Refer to the most recent evaluation result.
+ (nth 0 values)
+ => (A 3 t)
+ ;; That put a new element on,
+ ;; so all elements move back one.
+ (nth 1 values)
+ => (A 3 t)
+ ;; This gets the element that was next-to-most-recent
+ ;; before this example.
+ (nth 3 values)
+ => 1
+
+\1f
+File: lispref.info, Node: Forms, Next: Quoting, Prev: Eval, Up: Evaluation
+
+Kinds of Forms
+==============
+
+ A Lisp object that is intended to be evaluated is called a "form".
+How XEmacs evaluates a form depends on its data type. XEmacs has three
+different kinds of form that are evaluated differently: symbols, lists,
+and "all other types". This section describes all three kinds,
+starting with "all other types" which are self-evaluating forms.
+
+* Menu:
+
+* Self-Evaluating Forms:: Forms that evaluate to themselves.
+* Symbol Forms:: Symbols evaluate as variables.
+* Classifying Lists:: How to distinguish various sorts of list forms.
+* Function Indirection:: When a symbol appears as the car of a list,
+ we find the real function via the symbol.
+* Function Forms:: Forms that call functions.
+* Macro Forms:: Forms that call macros.
+* Special Forms:: "Special forms" are idiosyncratic primitives,
+ most of them extremely important.
+* Autoloading:: Functions set up to load files
+ containing their real definitions.
+
+\1f
+File: lispref.info, Node: Self-Evaluating Forms, Next: Symbol Forms, Up: Forms
+
+Self-Evaluating Forms
+---------------------
+
+ A "self-evaluating form" is any form that is not a list or symbol.
+Self-evaluating forms evaluate to themselves: the result of evaluation
+is the same object that was evaluated. Thus, the number 25 evaluates to
+25, and the string `"foo"' evaluates to the string `"foo"'. Likewise,
+evaluation of a vector does not cause evaluation of the elements of the
+vector--it returns the same vector with its contents unchanged.
+
+ '123 ; An object, shown without evaluation.
+ => 123
+ 123 ; Evaluated as usual--result is the same.
+ => 123
+ (eval '123) ; Evaluated "by hand"--result is the same.
+ => 123
+ (eval (eval '123)) ; Evaluating twice changes nothing.
+ => 123
+
+ It is common to write numbers, characters, strings, and even vectors
+in Lisp code, taking advantage of the fact that they self-evaluate.
+However, it is quite unusual to do this for types that lack a read
+syntax, because there's no way to write them textually. It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program. Here is an example:
+
+ ;; Build an expression containing a buffer object.
+ (setq buffer (list 'print (current-buffer)))
+ => (print #<buffer eval.texi>)
+ ;; Evaluate it.
+ (eval buffer)
+ -| #<buffer eval.texi>
+ => #<buffer eval.texi>
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Symbol Forms, Next: Classifying Lists, Prev: Self-Evaluating Forms, Up: Forms
+
+Symbol Forms
+------------
+
+ When a symbol is evaluated, it is treated as a variable. The result
+is the variable's value, if it has one. If it has none (if its value
+cell is void), an error is signaled. For more information on the use of
+variables, see *Note Variables::.
+
+ In the following example, we set the value of a symbol with `setq'.
+Then we evaluate the symbol, and get back the value that `setq' stored.
+
+ (setq a 123)
+ => 123
+ (eval 'a)
+ => 123
+ a
+ => 123
+
+ The symbols `nil' and `t' are treated specially, so that the value
+of `nil' is always `nil', and the value of `t' is always `t'; you
+cannot set or bind them to any other values. Thus, these two symbols
+act like self-evaluating forms, even though `eval' treats them like any
+other symbol.
+
+\1f
+File: lispref.info, Node: Classifying Lists, Next: Function Indirection, Prev: Symbol Forms, Up: Forms
+
+Classification of List Forms
+----------------------------
+
+ A form that is a nonempty list is either a function call, a macro
+call, or a special form, according to its first element. These three
+kinds of forms are evaluated in different ways, described below. The
+remaining list elements constitute the "arguments" for the function,
+macro, or special form.
+
+ The first step in evaluating a nonempty list is to examine its first
+element. This element alone determines what kind of form the list is
+and how the rest of the list is to be processed. The first element is
+*not* evaluated, as it would be in some Lisp dialects such as Scheme.
+
+\1f
+File: lispref.info, Node: Function Indirection, Next: Function Forms, Prev: Classifying Lists, Up: Forms
+
+Symbol Function Indirection
+---------------------------
+
+ If the first element of the list is a symbol then evaluation examines
+the symbol's function cell, and uses its contents instead of the
+original symbol. If the contents are another symbol, this process,
+called "symbol function indirection", is repeated until it obtains a
+non-symbol. *Note Function Names::, for more information about using a
+symbol as a name for a function stored in the function cell of the
+symbol.
+
+ One possible consequence of this process is an infinite loop, in the
+event that a symbol's function cell refers to the same symbol. Or a
+symbol may have a void function cell, in which case the subroutine
+`symbol-function' signals a `void-function' error. But if neither of
+these things happens, we eventually obtain a non-symbol, which ought to
+be a function or other suitable object.
+
+ More precisely, we should now have a Lisp function (a lambda
+expression), a byte-code function, a primitive function, a Lisp macro, a
+special form, or an autoload object. Each of these types is a case
+described in one of the following sections. If the object is not one of
+these types, the error `invalid-function' is signaled.
+
+ The following example illustrates the symbol indirection process. We
+use `fset' to set the function cell of a symbol and `symbol-function'
+to get the function cell contents (*note Function Cells::.).
+Specifically, we store the symbol `car' into the function cell of
+`first', and the symbol `first' into the function cell of `erste'.
+
+ ;; Build this function cell linkage:
+ ;; ------------- ----- ------- -------
+ ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
+ ;; ------------- ----- ------- -------
+
+ (symbol-function 'car)
+ => #<subr car>
+
+ (fset 'first 'car)
+ => car
+
+ (fset 'erste 'first)
+ => first
+
+ (erste '(1 2 3)) ; Call the function referenced by `erste'.
+ => 1
+
+ By contrast, the following example calls a function without any
+symbol function indirection, because the first element is an anonymous
+Lisp function, not a symbol.
+
+ ((lambda (arg) (erste arg))
+ '(1 2 3))
+ => 1
+
+Executing the function itself evaluates its body; this does involve
+symbol function indirection when calling `erste'.
+
+ The built-in function `indirect-function' provides an easy way to
+perform symbol function indirection explicitly.
+
+ - Function: indirect-function FUNCTION
+ This function returns the meaning of FUNCTION as a function. If
+ FUNCTION is a symbol, then it finds FUNCTION's function definition
+ and starts over with that value. If FUNCTION is not a symbol,
+ then it returns FUNCTION itself.
+
+ Here is how you could define `indirect-function' in Lisp:
+
+ (defun indirect-function (function)
+ (if (symbolp function)
+ (indirect-function (symbol-function function))
+ function))
+
+\1f
+File: lispref.info, Node: Function Forms, Next: Macro Forms, Prev: Function Indirection, Up: Forms
+
+Evaluation of Function Forms
+----------------------------
+
+ If the first element of a list being evaluated is a Lisp function
+object, byte-code object or primitive function object, then that list is
+a "function call". For example, here is a call to the function `+':
+
+ (+ 1 x)
+
+ The first step in evaluating a function call is to evaluate the
+remaining elements of the list from left to right. The results are the
+actual argument values, one value for each list element. The next step
+is to call the function with this list of arguments, effectively using
+the function `apply' (*note Calling Functions::.). If the function is
+written in Lisp, the arguments are used to bind the argument variables
+of the function (*note Lambda Expressions::.); then the forms in the
+function body are evaluated in order, and the value of the last body
+form becomes the value of the function call.
+
+\1f
+File: lispref.info, Node: Macro Forms, Next: Special Forms, Prev: Function Forms, Up: Forms
+
+Lisp Macro Evaluation
+---------------------
+
+ If the first element of a list being evaluated is a macro object,
+then the list is a "macro call". When a macro call is evaluated, the
+elements of the rest of the list are *not* initially evaluated.
+Instead, these elements themselves are used as the arguments of the
+macro. The macro definition computes a replacement form, called the
+"expansion" of the macro, to be evaluated in place of the original
+form. The expansion may be any sort of form: a self-evaluating
+constant, a symbol, or a list. If the expansion is itself a macro call,
+this process of expansion repeats until some other sort of form results.
+
+ Ordinary evaluation of a macro call finishes by evaluating the
+expansion. However, the macro expansion is not necessarily evaluated
+right away, or at all, because other programs also expand macro calls,
+and they may or may not evaluate the expansions.
+
+ Normally, the argument expressions are not evaluated as part of
+computing the macro expansion, but instead appear as part of the
+expansion, so they are computed when the expansion is computed.
+
+ For example, given a macro defined as follows:
+
+ (defmacro cadr (x)
+ (list 'car (list 'cdr x)))
+
+an expression such as `(cadr (assq 'handler list))' is a macro call,
+and its expansion is:
+
+ (car (cdr (assq 'handler list)))
+
+Note that the argument `(assq 'handler list)' appears in the expansion.
+
+ *Note Macros::, for a complete description of XEmacs Lisp macros.
+
+\1f
+File: lispref.info, Node: Special Forms, Next: Autoloading, Prev: Macro Forms, Up: Forms
+
+Special Forms
+-------------
+
+ A "special form" is a primitive function specially marked so that
+its arguments are not all evaluated. Most special forms define control
+structures or perform variable bindings--things which functions cannot
+do.
+
+ Each special form has its own rules for which arguments are evaluated
+and which are used without evaluation. Whether a particular argument is
+evaluated may depend on the results of evaluating other arguments.
+
+ Here is a list, in alphabetical order, of all of the special forms in
+XEmacs Lisp with a reference to where each is described.
+
+`and'
+ *note Combining Conditions::.
+
+`catch'
+ *note Catch and Throw::.
+
+`cond'
+ *note Conditionals::.
+
+`condition-case'
+ *note Handling Errors::.
+
+`defconst'
+ *note Defining Variables::.
+
+`defmacro'
+ *note Defining Macros::.
+
+`defun'
+ *note Defining Functions::.
+
+`defvar'
+ *note Defining Variables::.
+
+`function'
+ *note Anonymous Functions::.
+
+`if'
+ *note Conditionals::.
+
+`interactive'
+ *note Interactive Call::.
+
+`let'
+`let*'
+ *note Local Variables::.
+
+`or'
+ *note Combining Conditions::.
+
+`prog1'
+`prog2'
+`progn'
+ *note Sequencing::.
+
+`quote'
+ *note Quoting::.
+
+`save-current-buffer'
+ *note Excursions::.
+
+`save-excursion'
+ *note Excursions::.
+
+`save-restriction'
+ *note Narrowing::.
+
+`save-selected-window'
+ *note Excursions::.
+
+`save-window-excursion'
+ *note Window Configurations::.
+
+`setq'
+ *note Setting Variables::.
+
+`setq-default'
+ *note Creating Buffer-Local::.
+
+`unwind-protect'
+ *note Nonlocal Exits::.
+
+`while'
+ *note Iteration::.
+
+`with-output-to-temp-buffer'
+ *note Temporary Displays::.
+
+ Common Lisp note: here are some comparisons of special forms in
+ XEmacs Lisp and Common Lisp. `setq', `if', and `catch' are
+ special forms in both XEmacs Lisp and Common Lisp. `defun' is a
+ special form in XEmacs Lisp, but a macro in Common Lisp.
+ `save-excursion' is a special form in XEmacs Lisp, but doesn't
+ exist in Common Lisp. `throw' is a special form in Common Lisp
+ (because it must be able to throw multiple values), but it is a
+ function in XEmacs Lisp (which doesn't have multiple values).
+
+\1f
+File: lispref.info, Node: Autoloading, Prev: Special Forms, Up: Forms
+
+Autoloading
+-----------
+
+ The "autoload" feature allows you to call a function or macro whose
+function definition has not yet been loaded into XEmacs. It specifies
+which file contains the definition. When an autoload object appears as
+a symbol's function definition, calling that symbol as a function
+automatically loads the specified file; then it calls the real
+definition loaded from that file. *Note Autoload::.
+
+\1f
+File: lispref.info, Node: Quoting, Prev: Forms, Up: Evaluation
+
+Quoting
+=======
+
+ The special form `quote' returns its single argument, as written,
+without evaluating it. This provides a way to include constant symbols
+and lists, which are not self-evaluating objects, in a program. (It is
+not necessary to quote self-evaluating objects such as numbers, strings,
+and vectors.)
+
+ - Special Form: quote OBJECT
+ This special form returns OBJECT, without evaluating it.
+
+ Because `quote' is used so often in programs, Lisp provides a
+convenient read syntax for it. An apostrophe character (`'') followed
+by a Lisp object (in read syntax) expands to a list whose first element
+is `quote', and whose second element is the object. Thus, the read
+syntax `'x' is an abbreviation for `(quote x)'.
+
+ Here are some examples of expressions that use `quote':
+
+ (quote (+ 1 2))
+ => (+ 1 2)
+ (quote foo)
+ => foo
+ 'foo
+ => foo
+ ''foo
+ => (quote foo)
+ '(quote foo)
+ => (quote foo)
+ ['foo]
+ => [(quote foo)]
+
+ Other quoting constructs include `function' (*note Anonymous
+Functions::.), which causes an anonymous lambda expression written in
+Lisp to be compiled, and ``' (*note Backquote::.), which is used to
+quote only part of a list, while computing and substituting other parts.
+
+\1f
+File: lispref.info, Node: Control Structures, Next: Variables, Prev: Evaluation, Up: Top
+
+Control Structures
+******************
+
+ A Lisp program consists of expressions or "forms" (*note Forms::.).
+We control the order of execution of the forms by enclosing them in
+"control structures". Control structures are special forms which
+control when, whether, or how many times to execute the forms they
+contain.
+
+ The simplest order of execution is sequential execution: first form
+A, then form B, and so on. This is what happens when you write several
+forms in succession in the body of a function, or at top level in a
+file of Lisp code--the forms are executed in the order written. We
+call this "textual order". For example, if a function body consists of
+two forms A and B, evaluation of the function evaluates first A and
+then B, and the function's value is the value of B.
+
+ Explicit control structures make possible an order of execution other
+than sequential.
+
+ XEmacs Lisp provides several kinds of control structure, including
+other varieties of sequencing, conditionals, iteration, and (controlled)
+jumps--all discussed below. The built-in control structures are
+special forms since their subforms are not necessarily evaluated or not
+evaluated sequentially. You can use macros to define your own control
+structure constructs (*note Macros::.).
+
+* Menu:
+
+* Sequencing:: Evaluation in textual order.
+* Conditionals:: `if', `cond'.
+* Combining Conditions:: `and', `or', `not'.
+* Iteration:: `while' loops.
+* Nonlocal Exits:: Jumping out of a sequence.
+
+\1f
+File: lispref.info, Node: Sequencing, Next: Conditionals, Up: Control Structures
+
+Sequencing
+==========
+
+ Evaluating forms in the order they appear is the most common way
+control passes from one form to another. In some contexts, such as in a
+function body, this happens automatically. Elsewhere you must use a
+control structure construct to do this: `progn', the simplest control
+construct of Lisp.
+
+ A `progn' special form looks like this:
+
+ (progn A B C ...)
+
+and it says to execute the forms A, B, C and so on, in that order.
+These forms are called the body of the `progn' form. The value of the
+last form in the body becomes the value of the entire `progn'.
+
+ In the early days of Lisp, `progn' was the only way to execute two
+or more forms in succession and use the value of the last of them. But
+programmers found they often needed to use a `progn' in the body of a
+function, where (at that time) only one form was allowed. So the body
+of a function was made into an "implicit `progn'": several forms are
+allowed just as in the body of an actual `progn'. Many other control
+structures likewise contain an implicit `progn'. As a result, `progn'
+is not used as often as it used to be. It is needed now most often
+inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
+
+ - Special Form: progn FORMS...
+ This special form evaluates all of the FORMS, in textual order,
+ returning the result of the final form.
+
+ (progn (print "The first form")
+ (print "The second form")
+ (print "The third form"))
+ -| "The first form"
+ -| "The second form"
+ -| "The third form"
+ => "The third form"
+
+ Two other control constructs likewise evaluate a series of forms but
+return a different value:
+
+ - Special Form: prog1 FORM1 FORMS...
+ This special form evaluates FORM1 and all of the FORMS, in textual
+ order, returning the result of FORM1.
+
+ (prog1 (print "The first form")
+ (print "The second form")
+ (print "The third form"))
+ -| "The first form"
+ -| "The second form"
+ -| "The third form"
+ => "The first form"
+
+ Here is a way to remove the first element from a list in the
+ variable `x', then return the value of that former element:
+
+ (prog1 (car x) (setq x (cdr x)))
+
+ - Special Form: prog2 FORM1 FORM2 FORMS...
+ This special form evaluates FORM1, FORM2, and all of the following
+ FORMS, in textual order, returning the result of FORM2.
+
+ (prog2 (print "The first form")
+ (print "The second form")
+ (print "The third form"))
+ -| "The first form"
+ -| "The second form"
+ -| "The third form"
+ => "The second form"
+
+\1f
+File: lispref.info, Node: Conditionals, Next: Combining Conditions, Prev: Sequencing, Up: Control Structures
+
+Conditionals
+============
+
+ Conditional control structures choose among alternatives. XEmacs
+Lisp has two conditional forms: `if', which is much the same as in other
+languages, and `cond', which is a generalized case statement.
+
+ - Special Form: if CONDITION THEN-FORM ELSE-FORMS...
+ `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
+ value of CONDITION. If the evaluated CONDITION is non-`nil',
+ THEN-FORM is evaluated and the result returned. Otherwise, the
+ ELSE-FORMS are evaluated in textual order, and the value of the
+ last one is returned. (The ELSE part of `if' is an example of an
+ implicit `progn'. *Note Sequencing::.)
+
+ If CONDITION has the value `nil', and no ELSE-FORMS are given,
+ `if' returns `nil'.
+
+ `if' is a special form because the branch that is not selected is
+ never evaluated--it is ignored. Thus, in the example below,
+ `true' is not printed because `print' is never called.
+
+ (if nil
+ (print 'true)
+ 'very-false)
+ => very-false
+
+ - Special Form: cond CLAUSE...
+ `cond' chooses among an arbitrary number of alternatives. Each
+ CLAUSE in the `cond' must be a list. The CAR of this list is the
+ CONDITION; the remaining elements, if any, the BODY-FORMS. Thus,
+ a clause looks like this:
+
+ (CONDITION BODY-FORMS...)
+
+ `cond' tries the clauses in textual order, by evaluating the
+ CONDITION of each clause. If the value of CONDITION is non-`nil',
+ the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
+ the value of the last of BODY-FORMS becomes the value of the
+ `cond'. The remaining clauses are ignored.
+
+ If the value of CONDITION is `nil', the clause "fails", so the
+ `cond' moves on to the following clause, trying its CONDITION.
+
+ If every CONDITION evaluates to `nil', so that every clause fails,
+ `cond' returns `nil'.
+
+ A clause may also look like this:
+
+ (CONDITION)
+
+ Then, if CONDITION is non-`nil' when tested, the value of
+ CONDITION becomes the value of the `cond' form.
+
+ The following example has four clauses, which test for the cases
+ where the value of `x' is a number, string, buffer and symbol,
+ respectively:
+
+ (cond ((numberp x) x)
+ ((stringp x) x)
+ ((bufferp x)
+ (setq temporary-hack x) ; multiple body-forms
+ (buffer-name x)) ; in one clause
+ ((symbolp x) (symbol-value x)))
+
+ Often we want to execute the last clause whenever none of the
+ previous clauses was successful. To do this, we use `t' as the
+ CONDITION of the last clause, like this: `(t BODY-FORMS)'. The
+ form `t' evaluates to `t', which is never `nil', so this clause
+ never fails, provided the `cond' gets to it at all.
+
+ For example,
+
+ (cond ((eq a 'hack) 'foo)
+ (t "default"))
+ => "default"
+
+ This expression is a `cond' which returns `foo' if the value of
+ `a' is 1, and returns the string `"default"' otherwise.
+
+ Any conditional construct can be expressed with `cond' or with `if'.
+Therefore, the choice between them is a matter of style. For example:
+
+ (if A B C)
+ ==
+ (cond (A B) (t C))
+
+\1f
+File: lispref.info, Node: Combining Conditions, Next: Iteration, Prev: Conditionals, Up: Control Structures
+
+Constructs for Combining Conditions
+===================================
+
+ This section describes three constructs that are often used together
+with `if' and `cond' to express complicated conditions. The constructs
+`and' and `or' can also be used individually as kinds of multiple
+conditional constructs.
+
+ - Function: not CONDITION
+ This function tests for the falsehood of CONDITION. It returns
+ `t' if CONDITION is `nil', and `nil' otherwise. The function
+ `not' is identical to `null', and we recommend using the name
+ `null' if you are testing for an empty list.
+
+ - Special Form: and CONDITIONS...
+ The `and' special form tests whether all the CONDITIONS are true.
+ It works by evaluating the CONDITIONS one by one in the order
+ written.
+
+ If any of the CONDITIONS evaluates to `nil', then the result of
+ the `and' must be `nil' regardless of the remaining CONDITIONS; so
+ `and' returns right away, ignoring the remaining CONDITIONS.
+
+ If all the CONDITIONS turn out non-`nil', then the value of the
+ last of them becomes the value of the `and' form.
+
+ Here is an example. The first condition returns the integer 1,
+ which is not `nil'. Similarly, the second condition returns the
+ integer 2, which is not `nil'. The third condition is `nil', so
+ the remaining condition is never evaluated.
+
+ (and (print 1) (print 2) nil (print 3))
+ -| 1
+ -| 2
+ => nil
+
+ Here is a more realistic example of using `and':
+
+ (if (and (consp foo) (eq (car foo) 'x))
+ (message "foo is a list starting with x"))
+
+ Note that `(car foo)' is not executed if `(consp foo)' returns
+ `nil', thus avoiding an error.
+
+ `and' can be expressed in terms of either `if' or `cond'. For
+ example:
+
+ (and ARG1 ARG2 ARG3)
+ ==
+ (if ARG1 (if ARG2 ARG3))
+ ==
+ (cond (ARG1 (cond (ARG2 ARG3))))
+
+ - Special Form: or CONDITIONS...
+ The `or' special form tests whether at least one of the CONDITIONS
+ is true. It works by evaluating all the CONDITIONS one by one in
+ the order written.
+
+ If any of the CONDITIONS evaluates to a non-`nil' value, then the
+ result of the `or' must be non-`nil'; so `or' returns right away,
+ ignoring the remaining CONDITIONS. The value it returns is the
+ non-`nil' value of the condition just evaluated.
+
+ If all the CONDITIONS turn out `nil', then the `or' expression
+ returns `nil'.
+
+ For example, this expression tests whether `x' is either 0 or
+ `nil':
+
+ (or (eq x nil) (eq x 0))
+
+ Like the `and' construct, `or' can be written in terms of `cond'.
+ For example:
+
+ (or ARG1 ARG2 ARG3)
+ ==
+ (cond (ARG1)
+ (ARG2)
+ (ARG3))
+
+ You could almost write `or' in terms of `if', but not quite:
+
+ (if ARG1 ARG1
+ (if ARG2 ARG2
+ ARG3))
+
+ This is not completely equivalent because it can evaluate ARG1 or
+ ARG2 twice. By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
+ any argument more than once.
+
+\1f
+File: lispref.info, Node: Iteration, Next: Nonlocal Exits, Prev: Combining Conditions, Up: Control Structures
+
+Iteration
+=========
+
+ Iteration means executing part of a program repetitively. For
+example, you might want to repeat some computation once for each element
+of a list, or once for each integer from 0 to N. You can do this in
+XEmacs Lisp with the special form `while':
+
+ - Special Form: while CONDITION FORMS...
+ `while' first evaluates CONDITION. If the result is non-`nil', it
+ evaluates FORMS in textual order. Then it reevaluates CONDITION,
+ and if the result is non-`nil', it evaluates FORMS again. This
+ process repeats until CONDITION evaluates to `nil'.
+
+ There is no limit on the number of iterations that may occur. The
+ loop will continue until either CONDITION evaluates to `nil' or
+ until an error or `throw' jumps out of it (*note Nonlocal
+ Exits::.).
+
+ The value of a `while' form is always `nil'.
+
+ (setq num 0)
+ => 0
+ (while (< num 4)
+ (princ (format "Iteration %d." num))
+ (setq num (1+ num)))
+ -| Iteration 0.
+ -| Iteration 1.
+ -| Iteration 2.
+ -| Iteration 3.
+ => nil
+
+ If you would like to execute something on each iteration before the
+ end-test, put it together with the end-test in a `progn' as the
+ first argument of `while', as shown here:
+
+ (while (progn
+ (forward-line 1)
+ (not (looking-at "^$"))))
+
+ This moves forward one line and continues moving by lines until it
+ reaches an empty. It is unusual in that the `while' has no body,
+ just the end test (which also does the real work of moving point).
+
+\1f
+File: lispref.info, Node: Nonlocal Exits, Prev: Iteration, Up: Control Structures
+
+Nonlocal Exits
+==============
+
+ A "nonlocal exit" is a transfer of control from one point in a
+program to another remote point. Nonlocal exits can occur in XEmacs
+Lisp as a result of errors; you can also use them under explicit
+control. Nonlocal exits unbind all variable bindings made by the
+constructs being exited.
+
+* Menu:
+
+* Catch and Throw:: Nonlocal exits for the program's own purposes.
+* Examples of Catch:: Showing how such nonlocal exits can be written.
+* Errors:: How errors are signaled and handled.
+* Cleanups:: Arranging to run a cleanup form if an error happens.
+
+\1f
+File: lispref.info, Node: Catch and Throw, Next: Examples of Catch, Up: Nonlocal Exits
+
+Explicit Nonlocal Exits: `catch' and `throw'
+--------------------------------------------
+
+ Most control constructs affect only the flow of control within the
+construct itself. The function `throw' is the exception to this rule
+of normal program execution: it performs a nonlocal exit on request.
+(There are other exceptions, but they are for error handling only.)
+`throw' is used inside a `catch', and jumps back to that `catch'. For
+example:
+
+ (catch 'foo
+ (progn
+ ...
+ (throw 'foo t)
+ ...))
+
+The `throw' transfers control straight back to the corresponding
+`catch', which returns immediately. The code following the `throw' is
+not executed. The second argument of `throw' is used as the return
+value of the `catch'.
+
+ The `throw' and the `catch' are matched through the first argument:
+`throw' searches for a `catch' whose first argument is `eq' to the one
+specified. Thus, in the above example, the `throw' specifies `foo',
+and the `catch' specifies the same symbol, so that `catch' is
+applicable. If there is more than one applicable `catch', the
+innermost one takes precedence.
+
+ Executing `throw' exits all Lisp constructs up to the matching
+`catch', including function calls. When binding constructs such as
+`let' or function calls are exited in this way, the bindings are
+unbound, just as they are when these constructs exit normally (*note
+Local Variables::.). Likewise, `throw' restores the buffer and
+position saved by `save-excursion' (*note Excursions::.), and the
+narrowing status saved by `save-restriction' and the window selection
+saved by `save-window-excursion' (*note Window Configurations::.). It
+also runs any cleanups established with the `unwind-protect' special
+form when it exits that form (*note Cleanups::.).
+
+ The `throw' need not appear lexically within the `catch' that it
+jumps to. It can equally well be called from another function called
+within the `catch'. As long as the `throw' takes place chronologically
+after entry to the `catch', and chronologically before exit from it, it
+has access to that `catch'. This is why `throw' can be used in
+commands such as `exit-recursive-edit' that throw back to the editor
+command loop (*note Recursive Editing::.).
+
+ Common Lisp note: Most other versions of Lisp, including Common
+ Lisp, have several ways of transferring control nonsequentially:
+ `return', `return-from', and `go', for example. XEmacs Lisp has
+ only `throw'.
+
+ - Special Form: catch TAG BODY...
+ `catch' establishes a return point for the `throw' function. The
+ return point is distinguished from other such return points by TAG,
+ which may be any Lisp object. The argument TAG is evaluated
+ normally before the return point is established.
+
+ With the return point in effect, `catch' evaluates the forms of the
+ BODY in textual order. If the forms execute normally, without
+ error or nonlocal exit, the value of the last body form is
+ returned from the `catch'.
+
+ If a `throw' is done within BODY specifying the same value TAG,
+ the `catch' exits immediately; the value it returns is whatever
+ was specified as the second argument of `throw'.
+
+ - Function: throw TAG VALUE
+ The purpose of `throw' is to return from a return point previously
+ established with `catch'. The argument TAG is used to choose
+ among the various existing return points; it must be `eq' to the
+ value specified in the `catch'. If multiple return points match
+ TAG, the innermost one is used.
+
+ The argument VALUE is used as the value to return from that
+ `catch'.
+
+ If no return point is in effect with tag TAG, then a `no-catch'
+ error is signaled with data `(TAG VALUE)'.
+
+\1f
+File: lispref.info, Node: Examples of Catch, Next: Errors, Prev: Catch and Throw, Up: Nonlocal Exits
+
+Examples of `catch' and `throw'
+-------------------------------
+
+ One way to use `catch' and `throw' is to exit from a doubly nested
+loop. (In most languages, this would be done with a "go to".) Here we
+compute `(foo I J)' for I and J varying from 0 to 9:
+
+ (defun search-foo ()
+ (catch 'loop
+ (let ((i 0))
+ (while (< i 10)
+ (let ((j 0))
+ (while (< j 10)
+ (if (foo i j)
+ (throw 'loop (list i j)))
+ (setq j (1+ j))))
+ (setq i (1+ i))))))
+
+If `foo' ever returns non-`nil', we stop immediately and return a list
+of I and J. If `foo' always returns `nil', the `catch' returns
+normally, and the value is `nil', since that is the result of the
+`while'.
+
+ Here are two tricky examples, slightly different, showing two return
+points at once. First, two return points with the same tag, `hack':
+
+ (defun catch2 (tag)
+ (catch tag
+ (throw 'hack 'yes)))
+ => catch2
+
+ (catch 'hack
+ (print (catch2 'hack))
+ 'no)
+ -| yes
+ => no
+
+Since both return points have tags that match the `throw', it goes to
+the inner one, the one established in `catch2'. Therefore, `catch2'
+returns normally with value `yes', and this value is printed. Finally
+the second body form in the outer `catch', which is `'no', is evaluated
+and returned from the outer `catch'.
+
+ Now let's change the argument given to `catch2':
+
+ (defun catch2 (tag)
+ (catch tag
+ (throw 'hack 'yes)))
+ => catch2
+
+ (catch 'hack
+ (print (catch2 'quux))
+ 'no)
+ => yes
+
+We still have two return points, but this time only the outer one has
+the tag `hack'; the inner one has the tag `quux' instead. Therefore,
+`throw' makes the outer `catch' return the value `yes'. The function
+`print' is never called, and the body-form `'no' is never evaluated.
+
+\1f
+File: lispref.info, Node: Errors, Next: Cleanups, Prev: Examples of Catch, Up: Nonlocal Exits
+
+Errors
+------
+
+ When XEmacs Lisp attempts to evaluate a form that, for some reason,
+cannot be evaluated, it "signals" an "error".
+
+ When an error is signaled, XEmacs's default reaction is to print an
+error message and terminate execution of the current command. This is
+the right thing to do in most cases, such as if you type `C-f' at the
+end of the buffer.
+
+ In complicated programs, simple termination may not be what you want.
+For example, the program may have made temporary changes in data
+structures, or created temporary buffers that should be deleted before
+the program is finished. In such cases, you would use `unwind-protect'
+to establish "cleanup expressions" to be evaluated in case of error.
+(*Note Cleanups::.) Occasionally, you may wish the program to continue
+execution despite an error in a subroutine. In these cases, you would
+use `condition-case' to establish "error handlers" to recover control
+in case of error.
+
+ Resist the temptation to use error handling to transfer control from
+one part of the program to another; use `catch' and `throw' instead.
+*Note Catch and Throw::.
+
+* Menu:
+
+* Signaling Errors:: How to report an error.
+* Processing of Errors:: What XEmacs does when you report an error.
+* Handling Errors:: How you can trap errors and continue execution.
+* Error Symbols:: How errors are classified for trapping them.
+
+\1f
+File: lispref.info, Node: Signaling Errors, Next: Processing of Errors, Up: Errors
+
+How to Signal an Error
+......................
+
+ Most errors are signaled "automatically" within Lisp primitives
+which you call for other purposes, such as if you try to take the CAR
+of an integer or move forward a character at the end of the buffer; you
+can also signal errors explicitly with the functions `error' and
+`signal'.
+
+ Quitting, which happens when the user types `C-g', is not considered
+an error, but it is handled almost like an error. *Note Quitting::.
+
+ - Function: error FORMAT-STRING &rest ARGS
+ This function signals an error with an error message constructed by
+ applying `format' (*note String Conversion::.) to FORMAT-STRING
+ and ARGS.
+
+ These examples show typical uses of `error':
+
+ (error "You have committed an error.
+ Try something else.")
+ error--> You have committed an error.
+ Try something else.
+
+ (error "You have committed %d errors." 10)
+ error--> You have committed 10 errors.
+
+ `error' works by calling `signal' with two arguments: the error
+ symbol `error', and a list containing the string returned by
+ `format'.
+
+ If you want to use your own string as an error message verbatim,
+ don't just write `(error STRING)'. If STRING contains `%', it
+ will be interpreted as a format specifier, with undesirable
+ results. Instead, use `(error "%s" STRING)'.
+
+ - Function: signal ERROR-SYMBOL DATA
+ This function signals an error named by ERROR-SYMBOL. The
+ argument DATA is a list of additional Lisp objects relevant to the
+ circumstances of the error.
+
+ The argument ERROR-SYMBOL must be an "error symbol"--a symbol
+ bearing a property `error-conditions' whose value is a list of
+ condition names. This is how XEmacs Lisp classifies different
+ sorts of errors.
+
+ The number and significance of the objects in DATA depends on
+ ERROR-SYMBOL. For example, with a `wrong-type-arg' error, there
+ are two objects in the list: a predicate that describes the type
+ that was expected, and the object that failed to fit that type.
+ *Note Error Symbols::, for a description of error symbols.
+
+ Both ERROR-SYMBOL and DATA are available to any error handlers
+ that handle the error: `condition-case' binds a local variable to
+ a list of the form `(ERROR-SYMBOL . DATA)' (*note Handling
+ Errors::.). If the error is not handled, these two values are
+ used in printing the error message.
+
+ The function `signal' never returns (though in older Emacs versions
+ it could sometimes return).
+
+ (signal 'wrong-number-of-arguments '(x y))
+ error--> Wrong number of arguments: x, y
+
+ (signal 'no-such-error '("My unknown error condition."))
+ error--> peculiar error: "My unknown error condition."
+
+ Common Lisp note: XEmacs Lisp has nothing like the Common Lisp
+ concept of continuable errors.
+
+\1f
+File: lispref.info, Node: Processing of Errors, Next: Handling Errors, Prev: Signaling Errors, Up: Errors
+
+How XEmacs Processes Errors
+...........................
+
+ When an error is signaled, `signal' searches for an active "handler"
+for the error. A handler is a sequence of Lisp expressions designated
+to be executed if an error happens in part of the Lisp program. If the
+error has an applicable handler, the handler is executed, and control
+resumes following the handler. The handler executes in the environment
+of the `condition-case' that established it; all functions called
+within that `condition-case' have already been exited, and the handler
+cannot return to them.
+
+ If there is no applicable handler for the error, the current command
+is terminated and control returns to the editor command loop, because
+the command loop has an implicit handler for all kinds of errors. The
+command loop's handler uses the error symbol and associated data to
+print an error message.
+
+ An error that has no explicit handler may call the Lisp debugger.
+The debugger is enabled if the variable `debug-on-error' (*note Error
+Debugging::.) is non-`nil'. Unlike error handlers, the debugger runs
+in the environment of the error, so that you can examine values of
+variables precisely as they were at the time of the error.
+
+\1f
+File: lispref.info, Node: Handling Errors, Next: Error Symbols, Prev: Processing of Errors, Up: Errors
+
+Writing Code to Handle Errors
+.............................
+
+ The usual effect of signaling an error is to terminate the command
+that is running and return immediately to the XEmacs editor command
+loop. You can arrange to trap errors occurring in a part of your
+program by establishing an error handler, with the special form
+`condition-case'. A simple example looks like this:
+
+ (condition-case nil
+ (delete-file filename)
+ (error nil))
+
+This deletes the file named FILENAME, catching any error and returning
+`nil' if an error occurs.
+
+ The second argument of `condition-case' is called the "protected
+form". (In the example above, the protected form is a call to
+`delete-file'.) The error handlers go into effect when this form
+begins execution and are deactivated when this form returns. They
+remain in effect for all the intervening time. In particular, they are
+in effect during the execution of functions called by this form, in
+their subroutines, and so on. This is a good thing, since, strictly
+speaking, errors can be signaled only by Lisp primitives (including
+`signal' and `error') called by the protected form, not by the
+protected form itself.
+
+ The arguments after the protected form are handlers. Each handler
+lists one or more "condition names" (which are symbols) to specify
+which errors it will handle. The error symbol specified when an error
+is signaled also defines a list of condition names. A handler applies
+to an error if they have any condition names in common. In the example
+above, there is one handler, and it specifies one condition name,
+`error', which covers all errors.
+
+ The search for an applicable handler checks all the established
+handlers starting with the most recently established one. Thus, if two
+nested `condition-case' forms offer to handle the same error, the inner
+of the two will actually handle it.
+
+ When an error is handled, control returns to the handler. Before
+this happens, XEmacs unbinds all variable bindings made by binding
+constructs that are being exited and executes the cleanups of all
+`unwind-protect' forms that are exited. Once control arrives at the
+handler, the body of the handler is executed.
+
+ After execution of the handler body, execution continues by returning
+from the `condition-case' form. Because the protected form is exited
+completely before execution of the handler, the handler cannot resume
+execution at the point of the error, nor can it examine variable
+bindings that were made within the protected form. All it can do is
+clean up and proceed.
+
+ `condition-case' is often used to trap errors that are predictable,
+such as failure to open a file in a call to `insert-file-contents'. It
+is also used to trap errors that are totally unpredictable, such as
+when the program evaluates an expression read from the user.
+
+ Error signaling and handling have some resemblance to `throw' and
+`catch', but they are entirely separate facilities. An error cannot be
+caught by a `catch', and a `throw' cannot be handled by an error
+handler (though using `throw' when there is no suitable `catch' signals
+an error that can be handled).
+
+ - Special Form: condition-case VAR PROTECTED-FORM HANDLERS...
+ This special form establishes the error handlers HANDLERS around
+ the execution of PROTECTED-FORM. If PROTECTED-FORM executes
+ without error, the value it returns becomes the value of the
+ `condition-case' form; in this case, the `condition-case' has no
+ effect. The `condition-case' form makes a difference when an
+ error occurs during PROTECTED-FORM.
+
+ Each of the HANDLERS is a list of the form `(CONDITIONS BODY...)'.
+ Here CONDITIONS is an error condition name to be handled, or a
+ list of condition names; BODY is one or more Lisp expressions to
+ be executed when this handler handles an error. Here are examples
+ of handlers:
+
+ (error nil)
+
+ (arith-error (message "Division by zero"))
+
+ ((arith-error file-error)
+ (message
+ "Either division by zero or failure to open a file"))
+
+ Each error that occurs has an "error symbol" that describes what
+ kind of error it is. The `error-conditions' property of this
+ symbol is a list of condition names (*note Error Symbols::.).
+ Emacs searches all the active `condition-case' forms for a handler
+ that specifies one or more of these condition names; the innermost
+ matching `condition-case' handles the error. Within this
+ `condition-case', the first applicable handler handles the error.
+
+ After executing the body of the handler, the `condition-case'
+ returns normally, using the value of the last form in the handler
+ body as the overall value.
+
+ The argument VAR is a variable. `condition-case' does not bind
+ this variable when executing the PROTECTED-FORM, only when it
+ handles an error. At that time, it binds VAR locally to a list of
+ the form `(ERROR-SYMBOL . DATA)', giving the particulars of the
+ error. The handler can refer to this list to decide what to do.
+ For example, if the error is for failure opening a file, the file
+ name is the second element of DATA--the third element of VAR.
+
+ If VAR is `nil', that means no variable is bound. Then the error
+ symbol and associated data are not available to the handler.
+
+ Here is an example of using `condition-case' to handle the error
+that results from dividing by zero. The handler prints out a warning
+message and returns a very large number.
+
+ (defun safe-divide (dividend divisor)
+ (condition-case err
+ ;; Protected form.
+ (/ dividend divisor)
+ ;; The handler.
+ (arith-error ; Condition.
+ (princ (format "Arithmetic error: %s" err))
+ 1000000)))
+ => safe-divide
+
+ (safe-divide 5 0)
+ -| Arithmetic error: (arith-error)
+ => 1000000
+
+The handler specifies condition name `arith-error' so that it will
+handle only division-by-zero errors. Other kinds of errors will not be
+handled, at least not by this `condition-case'. Thus,
+
+ (safe-divide nil 3)
+ error--> Wrong type argument: integer-or-marker-p, nil
+
+ Here is a `condition-case' that catches all kinds of errors,
+including those signaled with `error':
+
+ (setq baz 34)
+ => 34
+
+ (condition-case err
+ (if (eq baz 35)
+ t
+ ;; This is a call to the function `error'.
+ (error "Rats! The variable %s was %s, not 35" 'baz baz))
+ ;; This is the handler; it is not a form.
+ (error (princ (format "The error was: %s" err))
+ 2))
+ -| The error was: (error "Rats! The variable baz was 34, not 35")
+ => 2
+
+\1f
+File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors
+
+Error Symbols and Condition Names
+.................................
+
+ When you signal an error, you specify an "error symbol" to specify
+the kind of error you have in mind. Each error has one and only one
+error symbol to categorize it. This is the finest classification of
+errors defined by the XEmacs Lisp language.
+
+ These narrow classifications are grouped into a hierarchy of wider
+classes called "error conditions", identified by "condition names".
+The narrowest such classes belong to the error symbols themselves: each
+error symbol is also a condition name. There are also condition names
+for more extensive classes, up to the condition name `error' which
+takes in all kinds of errors. Thus, each error has one or more
+condition names: `error', the error symbol if that is distinct from
+`error', and perhaps some intermediate classifications.
+
+ In order for a symbol to be an error symbol, it must have an
+`error-conditions' property which gives a list of condition names.
+This list defines the conditions that this kind of error belongs to.
+(The error symbol itself, and the symbol `error', should always be
+members of this list.) Thus, the hierarchy of condition names is
+defined by the `error-conditions' properties of the error symbols.
+
+ In addition to the `error-conditions' list, the error symbol should
+have an `error-message' property whose value is a string to be printed
+when that error is signaled but not handled. If the `error-message'
+property exists, but is not a string, the error message `peculiar
+error' is used.
+
+ Here is how we define a new error symbol, `new-error':
+
+ (put 'new-error
+ 'error-conditions
+ '(error my-own-errors new-error))
+ => (error my-own-errors new-error)
+ (put 'new-error 'error-message "A new error")
+ => "A new error"
+
+This error has three condition names: `new-error', the narrowest
+classification; `my-own-errors', which we imagine is a wider
+classification; and `error', which is the widest of all.
+
+ The error string should start with a capital letter but it should
+not end with a period. This is for consistency with the rest of Emacs.
+
+ Naturally, XEmacs will never signal `new-error' on its own; only an
+explicit call to `signal' (*note Signaling Errors::.) in your code can
+do this:
+
+ (signal 'new-error '(x y))
+ error--> A new error: x, y
+
+ This error can be handled through any of the three condition names.
+This example handles `new-error' and any other errors in the class
+`my-own-errors':
+
+ (condition-case foo
+ (bar nil t)
+ (my-own-errors nil))
+
+ The significant way that errors are classified is by their condition
+names--the names used to match errors with handlers. An error symbol
+serves only as a convenient way to specify the intended error message
+and list of condition names. It would be cumbersome to give `signal' a
+list of condition names rather than one error symbol.
+
+ By contrast, using only error symbols without condition names would
+seriously decrease the power of `condition-case'. Condition names make
+it possible to categorize errors at various levels of generality when
+you write an error handler. Using error symbols alone would eliminate
+all but the narrowest level of classification.
+
+ *Note Standard Errors::, for a list of all the standard error symbols
+and their conditions.
+
--- /dev/null
+This is Info file ../../info/lispref.info, produced by Makeinfo version
+1.68 from the input file lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref). XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+ Edition History:
+
+ GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+\1f
+File: lispref.info, Node: Cleanups, Prev: Errors, Up: Nonlocal Exits
+
+Cleaning Up from Nonlocal Exits
+-------------------------------
+
+ The `unwind-protect' construct is essential whenever you temporarily
+put a data structure in an inconsistent state; it permits you to ensure
+the data are consistent in the event of an error or throw.
+
+ - Special Form: unwind-protect BODY CLEANUP-FORMS...
+ `unwind-protect' executes the BODY with a guarantee that the
+ CLEANUP-FORMS will be evaluated if control leaves BODY, no matter
+ how that happens. The BODY may complete normally, or execute a
+ `throw' out of the `unwind-protect', or cause an error; in all
+ cases, the CLEANUP-FORMS will be evaluated.
+
+ If the BODY forms finish normally, `unwind-protect' returns the
+ value of the last BODY form, after it evaluates the CLEANUP-FORMS.
+ If the BODY forms do not finish, `unwind-protect' does not return
+ any value in the normal sense.
+
+ Only the BODY is actually protected by the `unwind-protect'. If
+ any of the CLEANUP-FORMS themselves exits nonlocally (e.g., via a
+ `throw' or an error), `unwind-protect' is *not* guaranteed to
+ evaluate the rest of them. If the failure of one of the
+ CLEANUP-FORMS has the potential to cause trouble, then protect it
+ with another `unwind-protect' around that form.
+
+ The number of currently active `unwind-protect' forms counts,
+ together with the number of local variable bindings, against the
+ limit `max-specpdl-size' (*note Local Variables::.).
+
+ For example, here we make an invisible buffer for temporary use, and
+make sure to kill it before finishing:
+
+ (save-excursion
+ (let ((buffer (get-buffer-create " *temp*")))
+ (set-buffer buffer)
+ (unwind-protect
+ BODY
+ (kill-buffer buffer))))
+
+You might think that we could just as well write `(kill-buffer
+(current-buffer))' and dispense with the variable `buffer'. However,
+the way shown above is safer, if BODY happens to get an error after
+switching to a different buffer! (Alternatively, you could write
+another `save-excursion' around the body, to ensure that the temporary
+buffer becomes current in time to kill it.)
+
+ Here is an actual example taken from the file `ftp.el'. It creates
+a process (*note Processes::.) to try to establish a connection to a
+remote machine. As the function `ftp-login' is highly susceptible to
+numerous problems that the writer of the function cannot anticipate, it
+is protected with a form that guarantees deletion of the process in the
+event of failure. Otherwise, XEmacs might fill up with useless
+subprocesses.
+
+ (let ((win nil))
+ (unwind-protect
+ (progn
+ (setq process (ftp-setup-buffer host file))
+ (if (setq win (ftp-login process host user password))
+ (message "Logged in")
+ (error "Ftp login failed")))
+ (or win (and process (delete-process process)))))
+
+ This example actually has a small bug: if the user types `C-g' to
+quit, and the quit happens immediately after the function
+`ftp-setup-buffer' returns but before the variable `process' is set,
+the process will not be killed. There is no easy way to fix this bug,
+but at least it is very unlikely.
+
+ Here is another example which uses `unwind-protect' to make sure to
+kill a temporary buffer. In this example, the value returned by
+`unwind-protect' is used.
+
+ (defun shell-command-string (cmd)
+ "Return the output of the shell command CMD, as a string."
+ (save-excursion
+ (set-buffer (generate-new-buffer " OS*cmd"))
+ (shell-command cmd t)
+ (unwind-protect
+ (buffer-string)
+ (kill-buffer (current-buffer)))))
+
+\1f
+File: lispref.info, Node: Variables, Next: Functions, Prev: Control Structures, Up: Top
+
+Variables
+*********
+
+ A "variable" is a name used in a program to stand for a value.
+Nearly all programming languages have variables of some sort. In the
+text of a Lisp program, variables are written using the syntax for
+symbols.
+
+ In Lisp, unlike most programming languages, programs are represented
+primarily as Lisp objects and only secondarily as text. The Lisp
+objects used for variables are symbols: the symbol name is the variable
+name, and the variable's value is stored in the value cell of the
+symbol. The use of a symbol as a variable is independent of its use as
+a function name. *Note Symbol Components::.
+
+ The Lisp objects that constitute a Lisp program determine the textual
+form of the program--it is simply the read syntax for those Lisp
+objects. This is why, for example, a variable in a textual Lisp program
+is written using the read syntax for the symbol that represents the
+variable.
+
+* Menu:
+
+* Global Variables:: Variable values that exist permanently, everywhere.
+* Constant Variables:: Certain "variables" have values that never change.
+* Local Variables:: Variable values that exist only temporarily.
+* Void Variables:: Symbols that lack values.
+* Defining Variables:: A definition says a symbol is used as a variable.
+* Accessing Variables:: Examining values of variables whose names
+ are known only at run time.
+* Setting Variables:: Storing new values in variables.
+* Variable Scoping:: How Lisp chooses among local and global values.
+* Buffer-Local Variables:: Variable values in effect only in one buffer.
+* Variable Aliases:: Making one variable point to another.
+
+\1f
+File: lispref.info, Node: Global Variables, Next: Constant Variables, Up: Variables
+
+Global Variables
+================
+
+ The simplest way to use a variable is "globally". This means that
+the variable has just one value at a time, and this value is in effect
+(at least for the moment) throughout the Lisp system. The value remains
+in effect until you specify a new one. When a new value replaces the
+old one, no trace of the old value remains in the variable.
+
+ You specify a value for a symbol with `setq'. For example,
+
+ (setq x '(a b))
+
+gives the variable `x' the value `(a b)'. Note that `setq' does not
+evaluate its first argument, the name of the variable, but it does
+evaluate the second argument, the new value.
+
+ Once the variable has a value, you can refer to it by using the
+symbol by itself as an expression. Thus,
+
+ x => (a b)
+
+assuming the `setq' form shown above has already been executed.
+
+ If you do another `setq', the new value replaces the old one:
+
+ x
+ => (a b)
+ (setq x 4)
+ => 4
+ x
+ => 4
+
+\1f
+File: lispref.info, Node: Constant Variables, Next: Local Variables, Prev: Global Variables, Up: Variables
+
+Variables That Never Change
+===========================
+
+ In XEmacs Lisp, some symbols always evaluate to themselves: the two
+special symbols `nil' and `t', as well as "keyword symbols", that is,
+symbols whose name begins with the character ``:''. These symbols
+cannot be rebound, nor can their value cells be changed. An attempt to
+change the value of `nil' or `t' signals a `setting-constant' error.
+
+ nil == 'nil
+ => nil
+ (setq nil 500)
+ error--> Attempt to set constant symbol: nil
+
+\1f
+File: lispref.info, Node: Local Variables, Next: Void Variables, Prev: Constant Variables, Up: Variables
+
+Local Variables
+===============
+
+ Global variables have values that last until explicitly superseded
+with new values. Sometimes it is useful to create variable values that
+exist temporarily--only while within a certain part of the program.
+These values are called "local", and the variables so used are called
+"local variables".
+
+ For example, when a function is called, its argument variables
+receive new local values that last until the function exits. The `let'
+special form explicitly establishes new local values for specified
+variables; these last until exit from the `let' form.
+
+ Establishing a local value saves away the previous value (or lack of
+one) of the variable. When the life span of the local value is over,
+the previous value is restored. In the mean time, we say that the
+previous value is "shadowed" and "not visible". Both global and local
+values may be shadowed (*note Scope::.).
+
+ If you set a variable (such as with `setq') while it is local, this
+replaces the local value; it does not alter the global value, or
+previous local values that are shadowed. To model this behavior, we
+speak of a "local binding" of the variable as well as a local value.
+
+ The local binding is a conceptual place that holds a local value.
+Entry to a function, or a special form such as `let', creates the local
+binding; exit from the function or from the `let' removes the local
+binding. As long as the local binding lasts, the variable's value is
+stored within it. Use of `setq' or `set' while there is a local
+binding stores a different value into the local binding; it does not
+create a new binding.
+
+ We also speak of the "global binding", which is where (conceptually)
+the global value is kept.
+
+ A variable can have more than one local binding at a time (for
+example, if there are nested `let' forms that bind it). In such a
+case, the most recently created local binding that still exists is the
+"current binding" of the variable. (This is called "dynamic scoping";
+see *Note Variable Scoping::.) If there are no local bindings, the
+variable's global binding is its current binding. We also call the
+current binding the "most-local existing binding", for emphasis.
+Ordinary evaluation of a symbol always returns the value of its current
+binding.
+
+ The special forms `let' and `let*' exist to create local bindings.
+
+ - Special Form: let (BINDINGS...) FORMS...
+ This special form binds variables according to BINDINGS and then
+ evaluates all of the FORMS in textual order. The `let'-form
+ returns the value of the last form in FORMS.
+
+ Each of the BINDINGS is either (i) a symbol, in which case that
+ symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL
+ VALUE-FORM)', in which case SYMBOL is bound to the result of
+ evaluating VALUE-FORM. If VALUE-FORM is omitted, `nil' is used.
+
+ All of the VALUE-FORMs in BINDINGS are evaluated in the order they
+ appear and *before* any of the symbols are bound. Here is an
+ example of this: `Z' is bound to the old value of `Y', which is 2,
+ not the new value, 1.
+
+ (setq Y 2)
+ => 2
+ (let ((Y 1)
+ (Z Y))
+ (list Y Z))
+ => (1 2)
+
+ - Special Form: let* (BINDINGS...) FORMS...
+ This special form is like `let', but it binds each variable right
+ after computing its local value, before computing the local value
+ for the next variable. Therefore, an expression in BINDINGS can
+ reasonably refer to the preceding symbols bound in this `let*'
+ form. Compare the following example with the example above for
+ `let'.
+
+ (setq Y 2)
+ => 2
+ (let* ((Y 1)
+ (Z Y)) ; Use the just-established value of `Y'.
+ (list Y Z))
+ => (1 1)
+
+ Here is a complete list of the other facilities that create local
+bindings:
+
+ * Function calls (*note Functions::.).
+
+ * Macro calls (*note Macros::.).
+
+ * `condition-case' (*note Errors::.).
+
+ Variables can also have buffer-local bindings (*note Buffer-Local
+Variables::.). These kinds of bindings work somewhat like ordinary
+local bindings, but they are localized depending on "where" you are in
+Emacs, rather than localized in time.
+
+ - Variable: max-specpdl-size
+ This variable defines the limit on the total number of local
+ variable bindings and `unwind-protect' cleanups (*note Nonlocal
+ Exits::.) that are allowed before signaling an error (with data
+ `"Variable binding depth exceeds max-specpdl-size"').
+
+ This limit, with the associated error when it is exceeded, is one
+ way that Lisp avoids infinite recursion on an ill-defined function.
+
+ The default value is 600.
+
+ `max-lisp-eval-depth' provides another limit on depth of nesting.
+ *Note Eval::.
+
+\1f
+File: lispref.info, Node: Void Variables, Next: Defining Variables, Prev: Local Variables, Up: Variables
+
+When a Variable is "Void"
+=========================
+
+ If you have never given a symbol any value as a global variable, we
+say that that symbol's global value is "void". In other words, the
+symbol's value cell does not have any Lisp object in it. If you try to
+evaluate the symbol, you get a `void-variable' error rather than a
+value.
+
+ Note that a value of `nil' is not the same as void. The symbol
+`nil' is a Lisp object and can be the value of a variable just as any
+other object can be; but it is *a value*. A void variable does not
+have any value.
+
+ After you have given a variable a value, you can make it void once
+more using `makunbound'.
+
+ - Function: makunbound SYMBOL
+ This function makes the current binding of SYMBOL void.
+ Subsequent attempts to use this symbol's value as a variable will
+ signal the error `void-variable', unless or until you set it again.
+
+ `makunbound' returns SYMBOL.
+
+ (makunbound 'x) ; Make the global value
+ ; of `x' void.
+ => x
+ x
+ error--> Symbol's value as variable is void: x
+
+ If SYMBOL is locally bound, `makunbound' affects the most local
+ existing binding. This is the only way a symbol can have a void
+ local binding, since all the constructs that create local bindings
+ create them with values. In this case, the voidness lasts at most
+ as long as the binding does; when the binding is removed due to
+ exit from the construct that made it, the previous or global
+ binding is reexposed as usual, and the variable is no longer void
+ unless the newly reexposed binding was void all along.
+
+ (setq x 1) ; Put a value in the global binding.
+ => 1
+ (let ((x 2)) ; Locally bind it.
+ (makunbound 'x) ; Void the local binding.
+ x)
+ error--> Symbol's value as variable is void: x
+
+ x ; The global binding is unchanged.
+ => 1
+
+ (let ((x 2)) ; Locally bind it.
+ (let ((x 3)) ; And again.
+ (makunbound 'x) ; Void the innermost-local binding.
+ x)) ; And refer: it's void.
+ error--> Symbol's value as variable is void: x
+
+ (let ((x 2))
+ (let ((x 3))
+ (makunbound 'x)) ; Void inner binding, then remove it.
+ x) ; Now outer `let' binding is visible.
+ => 2
+
+ A variable that has been made void with `makunbound' is
+indistinguishable from one that has never received a value and has
+always been void.
+
+ You can use the function `boundp' to test whether a variable is
+currently void.
+
+ - Function: boundp VARIABLE
+ `boundp' returns `t' if VARIABLE (a symbol) is not void; more
+ precisely, if its current binding is not void. It returns `nil'
+ otherwise.
+
+ (boundp 'abracadabra) ; Starts out void.
+ => nil
+
+ (let ((abracadabra 5)) ; Locally bind it.
+ (boundp 'abracadabra))
+ => t
+
+ (boundp 'abracadabra) ; Still globally void.
+ => nil
+
+ (setq abracadabra 5) ; Make it globally nonvoid.
+ => 5
+
+ (boundp 'abracadabra)
+ => t
+
+\1f
+File: lispref.info, Node: Defining Variables, Next: Accessing Variables, Prev: Void Variables, Up: Variables
+
+Defining Global Variables
+=========================
+
+ You may announce your intention to use a symbol as a global variable
+with a "variable definition": a special form, either `defconst' or
+`defvar'.
+
+ In XEmacs Lisp, definitions serve three purposes. First, they inform
+people who read the code that certain symbols are *intended* to be used
+a certain way (as variables). Second, they inform the Lisp system of
+these things, supplying a value and documentation. Third, they provide
+information to utilities such as `etags' and `make-docfile', which
+create data bases of the functions and variables in a program.
+
+ The difference between `defconst' and `defvar' is primarily a matter
+of intent, serving to inform human readers of whether programs will
+change the variable. XEmacs Lisp does not restrict the ways in which a
+variable can be used based on `defconst' or `defvar' declarations.
+However, it does make a difference for initialization: `defconst'
+unconditionally initializes the variable, while `defvar' initializes it
+only if it is void.
+
+ One would expect user option variables to be defined with
+`defconst', since programs do not change them. Unfortunately, this has
+bad results if the definition is in a library that is not preloaded:
+`defconst' would override any prior value when the library is loaded.
+Users would like to be able to set user options in their init files,
+and override the default values given in the definitions. For this
+reason, user options must be defined with `defvar'.
+
+ - Special Form: defvar SYMBOL [VALUE [DOC-STRING]]
+ This special form defines SYMBOL as a value and initializes it.
+ The definition informs a person reading your code that SYMBOL is
+ used as a variable that programs are likely to set or change. It
+ is also used for all user option variables except in the preloaded
+ parts of XEmacs. Note that SYMBOL is not evaluated; the symbol to
+ be defined must appear explicitly in the `defvar'.
+
+ If SYMBOL already has a value (i.e., it is not void), VALUE is not
+ even evaluated, and SYMBOL's value remains unchanged. If SYMBOL
+ is void and VALUE is specified, `defvar' evaluates it and sets
+ SYMBOL to the result. (If VALUE is omitted, the value of SYMBOL
+ is not changed in any case.)
+
+ When you evaluate a top-level `defvar' form with `C-M-x' in Emacs
+ Lisp mode (`eval-defun'), a special feature of `eval-defun'
+ evaluates it as a `defconst'. The purpose of this is to make sure
+ the variable's value is reinitialized, when you ask for it
+ specifically.
+
+ If SYMBOL has a buffer-local binding in the current buffer,
+ `defvar' sets the default value, not the local value. *Note
+ Buffer-Local Variables::.
+
+ If the DOC-STRING argument appears, it specifies the documentation
+ for the variable. (This opportunity to specify documentation is
+ one of the main benefits of defining the variable.) The
+ documentation is stored in the symbol's `variable-documentation'
+ property. The XEmacs help functions (*note Documentation::.) look
+ for this property.
+
+ If the first character of DOC-STRING is `*', it means that this
+ variable is considered a user option. This lets users set the
+ variable conveniently using the commands `set-variable' and
+ `edit-options'.
+
+ For example, this form defines `foo' but does not set its value:
+
+ (defvar foo)
+ => foo
+
+ The following example sets the value of `bar' to `23', and gives
+ it a documentation string:
+
+ (defvar bar 23
+ "The normal weight of a bar.")
+ => bar
+
+ The following form changes the documentation string for `bar',
+ making it a user option, but does not change the value, since `bar'
+ already has a value. (The addition `(1+ 23)' is not even
+ performed.)
+
+ (defvar bar (1+ 23)
+ "*The normal weight of a bar.")
+ => bar
+ bar
+ => 23
+
+ Here is an equivalent expression for the `defvar' special form:
+
+ (defvar SYMBOL VALUE DOC-STRING)
+ ==
+ (progn
+ (if (not (boundp 'SYMBOL))
+ (setq SYMBOL VALUE))
+ (put 'SYMBOL 'variable-documentation 'DOC-STRING)
+ 'SYMBOL)
+
+ The `defvar' form returns SYMBOL, but it is normally used at top
+ level in a file where its value does not matter.
+
+ - Special Form: defconst SYMBOL [VALUE [DOC-STRING]]
+ This special form defines SYMBOL as a value and initializes it.
+ It informs a person reading your code that SYMBOL has a global
+ value, established here, that will not normally be changed or
+ locally bound by the execution of the program. The user, however,
+ may be welcome to change it. Note that SYMBOL is not evaluated;
+ the symbol to be defined must appear explicitly in the `defconst'.
+
+ `defconst' always evaluates VALUE and sets the global value of
+ SYMBOL to the result, provided VALUE is given. If SYMBOL has a
+ buffer-local binding in the current buffer, `defconst' sets the
+ default value, not the local value.
+
+ *Please note:* Don't use `defconst' for user option variables in
+ libraries that are not standardly preloaded. The user should be
+ able to specify a value for such a variable in the `.emacs' file,
+ so that it will be in effect if and when the library is loaded
+ later.
+
+ Here, `pi' is a constant that presumably ought not to be changed
+ by anyone (attempts by the Indiana State Legislature
+ notwithstanding). As the second form illustrates, however, this
+ is only advisory.
+
+ (defconst pi 3.1415 "Pi to five places.")
+ => pi
+ (setq pi 3)
+ => pi
+ pi
+ => 3
+
+ - Function: user-variable-p VARIABLE
+ This function returns `t' if VARIABLE is a user option--a variable
+ intended to be set by the user for customization--and `nil'
+ otherwise. (Variables other than user options exist for the
+ internal purposes of Lisp programs, and users need not know about
+ them.)
+
+ User option variables are distinguished from other variables by the
+ first character of the `variable-documentation' property. If the
+ property exists and is a string, and its first character is `*',
+ then the variable is a user option.
+
+ If a user option variable has a `variable-interactive' property, the
+`set-variable' command uses that value to control reading the new value
+for the variable. The property's value is used as if it were the
+argument to `interactive'.
+
+ *Warning:* If the `defconst' and `defvar' special forms are used
+while the variable has a local binding, they set the local binding's
+value; the global binding is not changed. This is not what we really
+want. To prevent it, use these special forms at top level in a file,
+where normally no local binding is in effect, and make sure to load the
+file before making a local binding for the variable.
+
+\1f
+File: lispref.info, Node: Accessing Variables, Next: Setting Variables, Prev: Defining Variables, Up: Variables
+
+Accessing Variable Values
+=========================
+
+ The usual way to reference a variable is to write the symbol which
+names it (*note Symbol Forms::.). This requires you to specify the
+variable name when you write the program. Usually that is exactly what
+you want to do. Occasionally you need to choose at run time which
+variable to reference; then you can use `symbol-value'.
+
+ - Function: symbol-value SYMBOL
+ This function returns the value of SYMBOL. This is the value in
+ the innermost local binding of the symbol, or its global value if
+ it has no local bindings.
+
+ (setq abracadabra 5)
+ => 5
+ (setq foo 9)
+ => 9
+
+ ;; Here the symbol `abracadabra'
+ ;; is the symbol whose value is examined.
+ (let ((abracadabra 'foo))
+ (symbol-value 'abracadabra))
+ => foo
+
+ ;; Here the value of `abracadabra',
+ ;; which is `foo',
+ ;; is the symbol whose value is examined.
+ (let ((abracadabra 'foo))
+ (symbol-value abracadabra))
+ => 9
+
+ (symbol-value 'abracadabra)
+ => 5
+
+ A `void-variable' error is signaled if SYMBOL has neither a local
+ binding nor a global value.
+
+\1f
+File: lispref.info, Node: Setting Variables, Next: Variable Scoping, Prev: Accessing Variables, Up: Variables
+
+How to Alter a Variable Value
+=============================
+
+ The usual way to change the value of a variable is with the special
+form `setq'. When you need to compute the choice of variable at run
+time, use the function `set'.
+
+ - Special Form: setq [SYMBOL FORM]...
+ This special form is the most common method of changing a
+ variable's value. Each SYMBOL is given a new value, which is the
+ result of evaluating the corresponding FORM. The most-local
+ existing binding of the symbol is changed.
+
+ `setq' does not evaluate SYMBOL; it sets the symbol that you
+ write. We say that this argument is "automatically quoted". The
+ `q' in `setq' stands for "quoted."
+
+ The value of the `setq' form is the value of the last FORM.
+
+ (setq x (1+ 2))
+ => 3
+ x ; `x' now has a global value.
+ => 3
+ (let ((x 5))
+ (setq x 6) ; The local binding of `x' is set.
+ x)
+ => 6
+ x ; The global value is unchanged.
+ => 3
+
+ Note that the first FORM is evaluated, then the first SYMBOL is
+ set, then the second FORM is evaluated, then the second SYMBOL is
+ set, and so on:
+
+ (setq x 10 ; Notice that `x' is set before
+ y (1+ x)) ; the value of `y' is computed.
+ => 11
+
+ - Function: set SYMBOL VALUE
+ This function sets SYMBOL's value to VALUE, then returns VALUE.
+ Since `set' is a function, the expression written for SYMBOL is
+ evaluated to obtain the symbol to set.
+
+ The most-local existing binding of the variable is the binding
+ that is set; shadowed bindings are not affected.
+
+ (set one 1)
+ error--> Symbol's value as variable is void: one
+ (set 'one 1)
+ => 1
+ (set 'two 'one)
+ => one
+ (set two 2) ; `two' evaluates to symbol `one'.
+ => 2
+ one ; So it is `one' that was set.
+ => 2
+ (let ((one 1)) ; This binding of `one' is set,
+ (set 'one 3) ; not the global value.
+ one)
+ => 3
+ one
+ => 2
+
+ If SYMBOL is not actually a symbol, a `wrong-type-argument' error
+ is signaled.
+
+ (set '(x y) 'z)
+ error--> Wrong type argument: symbolp, (x y)
+
+ Logically speaking, `set' is a more fundamental primitive than
+ `setq'. Any use of `setq' can be trivially rewritten to use
+ `set'; `setq' could even be defined as a macro, given the
+ availability of `set'. However, `set' itself is rarely used;
+ beginners hardly need to know about it. It is useful only for
+ choosing at run time which variable to set. For example, the
+ command `set-variable', which reads a variable name from the user
+ and then sets the variable, needs to use `set'.
+
+ Common Lisp note: In Common Lisp, `set' always changes the
+ symbol's special value, ignoring any lexical bindings. In
+ XEmacs Lisp, all variables and all bindings are (in effect)
+ special, so `set' always affects the most local existing
+ binding.
+
+ One other function for setting a variable is designed to add an
+element to a list if it is not already present in the list.
+
+ - Function: add-to-list SYMBOL ELEMENT
+ This function sets the variable SYMBOL by consing ELEMENT onto the
+ old value, if ELEMENT is not already a member of that value. It
+ returns the resulting list, whether updated or not. The value of
+ SYMBOL had better be a list already before the call.
+
+ The argument SYMBOL is not implicitly quoted; `add-to-list' is an
+ ordinary function, like `set' and unlike `setq'. Quote the
+ argument yourself if that is what you want.
+
+ Here's a scenario showing how to use `add-to-list':
+
+ (setq foo '(a b))
+ => (a b)
+
+ (add-to-list 'foo 'c) ;; Add `c'.
+ => (c a b)
+
+ (add-to-list 'foo 'b) ;; No effect.
+ => (c a b)
+
+ foo ;; `foo' was changed.
+ => (c a b)
+
+ An equivalent expression for `(add-to-list 'VAR VALUE)' is this:
+
+ (or (member VALUE VAR)
+ (setq VAR (cons VALUE VAR)))
+
+\1f
+File: lispref.info, Node: Variable Scoping, Next: Buffer-Local Variables, Prev: Setting Variables, Up: Variables
+
+Scoping Rules for Variable Bindings
+===================================
+
+ A given symbol `foo' may have several local variable bindings,
+established at different places in the Lisp program, as well as a global
+binding. The most recently established binding takes precedence over
+the others.
+
+ Local bindings in XEmacs Lisp have "indefinite scope" and "dynamic
+extent". "Scope" refers to *where* textually in the source code the
+binding can be accessed. Indefinite scope means that any part of the
+program can potentially access the variable binding. "Extent" refers
+to *when*, as the program is executing, the binding exists. Dynamic
+extent means that the binding lasts as long as the activation of the
+construct that established it.
+
+ The combination of dynamic extent and indefinite scope is called
+"dynamic scoping". By contrast, most programming languages use
+"lexical scoping", in which references to a local variable must be
+located textually within the function or block that binds the variable.
+
+ Common Lisp note: Variables declared "special" in Common Lisp are
+ dynamically scoped, like variables in XEmacs Lisp.
+
+* Menu:
+
+* Scope:: Scope means where in the program a value is visible.
+ Comparison with other languages.
+* Extent:: Extent means how long in time a value exists.
+* Impl of Scope:: Two ways to implement dynamic scoping.
+* Using Scoping:: How to use dynamic scoping carefully and avoid problems.
+
+\1f
+File: lispref.info, Node: Scope, Next: Extent, Up: Variable Scoping
+
+Scope
+-----
+
+ XEmacs Lisp uses "indefinite scope" for local variable bindings.
+This means that any function anywhere in the program text might access a
+given binding of a variable. Consider the following function
+definitions:
+
+ (defun binder (x) ; `x' is bound in `binder'.
+ (foo 5)) ; `foo' is some other function.
+
+ (defun user () ; `x' is used in `user'.
+ (list x))
+
+ In a lexically scoped language, the binding of `x' in `binder' would
+never be accessible in `user', because `user' is not textually
+contained within the function `binder'. However, in dynamically scoped
+XEmacs Lisp, `user' may or may not refer to the binding of `x'
+established in `binder', depending on circumstances:
+
+ * If we call `user' directly without calling `binder' at all, then
+ whatever binding of `x' is found, it cannot come from `binder'.
+
+ * If we define `foo' as follows and call `binder', then the binding
+ made in `binder' will be seen in `user':
+
+ (defun foo (lose)
+ (user))
+
+ * If we define `foo' as follows and call `binder', then the binding
+ made in `binder' *will not* be seen in `user':
+
+ (defun foo (x)
+ (user))
+
+ Here, when `foo' is called by `binder', it binds `x'. (The
+ binding in `foo' is said to "shadow" the one made in `binder'.)
+ Therefore, `user' will access the `x' bound by `foo' instead of
+ the one bound by `binder'.
+
+\1f
+File: lispref.info, Node: Extent, Next: Impl of Scope, Prev: Scope, Up: Variable Scoping
+
+Extent
+------
+
+ "Extent" refers to the time during program execution that a variable
+name is valid. In XEmacs Lisp, a variable is valid only while the form
+that bound it is executing. This is called "dynamic extent". "Local"
+or "automatic" variables in most languages, including C and Pascal,
+have dynamic extent.
+
+ One alternative to dynamic extent is "indefinite extent". This
+means that a variable binding can live on past the exit from the form
+that made the binding. Common Lisp and Scheme, for example, support
+this, but XEmacs Lisp does not.
+
+ To illustrate this, the function below, `make-add', returns a
+function that purports to add N to its own argument M. This would work
+in Common Lisp, but it does not work as intended in XEmacs Lisp,
+because after the call to `make-add' exits, the variable `n' is no
+longer bound to the actual argument 2.
+
+ (defun make-add (n)
+ (function (lambda (m) (+ n m)))) ; Return a function.
+ => make-add
+ (fset 'add2 (make-add 2)) ; Define function `add2'
+ ; with `(make-add 2)'.
+ => (lambda (m) (+ n m))
+ (add2 4) ; Try to add 2 to 4.
+ error--> Symbol's value as variable is void: n
+
+ Some Lisp dialects have "closures", objects that are like functions
+but record additional variable bindings. XEmacs Lisp does not have
+closures.
+
+\1f
+File: lispref.info, Node: Impl of Scope, Next: Using Scoping, Prev: Extent, Up: Variable Scoping
+
+Implementation of Dynamic Scoping
+---------------------------------
+
+ A simple sample implementation (which is not how XEmacs Lisp actually
+works) may help you understand dynamic binding. This technique is
+called "deep binding" and was used in early Lisp systems.
+
+ Suppose there is a stack of bindings: variable-value pairs. At entry
+to a function or to a `let' form, we can push bindings on the stack for
+the arguments or local variables created there. We can pop those
+bindings from the stack at exit from the binding construct.
+
+ We can find the value of a variable by searching the stack from top
+to bottom for a binding for that variable; the value from that binding
+is the value of the variable. To set the variable, we search for the
+current binding, then store the new value into that binding.
+
+ As you can see, a function's bindings remain in effect as long as it
+continues execution, even during its calls to other functions. That is
+why we say the extent of the binding is dynamic. And any other function
+can refer to the bindings, if it uses the same variables while the
+bindings are in effect. That is why we say the scope is indefinite.
+
+ The actual implementation of variable scoping in XEmacs Lisp uses a
+technique called "shallow binding". Each variable has a standard place
+in which its current value is always found--the value cell of the
+symbol.
+
+ In shallow binding, setting the variable works by storing a value in
+the value cell. Creating a new binding works by pushing the old value
+(belonging to a previous binding) on a stack, and storing the local
+value in the value cell. Eliminating a binding works by popping the
+old value off the stack, into the value cell.
+
+ We use shallow binding because it has the same results as deep
+binding, but runs faster, since there is never a need to search for a
+binding.
+
+\1f
+File: lispref.info, Node: Using Scoping, Prev: Impl of Scope, Up: Variable Scoping
+
+Proper Use of Dynamic Scoping
+-----------------------------
+
+ Binding a variable in one function and using it in another is a
+powerful technique, but if used without restraint, it can make programs
+hard to understand. There are two clean ways to use this technique:
+
+ * Use or bind the variable only in a few related functions, written
+ close together in one file. Such a variable is used for
+ communication within one program.
+
+ You should write comments to inform other programmers that they
+ can see all uses of the variable before them, and to advise them
+ not to add uses elsewhere.
+
+ * Give the variable a well-defined, documented meaning, and make all
+ appropriate functions refer to it (but not bind it or set it)
+ wherever that meaning is relevant. For example, the variable
+ `case-fold-search' is defined as "non-`nil' means ignore case when
+ searching"; various search and replace functions refer to it
+ directly or through their subroutines, but do not bind or set it.
+
+ Then you can bind the variable in other programs, knowing reliably
+ what the effect will be.
+
+ In either case, you should define the variable with `defvar'. This
+helps other people understand your program by telling them to look for
+inter-function usage. It also avoids a warning from the byte compiler.
+Choose the variable's name to avoid name conflicts--don't use short
+names like `x'.
+
+\1f
+File: lispref.info, Node: Buffer-Local Variables, Next: Variable Aliases, Prev: Variable Scoping, Up: Variables
+
+Buffer-Local Variables
+======================
+
+ Global and local variable bindings are found in most programming
+languages in one form or another. XEmacs also supports another, unusual
+kind of variable binding: "buffer-local" bindings, which apply only to
+one buffer. XEmacs Lisp is meant for programming editing commands, and
+having different values for a variable in different buffers is an
+important customization method.
+
+* Menu:
+
+* Intro to Buffer-Local:: Introduction and concepts.
+* Creating Buffer-Local:: Creating and destroying buffer-local bindings.
+* Default Value:: The default value is seen in buffers
+ that don't have their own local values.
+
+\1f
+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::.
+
+\1f
+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 &optional BUFFER
+ This returns `t' if VARIABLE is buffer-local in buffer BUFFER
+ (which defaults to the current buffer); otherwise, `nil'.
+
+ - 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.
+
+\1f
+File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables
+
+The Default Value of a Buffer-Local Variable
+--------------------------------------------
+
+ The global value of a variable with buffer-local bindings is also
+called the "default" value, because it is the value that is in effect
+except when specifically overridden.
+
+ The functions `default-value' and `setq-default' access and change a
+variable's default value regardless of whether the current buffer has a
+buffer-local binding. For example, you could use `setq-default' to
+change the default setting of `paragraph-start' for most buffers; and
+this would work even when you are in a C or Lisp mode buffer that has a
+buffer-local value for this variable.
+
+ The special forms `defvar' and `defconst' also set the default value
+(if they set the variable at all), rather than any local value.
+
+ - Function: default-value SYMBOL
+ This function returns SYMBOL's default value. This is the value
+ that is seen in buffers that do not have their own values for this
+ variable. If SYMBOL is not buffer-local, this is equivalent to
+ `symbol-value' (*note Accessing Variables::.).
+
+ - Function: default-boundp SYMBOL
+ The function `default-boundp' tells you whether SYMBOL's default
+ value is nonvoid. If `(default-boundp 'foo)' returns `nil', then
+ `(default-value 'foo)' would get an error.
+
+ `default-boundp' is to `default-value' as `boundp' is to
+ `symbol-value'.
+
+ - Special Form: setq-default SYMBOL VALUE
+ This sets the default value of SYMBOL to VALUE. It does not
+ evaluate SYMBOL, but does evaluate VALUE. The value of the
+ `setq-default' form is VALUE.
+
+ If a SYMBOL is not buffer-local for the current buffer, and is not
+ marked automatically buffer-local, `setq-default' has the same
+ effect as `setq'. If SYMBOL is buffer-local for the current
+ buffer, then this changes the value that other buffers will see
+ (as long as they don't have a buffer-local value), but not the
+ value that the current buffer sees.
+
+ ;; In buffer `foo':
+ (make-local-variable 'local)
+ => local
+ (setq local 'value-in-foo)
+ => value-in-foo
+ (setq-default local 'new-default)
+ => new-default
+ local
+ => value-in-foo
+ (default-value 'local)
+ => new-default
+
+ ;; In (the new) buffer `bar':
+ local
+ => new-default
+ (default-value 'local)
+ => new-default
+ (setq local 'another-default)
+ => another-default
+ (default-value 'local)
+ => another-default
+
+ ;; Back in buffer `foo':
+ local
+ => value-in-foo
+ (default-value 'local)
+ => another-default
+
+ - Function: set-default SYMBOL VALUE
+ This function is like `setq-default', except that SYMBOL is
+ evaluated.
+
+ (set-default (car '(a b c)) 23)
+ => 23
+ (default-value 'a)
+ => 23
+
--- /dev/null
+This is Info file ../../info/new-users-guide.info, produced by Makeinfo
+version 1.68 from the input file new-users-guide.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Intro: (new-users-guide). Introduction to the XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This manual serves as an introduction to the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+\1f
+Indirect:
+new-users-guide.info-1: 648
+new-users-guide.info-2: 50484
+new-users-guide.info-3: 99987
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f648
+Node: Intro\7f4626
+Node: Entering\7f7209
+Node: Enter\7f8723
+Node: Frame\7f9405
+Node: Exiting\7f11074
+Node: Mode Line\7f12274
+Node: Echo Area\7f14421
+Node: Windows and Menus\7f15776
+Node: XEmacs Window\7f16229
+Node: Pull-down Menus\7f19850
+Node: File menu\7f20729
+Node: Edit menu\7f23988
+Node: Options Menu\7f26515
+Node: Buffers Menu\7f31297
+Node: Help menu\7f31683
+Node: Edit\7f32181
+Node: Insert\7f33775
+Node: Cursor Position\7f35103
+Node: Erase\7f37174
+Node: Numeric Argument\7f38328
+Node: Undo\7f39512
+Node: Customization Basics\7f40275
+Node: Customizing key Bindings\7f41504
+Node: Customizing Menus\7f44994
+Node: Help\7f50484
+Node: The Help Menu\7f51172
+Node: Modes\7f56097
+Node: Major Modes\7f57013
+Node: Minor Modes\7f60962
+Node: Files\7f65048
+Node: File Names\7f65770
+Node: Visiting\7f67573
+Node: Saving Files\7f69697
+Node: Other Customizations\7f73075
+Node: Setting Variables\7f75544
+Node: Init File\7f78753
+Node: Select and Move\7f84222
+Node: Selecting Text\7f85176
+Node: Mouse\7f86689
+Node: Region Operation\7f88014
+Node: Moving Text\7f89274
+Node: Accumulating text\7f90514
+Node: Search and Replace\7f92834
+Node: Key Index\7f96698
+Node: Command Index\7f99987
+Node: Variable Index\7f104089
+Node: Concept Index\7f104666
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../../info/new-users-guide.info, produced by Makeinfo
+version 1.68 from the input file new-users-guide.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Intro: (new-users-guide). Introduction to the XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This manual serves as an introduction to the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+\1f
+File: new-users-guide.info, Node: Top, Next: Intro, Prev: (dir), Up: (dir)
+
+ The Emacs Editor ****************
+
+ Emacs is the extensible, customizable, self-documenting real-time
+display editor. This Info file will help you get started on using
+XEmacs. It corresponds to XEmacs version 19.13.
+
+* Menu:
+
+* Intro:: Introduction to XEmacs editor
+
+Indices, nodes containing large menus
+* Key Index:: An item for each standard Emacs key sequence.
+* Command Index:: An item for each command and function name
+* Variable Index:: An item for each variable in User-Guide
+* Concept Index:: An item for the concepts introduced
+
+Entering, Exiting and Editing Emacs
+* Entering:: Starting Emacs from the shell and Exiting
+* Windows and Menus:: Description of Pull-down menus
+* Edit:: Basic Editing commands
+
+Other Features of XEmacs
+* Customization Basics:: Customize Emacs menus and keybindings
+* Help:: Help menu and other help commands
+* Modes:: Major and Minor modes in XEmacs
+* Files:: Visiting, Saving and Listing Files
+* Other Customizations:: Customizing Variables, Modes, etc
+* Select and Move:: Selecting text and moving text
+* Search and Replace:: Searching and Replacing text
+
+
+
+ -- The Detailed Node Listing --
+
+Entering and Exiting Emacs
+
+* Enter:: Entering Emacs from the shell
+* Frame:: Basic information about the XEmacs Frame
+* Exiting:: Exiting Emacs
+* Mode Line:: Interpreting the mode line.
+* Echo Area:: Bottom of the frame where you interact
+ with Emacs.
+
+XEmacs Windows and Menus
+
+* XEmacs Window:: Manipulating XEmacs Windows
+* Pull-down Menus:: Description of XEmacs Pull-down Menus
+
+Pull-down menus
+
+* File menu:: Items on the File Menu
+* Edit menu:: Items on the Edit Menu
+* Options Menu:: Items on the Options Menu
+* Buffers Menu:: Items on the Buffers Menu
+* Help menu:: The Help Menu at the extreme right on
+ the frame
+
+Basic Editing Commands
+
+* Insert:: Insert text in Emacs by simply typing at
+ the cursor position.
+* Cursor Position:: Moving Around the cursor in the buffer,
+* Erase:: Different commands for erasing text
+* Numeric Argument:: Giving Numeric Arguments to commands
+* Undo:: Undoing Changes made by mistake
+
+Customize key bindings and menus
+
+* Customizing key Bindings:: Changing Key Bindings
+* Customizing Menus:: Adding, Deleting, Enabling and Disabling Menus
+
+Help
+
+* The Help Menu:: Items on the Help Menu
+
+Major and Minor Modes
+
+* Major Modes:: Choosing Major Modes
+* Minor Modes:: Auto-Fill, Abbrev and other minor modes
+
+Emacs Files
+
+* File Names:: How to type and edit file name arguments.
+* Visiting:: Visiting a file prepares Emacs to edit the file.
+* Saving Files:: How to save Emacs files.
+
+Other Customizations
+
+* Setting Variables:: Customizing Emacs variables
+* Init File:: Some examples of Lisp expressions in
+ .emacs file
+
+Selecting and Moving Text
+
+* Selecting Text:: Select a region of text by setting the Mark
+* Mouse:: Selecting Text with Mouse
+* Region Operation:: Various ways to operate on a selected text
+* Moving Text:: Moving Text
+* Accumulating text:: Accumulating Text from several buffers
+
+No sub menu for the node search and replace
+
+\1f
+File: new-users-guide.info, Node: Intro, Next: Key Index, Prev: Top, Up: Top
+
+Introduction
+************
+
+ You are reading about XEmacs which is a self-documenting,
+customizable, extensible real-time display editor.
+
+ XEmacs is a "display" editor because normally the text being edited
+is visible on the screen and is updated automatically as you type.
+*Note Display: (xemacs)Frame.
+
+ It is a "real-time" editor because the display is updated very
+frequently, usually after each character or pair of characters you type.
+This minimizes the amount of information you must keep in your head as
+you edit. *Note Real-time: (xemacs)Basic.
+
+ It is advanced because it provides facilities that go beyond simple
+insertion and deletion: filling of text; automatic indentation of
+programs; viewing two or more files at once; and dealing in terms of
+characters, words, lines, sentences, paragraphs, and pages, as well as
+expressions and comments in several different programming languages.
+It is much easier to type one command meaning "go to the end of the
+paragraph" than to find that spot with simple cursor keys.
+
+ "Self-documenting" means that at any time you can type a special
+character, `Control-h', to find out what your options are. You can
+also use `C-h' to find out what a command does, or to find all the
+commands relevant to a topic. *Note Help: (xemacs)Help.
+
+ "Customizable" means you can change the definitions of Emacs
+commands. For example, if you use a programming language in which
+comments start with `<**' and end with `**>', you can tell the Emacs
+comment manipulation commands to use those strings (*note Comments:
+(xemacs)Comments.). Another sort of customization is rearrangement of
+the command set. For example, you can set up the four basic cursor
+motion commands (up, down, left and right) on keys in a diamond pattern
+on the keyboard if you prefer. *Note Customization:
+(xemacs)Customization.
+
+ "Extensible" means you can go beyond simple customization and write
+entirely new commands, programs in the Lisp language to be run by
+Emacs's own Lisp interpreter. Emacs is an "on-line extensible" system:
+it is divided into many functions that call each other. You can
+redefine any function in the middle of an editing session and replace
+any part of Emacs without making a separate copy of all of Emacs. Most
+of the editing commands of Emacs are written in Lisp; the few
+exceptions could have been written in Lisp but are written in C for
+efficiency. Only a programmer can write an extension to Emacs, but
+anybody can use it afterward.
+
+\1f
+File: new-users-guide.info, Node: Entering, Next: Windows and Menus, Prev: Concept Index, Up: Top
+
+Entering and Exiting Emacs
+**************************
+
+ While using Emacs you should be familiar with the following three
+terms:
+
+Buffer
+ A buffer is a region of memory holding characters. It is the basic
+ editing unit; one buffer corresponds to one piece of text being
+ edited. You can have multiple buffers but you can edit only one
+ buffer at any one time. For more information, *Note Buffers:
+ (xemacs)Buffers.
+
+File
+ A file is a region of disk space holding characters. Emacs edits a
+ file by reading it into a buffer, editing that buffer and writing
+ out the buffer back to the file. To save your work permanently you
+ have to write it to a file. So after you load and work with a
+ file, you have to save it back.
+
+Windows
+ A window is a rectangular region in which a buffer is displayed.
+ You can open multiple windows with multiple buffers and edit them
+ by selecting the corresponding buffer. Initially, when you start
+ emacs, it will automatically open up a window for you.
+
+* Menu:
+
+* Enter:: Entering Emacs from the shell
+* Frame:: Basic information about the XEmacs Frame
+* Exiting:: Exiting Emacs
+* Mode Line:: Interpreting the mode line.
+* Echo Area:: Bottom of the frame where you interact
+ with Emacs.
+
+\1f
+File: new-users-guide.info, Node: Enter, Next: Frame, Prev: Entering, Up: Entering
+
+Entering Emacs
+==============
+
+ To enter Emacs type `xemacs' and press the Return key at the shell
+i.e. `xemacs <RET>'. This will bring up an emacs window with
+`*scratch*' as the default buffer because Emacs must always have a
+buffer to work on. Then choose the Open... option from the File menu on
+the menubar at the top of the frame. It will prompt you to enter a
+filename. After you enter the filename, Emacs will read that file into
+the current buffer. You can also type :
+ xemacs <filename> <RET>
+ directly which will bring up an Emacs frame with the "filename" as
+the buffer.
+
+\1f
+File: new-users-guide.info, Node: Frame, Next: Exiting, Prev: Enter, Up: Entering
+
+Emacs Frame
+===========
+
+ When you run XEmacs under X, a menu bar on top of the Emacs frame
+provides access to pull-down menus of file, edit, and help-related
+commands. The menus only provide convenient shortcuts, the options that
+they provide are available via key commands. You can invoke those
+commands from the keyboard also. For many of the options, their
+corresponding key commands are displayed right besides them. The five
+default menus on the menubar that you will see on the frame are File,
+Edit, Options, Buffers and Help. *Note XEmacs Pull-down Menus:
+(xemacs)XEmacs Pull-down Menus, for detailed information on the
+functions provided by the pull-down menus.
+
+ The Emacs frame has a rectangle shaped box at the extreme right and
+you can drag it up or down to scroll the window accordingly. Clicking
+on the arrows also serves the same purpose.
+
+ The last line in your window is `the Mode line' which will give you
+a description of what's going on in that particular window. *Note Mode
+Line::, for more information. Below the mode line is the `Echo area'.
+Emacs uses this area to interact with the user. *Note Echo Area::.
+
+ If you wish to open another file in a new window after you enter
+XEmacs, select Open in New Frame... from the File menu, which will
+prompt you for a filename and open a new window with that filename as
+the current buffer. If you want to open a new file in the same window,
+select Open.. from the File menu. You need to enter XEmacs only once,
+you can edit multiple files by opening several other frames or by
+switching between buffers.
+
+\1f
+File: new-users-guide.info, Node: Exiting, Next: Mode Line, Prev: Frame, Up: Entering
+
+Exiting Emacs
+=============
+
+ There are two commands for exiting Emacs, one for "suspending" Emacs
+and the other for "killing" Emacs. "Suspending" means stopping Emacs
+temporarily and returning control to the shell, allowing you to resume
+editing later in the same Emacs job, with the same files, same kill
+ring, same undo history, and so on. This is the usual way to exit.
+"Killing" Emacs means destroying the Emacs job. You can run Emacs
+again later, but you will get a fresh Emacs; there is no way to resume
+the same editing session after it has been killed.
+
+`C-z'
+ Suspend Emacs (`suspend-emacs'). If used under the X window
+ system, this command will shrink the X window containing the Emacs
+ frame to an icon. Clicking on the icon will resume that Emacs
+ process again. *Note Exiting Emacs: (xemacs)Exiting Emacs.
+
+`C-x C-c'
+ Kill Emacs (`save-buffers-kill-emacs'). You can also select Exit
+ Emacs option from the File menu to kill that Emacs process. If you
+ haven't saved the file, Emacs will ask you if you wish to save the
+ file before killing that process.
+
+\1f
+File: new-users-guide.info, Node: Mode Line, Next: Echo Area, Prev: Exiting, Up: Entering
+
+The Mode Line
+=============
+
+ When you enter XEmacs, each text window's last line is a "mode line"
+which describes what is going on in that window. Normally, the mode
+line looks like :
+
+ --CH-XEmacs: BUF (MAJOR MINOR)----POS------
+
+This gives information about the buffer being displayed in the window:
+the buffer's name, what major and minor modes are in use, whether the
+buffer's text has been changed, and how far down the buffer you are
+currently looking.
+
+ The CH contains :
+`**'
+ if the text in the buffer has been edited
+
+`--'
+ if the text in the buffer has not been edited
+
+`%%'
+ if the buffer is a read-only-buffer i.e. it cannot be edited
+
+ BUF is the name of the window's chosen "buffer". If you are editing
+a file (which is the selected buffer), the file name appears in BUF.
+*Note Buffers: (xemacs)Buffers.
+
+ POS contains :
+`All'
+ if your entire file is visible on the screen.
+
+`Top'
+ if you are looking at the beginning of the file.
+
+`Bot'
+ if you are looking at the end of the file.
+
+`NN%'
+ NN will be a number corresponding to the percentage of the file
+ above the top of the screen, for example `52', which means that 52%
+ of the file is above the top of the screen.
+
+ MAJOR is the name of the "major mode" in effect in the buffer. At
+any time, each buffer is in one and only one major mode. The available
+major modes include Fundamental mode (the least specialized), Text
+mode, Lisp mode, and C mode. *Note Major Modes: (xemacs)Major Modes,
+for details on how the modes differ and how you select one.
+
+ MINOR is a list of some of the "minor modes" that are turned on in
+the window's chosen buffer. For example, `Fill' means that Auto Fill
+mode is on which means that lines are broken automatically when they
+become too wide. *Note Minor Modes: (xemacs)Minor Modes, for more
+information on various minor modes and how to enable them.
+
+ You can also display time in the mode line. *Note The Mode Line:
+(xemacs)The Mode Line, for more information regarding the mode line.
+
+\1f
+File: new-users-guide.info, Node: Echo Area, Prev: Mode Line, Up: Entering
+
+The Echo Area
+=============
+
+ The line at the bottom of the frame (below the mode line) is the
+"echo area". Emacs uses this area to communicate with you:
+
+ * The "echo area" will print out the characters that you type. For
+ example, if you choose the Open... option from the File menu you
+ might get the following in the echo area:
+
+ Find file: /usr/lib/x11/
+
+ Now you need to give a file name to open, for example if the file
+ name is `myfile', you will type `myfile' after `/usr/lib/x11/' and
+ press the <Return> key. If you pause for more than a second while
+ typing, you will see the characters that you type in the "echo
+ area".
+
+ * The "echo area" also prints error messages. For example, if you
+ misspell `usr' and type `/urs/lib/x11/myfile' <RETURN> in the
+ above example you might get an error message. Since Emacs will not
+ be able to find the `/urs' directory, the "echo area" will say:
+
+ error--> Opening directory: no such file or directory, /urs/lib/x11/myfile
+
+ This error message will be accompanied by a beep. Some XEmacs
+ commands will print informative messages in the "echo area". *Note
+ The Echo Area: (xemacs)The Echo Area, for more information on the
+ "echo area".
+
+\1f
+File: new-users-guide.info, Node: Windows and Menus, Next: Edit, Prev: Entering, Up: Top
+
+XEmacs Windows and Menus
+************************
+
+ The first section of this chapter will show you how you can
+manipulate XEmacs Windows and the other section will explain the
+Pull-down Menus of an XEmacs window.
+
+* Menu:
+
+* XEmacs Window:: Manipulating XEmacs Windows
+* Pull-down Menus:: Description of XEmacs Pull-down Menus
+
+\1f
+File: new-users-guide.info, Node: XEmacs Window, Next: Pull-down Menus, Prev: Windows and Menus, Up: Windows and Menus
+
+XEmacs Windows
+==============
+
+ When you use XEmacs under X, you can open multiple windows and each
+window can display one buffer or multiple parts of one buffer. Each
+window will have its own "mode line" and "echo area". At any one time
+there is only one "selected window" and the buffer it displays is the
+"selected buffer". There are some commands for manipulating windows:
+
+`M-C-v'
+ This command will scroll the window which is not "selected"
+ (`scroll-other-window').
+
+`C-x 0'
+ This command will get rid of the selected window (`delete-window').
+ That is a zero. If there is more than one Emacs frame, deleting the
+ sole remaining window on that frame deletes the frame as well. If
+ the current frame is the only frame, it is not deleted.
+
+`C-x 1'
+ This command will get rid of all the windows except the selected
+ one. (`delete-other-windows'). For example, if you use the
+ Describe variable option from the Help menu, the window will split
+ vertically and the bottom window will contain documentation for
+ that variable. After you are done looking at that variable's
+ documentation you might want to come back to your original single
+ window. Just type `C-x 1' after your cursor is in the top window
+ (the window which you want to keep) and hit <RET>.
+
+`C-x 2'
+ This command will split the selected window into two windows, one
+ above the other (`split-window-vertically'). Both the windows will
+ start out by displaying the same buffer. The window in which you
+ have your cursor will be your "selected window".
+
+`C-x 3'
+ This will split the selected window into two windows positioned
+ side by side (`split-window-horizontally'). A line of vertical
+ bars will separate the window.
+
+You can select a buffer in another window by using some other commands.
+These commands all have a prefix key `C-x 4'
+`C-x 4 b BUFNAME <RET>'
+ This command will select a buffer BUFNAME in another window. This
+ runs `switch-to-buffer-other-window'. It will prompt you for a
+ buffername.
+
+`C-x 4 f FILENAME <RET>'
+ Visit file FILENAME and select its buffer in another window. This
+ runs `find-file-other-window'. *Note Visiting: (xemacs)Visiting.
+ It will prompt you for a filename.
+
+`C-x 4 d DIRECTORY <RET>'
+ Select a Dired buffer for directory DIRECTORY in another window.
+ This runs `dired-other-window'. *Note Dired: (xemacs)Dired.
+
+`C-x 4 m'
+ Start composing a mail message in another window. This runs
+ `mail-other-window', and its same-window version is `C-x m'.
+ *Note Sending Mail: (xemacs)Sending Mail, for information on how
+ to Send Mail using XEmacs. *Note Reading Mail With Rmail:
+ (xemacs)Reading Mail With Rmail, for information on reading mail
+ using Rmail.
+
+ If you click the right button on the mouse on a mode line, you will
+get a menu with following options:
+Delete Window
+ Choosing this menu will remove the window above this modeline from
+ the frame.
+
+Delete Other Windows
+ Delete all windows on the frame except for the one above this
+ modeline.
+
+Split Window
+ Split the window above the mode line in half, creating another
+ window.
+
+Split Window Horizontally
+ Split the window above the mode line in half horizontally, so that
+ there will be two windows side-by-side.
+
+Balance Windows
+ Readjust the sizes of all windows on the frame until all windows
+ have roughly the same number of lines.
+
+\1f
+File: new-users-guide.info, Node: Pull-down Menus, Prev: XEmacs Window, Up: Windows and Menus
+
+XEmacs Pull-down Menus
+======================
+
+ When you run XEmacs under X, each Emacs frame has a menu-bar at the
+top which provides commands for editing, help and other options. All
+these options are also available via key commands, the menus just
+provide convenient short-cuts. The key commands are displayed right
+besides some of the options. The following is a brief description of
+the four default menus on the menu bar:
+
+* Menu:
+
+* File menu:: Items on the File menu
+* Edit menu:: Items on the Edit menu
+* Options Menu:: Items on the Options Menu
+* Buffers Menu:: Items on the Buffers Menu
+* Help menu:: The Help Menu at the extreme right on
+ the frame
+
+\1f
+File: new-users-guide.info, Node: File menu, Next: Edit menu, Prev: Pull-down Menus, Up: Pull-down Menus
+
+The File Menu
+-------------
+
+ The File menu bar contains the following items. To choose a
+particular option, press the left mouse button and drag it to the item
+you wish to select. Then release the button.
+
+Open...
+ This option will prompt you for a file name. You will get a
+ message in the echo area:
+
+ Find File:
+
+ After Find File, there might be a directory path also. After you
+ type the file name and press <RET> the file will be loaded into a
+ new buffer.
+
+Open in New Frame...
+ It prompts you for a file name and loads that file in a new buffer
+ in a new frame. You can open many frames for the same Emacs
+ session. You can delete the frame by selecting Delete Frame.
+
+Insert File...
+ Prompts you for a filename and inserts the contents of this
+ filename in your current buffer. Position your cursor at the place
+ you wish to insert the file and select this option. You will get
+ the following message in the echo area:
+
+ Insert file:
+
+ Insert the file name and press <RET>.
+
+Save <Buffername>
+ It saves the changes you have made to the buffer. If you have made
+ changes which are not saved yet, the option will appear dark,
+ otherwise it will be light and unselectable. If you do not wish to
+ save the changes, select Revert Buffer.
+
+Save As...
+ Prompts you for a filename and saves the current buffer in that
+ file. It loads the new file if the filename you specify is
+ different from the one you were working with.
+
+Print Buffer <buffername>
+ Prints a hardcopy of the current or "selected" buffer.
+
+New Frame
+ Opens a new frame with *scratch* as the default buffer. It doesn't
+ prompt you for a filename. To open a file you need to go to that
+ frame and select Open...
+
+Split Frame
+ Splits the current window into two equal-sized windows with the
+ same buffer. To get back a single frame, select Un-Split (Keep
+ This). *Note XEmacs Window::, for more information about windows.
+
+Un-Split (Keep This)
+ If the frame contains multiple windows, it will remove all windows
+ except the selected one.
+
+Un-Split (Keep Others)
+ If the frame contains multiple windows, it will remove the selected
+ window and keep the other one.
+
+Revert Buffer <buffername>
+ If you do not wish to save the changes you made to the file since
+ you opened it, select this option. It will restore the last saved
+ version of the file to the current buffer.
+
+Kill Buffer <buffername>
+ It will kill the current buffer. If will prompt you if there are
+ unsaved changes.
+
+Exit Emacs
+ It will kill the Emacs "process" as opposed to simply killing the
+ "buffer". Before it kills the process, it will prompt you as to
+ which unsaved buffers you wish to save by going through the list
+ of the buffers.
+
+* Menu:
+
+* Edit menu:: Items on the Edit Menu
+* Options Menu:: Items on the Options Menu
+* Buffers Menu:: Items on the Buffers Menu
+* Help menu:: The Help Menu at the extreme right on
+ the frame
+
+\1f
+File: new-users-guide.info, Node: Edit menu, Next: Options Menu, Prev: File menu, Up: Pull-down Menus
+
+The Edit Menu
+-------------
+
+ Most of the commands in this menu work on a block of text or a
+selected region. The text will be highlighted as you select it.
+Undo
+ Undoes the previous command. If you type something by mistake you
+ can use this command. For example, if you select Insert File...
+ from the File menu and insert a wrong file by mistake, you can
+ select this item and it will remove the inserted file. It undoes a
+ batch of text which is worth an emacs command.
+
+Cut
+ Removes the selected text block from the current buffer, makes it
+ the X clipboard selection, and places it in the kill ring (*note
+ Moving Text::.). Before executing this command, you have to select
+ a region using Emacs region selection commands or with the mouse.
+ *Note Selecting Text::.
+
+Copy
+ Makes a selected text block the X clipboard selection, and places
+ it in the kill ring. You can select text using one of the Emacs
+ region selection commands or by selecting a text region with the
+ mouse. *Note Selecting Text::, for more information.
+
+Paste
+ Inserts the current value of the X clipboard selection in the
+ current buffer. Note that this is not necessarily the same as the
+ Emacs `yank' command, because the Emacs kill ring and the X
+ clipboard selection are not the same thing. You can paste in text
+ you have placed in the clipboard using Copy or Cut. You can also
+ use Paste to insert text that was pasted into the clipboard from
+ other applications. *Note X Clipboard Selection: (xemacs)X
+ Clipboard Selection, for information on using Clipboard Selection.
+
+Clear
+ Removes the selected text block from the current buffer but does
+ not place it in the kill ring or the X clipboard selection. You
+ will not be able to get this text back.
+
+Start Macro Recording
+ After selecting this, Emacs will remember every keystroke you type
+ until End Macro Recording is selected.
+
+End Macro Recording
+ Selecting this tells emacs to stop remembering your keystrokes.
+
+Execute Last Macro
+ Selecting this item will cause emacs to re-interpret all of the
+ keystrokes which were saved between selections of the Start Macro
+ Recording and End Macro Recording menu items. You can now execute
+ the most recent keyboard macro. *Note Keyboard Macros:
+ (xemacs)Keyboard Macros, for further information.
+
+\1f
+File: new-users-guide.info, Node: Options Menu, Next: Buffers Menu, Prev: Edit menu, Up: Pull-down Menus
+
+The Options Menu
+----------------
+
+ There are sub-menus for some of the menus which you will need to
+select. If sub-menus exist for an item, they will be displayed
+automatically when you drag the mouse on that item. The items in this
+menu provide some fancy editing operations.
+
+Read Only
+ Selecting this item will cause the buffer to visit the file in a
+ read-only mode. Changes to the file will not be allowed.
+
+Case Sensitive Search
+ Selecting this item will cause searches to be case-sensitive. If
+ its not selected then searches will ignore case. This option is
+ local to the buffer. For example, if this item is selected and you
+ are searching for `Smile', then an occurrence of `smile' will not
+ be recognized because of the smaller case of `s'.
+
+Overstrike
+ After selecting this item, when you type letters they will replace
+ existing text on a one-to-one basis, rather than pushing it to the
+ right. At the end of a line, such characters extend the line.
+ Before a tab, such characters insert until the tab is filled in.
+
+Auto Delete Selection
+ Selecting this item will cause automatic deletion of the selected
+ region. After you select a region and hit the <RET> key, the
+ selected text will be deleted. The typed text will replace the
+ selection if the selection is active (i.e. if its highlighted). If
+ the option is not selected then the typed text is just inserted at
+ the cursor.
+
+Teach Extended Commands
+ After you select this item, any time you execute a command with
+ `M-x' which has a shorter keybinding, you will be shown the
+ alternate binding before the command executes. For example if you
+ type `M-x find-file-other-window' which performs the same function
+ as the Open in Other Window... in File menu you will see the
+ following message:
+
+ M-x find-file-other-window (bound to keys: C-x 4 f, C-x 4 C-f)
+
+Syntax Highlighting
+ You can customize your `.emacs' file to include the font-lock mode
+ so that when you select this item, the comments will be displayed
+ in one face, strings in another, reserved words in another, and so
+ on. *Note Customization: (xemacs)Customization, for more
+ information on customizing `.emacs' file. After selecting this
+ item, you will find your code a lot easier to read. When Fonts is
+ selected, different parts of the program will appear in different
+ Fonts. When Colors is selected, then the program will be displayed
+ in different colors. Selecting None causes the program to appear in
+ just one Font and Color. Selecting Less resets the Fonts and Colors
+ to a fast, minimal set of decorations. Selecting More resets the
+ Fonts and Colors to a larger set of decorations. For example, if
+ Less is selected (which is the default setting) then you might have
+ all comments in green color. It does not matter what the comments
+ contain. Whereas, if More is selected then a function name in the
+ comments themselves might appear in a different Color or Font. Even
+ though the comments themselves might appear in green color, a
+ function name "within" the comments might appear in red color.
+
+Paren Highlighting
+ After selecting Blink from this item, if you place the cursor on a
+ parenthesis, the matching parenthesis will blink. If you select
+ Highlight and place the cursor on a parenthesis, the whole
+ expression of the parenthesis under the cursor will be highlighted.
+ Selecting None will turn off the options (regarding Paren
+ Highlighting) which you had selected earlier.
+
+Font
+ You can select any Font for your program by choosing from one of
+ the available Fonts. The whole buffer will be converted to the
+ Font you select.
+
+Size
+ You can select any size for the text in your buffer (ranging from
+ 2 to 24) by selecting the appropriate option.
+
+Weight
+ You can choose either Bold or Medium for the weight of the text of
+ your buffer.
+
+Buffers Menu Length...
+ Prompts you for the number of buffers to display. Then it will
+ display that number of most recently selected buffers.
+
+Buffers Sub-Menus
+ After selection of this item the Buffers menu will contain several
+ commands, as submenus of each buffer line. If this item is
+ unselected, then there are no submenus for each buffer line, the
+ only command available will be selecting that buffer.
+
+Save Options
+ Selecting this item will save the current settings of your Options
+ menu to your `.emacs' file so that the next time you start XEmacs,
+ you won't need to select the options again.
+
+\1f
+File: new-users-guide.info, Node: Buffers Menu, Next: Help menu, Prev: Options Menu, Up: Pull-down Menus
+
+The Buffers Menu
+----------------
+
+ The Buffers menu provides a selection of up to ten buffers and the
+item List All Buffers, which provides a Buffer List. If you select
+Buffers Sub-menus from the Options menu, you will get some sub-menus
+for each of the buffer listing.
+
+\1f
+File: new-users-guide.info, Node: Help menu, Prev: Buffers Menu, Up: Pull-down Menus
+
+The Help Menu
+-------------
+
+ The Help Menu gives you access to Emacs Info and provides a menu
+equivalent for some of the choices you have when using `C-h'. *Note
+Help::, for more information.
+
+ The Describe variable and Describe function will provide
+documentation for the corresponding variable or function. The Help menu
+also gives access to UNIX online manual pages via the UNIX Manual...
+option.
+
+\1f
+File: new-users-guide.info, Node: Edit, Next: Customization Basics, Prev: Windows and Menus, Up: Top
+
+Basic Editing Commands
+**********************
+
+ This chapter will introduce you to some basic editing commands. You
+can also learn the basic editing commands by typing `Control-h t'
+(`help-with-tutorial' OR by selecting Emacs Tutorial from the Help menu
+on the menu bar. Most of the Emacs commands will use the <CONTROL> key
+or the <META> key. The following abbreviations will be used for the
+<CONTROL> and <META> key in this manual:
+
+`C-<chr>'
+ This means that you should hold down the <CONTROL> key while typing
+ `<chr>'. For example, if the command is `C-g', you should hold the
+ <CONTROL> key and type <g>.
+
+`M-<chr>'
+ This means that you should hold down the `META' key while typing
+ `<chr>'. If there is no `META' key on your keyboard, use the `ESC'
+ key instead. For example, if the command is `M-x', then type
+ `ESC', release it and type `x'.
+
+ The following abbreviations will be used for some other keys:
+
+<SPC>
+ Space bar.
+
+<RET>
+ Return key.
+
+<LFD>
+ Linefeed key.
+
+<TAB>
+ Tab.
+
+<ESC>
+ Escape.
+
+<SFT>
+ Shift.
+
+* Menu:
+
+* Insert:: Insert text in Emacs by simply typing at
+ the cursor position.
+* Cursor Position:: Moving Around the cursor in the buffer,
+* Erase:: Different commands for erasing text
+* Numeric Argument:: Giving Numeric Arguments to commands
+* Undo:: Undoing Changes made by mistake
+
+\1f
+File: new-users-guide.info, Node: Insert, Next: Cursor Position, Prev: Edit, Up: Edit
+
+Inserting Text
+==============
+
+ To insert printing characters into the text you are editing, just
+type them. Emacs will automatically insert the characters that you type
+into the buffer at the cursor. The cursor moves forward, but if you
+prefer to have text characters replace (overwrite) existing text
+characters, you can enable the Overstrike option from the Options menu
+in the menu bar.
+
+ To "delete" text you have just inserted, use <DEL>. <DEL> deletes
+the character BEFORE the cursor (not the one that the cursor is on top
+of or under; that is the character AFTER the cursor). The cursor and
+all characters after it move backwards. Therefore, if you type a
+printing character and then type <DEL>, they cancel out.
+
+ To end a line and start typing a new one, type <RET>. This inserts
+a newline character in the buffer. If point is in the middle of a
+line, <RET> splits the line. Typing <DEL> when the cursor is at the
+beginning of a line rubs out the newline before the line, thus joining
+the line with the preceding line.
+
+ Emacs automatically splits lines when they become too long, if you
+turn on a special mode called "Auto Fill" mode. *Note Filling:
+(xemacs)Filling, for information on using Auto Fill mode.
+
+\1f
+File: new-users-guide.info, Node: Cursor Position, Next: Erase, Prev: Insert, Up: Edit
+
+Moving Around
+=============
+
+ The following commands will allow you to move the cursor around the
+screen. The actual function names corresponding to these commands are
+given in parenthesis. You can also invoke these commands by typing `M-x
+<function name>'. You can do this for any command in XEmacs.
+
+`C-b'
+ Move the cursor backward one character (`backward-char').
+
+`C-f'
+ Move the cursor forward one character (`forward-char').
+
+`C-p'
+ Move the cursor up one line vertically (`previous-line').
+
+`C-n'
+ Move the cursor down one line vertically (`next-line').
+
+`C-a'
+ Move the cursor to the beginning of the line (`beginning-of-line').
+
+`C-e'
+ Move the cursor to the end of the line (`end-of-line').
+
+`M-f'
+ Move the cursor forward one word (`forward-word').
+
+`M-b'
+ Move the cursor backword one word (`backward-word').
+
+`M-<'
+ Move the cursor to the top of the buffer (`beginning-of-buffer').
+
+`M->'
+ Move the cursor to the end of the buffer (`end-of-buffer').
+
+`M-x goto-char RET <number> RET'
+ To enable this command type `M-x goto-char', and hit <RETURN> key.
+ In the "echo area" you will see:
+
+ Goto char:
+
+ You should then type in a number right after the colon and hit the
+ `RETURN' key again. After reading a number N this command will
+ move the cursor to character number N. Position 1 is the
+ beginning of the buffer. For example, if you type `M-x goto-char
+ RET 200 RET', then the cursor will move to the 200th character
+ starting from the beginning of the buffer.
+
+`M-x goto-line RET <number> RET'
+ To enable this command type `M-x goto-line', and hit the <RETURN>
+ key. After you see `Goto line:' in the "echo area", type in a
+ number N and hit <RETURN> key again. This command will position
+ the cursor on the nth line starting from the beginning of the
+ buffer.
+
+`M-x what-line RET'
+ This command will display the current line number in the echo area.
+
+\1f
+File: new-users-guide.info, Node: Erase, Next: Numeric Argument, Prev: Cursor Position, Up: Edit
+
+Erasing Text
+============
+
+`<DEL>'
+ If you press <DEL> i.e. the "delete" key, it will delete the
+ character before the cursor (`delete-backward-char').
+
+`C-d'
+ This will delete the character after the cursor (`delete-char').
+
+`C-k'
+ Kill to the end of the line (`kill-line'). If you kill the line by
+ mistake you can "yank" or `paste' it back by typing `C-y'. *Note
+ Moving Text::, for more information on yanking.
+
+`M-d'
+ Kill forward to the end of the next word (`kill-word').
+
+`M-<DEL>'
+ Kill back to the beginning of the previous word
+ (`backward-kill-word').
+
+`M-k'
+ Kill to the end of current sentence (`kill-sentence').
+
+`M-z CHAR'
+ Kill up to next occurrence of CHAR (`zap-to-char'). To use this
+ command type `M-z'. You will see the following statement in the
+ echo area :
+
+ Zap to char:
+
+ Type any char and press the <RET> key. For example, if you type
+ `p' then the entire text starting from the position of the cursor
+ until the first occurrence of `p' is killed.
+
+\1f
+File: new-users-guide.info, Node: Numeric Argument, Next: Undo, Prev: Erase, Up: Edit
+
+Giving Numeric Arguments
+========================
+
+ Any Emacs command can be given a "numeric argument". Some commands
+interpret the argument as a repetition count. For example, if you want
+to move forward ten characters, you could type `C-f' ten times.
+However, a more efficient way to do this would be to give an argument
+of ten to the key `C-f' (the command `forward-char', move forward one
+character). Negative arguments are also allowed. Often they tell a
+command to move or act backwards. For example, if you want to move down
+ten lines, type the following:
+ C-u 10 C-n RET
+
+After you press <RET> key, the cursor will move ten lines downward. You
+can also type:
+ M-10 C-n RET
+
+Both `C-u' and `M-' allow you to give numeric arguments. If you want to
+move ten lines backward, you can also give negative arguments, like:
+ C-u -10 C-n RET
+
+OR you could also type:
+ M--10 C-n RET
+
+You can obviously use `C-b' to move backward rather than giving
+negative arguments to `C-n'. *Note Numeric Arguments: (xemacs)Numeric
+Arguments, for more information on numeric arguments.
+
+\1f
+File: new-users-guide.info, Node: Undo, Prev: Numeric Argument, Up: Edit
+
+Undoing Changes
+===============
+
+ When you are editing a buffer, you might type something by mistake.
+Emacs allows you to undo all changes you make to a buffer (but not more
+than 8000 characters). Each buffer in Emacs keeps a record of the
+changes made to it individually, so the undo command applies to the
+current buffer. There are two undo commands:
+
+`C-x u'
+ Undo one batch of changes (usually, one command's worth).
+ (`undo').
+
+`C-_'
+ The same as above, but this command might not be obvious to type
+ on some keyboards so it might be better to use the above command.
+
+ *Note Undoing Changes: (xemacs)Undoing Changes, for more information
+on undoing changes.
+
+\1f
+File: new-users-guide.info, Node: Customization Basics, Next: Help, Prev: Edit, Up: Top
+
+Customize key bindings and menus
+********************************
+
+ When you start Emacs, it reads the file `~/.emacs' in your home
+directory. You can use this file to initialize and customize Emacs to
+your liking. This file should contain lisp-code. You can customize your
+`.emacs' file to create new menus, disable menus, change key bindings,
+enable a minor mode, etc. Any kind of customization affects only a
+particular Emacs job that you do them in. If you want to save your
+customizations `permanently' i.e. for future use also, you have to put
+it in your `.emacs' file. After you make changes to your `.emacs' file
+and save it, the changes will be effective only after you start Emacs
+again i.e. for a new Emacs process. To try out some of the examples in
+this section, highlight that region and evaluate the region by giving
+the command `M-x eval-region'. You will be able to see the results of
+your customizations in that Emacs session only (*note Lisp Eval:
+(xemacs)Lisp Eval.).
+
+* Menu:
+
+* Customizing key Bindings:: Changing Key Bindings
+* Customizing Menus:: Adding, Deleting, Enabling and Disabling Menus
+
+\1f
+File: new-users-guide.info, Node: Customizing key Bindings, Next: Customizing Menus, Prev: Customization Basics, Up: Customization Basics
+
+Customize key bindings
+======================
+
+ Most of Emacs commands use key sequences. *Note Keystrokes:
+(xemacs)Keystrokes, for more information about Keys and Commands. In
+Emacs, the keys themselves carry no meaning unless they are bound to a
+function. For example, `C-n' moves the cursor to the next line because
+its bound to the function next-line. Similarly, `C-p' moves to the
+previous line because its bound to the function previous-line. The
+functions themselves define a particular behavior. You can customize
+the key `C-n' to move to the previous line by binding it to
+previous-line and `C-p' to move to the next line by binding it to
+next-line. To bind keys to globally run commands you need to use the
+following syntax in your .emacs file:
+
+ `(global-set-key KEYS CMD)'
+
+Here, `global-set-key' is a function which will bind the "keys" to the
+specified "cmd". For example, if you type the following in your .emacs
+file:
+
+ (global-set-key "\C-p" 'next-line)
+ (global-set-key "\C-n" 'previous-line)
+
+then `C-p' will move to the next line and `C-n' to the previous line.
+
+ You can also disable a key binding, by using `nil' as the CMD in the
+syntax stated above. Here, `nil' stands for `false' which means disable
+a command or turn off a feature. If you want to enable a command or
+turn on a particular feature use `t' which stands for `true'. For
+example, if you do not wish `C-x C-c' to `Exit Emacs' you can type the
+following expression in your `.emacs' file:
+
+ (global-set-key "\C-x\C-c" nil)
+
+You might want to have this statement in your `.emacs' file because its
+easy to hit this command by mistake and it could be annoying to exit
+Emacs unintentionally. There is a Exit Emacs option in the File menu
+which you might want to use instead. To make a particular key undefined
+you can also use:
+
+ (global-unset-key "\C-x\C-c")
+
+Now if you use the command `C-x C-c', you will get an error saying that
+the command is undefined.
+
+ Some other customizations you could try are:
+ * (global-set-key 'button3 'beginning-of-buffer)
+
+ Now when you press the third button of your mouse, the cursor will
+ be placed at the `beginning-of-buffer'.
+
+ * (global-set-key 'f1 'goto-line)
+
+ If you press the <F1> key, you will be prompted for a line number.
+ After you type the line number and hit <RET>, the cursor will be
+ placed on that line number.
+
+ * (global-set-key 'f2 'undo)
+
+ Pressing <F2> will undo the last command. If you have a <undo> key
+ on your keyboard, try binding that key to the undo command.
+
+ Another syntax for customizing key bindings is: `(define-key KEYMAP
+KEYS DEF)' It defines KEYS to run DEF in the keymap KEYMAP.
+
+ KEYMAP is a keymap object which records the bindings of keys to the
+commands that they run.
+
+ KEYS is the sequence of keystrokes to bind.
+
+ DEF is anything that can be a key's definition:
+
+ Look at the following two examples:
+
+ (define-key global-map "\C-xl" 'make-symbolic-link)
+ (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+
+Both the examples bind the key `C-xl' to run the function
+`make-symbolic-link' (*note Misc File Ops: (xemacs)Misc File Ops.).
+However, the second example will bind the key only for C mode. *Note
+Major Modes: (xemacs)Major Modes, for more information on Major Modes
+in XEmacs.
+
+\1f
+File: new-users-guide.info, Node: Customizing Menus, Prev: Customizing key Bindings, Up: Customization Basics
+
+Customizing Menus
+=================
+
+ You can customize any of the XEmacs Pull-down-Menus. You can create
+your own menu, delete an existing one, enable a menu or disable a menu.
+For more information on the default menus available to you, *Note
+Pull-down Menus::.
+
+ Some of the functions which are available to you for customization
+are:
+ 1. add-menu-item: (MENU-NAME ITEM-NAME FUNCTION ENABLED-P &OPTIONAL
+ BEFORE)
+
+ This function will add a menu item to a menu, creating the menu
+ first if necessary. If the named item already exists, the menu
+ will remain unchanged. For example, if you add the following
+ example to your `.emacs' file or evaluate it (*note Customization
+ Basics::.),
+
+ (add-menu-item '("Edit") "Replace String" replace-string t "Clear")
+
+ a sub-menu Replace String will be created under Edit menu before
+ the sub-menu Clear. The Edit menu will now look like:
+
+ Undo C-x u
+ Cut cut
+ Copy copy
+ Paste paste
+ Replace String
+ Clear
+ Start Macro Recording C-x(
+ End Macro Recording C-x)
+ Execute Last Macro C-xe
+
+ Replace String will now execute the function `replace-string'.
+ Select this menu item. Emacs will prompt you for a string name to
+ be replaced. Type a string and hit <RET>. Now type a new string to
+ replace the old string and hit <RET>. All occurrences of the old
+ string will be replaced by the new string. In this example,
+
+ `Edit' is the MENU-NAME which identifies the menu into which the
+ new menu item should be inserted.
+
+ `Replace String' is the ITEM-NAME which names the menu item to be
+ added.
+
+ `replace-string' is the FUNCTION i.e. the command to be invoked
+ when the menu item "Replace String" is selected.
+
+ `t' is the ENABLED-P parameter which controls whether the menu
+ item is selectable or not. This parameter can be either `t'
+ (selectable), `nil' (not selectable), or a form to evaluate. This
+ form is evaluated just before the menu is displayed, and the menu
+ item will be selectable if the form returns non-`nil'.
+
+ `Clear' is the &OPTIONAL BEFORE parameter which is the name of the
+ menu before which the new menu or sub-menu should be added. The
+ &OPTIONAL string means that this parameter is optional. You do not
+ need to specify this parameter. If you do not specify this
+ parameter in the example above, the Replace String menu item will
+ be added at the end of the list of sub-menus in the Edit menu i.e.
+ after Execute Last Macro.
+
+ If you wish to add a new menu to the menubar, try:
+
+ (add-menu-item nil "Bot" 'end-of-buffer t)
+
+ This will create a new menu Bot on the menu bar. Selecting this
+ menu will take you to the end of the buffer. Using `nil' for the
+ parameter MENU-NAME will create a new menu. Your menu-bar will now
+ look like:
+
+ File Edit Options Buffers Bot Help
+
+ The following example will illustrate how you can add sub-menus to
+ the submenus themselves:
+
+ (add-menu-item '("File" "Management") "Copy File" 'copy-file t)
+ (add-menu-item '("File" "Management") "Delete File" 'delete-file t)
+ (add-menu-item '("File" "Management") "Rename File" 'rename-file t)
+
+ This will create a sub-menu Management under the File menu. When
+ you select the submenu Management, it will contain three submenus:
+ Copy File, Delete File and Rename File.
+
+ 2. delete-menu-item: (MENU-PATH) This function will remove the menu
+ item defined by MENU-NAME from the menu hierarchy. Look at the
+ following examples and the comments just above them which specify
+ what the examples do.
+
+ ;; deletes the "Replace String" menu item created earlier
+ (delete-menu-item '("Edit" "Replace String"))
+
+ ;; deletes the "Bot" menu created earlier
+ (delete-menu-item '("Bot"))
+
+ ;; deletes the sub-menu "Copy File" created earlier
+ (delete-menu-item '("File" "File Management" "Copy File"))
+
+ ;; deletes the sub-menu "Delete File" created earlier
+ (delete-menu-item '("File" "Management" "Delete File"))
+
+ ;; deletes the sub-menu "Rename File" created earlier
+ (delete-menu-item '("File" "Management" "Rename File"))
+
+ 3. disable-menu-item: (MENU-NAME) Disables the specified menu item.
+ The following example
+
+ (disable-menu-item '("File" "Management" "Copy File"))
+
+ will make the Copy File item unselectable. This menu-item would
+ still be there but it will appear faded which would mean that it
+ cannot be selected.
+
+ 4. enable-menu-item: (MENU-NAME) Enables the specified previously
+ disabled menu item.
+
+ (enable-menu-item '("File" "Management" "Copy File"))
+
+ This will enable the sub-menu Copy File, which was disabled by the
+ earlier command.
+
+ 5. relabel-menu-item: (MENU-NAME NEW-NAME) Change the string of the
+ menu item specified by MENU-NAME to NEW-NAME.
+
+ (relabel-menu-item '("File" "Open...") "Open File")
+
+ This example will rename the Open... menu item from the File menu
+ to Open File.
+
+
--- /dev/null
+This is Info file ../../info/new-users-guide.info, produced by Makeinfo
+version 1.68 from the input file new-users-guide.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Intro: (new-users-guide). Introduction to the XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This manual serves as an introduction to the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+\1f
+File: new-users-guide.info, Node: Help, Next: Modes, Prev: Customization Basics, Up: Top
+
+Help
+****
+
+ XEmacs provides a comprehensive Help facility. On the extreme right
+of the menu-bar there is a Help menu. There are several help commands
+provided by this menu. You can also use `C-h' for invoking the Help
+facility. Type "?" for a list of keys you can type after typing `C-h'.
+If you want more information on what your options are and what kind of
+help you can get type "?" again. You will get a listing of all the keys
+you can type and what they will do. Initially if you want help, type
+`C-h' three times.
+
+* Menu:
+
+* The Help Menu:: Items on the Help menu
+
+\1f
+File: new-users-guide.info, Node: The Help Menu, Prev: Help, Up: Help
+
+Help menu
+=========
+
+ When you click on the Help menu with any of the mouse buttons you
+will get the following menu items:
+
+Info
+ Selecting this item will take you to the Info page which is the
+ online documentation browsing system. You can simply click on the
+ highlighted items and "Info" will take you to the document
+ providing information about that topic.
+
+Describe Mode
+ After you select this item, you will get a documentation on the
+ major and minor modes which are enabled in the buffer you are
+ working with. *Note Modes::, for information on Modes.
+
+Hyper Apropos...
+ After you select this item, you will see the following message in
+ the echo area:
+
+ List symbols matching regexp:
+
+ If you type "mode" and hit <RET>, you will get a list of all the
+ symbols (like functions and commands). You can now get
+ documentation on any of the given symbols by "clicking" on any of
+ the symbols (i.e. drag your mouse on the appropriate symbol and
+ release the button). For example, if you "click" on the
+ 'auto-fill-mode' you will get the following message in the window
+ at the bottom:
+
+ auto-fill-mode
+
+ Function, Command:
+
+ Toggle auto-fill mode.
+ With arg, turn auto-fill mode on if and only if arg is positive.
+ In auto-fill mode, inserting a space at a column beyond `fill-column'
+ automatically breaks the line at a previous space.
+
+ Variable:
+
+ value = nil
+
+ variable not documented
+
+Command Apropos...
+ Selecting this item will prompt you for a string just like when you
+ select Hyper Apropos.... After you give a string name, you will get
+ a listing of all the functions and commands containing that string
+ name with a very short description about what that command does.
+
+Full Apropos...
+ After you select this item, you will be prompted for a string name
+ in the echo area:
+
+ Apropos (regexp):
+
+ Now you can give any string name, for example "mode" and hit
+ <RET>. You will get a listing of all the variables and commands
+ containing that string i.e "mode" with a short description of its
+ function.
+
+List Keybindings
+ Select this item and you will get a listing of all the keys and the
+ commands that they execute. Depending on which Major mode your
+ buffer is in, you will get a listing of the special keybindings
+ for that particular buffer also. For example, if you are in
+ "Texinfo" mode, part of your list will contain:
+
+ C-c C-c n texinfo-insert-@node
+ C-c C-c o texinfo-insert-@noindent
+ C-c C-c s texinfo-insert-@samp
+ C-c C-c t texinfo-insert-@table
+ C-c C-c v texinfo-insert-@var
+ C-c C-c x texinfo-insert-@example
+ C-c C-c { texinfo-insert-braces
+
+ These keybindings apply only to "Texinfo" mode. *Note Modes::, for
+ more information on various modes.
+
+Describe Key...
+ After you select this item, you will be see the following message
+ in the echo area:
+
+ Describe Key:
+ After you type a command key sequence, full documentation of that
+ command will be displayed. For example if you type `C-g', you will
+ see the following documentation for `C-g':
+
+ keyboard-quit:
+ Signal a `quit' condition.
+ This means that `C-g' will quit whatever command you gave earlier.
+
+Describe Function...
+ This menu item provides documentation for a function. After you
+ select this item, it will prompt you for a function name in the
+ echo area:
+
+ Describe function (default <some function name>):
+
+ If you hit <RET> without giving a function name, you will get
+ documentation for that default function name, otherwise if you
+ type a function name and hit <RET>, you will get documentation for
+ the given function.
+
+Describe Variable...
+ You can get documentation on any variable by selecting this menu
+ item. It is similar to Describe Function and will prompt you for a
+ variable name.
+
+Unix Manual...
+ After you select this item you will be prompted for a Unix command
+ for which you wish to see the man page. You will see the following
+ message in the echo area:
+
+ Manual entry: (default <some name>)
+
+ Now you can type any command, for example type `who' and press
+ <RET>. You will get the man page for the Unix command `who' which
+ lists who is on the system.
+
+Emacs Tutorial
+ Select this item and you will get a tutorial on Emacs. It is good
+ for new users.
+
+Emacs News
+ Select this item and you will get a lot of historical and current
+ news on Emacs !
+
+ For more information on the Help facility, *Note Help: (xemacs)Help.
+
+\1f
+File: new-users-guide.info, Node: Modes, Next: Files, Prev: Help, Up: Top
+
+Major and Minor Modes
+*********************
+
+ XEmacs is "language sensitive". It has several "major" and "minor"
+modes. The major modes customize Emacs to edit text of a particular
+sort. There are major modes for C, Lisp, Emacs Lisp, LaTeX, English
+etc. Within each major mode, certain functions and keys are redefined
+to "suit" that particular sort of text. The minor modes provide certain
+features which can be turned off or on at any time. Emacs can only be
+in one major mode at any time, but it can turn on several minor modes
+at the same time. After you have selected any major or minor mode, you
+can select Describe Mode from the Help menu and you will get
+documentation about those modes.
+
+* Menu:
+
+* Major Modes:: Choosing Major Modes
+* Minor Modes:: Auto-Fill, Abbrev and other minor modes
+
+\1f
+File: new-users-guide.info, Node: Major Modes, Next: Minor Modes, Prev: Modes, Up: Modes
+
+Major Modes
+===========
+
+ Emacs has several major modes which customize Emacs to edit text of
+various sorts. You can have only one major mode at any time. Within each
+major mode, Emacs redefines certain functions (like cursor movement,
+indentation and text killing) to suit the needs of the text being
+edited. When you are editing a specific type of text you should switch
+to the appropriate mode. If you are working with C code, you should
+switch to C mode; if you are working with Lisp code, then switch to lisp
+mode and if you are working with English text switch to Text mode.
+
+ When you open a file to work on, Emacs usually selects the
+appropriate mode. For example, if you open a file called `guide.c' then
+Emacs will select the C mode because of the ".c" extension of the file.
+To explicitly select a mode type the following command:
+
+ ;;; selects lisp mode
+ M-x lisp-mode
+
+ ;;; selects C mode
+ M-x c-mode
+
+To select any other mode, just add the major mode name before the
+'-mode'. The current mode in which you are in will be displayed in
+parenthesis in the mode-line at the bottom of the frame. All major
+modes have some special keybindings and you can get a listing of those
+keybindings by selecting List Keybindings from the Help menu on the
+menu bar.
+
+ Some of the available modes in XEmacs are :
+
+fundamental-mode
+ When you start XEmacs, usually you start with the default
+ "Fundamental" mode. This mode has no special definitions or
+ settings.
+
+nroff-mode
+ Use this mode when you have to format a text with nroff before it
+ can be available in readable form. It redefines some indentation
+ commands. *Note Nroff Mode: (xemacs)Nroff Mode, for information on
+ this mode.
+
+tex-mode
+ Use this mode if you are using the LaTeX text-formatter. It
+ provides commands for insertion of quotes, braces and other
+ characters. It also allows you to format the buffer for printing.
+ *Note TeX Mode: (xemacs)TeX Mode, for information on this mode.
+
+texinfo-mode
+ Texinfo is a documentation system that uses a single source file to
+ produce both printed output and on-line documentation. When you
+ use this mode, there will be some special keybindings for
+ inserting some characters and executing some commands.
+
+ This info file which you are reading right now is produced by
+ 'Texinfo'
+
+outline-mode
+ Use this mode for editing outlines. When you enable this mode, you
+ can make part of the text temporarily invisible so that you can
+ see the overall structure of the outline. *Note Outline Mode:
+ (xemacs)Outline Mode, for information on this mode.
+
+c-mode
+ Use this mode for C programs. It will redefine some indentation
+ commands. *Note C Indent: (xemacs)C Indent.
+
+lisp-mode
+ Use this mode for Lisp programs. Look at the XEmacs User's Manual
+ for more information.
+
+fortran-mode
+ Use this mode for Fortran programs. This mode provides special
+ commands to move around and some other indentation commands. For
+ more information on this mode, *Note Fortran: (xemacs)Fortran.
+
+edit-picture
+ This is the picture mode which you can use to create a picture out
+ of text characters. *Note Picture: (xemacs)Picture, for more
+ information.
+
+asm-mode
+ Use asm-mode for editing files of assembler code. Look at the file
+ ` /usr/local/lib/xemacs-19.11/lisp/modes/asm.el' for more
+ information.
+
+ There are some other modes and commands for working with other kinds
+of text or programs. Emacs also provides commands for reading and
+sending Mail. For more information on these features look at the XEmacs
+Manual. Emacs also provides the functions of a desk calendar, with a
+diary of past or planned events. For more information on the calendar
+mode look at the manual for Calendar Mode and Diary.
+
+\1f
+File: new-users-guide.info, Node: Minor Modes, Prev: Major Modes, Up: Modes
+
+Minor Modes
+===========
+
+ The minor modes in Emacs provide some optional features which you can
+turn on or off. Any number of minor modes can be active at the same time
+with any major mode. You can enable a minor mode in one buffer and
+disable it in other mode. To enable a minor mode, for example the
+font-lock mode type the following command:
+
+ M-x font-lock-mode
+
+To enable the other minor modes, replace the "font-lock" with the name
+of the minor mode. To disable the mode type the command again. A
+positive argument will always turn the mode on. Whenever you type this
+command, it will turn the mode on if it was off, OR it will turn it off
+if it was on i.e. it toggles. Look at the mode-line at the bottom of the
+frame. If it says FLock in parentheses, then it means that this mode is
+on, otherwise it is off.
+
+ The following are some of the minor modes available in XEmacs. To
+enable any one of them type "M-x" in front of them.
+
+font-lock-mode
+ You can also choose this mode by selecting the Syntax Highlighting
+ menu item from the Options menu on the menu-bar at the top. If you
+ wish to have this mode enabled permanently, choose Save Options
+ from the Options menu. *Note Options Menu::, for more information
+ on the Options menu. You can also add statements in your `.emacs'
+ file. For each major mode in which you wish to enable this minor
+ mode, you need a statement in your `.emacs' file. The following
+ example shows how to enable the font-lock mode when the major mode
+ is c-mode.
+
+ (add-hook 'c-mode-hook 'turn-on-font-lock)
+
+ *Note Other Customizations::.
+
+ When you enable this mode, the text will be displayed in different
+ colors and fonts depending on the type of the text. This makes the
+ text very easy to read and understand. For example, comments might
+ be displayed in red, variables in black, functions in blue and
+ other keywords in different colors and fonts. When you select More
+ from the Syntax Highlighting option, you get very detailed display
+ of colors and fonts; function names within comments themselves
+ might appear in a different font and color.
+
+auto-fill-mode
+ Enabling this mode will provide automatic word-wrapping. The <SPC>
+ key will break lines i.e. insert newlines as you type to prevent
+ lines from becoming too long.
+
+overwrite-mode
+ When you enable this mode, the text that you type will replace the
+ existing text rather than moving it to the right (the default
+ case). You can enable this mode by selecting Overstrike menu-item
+ from the Options menu from the menu-bar.
+
+abbrev-mode
+ After you enable this mode, you can define words which will expand
+ into some different text i.e. you can define abbreviations. For
+ example, you might define "expand" to "expand will eventually
+ expand to this text". After this definition you will be able to
+ get "expand will eventually expand to this text" simply by typing
+
+ expand <SPC>
+
+ *Note Abbrevs: (xemacs)Abbrevs, for more information on this mode
+ and on defining abbreviations.
+
+auto-save-mode
+ After you enable this mode in a buffer, the contents of that
+ buffer will be saved periodically. This will reduce the amount you
+ might lose in case of a system crash.
+
+line-number-mode
+ After you enable this mode, the line number at which your cursor is
+ present will be displayed continously in the mode line.
+
+blink-paren
+ To enable this command, just type
+ M-x blink-paren
+
+ Do not add the "-mode" to it. You can also select the Paren
+ Highlighting option from the Options menu. After you enable this
+ command, put your cursor on one of the left parenthesis. The other
+ matching parenthesis will start blinking. *Note Options Menu::,
+ for more information on the Paren Highlighting option.
+
+ For information on some other modes, look at the XEmacs User's Manual
+and the associated files.
+
+\1f
+File: new-users-guide.info, Node: Files, Next: Other Customizations, Prev: Modes, Up: Top
+
+Files
+*****
+
+ The basic unit of stored data in Unix is the "file". To edit a file,
+you must tell Emacs to read the file into a buffer. This is called
+"visiting" the file. You can now edit the buffer and to save the
+changes you must write the buffer back to the file.
+
+ In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, and operate on file directories.
+
+* Menu:
+
+* File Names:: How to type and edit file name arguments.
+* Visiting:: Visiting a file prepares Emacs to edit the file.
+* Saving Files:: How to save Emacs files.
+
+\1f
+File: new-users-guide.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
+
+File Names
+==========
+
+ Most of the Emacs commands that operate on a file require you to
+specify a file name. For example, you might specify the file name
+initially when you enter Emacs :
+
+ xemacs myfile RET
+
+After you hit <RET>, you will enter XEmacs with "myfile" read into the
+current buffer. If you do not specify the filename when entering Emacs,
+you can use the Open... option from the File menu. You will be prompted
+for a filename in the echo area:
+
+ Find file: /usr/workspace/
+
+Type in a file name which you want to open after the "/" and hit <RET>.
+The specified file will be read into the current buffer. The
+"/usr/workspace" might be the "default directory". When Emacs prompts
+you for a file, it uses the default-directory unless you specify a
+directory. You can see what the default directory of the current buffer
+is by using the Describe Variable option from the Help menu. When Emacs
+prompts you for the variable name to describe, type DEFAULT-DIRECTORY.
+If you wish to open a file in some other directory, use <DEL> or the
+<BackSpace> key to go back and type the path name of the new directory.
+
+ You can create a new directory by typing `M-x make-directory'. This
+command will prompt you for a directory name:
+
+ Create directory: /usr/workspace/
+
+After you type a directory name and press <RET>, a new directory with
+the specified name will be created. If you do not wish to create a new
+directory, then simply press `C-g' to quit the command. Similarly, you
+can also remove a directory by using the command `remove-directory'.
+The command `M-x pwd' will print the current buffer's default
+directory. For more information on file names, *Note File Names:
+(xemacs)File Names.
+
+\1f
+File: new-users-guide.info, Node: Visiting, Next: Saving Files, Prev: File Names, Up: Files
+
+Visiting Files
+==============
+
+ To edit a file in Emacs you need to "visit" it. "Visiting" a file
+means copying its contents (or reading them) into the current buffer.
+Emacs will create a new buffer for each file that you visit. The buffer
+will be named after the file that you open. If you open a file
+`/usr/workspace/myfile.texinfo', the buffer will be called
+"myfile.texinfo". If a buffer with this name already exists, a unique
+name will be constructed by appending `<2>', `<3>', etc. If this is the
+second buffer with the same name, a "<2>" will be appended, "<3>" for a
+third buffer and so on. The name of the buffer which is being displayed
+in the window will be shown both at the top and bottom of the frame.
+Once you are in XEmacs, you can use the following commands:
+
+`C-x C-f'
+ This command will visit a file (`find-file'). It will prompt you
+ for a file name to visit. The Open... option from the File menu
+ does the same thing:
+
+ Find file: /usr/workspace/
+
+ Type in a filename and press <RET>. You will see a new buffer on
+ the screen with its name in the mode-line. If the filename you
+ specify already exists in Emacs, the buffer containing that file
+ will be selected. You will get an error message if the filename
+ does not exist. If you still press <RET>, a new buffer with the
+ given filename will be displayed on the screen.
+
+`C-x C-v'
+ This command (`find-alternate-file'), will visit a different file
+ instead of the one visited last. It is similar to `C-c C-f' except
+ that it kills the current buffer (after offering to save it).
+
+`C-x 5 C-f'
+ This command will visit a file in another frame
+ (`find-file-other-frame') without changing the current window or
+ frame. The Open in New Frame... from the File menu will do the
+ same thing. It will prompt you for a file name in the echo area.
+ After you type the file name and press <RET>, the specified file
+ will be read into a new buffer and displayed on a new frame.
+
+\1f
+File: new-users-guide.info, Node: Saving Files, Prev: Visiting, Up: Files
+
+Saving Files
+============
+
+ The changes that you make after visiting a file will not be saved
+unless you save the buffer. When you save the buffer, Emacs writes the
+current contents of the buffer into the visited file. Some commands to
+save buffers are:
+
+`C-x C-s'
+ This command will permanently save the current buffer in its
+ visited file (`save-buffer'). You will see the following message
+ in the echo area if you save a file called "myfile.texinfo" :
+
+ Wrote /usr/workspace/myfile.texinfo
+
+ Try using this command twice. You will get the above message the
+ first time you use this command, the second time you will get the
+ following message:
+
+ (No changes need to be saved)
+
+ This message indicates that you haven't made any changes since the
+ last time you saved the file.
+
+`C-x s'
+ This command will save all the buffers in their visited files
+ (`save-some-buffers'). It will prompt you for typing yes or no:
+
+ Save file /usr/workspace/myfile.texinfo? (y or n)
+
+ You will get the above message for all the buffers. Type "y" if
+ you want to save the buffer.
+
+`C-x C-w'
+ This command will prompt you for a file name and save the current
+ buffer in that file. (`write-file'). You will see the following
+ message in the echo area:
+
+ Write file: /usr/workspace/
+
+ After you type in a file name, press <RET>. The buffer will be
+ saved in a new file. You can make copies of a particular file
+ using this command.
+
+ You can also undo all the changes made since the file was visited or
+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
+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
+set-variable' to set it to `t' (*note Setting Variables::.). The backup
+file will contain the contents from the last time you visited the file.
+Emacs also provides options for creating numbered backups. For more
+information on backups, *Note Backup: (xemacs)Backup.
+
+ Emacs also saves all the files from time to time so that in case of a
+system crash you don't lose lot of your work. You will see the message
+`Auto-saving...' displayed in the echo area when the buffer is being
+saved automatically. The auto saved files are named by putting the
+character `#' in front and back. For example a file called
+"myfile.texinfo" would be named as `#myfile.texinfo#'. For information
+on controlling auto-saving and recovering data from auto-saving, *Note
+Auto Save Files: (xemacs)Auto Save Files.
+
+ Emacs provides protection from simultaneous editing which occurs if
+two users are visiting the same file and trying to save their changes.
+It will put a lock on a file which is being visited and modified. If
+any other user tries to modify that file, it will inform the user about
+the lock and provide some options. For more information on protection
+against simultaneous editing, *Note Interlocking: (xemacs)Interlocking.
+
+\1f
+File: new-users-guide.info, Node: Other Customizations, Next: Select and Move, Prev: Files, Up: Top
+
+Other Customizations
+********************
+
+ You can modify the behavior of Emacs in minor ways permanently by
+putting your changes in your `.emacs' file. This file contains Lisp
+function call expressions. Each of these expressions will consist of a
+function name followed by arguments, all surrounded by parentheses. For
+example, to turn on the auto-fill-mode (i.e. break lines automatically
+when they become too long) , put the following line in your `.emacs'
+file:
+
+ (add-hook 'text-mode-hook
+ '(lambda() (auto-fill-mode 1)))
+
+Emacs has a function named "turn-on-auto-fill" which is defined as
+"(lambda() (auto-fill-mode 1))". Therefore you can also write the above
+as:
+
+ (add-hook 'text-mode-hook 'turn-on-auto-fill)
+
+Emacs provides a number of hooks for the sake of customization. The hook
+variables contain list of functions to be called with no arguments. To
+turn on the auto-fill-mode, add the appropriate hook as shown in the
+example above.
+
+ Similarly, to enable the "font-lock mode" which displays your
+program in different fonts and colors(*note Modes::.), put the
+following in your `.emacs' file. The comments above the statement
+explain what the statements do.
+
+ ;;; enables the font-lock-mode in Lisp Mode
+ (add-hook 'lisp-mode-hook 'turn-on-font-lock)
+
+ ;;; enables the font-lock-mode in Texinfo Mode
+ (add-hook 'texinfo-mode-hook 'turn-on-font-lock)
+
+ ;;; enables the font-lock mode in C Mode
+ (add-hook 'c-mode-hook 'turn-on-font-lock)
+
+ To turn on the font-lock mode in other Major Modes like emacs-lisp,
+just put the name of the mode with "-hook" appended to it as the middle
+parameter in the above examples. You can also select the color that the
+functions, comments or other keywords should be displayed in :
+
+ ;;; the function names will now be displayed in blue color
+ (set-face-foreground 'font-lock-function-name-face "blue")
+
+ ;;; the comments will be displayed in forest green
+ (set-face-foreground 'font-lock-comment-face "forest green")
+
+For other customizations regarding the font-lock face, look at the file
+`/usr/local/lib/xemacs-19.11/etc/sample.emacs'.
+
+* Menu:
+
+* Setting Variables:: Customizing Emacs variables
+* Init File:: Some examples of Lisp expressions in
+ .emacs file
+
+\1f
+File: new-users-guide.info, Node: Setting Variables, Next: Init File, Prev: Other Customizations, Up: Other Customizations
+
+Other Customizations
+====================
+
+ In XEmacs, "variables" are used for internal record-keeping and
+customizations. There are some variables called "options" which you can
+use for customizations. To examine a variable use:
+
+ ;;; print the value and documentation of the variable, use either of the
+ ;;; following commands
+ C-h v
+ M-x describe variable
+
+ After you type any of the above commands, you will be prompted for a
+variable name in the "echo area". Type in the name of the variable, for
+example, type CASE-FOLD-SEARCH <RET> Your window will split into two
+and you will see the following message in that window:
+
+ case-fold-search's value is t
+ This value is specific to the current buffer.
+
+ Documentation:
+ *Non-nil if searches should ignore case.
+ Automatically becomes buffer-local when set in any fashion.
+
+Since this variable's value is 't' searches will ignore case. If you
+want case-sensitive-search (i.e. if you are searching for "Foo" and you
+do not want "foo" to be included in the search, you need to set this
+variable to "nil". In order to do that, use:
+
+ M-x set-variable
+
+Emacs will prompt you for the variable which you wish to set. Type in
+"case-fold-search" and hit <RET>. You will see the following message:
+
+ Set case-fold-search to value:
+
+Type "nil" and hit <RET>. Now if you again use `M-x describe variable'
+, you will see that the new value of case-fold-search will be "nil" and
+your searches will be case-sensitive. This will be effective only for
+that Emacs session. If you want to change the value of a variable
+permanently put the following statement in your `.emacs' file :
+
+ (setq case-fold-search nil)
+
+This statement will make searches case-sensitive only in the current
+buffer which is the `.emacs' file. This will not be very useful. To
+make searches case-sensitive globally in all buffers, use:
+
+ (setq-default case-fold-search nil)
+
+ If you want to change the value of any other variable, use :
+
+ (setq <variable-name> <new value>)
+
+"setq" will assign the "new value" to the "variable-name" .
+
+ If you want a list of the "options" i.e. the variables available for
+customization type:
+
+
+ ;;; displays a buffer listing names, values and documentation of options
+ M-x list-options
+
+ ;;; displays options and allows you to edit those list of options
+ M-x edit-options
+
+Try these options. If you are using edit-options to edit a variable,
+just point at the variable you wish to edit and use one of the following
+commands:
+
+1
+ Set the value of the variable to t (non-nil).
+
+0
+ Set the value of the variable to nil.
+
+n
+ Move to the next variable.
+
+p
+ Move to the previous variable.
+
+ There are some other options available to make the value of a
+variable local to a buffer and then to switch to its global value. You
+can also have a "local variables list" in a file which specifies the
+values to use for certain Emacs variables when you edit that file.
+*Note Variables: (xemacs)Variables, for information on these options.
+
+\1f
+File: new-users-guide.info, Node: Init File, Prev: Setting Variables, Up: Other Customizations
+
+Init File Examples
+==================
+
+ For customizing Emacs, you need to put Lisp expressions in your
+`.emacs' file. The following are some useful Lisp expressions. If you
+find any of them useful, just type them in your `.emacs' file:
+
+ * The following expression will make <TAB> in C mode insert a real
+ tab character if the cursor or point is in the middle of the line.
+ Now hitting the <TAB> key will indent a line only if the cursor is
+ at the left margin or in the line's indentation:
+
+ (setq c-tab-always-indent nil)
+
+ The value of the variable C-TAB-ALWAYS-INDENT is usually `t' for
+ `true'. When this variable is true, then hitting the <TAB> key
+ always indents the current line.
+
+ * This expression will turn on the AUTO-FILL-MODE when you are in
+ text mode:
+
+ (setq text-mode-hook 'turn-on-auto-fill)
+
+ This mode will automatically break lines when you type a space so
+ that the lines don't become too long. The length of the lines is
+ controlled by the variable FILL-COLUMN. You can set this variable
+ to a value you wish. Look at the documentation for this variable
+ to see its default value. To change the value to 75 for example,
+ use:
+
+ (setq-default fill-column 75)
+
+ This will change the value of this variable globally.
+
+ * The following expression will enable the use of EVAL-EXPRESSION
+ without confirmation:
+
+ (put 'eval-expression 'disabled nil)
+
+ Now when you use EVAL-EXPRESSION, it will print the value of the
+ expression you specify in the "echo area" without confirming with
+ you.
+
+ * This expression will remove the binding of `C-x C-c', because its
+ easy to hit this key by mistake and you will exit Emacs
+ unintentionally. You can use the Exit Emacs option from the File
+ menu to exit Emacs.
+
+ (global-set-key "\C-x\C-c" nil)
+
+ Now if you type `C-x C-c', you won't exit Emacs.
+
+ * The following expression will make the <BACKSPACE> and the <DEL>
+ key work in the same manner:
+
+ (global-set-key 'backspace [delete])
+
+ * This expression will make searches case sensitive:
+
+ (setq-default case-fold-search nil)
+
+ If we use "setq" instead of "setq-default" then searches will be
+ case-sensitive only in the current buffer's local value. In this
+ case the buffer would be the `.emacs' file. Since this would not
+ be too helpful and we want to have case-sensitive searches in all
+ buffers, we have to use "setq-default".
+
+ * This expression will enable the font-lock mode when you are using
+ texinfo mode:
+
+ (add-hook 'texinfo-mode-hook 'turn-on-font-lock)
+
+ *Note Minor Modes::, for information on font-lock mode.
+
+ * Rebinds the key `C-x l' to run the function `make-symbolic-link':
+
+ (global-set-key "\C-xl" 'make-symbolic-link)
+
+ We use the single quote before "make-symbolic-link" because its a
+ function name. You can also use the following expression which
+ does the same thing:
+
+ (define-key global-map "C-xl" 'make-symbolic-link)
+
+ * The following expression will bind `C-x l' to run the function
+ `make-symbolic-link' in C mode only:
+
+ (define-key c-mode-map "C-xl" 'make-symbolic-link)
+
+ Instead of binding `C-xl' to run `make-symbolic-link', you can
+ bind the <F1> key to run this function:
+
+ (define-key c-mode-map 'f1 'make-symbolic-link)
+
+ Here, you have to use lower case for naming function keys like
+ <F1>.
+
+ * You can bind the function `undo' i.e. `C-x u' to any key, for
+ example to <F2>:
+
+ (global-set-key 'f2 'undo)
+
+ * The following statement will display the current time in the
+ modeline of the buffer:
+
+ (display-time)
+
+ * This displays the current line number on which the cursor is
+ present in the modeline:
+
+ (setq line-number-mode t)
+
+ * If you don't want the text to be highlighted when you use commands
+ for marking regions so as to use the "kill" and "yank" commands
+ later, you can use the following expression in your `.emacs' file:
+
+ (setq zmacs-regions nil)
+
+ Now if you use a command like `C-x C-p' (`mark-page'), the text
+ will not be highlighted.
+
+ * To control the number of buffers listed when you select the Buffers
+ menu, you need to set the variable BUFFERS-MENU-MAX-SIZE to
+ whatever value you wish. For example, if you want 20 buffers to be
+ listed when you select Buffers use:
+
+ (setq buffers-menu-max-size 20)
+
+ * If you want the window title area to display the full
+ directory/name of the current buffer's file, and not just the
+ name, use:
+
+ (setq frame-title-format "%S: %f")
+
+ * To get rid of the menu, use :
+
+ (set-menubar nil)
+
+ * If you want an extensive menu-bar use the following expression in
+ your `.emacs' file.
+
+ (load "big-menubar")
+
+ If you want to write your own menus, you can look at some of the
+ examples in
+ `/usr/local/lib/xemacs-20.0/lisp/packages/big-menubar.el' file.
+
+ For more information on initializing your `.emacs' file, *Note Init
+File: (xemacs)Init File. You should also look at
+`/usr/local/lib/xemacs-20.0/etc/sample.emacs', which is a sample
+`.emacs' file. It contains some of the commonly desired customizations
+in Emacs.
+
+\1f
+File: new-users-guide.info, Node: Select and Move, Next: Search and Replace, Prev: Other Customizations, Up: Top
+
+Selecting and Moving Text
+*************************
+
+ Many Emacs commands operate on an arbitrary contiguous part of the
+current buffer. You can select some part of the buffer and edit only
+that part of the buffer. This selected buffer is called a "region". You
+can select text in two ways:
+
+ * You use special keys to select text by defining a region between
+ the cursor and "the mark" (which you set).
+
+ * If you are running XEmacs under X, you can also select text with
+ the mouse.
+
+* Menu:
+
+* Selecting Text:: Select a region of text by setting the Mark
+* Mouse:: Selecting Text with Mouse
+* Region Operation:: Various ways to operate on a selected text
+* Moving Text:: Moving Text
+* Accumulating text:: Accumulating Text from several buffers
+
+\1f
+File: new-users-guide.info, Node: Selecting Text, Next: Mouse, Prev: Select and Move, Up: Select and Move
+
+Setting the Mark
+================
+
+ To define a region you need to set "the mark" at one end of it and
+move the cursor to the other end. Once you set the mark, it remains
+there until you set it again to some other place. Each buffer has its
+own "mark ring" (a place where Emacs remembers 16 previous locations of
+the mark). To set "the mark", you can use the following commands:
+
+`C-<SPC>'
+ This command will set "the mark" at the position of your cursor
+ (`set-mark-command'). You can move your cursor around and "the
+ mark" will stay there.
+
+`C-x C-x'
+ Interchange mark and point (`exchange-point-and-mark'). Since Emacs
+ will have only one cursor, after you move the cursor it will be
+ unable to show you where you set the "the mark". In order to see
+ "the mark" you can type the command `C-x C-x' which will put your
+ cursor on the position of your mark and your mark on the position
+ of your cursor. Use the command again to reset the positions of
+ your cursor and mark.
+
+`C-<'
+ This command will push the mark at the beginning of the buffer
+ without changing the position of your cursor.
+
+`C->'
+ This command will push the mark at the end of the buffer without
+ changing the position of your cursor.
+
+You can also give arguments to `C-<' or `C->'. *Note The Mark and the
+Region: (xemacs)The Mark and the Region, for more information.
+
+\1f
+File: new-users-guide.info, Node: Mouse, Next: Region Operation, Prev: Selecting Text, Up: Select and Move
+
+Selecting Text with Mouse
+=========================
+
+ If you are using XEmacs under X, you can use the mouse to select
+text. The selected text will always be highlighted, so just by looking
+at the text you know what you have selected so far. To select a word
+just double-click with the left-mouse-button on the word. To select a
+whole line triple-click anywhere on the line with the
+left-mouse-button. You can also use the Copy item from the Edit menu on
+the menu-bar to select text. This kind of selection is called Clipboard
+selection, *Note X Clipboard Selection: (xemacs)X Clipboard Selection,
+for more information. To select an arbitrary region, follow these steps:
+
+ 1. Move the mouse cursor over the character at the beginning of the
+ region of text you want to select.
+
+ 2. Press and hold the left mouse button.
+
+ 3. While holding the left mouse button down, drag the cursor to the
+ character at the end of the region of text you want to select.
+
+ 4. Release the left mouse button.
+ The selected region of text is highlighted.
+
+ *Note Selecting Text with the Mouse: (xemacs)Selecting Text with the
+Mouse, for more information regarding the Mouse and additional mouse
+operations.
+
+\1f
+File: new-users-guide.info, Node: Region Operation, Next: Moving Text, Prev: Mouse, Up: Select and Move
+
+Operating on the Region
+=======================
+
+ Once you have selected a region you can do a lot of things to the
+text in the region:
+ * Kill the text with `C-w'. For example if you want to kill a
+ paragraph, position the cursor to the beginning of the paragraph
+ and type `C-SPC'. Then go to the end of the paragraph and type
+ `C-w'. The entire paragraph will be deleted. You can also select
+ the text with a mouse and type `C-w' to kill the entire region.
+ *Note Killing: (xemacs)Killing, for more information.
+
+ * Save the text in a buffer or a file (*note Accumulating Text:
+ (xemacs)Accumulating Text.).
+
+ * You can convert the case of the text with `C-x C-l' or `C-x C-u'
+ If you type `C-x C-u' the selected text will become all
+ upper-case. If you type `C-x C-l' the selected text will become all
+ lower-case.
+
+ * Print hardcopy with `M-x print-region'. *Note Hardcopy:
+ (xemacs)Hardcopy, for more information. This command will print a
+ hardcopy of only the selected text.
+
+ * Indent it with `C-x <TAB>' or `C-M-\' *Note Indentation:
+ (xemacs)Indentation, for more information.
+
+\1f
+File: new-users-guide.info, Node: Moving Text, Next: Accumulating text, Prev: Region Operation, Up: Select and Move
+
+Moving Text
+===========
+
+ The most common way to move or copy text in Emacs is through
+"killing" or `cutting' it and then "yanking" or `pasting' it. You can
+also use the Cut or Copy option from the Edit menu for killing and
+copying respectively. *Note Edit menu::, for reviewing the commands for
+killing text. All the killed text in Emacs is recorded in the "kill
+ring". Since there is only one kill ring in Emacs, you can kill text in
+one buffer and yank it in another buffer. To `paste' or `yank' the
+killed text you can use the following commands:
+`C-y'
+ This command will yank or paste the last killed text (`yank').
+
+`M-w'
+ Save region as last killed text without actually killing it
+ (`copy-region-as-kill'). You can use this command to copy a
+ selected region and then yank (or paste) it without actually
+ removing it from the buffer.
+
+`C-M-w'
+ Append next kill to last batch of killed text
+ (`append-next-kill'). This command will append whatever you killed
+ last to what you kill now. Then later you will be able to yank the
+ entire appended text from the "kill ring".
+
+\1f
+File: new-users-guide.info, Node: Accumulating text, Prev: Moving Text, Up: Select and Move
+
+Accumulating Text
+=================
+
+ The following commands can be used for accumulating text from
+different buffers into one place or for copying one region of text into
+many buffers:
+
+`M-x append-to-buffer'
+ Append region to contents of specified buffer
+ (`append-to-buffer'). After you type in this command and press
+ <RET>, Emacs will prompt you for a buffer name. You will see a
+ message in the echo area:
+ Append to buffer: (default <buffer name>)
+
+ After you type in a buffer name, a copy of the region will be
+ inserted at the location of the cursor into that buffer. If there
+ is no buffer with the name given by you, Emacs will create a new
+ buffer with that name. By default the cursor's position in the
+ <buffer name> is at the end.
+
+`M-x prepend-to-buffer'
+ Prepend region to contents of specified buffer. This command is
+ similar to the above command except that the cursor in the buffer
+ (by default) is at the beginning rather than at the end.
+
+`M-x copy-to-buffer'
+ Copy region into specified buffer, deleting that buffer's old
+ contents. This command will also prompt you for a buffer name.
+
+`M-x insert-buffer'
+ Insert contents of specified buffer into current buffer at point.
+ This command will prompt you for a buffername which you want to be
+ copied into the current buffer at the location of the cursor.
+
+`M-x append-to-file'
+ This command will prompt you for a filename and append the region
+ to the end of the contents of the specified file.
+
+*Note Accumulating Text: (xemacs)Accumulating Text, for more
+information regarding this topic.
+
+ You can also use "rectangle commands" for operating on rectangular
+areas of text. *Note Rectangles: (xemacs)Rectangles, for more
+information regarding rectangle commands.
+
+ Emacs also provides "registers" which serve as temporary storage for
+text or positions. Each register has a one character name and they can
+store "regions", a "rectangle", or a "mark" i.e. a cursor position.
+Whatever you store in register stays there until you store something
+else in that register. To find out about commands which manipulate
+registers *Note Registers: (xemacs)Registers.
+
+\1f
+File: new-users-guide.info, Node: Search and Replace, Prev: Select and Move, Up: Top
+
+Searching and Replacing
+***********************
+
+ Emacs provides commands for searching for occurrences of a particular
+string. The search is incremental i.e. it begins even before you
+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
+searches case-sensitive. For information on setting variables, *Note
+Setting Variables::. The two commands for searching for strings in
+XEmacs are:
+
+`C-s'
+ This command will prompt you for a string to search :
+
+ I-search:
+
+ If you type "myname" as the string to be searched, then Emacs will
+ start searching for "m", "my", "myn", etc as you go on typing the
+ whole string in the forward direction. The cursor will be on the
+ matching string which has been found so far. If you find the
+ correct match just hit <RET> or type `C-f' or `C-b' to set the
+ cursor's position. If you find a matching string "myname" but you
+ were looking for a different occurrence of it, use `C-s' again. If
+ the search is unable to find the string, it will give you an error
+ message.
+
+`C-r'
+ This command will perform an incremental search in the backward
+ direction. It will prompt you for a string name:
+
+ I-search backward:
+
+ After you start typing the string name, it will search for the
+ string in the same fashion as it does for `C-s' except that it
+ will search in the backward direction. If it cannot find the
+ string name, it will give you an error message.
+
+ If you make a mistake while typing the string names when you use the
+above commands, you can use the <DEL> key to erase characters. Each
+<DEL> will erase the last character. At any time if you want to quit
+the search, just type `C-g'.
+
+ To do a non-incremental search i.e. to start the search only after
+you have typed the whole string you can use the following commands:
+
+`C-s RET "string" RET'
+ This command will search for the specified string in the forward
+ direction and will give an error message if the string is not
+ found.
+
+`C-r RET "string" RET'
+ This command will search for the specified string in the backward
+ direction.
+
+ For information on how Emacs searches for words and regular
+expressions, *Note Search: (xemacs)Search.
+
+ To replace all occurrences of a string in Emacs, you can use the
+following command:
+ M-x replace-string
+
+After you type `M-x replace-string', you will be prompted for a string
+name to replace:
+
+ Replace string:
+
+After you type in a string name, for example "FOO" and press <RET>, you
+will see another prompt:
+
+ Replace string FOO with:
+
+Now type the string which you want to replace "FOO" with and press
+<RET>. After all the occurrences are replaced you will see the message
+"Done" in the echo area. If you want only some occurrences of the
+string to be replaced, use `M-x query-replace RET <string> RET
+<newstring> RET'. For more information, *Note Query Replace:
+(xemacs)Query Replace.
+
+ XEmacs also provides a utility for checking spellings. Use `M-x
+ispell-buffer' to check for spellings in the whole buffer. You can also
+check the spelling of a word or a region. You can use menus to check
+for spellings:
+
+Evaluate the expression `(load "big-menubar")'. To evaluate this
+expression you need to hit the <META> or the <ESC> key twice and type
+in the expression in the echo area before hitting <RET>. You will get
+an extensive menubar. Select the Spell Check menu item from the
+Utilities menu for checking spellings.
+
+\1f
+File: new-users-guide.info, Node: Key Index, Next: Command Index, Prev: Intro, Up: Top
+
+Key (Character) Index
+*********************
+
+* Menu:
+
+* C-<: Selecting Text.
+* C->: Selecting Text.
+* C-a: Cursor Position.
+* C-b: Cursor Position.
+* C-d: Erase.
+* C-e: Cursor Position.
+* C-fx: Cursor Position.
+* C-g: The Help Menu.
+* C-h d: The Help Menu.
+* C-h k: The Help Menu.
+* C-h t: Edit.
+* C-k: Erase.
+* C-M-\: Region Operation.
+* C-n: Cursor Position.
+* C-p: Cursor Position.
+* C-r: Search and Replace.
+* C-s: Search and Replace.
+* C-SPC <1>: Selecting Text.
+* C-SPC: Region Operation.
+* C-t: Cursor Position.
+* C-u: Numeric Argument.
+* C-v: Cursor Position.
+* C-w: Region Operation.
+* C-x 0: XEmacs Window.
+* C-x 1: XEmacs Window.
+* C-x 2: XEmacs Window.
+* C-x 3: XEmacs Window.
+* C-x 4: XEmacs Window.
+* C-x 4 b: XEmacs Window.
+* C-x 4 d: XEmacs Window.
+* C-x 4 f: XEmacs Window.
+* C-x 4 m: XEmacs Window.
+* C-x 5 C-f: Visiting.
+* C-x C-c: Exiting.
+* C-x C-f: Visiting.
+* C-x C-l: Region Operation.
+* C-x C-s: Saving Files.
+* C-x C-u: Region Operation.
+* C-x C-v: Visiting.
+* C-x C-w: Saving Files.
+* C-x C-x: Selecting Text.
+* C-x s: Saving Files.
+* C-x TAB: Region Operation.
+* C-x u: Undo.
+* C-y: Moving Text.
+* C-z: Exiting.
+* DEL: Insert.
+* M--: Numeric Argument.
+* M-<: Cursor Position.
+* M->: Cursor Position.
+* M-C-v: XEmacs Window.
+* M-d: Erase.
+* M-DEL: Erase.
+* M-k: Erase.
+* M-v: Cursor Position.
+* M-z: Erase.
+* RET: Insert.
+
--- /dev/null
+This is Info file ../../info/new-users-guide.info, produced by Makeinfo
+version 1.68 from the input file new-users-guide.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Intro: (new-users-guide). Introduction to the XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This manual serves as an introduction to the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+\1f
+File: new-users-guide.info, Node: Command Index, Next: Variable Index, Prev: Key Index, Up: Top
+
+Command and Function Index
+**************************
+
+* Menu:
+
+* add-menu-item: Customizing Menus.
+* append-to-buffer: Accumulating text.
+* append-to-file: Accumulating text.
+* auto-fill-mode <1>: Minor Modes.
+* auto-fill-mode: Insert.
+* backward-char: Cursor Position.
+* backward-kill-word: Erase.
+* backward-word: Cursor Position.
+* beginning-of-buffer: Cursor Position.
+* beginning-of-line: Cursor Position.
+* copy-to-buffer: Accumulating text.
+* delete-backward-char: Erase.
+* delete-char: Erase.
+* delete-menu-item: Customizing Menus.
+* delete-other-windows <1>: Windows and Menus.
+* delete-other-windows: XEmacs Window.
+* delete-window <1>: XEmacs Window.
+* delete-window: Windows and Menus.
+* describe-variable: Setting Variables.
+* dired-other-window: XEmacs Window.
+* disable-menu-item: Customizing Menus.
+* edit-options: Setting Variables.
+* enable-menu-item: Customizing Menus.
+* end-of-buffer: Cursor Position.
+* end-of-line: Cursor Position.
+* eval-expression: Init File.
+* eval-region: Customization Basics.
+* exchange-point-and-mark: Selecting Text.
+* find-alternate-file: Visiting.
+* find-file: Visiting.
+* find-file-other-frame: Visiting.
+* find-file-other-window: XEmacs Window.
+* forward-char: Cursor Position.
+* forward-word: Cursor Position.
+* goto-char: Cursor Position.
+* goto-line: Cursor Position.
+* help-with-tutorial: Edit.
+* isearch-backward: Search and Replace.
+* isearch-forward: Search and Replace.
+* kill-line: Erase.
+* kill-sentence: Erase.
+* kill-word: Erase.
+* list-options: Setting Variables.
+* mail-other-window: XEmacs Window.
+* make-directory: File Names.
+* make-symbolic-link: Customizing key Bindings.
+* mark-beginning-of-buffer: Selecting Text.
+* mark-end-of-buffer: Selecting Text.
+* next-line: Cursor Position.
+* prepend-to-buffer: Accumulating text.
+* previous-line: Cursor Position.
+* print-region: Region Operation.
+* relabel-menu-items: Customizing Menus.
+* remove-directory: File Names.
+* replace-string: Search and Replace.
+* save-buffer: Saving Files.
+* save-buffers-kill-emacs: Exiting.
+* save-some-buffers: Saving Files.
+* scroll-other-window <1>: XEmacs Window.
+* scroll-other-window: Windows and Menus.
+* set-mark-command: Selecting Text.
+* set-variable: Setting Variables.
+* split-window-horizontally: XEmacs Window.
+* split-window-vertically: XEmacs Window.
+* suspend-emacs: Exiting.
+* switch-to-buffer-other-window: XEmacs Window.
+* transpose-chars: Cursor Position.
+* write file: Saving Files.
+* yank: Moving Text.
+* zap-to-char: Erase.
+
+\1f
+File: new-users-guide.info, Node: Variable Index, Next: Concept Index, Prev: Command Index, Up: Top
+
+Variable Index
+**************
+
+* Menu:
+
+* buffers-menu-max-size: Init File.
+* case-fold-search: Search and Replace.
+* default-directory: File Names.
+* display-time: Init File.
+* fill-column: Init File.
+* frame-title-format: Init File.
+* make-backup-files: Saving Files.
+* zmacs-regions: Init File.
+
+\1f
+File: new-users-guide.info, Node: Concept Index, Next: Entering, Prev: Variable Index, Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* .emacs: Customization Basics.
+* abbrev-mode: Minor Modes.
+* accumulating text: Accumulating text.
+* add menus: Customizing Menus.
+* asm-mode: Major Modes.
+* Auto Delete Selection menu item: Options Menu.
+* auto saving: Saving Files.
+* auto-save-mode: Minor Modes.
+* binding keys: Customizing key Bindings.
+* blink-paren: Minor Modes.
+* buffer: Entering.
+* Buffers menu: Buffers Menu.
+* Buffers Menu Length... menu item: Options Menu.
+* Buffers Sub-Menus menu item: Options Menu.
+* c-mode: Major Modes.
+* Case Sensitive Search menu item: Options Menu.
+* Clear menu item: Edit menu.
+* clipboard selection: Mouse.
+* Copy menu item: Edit menu.
+* copying text: Accumulating text.
+* creating-directories: File Names.
+* cursor control: Cursor Position.
+* cursor position: Cursor Position.
+* cursor shapes: Mouse.
+* customize <1>: Customization Basics.
+* customize: Other Customizations.
+* customize menus: Customizing Menus.
+* Cut menu item: Edit menu.
+* Delete Frame menu item: File menu.
+* delete menus: Customizing Menus.
+* deleting: Erase.
+* deleting menu items: Customizing Menus.
+* deletion: Insert.
+* digit argument: Numeric Argument.
+* disable menus: Customizing Menus.
+* disabling menu items: Customizing Menus.
+* displaying time: Init File.
+* echo area: Echo Area.
+* edit-picture: Major Modes.
+* enabling menu items: Customizing Menus.
+* End Macro Recording menu item: Edit menu.
+* entering Emacs: Enter.
+* entering XEmacs: Enter.
+* erasing: Erase.
+* Execute Last Macro menu item: Edit menu.
+* Exit Emacs menu item: File menu.
+* exiting: Exiting.
+* file: Entering.
+* File menu: File menu.
+* file names: File Names.
+* files: Files.
+* Font menu item: Options Menu.
+* font-lock-mode <1>: Other Customizations.
+* font-lock-mode: Minor Modes.
+* fortran-mode: Major Modes.
+* fundamental-mode: Major Modes.
+* goto-line: Cursor Position.
+* help <1>: Help.
+* help: The Help Menu.
+* Help menu: Help menu.
+* hook: Other Customizations.
+* init file examples: Init File.
+* Insert File... menu item: File menu.
+* insertion: Insert.
+* key bindings: Customizing key Bindings.
+* keystrokes: Customizing key Bindings.
+* Kill Buffer menu item: File menu.
+* kill ring: Moving Text.
+* killing: Moving Text.
+* killing Emacs: Exiting.
+* line-number-mode: Minor Modes.
+* lisp-mode: Major Modes.
+* major modes: Major Modes.
+* mark: Select and Move.
+* menus: XEmacs Window.
+* minor modes: Minor Modes.
+* mistakes, correcting: Undo.
+* mode line: Mode Line.
+* modes: Modes.
+* mouse selection: Mouse.
+* moving text: Moving Text.
+* negative argument: Numeric Argument.
+* New Frame menu item: File menu.
+* newline: Insert.
+* nroff-mode: Major Modes.
+* numeric argument: Numeric Argument.
+* Open ... menu item: File menu.
+* open another file: Frame.
+* Open in New Frame... menu item: File menu.
+* Options menu: Options Menu.
+* outline-mode: Major Modes.
+* overstrike: Insert.
+* Overstrike menu item: Options Menu.
+* overwrite-mode: Minor Modes.
+* Paren Highlighting menu item: Options Menu.
+* Paste menu item: Edit menu.
+* pasting: Moving Text.
+* primary selection: Mouse.
+* Print Buffer menu item: File menu.
+* pull-down-menus: XEmacs Window.
+* Read Only menu item: Options Menu.
+* rectangle commands: Accumulating text.
+* region: Select and Move.
+* registers: Accumulating text.
+* relabelling menu items: Customizing Menus.
+* removing-directories: File Names.
+* replace: Search and Replace.
+* Revert Buffer menu item: File menu.
+* Save Buffer As ... menu item: File menu.
+* Save Buffer menu item: File menu.
+* Save Options: Options Menu.
+* saving files: Saving Files.
+* searching: Search and Replace.
+* selected window: Windows and Menus.
+* setting variables: Setting Variables.
+* shrinking XEmacs frame: Exiting.
+* simultaneous editing: Saving Files.
+* Size menu item: Options Menu.
+* Split Frame: File menu.
+* Start Macro Recording menu item: Edit menu.
+* suspending: Exiting.
+* Syntax Highlighting menu item: Options Menu.
+* Teach Extended Commands menu item: Options Menu.
+* temporary storage: Accumulating text.
+* tex-mode: Major Modes.
+* texinfo-mode: Major Modes.
+* top level: Mode Line.
+* Un-split (Keep Others): File menu.
+* Un-split (Keep This): File menu.
+* undo: Undo.
+* Undo menu item: Edit menu.
+* visiting files: Visiting.
+* Weight menu item: Options Menu.
+* windows <1>: XEmacs Window.
+* windows <2>: Entering.
+* windows: Windows and Menus.
+* yanking: Moving Text.
+
+
--- /dev/null
+This is Info file ../info/standards.info, produced by Makeinfo version
+1.68 from the input file standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
+Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+Indirect:
+standards.info-1: 982
+standards.info-2: 49841
+standards.info-3: 95838
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f982
+Node: Preface\7f1491
+Node: Intellectual Property\7f2529
+Node: Reading Non-Free Code\7f2885
+Node: Contributions\7f4617
+Node: Design Advice\7f6215
+Node: Compatibility\7f6698
+Node: Using Extensions\7f8342
+Node: ANSI C\7f9844
+Node: Source Language\7f11080
+Node: Program Behavior\7f12214
+Node: Semantics\7f12806
+Node: Libraries\7f16560
+Node: Errors\7f17795
+Node: User Interfaces\7f19018
+Node: Memory Usage\7f36043
+Node: Writing C\7f37040
+Node: Formatting\7f37750
+Node: Comments\7f41022
+Node: Syntactic Conventions\7f43815
+Node: Names\7f46753
+Node: System Portability\7f48065
+Node: CPU Portability\7f49841
+Node: System Functions\7f52002
+Node: Internationalization\7f56903
+Node: Documentation\7f59104
+Node: GNU Manuals\7f59648
+Node: Manual Structure Details\7f61690
+Node: NEWS File\7f63095
+Node: Change Logs\7f63776
+Node: Man Pages\7f67978
+Node: Reading other Manuals\7f69597
+Node: Managing Releases\7f70381
+Node: Configuration\7f71087
+Node: Makefile Conventions\7f78027
+Node: Makefile Basics\7f78551
+Node: Utilities in Makefiles\7f81022
+Node: Command Variables\7f82896
+Node: Directory Variables\7f85732
+Node: Standard Targets\7f95838
+Node: Releases\7f105580
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/standards.info, produced by Makeinfo version
+1.68 from the input file standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
+Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
+
+Version
+*******
+
+ Last updated 17 May 1996.
+
+* Menu:
+
+* Preface:: About the GNU Coding Standards
+* Intellectual Property:: Keeping Free Software Free
+* Design Advice:: General Program Design
+* Program Behavior:: Program Behavior for All Programs
+* Writing C:: Making The Best Use of C
+* Documentation:: Documenting Programs
+* Managing Releases:: The Release Process
+
+\1f
+File: standards.info, Node: Preface, Next: Intellectual Property, Prev: Top, Up: Top
+
+About the GNU Coding Standards
+******************************
+
+ The GNU Coding Standards were written by Richard Stallman and other
+GNU Project volunteers. Their purpose is to make the GNU system clean,
+consistent, and easy to install. This document can also be read as a
+guide to writing portable, robust and reliable programs. It focuses on
+programs written in C, but many of the rules and principles are useful
+even if you write in another programming language. The rules often
+state reasons for writing in a certain way.
+
+ Corrections or suggestions regarding this document should be sent to
+`gnu@prep.ai.mit.edu'. If you make a suggestion, please include a
+suggested new wording for it; our time is limited. We prefer a context
+diff to the `standards.texi' or `make-stds.texi' files, but if you
+don't have those files, please mail your suggestion anyway.
+
+ This release of the GNU Coding Standards was last updated 17 May
+1996.
+
+\1f
+File: standards.info, Node: Intellectual Property, Next: Design Advice, Prev: Preface, Up: Top
+
+Keeping Free Software Free
+**************************
+
+ This node discusses how you can make sure that GNU software remains
+unencumbered.
+
+* Menu:
+
+* Reading Non-Free Code:: Referring to Proprietary Programs
+* Contributions:: Accepting Contributions
+
+\1f
+File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Intellectual Property
+
+Referring to Proprietary Programs
+=================================
+
+ Don't in any circumstances refer to Unix source code for or during
+your work on GNU! (Or to any other proprietary programs.)
+
+ If you have a vague recollection of the internals of a Unix program,
+this does not absolutely mean you can't write an imitation of it, but
+do try to organize the imitation internally along different lines,
+because this is likely to make the details of the Unix version
+irrelevant and dissimilar to your results.
+
+ For example, Unix utilities were generally optimized to minimize
+memory use; if you go for speed instead, your program will be very
+different. You could keep the entire input file in core and scan it
+there instead of using stdio. Use a smarter algorithm discovered more
+recently than the Unix program. Eliminate use of temporary files. Do
+it in one pass instead of two (we did this in the assembler).
+
+ Or, on the contrary, emphasize simplicity instead of speed. For some
+applications, the speed of today's computers makes simpler algorithms
+adequate.
+
+ Or go for generality. For example, Unix programs often have static
+tables or fixed-size strings, which make for arbitrary limits; use
+dynamic allocation instead. Make sure your program handles NULs and
+other funny characters in the input files. Add a programming language
+for extensibility and write part of the program in that language.
+
+ Or turn some parts of the program into independently usable
+libraries. Or use a simple garbage collector instead of tracking
+precisely when to free memory, or use a new GNU facility such as
+obstacks.
+
+\1f
+File: standards.info, Node: Contributions, Prev: Reading Non-Free Code, Up: Intellectual Property
+
+Accepting Contributions
+=======================
+
+ If someone else sends you a piece of code to add to the program you
+are working on, we need legal papers to use it--the same sort of legal
+papers we will need to get from you. *Each* significant contributor to
+a program must sign some sort of legal papers in order for us to have
+clear title to the program. The main author alone is not enough.
+
+ So, before adding in any contributions from other people, tell us so
+we can arrange to get the papers. Then wait until we tell you that we
+have received the signed papers, before you actually use the
+contribution.
+
+ This applies both before you release the program and afterward. If
+you receive diffs to fix a bug, and they make significant changes, we
+need legal papers for it.
+
+ You don't need papers for changes of a few lines here or there, since
+they are not significant for copyright purposes. Also, you don't need
+papers if all you get from the suggestion is some ideas, not actual code
+which you use. For example, if you write a different solution to the
+problem, you don't need to get papers.
+
+ We know this is frustrating; it's frustrating for us as well. But if
+you don't wait, you are going out on a limb--for example, what if the
+contributor's employer won't sign a disclaimer? You might have to take
+that code out again!
+
+ The very worst thing is if you forget to tell us about the other
+contributor. We could be very embarrassed in court some day as a
+result.
+
+\1f
+File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Intellectual Property, Up: Top
+
+General Program Design
+**********************
+
+ This node discusses some of the issues you should take into account
+when designing your program.
+
+* Menu:
+
+* Compatibility:: Compatibility with other implementations
+* Using Extensions:: Using non-standard features
+* ANSI C:: Using ANSI C features
+* Source Language:: Using languages other than C
+
+\1f
+File: standards.info, Node: Compatibility, Next: Using Extensions, Up: Design Advice
+
+Compatibility with Other Implementations
+========================================
+
+ With occasional exceptions, utility programs and libraries for GNU
+should be upward compatible with those in Berkeley Unix, and upward
+compatible with ANSI C if ANSI C specifies their behavior, and upward
+compatible with POSIX if POSIX specifies their behavior.
+
+ When these standards conflict, it is useful to offer compatibility
+modes for each of them.
+
+ ANSI C and POSIX prohibit many kinds of extensions. Feel free to
+make the extensions anyway, and include a `--ansi', `--posix', or
+`--compatible' option to turn them off. However, if the extension has
+a significant chance of breaking any real programs or scripts, then it
+is not really upward compatible. Try to redesign its interface.
+
+ Many GNU programs suppress extensions that conflict with POSIX if the
+environment variable `POSIXLY_CORRECT' is defined (even if it is
+defined with a null value). Please make your program recognize this
+variable if appropriate.
+
+ When a feature is used only by users (not by programs or command
+files), and it is done poorly in Unix, feel free to replace it
+completely with something totally different and better. (For example,
+`vi' is replaced with Emacs.) But it is nice to offer a compatible
+feature as well. (There is a free `vi' clone, so we offer it.)
+
+ Additional useful features not in Berkeley Unix are welcome.
+Additional programs with no counterpart in Unix may be useful, but our
+first priority is usually to duplicate what Unix already has.
+
+\1f
+File: standards.info, Node: Using Extensions, Next: ANSI C, Prev: Compatibility, Up: Design Advice
+
+Using Non-standard Features
+===========================
+
+ Many GNU facilities that already exist support a number of convenient
+extensions over the comparable Unix facilities. Whether to use these
+extensions in implementing your program is a difficult question.
+
+ On the one hand, using the extensions can make a cleaner program.
+On the other hand, people will not be able to build the program unless
+the other GNU tools are available. This might cause the program to
+work on fewer kinds of machines.
+
+ With some extensions, it might be easy to provide both alternatives.
+For example, you can define functions with a "keyword" `INLINE' and
+define that as a macro to expand into either `inline' or nothing,
+depending on the compiler.
+
+ In general, perhaps it is best not to use the extensions if you can
+straightforwardly do without them, but to use the extensions if they
+are a big improvement.
+
+ An exception to this rule are the large, established programs (such
+as Emacs) which run on a great variety of systems. Such programs would
+be broken by use of GNU extensions.
+
+ Another exception is for programs that are used as part of
+compilation: anything that must be compiled with other compilers in
+order to bootstrap the GNU compilation facilities. If these require
+the GNU compiler, then no one can compile them without having them
+installed already. That would be no good.
+
+\1f
+File: standards.info, Node: ANSI C, Next: Source Language, Prev: Using Extensions, Up: Design Advice
+
+ANSI C and pre-ANSI C
+=====================
+
+ Do not ever use the "trigraph" feature of ANSI C.
+
+ ANSI C is widespread enough now that it is ok to write new programs
+that use ANSI C features (and therefore will not work in non-ANSI
+compilers). And if a program is already written in ANSI C, there's no
+need to convert it to support non-ANSI compilers.
+
+ However, it is easy to support non-ANSI compilers in most programs,
+so you might still consider doing so when you write a program. Instead
+of writing function definitions in ANSI prototype form,
+
+ int
+ foo (int x, int y)
+ ...
+
+write the definition in pre-ANSI style like this,
+
+ int
+ foo (x, y)
+ int x, y;
+ ...
+
+and use a separate declaration to specify the argument prototype:
+
+ int foo (int, int);
+
+ You need such a declaration anyway, in a header file, to get the
+benefit of ANSI C prototypes in all the files where the function is
+called. And once you have it, you lose nothing by writing the function
+definition in the pre-ANSI style.
+
+ If you don't know non-ANSI C, there's no need to learn it; just
+write in ANSI C.
+
+\1f
+File: standards.info, Node: Source Language, Prev: ANSI C, Up: Design Advice
+
+Using Languages Other Than C
+============================
+
+ Using a language other than C is like using a non-standard feature:
+it will cause trouble for users. Even if GCC supports the other
+language, users may find it inconvenient to have to install the
+compiler for that other language in order to build your program. So
+please write in C.
+
+ There are three exceptions for this rule:
+
+ * It is okay to use a special language if the same program contains
+ an interpreter for that language.
+
+ For example, if your program links with GUILE, it is ok to write
+ part of the program in Scheme or another language supported by
+ GUILE.
+
+ * It is okay to use another language in a tool specifically intended
+ for use with that language.
+
+ This is okay because the only people who want to build the tool
+ will be those who have installed the other language anyway.
+
+ * If an application is not of extremely widespread interest, then
+ perhaps it's not important if the application is inconvenient to
+ install.
+
+\1f
+File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
+
+Program Behavior for All Programs
+*********************************
+
+ This node describes how to write robust software. It also describes
+general standards for error messages, the command line interface, and
+how libraries should behave.
+
+* Menu:
+
+* Semantics:: Writing robust programs
+* Libraries:: Library behavior
+* Errors:: Formatting error messages
+* User Interfaces:: Standards for command line interfaces
+* Memory Usage:: When and how to care about memory needs
+
+\1f
+File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior
+
+Writing Robust Programs
+=======================
+
+ Avoid arbitrary limits on the length or number of *any* data
+structure, including file names, lines, files, and symbols, by
+allocating all data structures dynamically. In most Unix utilities,
+"long lines are silently truncated". This is not acceptable in a GNU
+utility.
+
+ Utilities reading files should not drop NUL characters, or any other
+nonprinting characters *including those with codes above 0177*. The
+only sensible exceptions would be utilities specifically intended for
+interface to certain types of printers that can't handle those
+characters.
+
+ Check every system call for an error return, unless you know you
+wish to ignore errors. Include the system error text (from `perror' or
+equivalent) in *every* error message resulting from a failing system
+call, as well as the name of the file if any and the name of the
+utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
+
+ Check every call to `malloc' or `realloc' to see if it returned
+zero. Check `realloc' even if you are making the block smaller; in a
+system that rounds block sizes to a power of 2, `realloc' may get a
+different block if you ask for less space.
+
+ In Unix, `realloc' can destroy the storage block if it returns zero.
+GNU `realloc' does not have this bug: if it fails, the original block
+is unchanged. Feel free to assume the bug is fixed. If you wish to
+run your program on Unix, and wish to avoid lossage in this case, you
+can use the GNU `malloc'.
+
+ You must expect `free' to alter the contents of the block that was
+freed. Anything you want to fetch from the block, you must fetch before
+calling `free'.
+
+ If `malloc' fails in a noninteractive program, make that a fatal
+error. In an interactive program (one that reads commands from the
+user), it is better to abort the command and return to the command
+reader loop. This allows the user to kill other processes to free up
+virtual memory, and then try the command again.
+
+ Use `getopt_long' to decode arguments, unless the argument syntax
+makes this unreasonable.
+
+ When static storage is to be written in during program execution, use
+explicit C code to initialize it. Reserve C initialized declarations
+for data that will not be changed.
+
+ Try to avoid low-level interfaces to obscure Unix data structures
+(such as file directories, utmp, or the layout of kernel memory), since
+these are less likely to work compatibly. If you need to find all the
+files in a directory, use `readdir' or some other high-level interface.
+These will be supported compatibly by GNU.
+
+ By default, the GNU system will provide the signal handling
+functions of BSD and of POSIX. So GNU software should be written to use
+these.
+
+ In error checks that detect "impossible" conditions, just abort.
+There is usually no point in printing any message. These checks
+indicate the existence of bugs. Whoever wants to fix the bugs will have
+to read the source code and run a debugger. So explain the problem with
+comments in the source. The relevant data will be in variables, which
+are easy to examine with the debugger, so there is no point moving them
+elsewhere.
+
+ Do not use a count of errors as the exit status for a program.
+*That does not work*, because exit status values are limited to 8 bits
+(0 through 255). A single run of the program might have 256 errors; if
+you try to return 256 as the exit status, the parent process will see 0
+as the status, and it will appear that the program succeeded.
+
+ If you make temporary files, check the `TMPDIR' environment
+variable; if that variable is defined, use the specified directory
+instead of `/tmp'.
+
+\1f
+File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
+
+Library Behavior
+================
+
+ Try to make library functions reentrant. If they need to do dynamic
+storage allocation, at least try to avoid any nonreentrancy aside from
+that of `malloc' itself.
+
+ Here are certain name conventions for libraries, to avoid name
+conflicts.
+
+ Choose a name prefix for the library, more than two characters long.
+All external function and variable names should start with this prefix.
+In addition, there should only be one of these in any given library
+member. This usually means putting each one in a separate source file.
+
+ An exception can be made when two external symbols are always used
+together, so that no reasonable program could use one without the
+other; then they can both go in the same file.
+
+ External symbols that are not documented entry points for the user
+should have names beginning with `_'. They should also contain the
+chosen name prefix for the library, to prevent collisions with other
+libraries. These can go in the same files with user entry points if
+you like.
+
+ Static functions and variables can be used as you like and need not
+fit any naming convention.
+
+\1f
+File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
+
+Formatting Error Messages
+=========================
+
+ Error messages from compilers should look like this:
+
+ SOURCE-FILE-NAME:LINENO: MESSAGE
+
+ Error messages from other noninteractive programs should look like
+this:
+
+ PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
+
+when there is an appropriate source file, or like this:
+
+ PROGRAM: MESSAGE
+
+when there is no relevant source file.
+
+ In an interactive program (one that is reading commands from a
+terminal), it is better not to include the program name in an error
+message. The place to indicate which program is running is in the
+prompt or with the screen layout. (When the same program runs with
+input from a source other than a terminal, it is not interactive and
+would do best to print error messages using the noninteractive style.)
+
+ The string MESSAGE should not begin with a capital letter when it
+follows a program name and/or file name. Also, it should not end with
+a period.
+
+ Error messages from interactive programs, and other messages such as
+usage messages, should start with a capital letter. But they should not
+end with a period.
+
+\1f
+File: standards.info, Node: User Interfaces, Next: Memory Usage, Prev: Errors, Up: Program Behavior
+
+Standards for Command Line Interfaces
+=====================================
+
+ Please don't make the behavior of a utility depend on the name used
+to invoke it. It is useful sometimes to make a link to a utility with
+a different name, and that should not change what it does.
+
+ Instead, use a run time option or a compilation switch or both to
+select among the alternate behaviors.
+
+ Likewise, please don't make the behavior of the program depend on the
+type of output device it is used with. Device independence is an
+important principle of the system's design; do not compromise it merely
+to save someone from typing an option now and then.
+
+ If you think one behavior is most useful when the output is to a
+terminal, and another is most useful when the output is a file or a
+pipe, then it is usually best to make the default behavior the one that
+is useful with output to a terminal, and have an option for the other
+behavior.
+
+ Compatibility requires certain programs to depend on the type of
+output device. It would be disastrous if `ls' or `sh' did not do so in
+the way all users expect. In some of these cases, we supplement the
+program with a preferred alternate version that does not depend on the
+output device type. For example, we provide a `dir' program much like
+`ls' except that its default output format is always multi-column
+format.
+
+ It is a good idea to follow the POSIX guidelines for the
+command-line options of a program. The easiest way to do this is to use
+`getopt' to parse them. Note that the GNU version of `getopt' will
+normally permit options anywhere among the arguments unless the special
+argument `--' is used. This is not what POSIX specifies; it is a GNU
+extension.
+
+ Please define long-named options that are equivalent to the
+single-letter Unix-style options. We hope to make GNU more user
+friendly this way. This is easy to do with the GNU function
+`getopt_long'.
+
+ One of the advantages of long-named options is that they can be
+consistent from program to program. For example, users should be able
+to expect the "verbose" option of any GNU program which has one, to be
+spelled precisely `--verbose'. To achieve this uniformity, look at the
+table of common long-option names when you choose the option names for
+your program. The table appears below.
+
+ If you use names not already in the table, please send
+`gnu@prep.ai.mit.edu' a list of them, with their meanings, so we can
+update the table.
+
+ It is usually a good idea for file names given as ordinary arguments
+to be input files only; any output files would be specified using
+options (preferably `-o'). Even if you allow an output file name as an
+ordinary argument for compatibility, try to provide a suitable option
+as well. This will lead to more consistency among GNU utilities, so
+that there are fewer idiosyncracies for users to remember.
+
+ Programs should support an option `--version' which prints the
+program's version number on standard output and exits successfully, and
+an option `--help' which prints option usage information on standard
+output and exits successfully. These options should inhibit the normal
+function of the command; they should do nothing except print the
+requested information.
+
+ Here is the table of long options used by GNU programs.
+
+`after-date'
+ `-N' in `tar'.
+
+`all'
+ `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
+
+`all-text'
+ `-a' in `diff'.
+
+`almost-all'
+ `-A' in `ls'.
+
+`append'
+ `-a' in `etags', `tee', `time'; `-r' in `tar'.
+
+`archive'
+ `-a' in `cp'.
+
+`archive-name'
+ `-n' in `shar'.
+
+`arglength'
+ `-l' in `m4'.
+
+`ascii'
+ `-a' in `diff'.
+
+`assign'
+ `-v' in `gawk'.
+
+`assume-new'
+ `-W' in Make.
+
+`assume-old'
+ `-o' in Make.
+
+`auto-check'
+ `-a' in `recode'.
+
+`auto-pager'
+ `-a' in `wdiff'.
+
+`auto-reference'
+ `-A' in `ptx'.
+
+`avoid-wraps'
+ `-n' in `wdiff'.
+
+`backward-search'
+ `-B' in `ctags'.
+
+`basename'
+ `-f' in `shar'.
+
+`batch'
+ Used in GDB.
+
+`baud'
+ Used in GDB.
+
+`before'
+ `-b' in `tac'.
+
+`binary'
+ `-b' in `cpio' and `diff'.
+
+`bits-per-code'
+ `-b' in `shar'.
+
+`block-size'
+ Used in `cpio' and `tar'.
+
+`blocks'
+ `-b' in `head' and `tail'.
+
+`break-file'
+ `-b' in `ptx'.
+
+`brief'
+ Used in various programs to make output shorter.
+
+`bytes'
+ `-c' in `head', `split', and `tail'.
+
+`c++'
+ `-C' in `etags'.
+
+`catenate'
+ `-A' in `tar'.
+
+`cd'
+ Used in various programs to specify the directory to use.
+
+`changes'
+ `-c' in `chgrp' and `chown'.
+
+`classify'
+ `-F' in `ls'.
+
+`colons'
+ `-c' in `recode'.
+
+`command'
+ `-c' in `su'; `-x' in GDB.
+
+`compare'
+ `-d' in `tar'.
+
+`compat'
+ Used in `gawk'.
+
+`compress'
+ `-Z' in `tar' and `shar'.
+
+`concatenate'
+ `-A' in `tar'.
+
+`confirmation'
+ `-w' in `tar'.
+
+`context'
+ Used in `diff'.
+
+`copyleft'
+ `-W copyleft' in `gawk'.
+
+`copyright'
+ `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
+
+`core'
+ Used in GDB.
+
+`count'
+ `-q' in `who'.
+
+`count-links'
+ `-l' in `du'.
+
+`create'
+ Used in `tar' and `cpio'.
+
+`cut-mark'
+ `-c' in `shar'.
+
+`cxref'
+ `-x' in `ctags'.
+
+`date'
+ `-d' in `touch'.
+
+`debug'
+ `-d' in Make and `m4'; `-t' in Bison.
+
+`define'
+ `-D' in `m4'.
+
+`defines'
+ `-d' in Bison and `ctags'.
+
+`delete'
+ `-D' in `tar'.
+
+`dereference'
+ `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
+
+`dereference-args'
+ `-D' in `du'.
+
+`diacritics'
+ `-d' in `recode'.
+
+`dictionary-order'
+ `-d' in `look'.
+
+`diff'
+ `-d' in `tar'.
+
+`digits'
+ `-n' in `csplit'.
+
+`directory'
+ Specify the directory to use, in various programs. In `ls', it
+ means to show directories themselves rather than their contents.
+ In `rm' and `ln', it means to not treat links to directories
+ specially.
+
+`discard-all'
+ `-x' in `strip'.
+
+`discard-locals'
+ `-X' in `strip'.
+
+`dry-run'
+ `-n' in Make.
+
+`ed'
+ `-e' in `diff'.
+
+`elide-empty-files'
+ `-z' in `csplit'.
+
+`end-delete'
+ `-x' in `wdiff'.
+
+`end-insert'
+ `-z' in `wdiff'.
+
+`entire-new-file'
+ `-N' in `diff'.
+
+`environment-overrides'
+ `-e' in Make.
+
+`eof'
+ `-e' in `xargs'.
+
+`epoch'
+ Used in GDB.
+
+`error-limit'
+ Used in `makeinfo'.
+
+`error-output'
+ `-o' in `m4'.
+
+`escape'
+ `-b' in `ls'.
+
+`exclude-from'
+ `-X' in `tar'.
+
+`exec'
+ Used in GDB.
+
+`exit'
+ `-x' in `xargs'.
+
+`exit-0'
+ `-e' in `unshar'.
+
+`expand-tabs'
+ `-t' in `diff'.
+
+`expression'
+ `-e' in `sed'.
+
+`extern-only'
+ `-g' in `nm'.
+
+`extract'
+ `-i' in `cpio'; `-x' in `tar'.
+
+`faces'
+ `-f' in `finger'.
+
+`fast'
+ `-f' in `su'.
+
+`fatal-warnings'
+ `-E' in `m4'.
+
+`file'
+ `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
+ in `touch'.
+
+`field-separator'
+ `-F' in `gawk'.
+
+`file-prefix'
+ `-b' in Bison.
+
+`file-type'
+ `-F' in `ls'.
+
+`files-from'
+ `-T' in `tar'.
+
+`fill-column'
+ Used in `makeinfo'.
+
+`flag-truncation'
+ `-F' in `ptx'.
+
+`fixed-output-files'
+ `-y' in Bison.
+
+`follow'
+ `-f' in `tail'.
+
+`footnote-style'
+ Used in `makeinfo'.
+
+`force'
+ `-f' in `cp', `ln', `mv', and `rm'.
+
+`force-prefix'
+ `-F' in `shar'.
+
+`format'
+ Used in `ls', `time', and `ptx'.
+
+`freeze-state'
+ `-F' in `m4'.
+
+`fullname'
+ Used in GDB.
+
+`gap-size'
+ `-g' in `ptx'.
+
+`get'
+ `-x' in `tar'.
+
+`graphic'
+ `-i' in `ul'.
+
+`graphics'
+ `-g' in `recode'.
+
+`group'
+ `-g' in `install'.
+
+`gzip'
+ `-z' in `tar' and `shar'.
+
+`hashsize'
+ `-H' in `m4'.
+
+`header'
+ `-h' in `objdump' and `recode'
+
+`heading'
+ `-H' in `who'.
+
+`help'
+ Used to ask for brief usage information.
+
+`here-delimiter'
+ `-d' in `shar'.
+
+`hide-control-chars'
+ `-q' in `ls'.
+
+`idle'
+ `-u' in `who'.
+
+`ifdef'
+ `-D' in `diff'.
+
+`ignore'
+ `-I' in `ls'; `-x' in `recode'.
+
+`ignore-all-space'
+ `-w' in `diff'.
+
+`ignore-backups'
+ `-B' in `ls'.
+
+`ignore-blank-lines'
+ `-B' in `diff'.
+
+`ignore-case'
+ `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
+
+`ignore-errors'
+ `-i' in Make.
+
+`ignore-file'
+ `-i' in `ptx'.
+
+`ignore-indentation'
+ `-I' in `etags'.
+
+`ignore-init-file'
+ `-f' in Oleo.
+
+`ignore-interrupts'
+ `-i' in `tee'.
+
+`ignore-matching-lines'
+ `-I' in `diff'.
+
+`ignore-space-change'
+ `-b' in `diff'.
+
+`ignore-zeros'
+ `-i' in `tar'.
+
+`include'
+ `-i' in `etags'; `-I' in `m4'.
+
+`include-dir'
+ `-I' in Make.
+
+`incremental'
+ `-G' in `tar'.
+
+`info'
+ `-i', `-l', and `-m' in Finger.
+
+`initial'
+ `-i' in `expand'.
+
+`initial-tab'
+ `-T' in `diff'.
+
+`inode'
+ `-i' in `ls'.
+
+`interactive'
+ `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
+ `-w' in `tar'.
+
+`intermix-type'
+ `-p' in `shar'.
+
+`jobs'
+ `-j' in Make.
+
+`just-print'
+ `-n' in Make.
+
+`keep-going'
+ `-k' in Make.
+
+`keep-files'
+ `-k' in `csplit'.
+
+`kilobytes'
+ `-k' in `du' and `ls'.
+
+`language'
+ `-l' in `etags'.
+
+`less-mode'
+ `-l' in `wdiff'.
+
+`level-for-gzip'
+ `-g' in `shar'.
+
+`line-bytes'
+ `-C' in `split'.
+
+`lines'
+ Used in `split', `head', and `tail'.
+
+`link'
+ `-l' in `cpio'.
+
+`lint'
+`lint-old'
+ Used in `gawk'.
+
+`list'
+ `-t' in `cpio'; `-l' in `recode'.
+
+`list'
+ `-t' in `tar'.
+
+`literal'
+ `-N' in `ls'.
+
+`load-average'
+ `-l' in Make.
+
+`login'
+ Used in `su'.
+
+`machine'
+ No listing of which programs already use this; someone should
+ check to see if any actually do and tell `gnu@prep.ai.mit.edu'.
+
+`macro-name'
+ `-M' in `ptx'.
+
+`mail'
+ `-m' in `hello' and `uname'.
+
+`make-directories'
+ `-d' in `cpio'.
+
+`makefile'
+ `-f' in Make.
+
+`mapped'
+ Used in GDB.
+
+`max-args'
+ `-n' in `xargs'.
+
+`max-chars'
+ `-n' in `xargs'.
+
+`max-lines'
+ `-l' in `xargs'.
+
+`max-load'
+ `-l' in Make.
+
+`max-procs'
+ `-P' in `xargs'.
+
+`mesg'
+ `-T' in `who'.
+
+`message'
+ `-T' in `who'.
+
+`minimal'
+ `-d' in `diff'.
+
+`mixed-uuencode'
+ `-M' in `shar'.
+
+`mode'
+ `-m' in `install', `mkdir', and `mkfifo'.
+
+`modification-time'
+ `-m' in `tar'.
+
+`multi-volume'
+ `-M' in `tar'.
+
+`name-prefix'
+ `-a' in Bison.
+
+`nesting-limit'
+ `-L' in `m4'.
+
+`net-headers'
+ `-a' in `shar'.
+
+`new-file'
+ `-W' in Make.
+
+`no-builtin-rules'
+ `-r' in Make.
+
+`no-character-count'
+ `-w' in `shar'.
+
+`no-check-existing'
+ `-x' in `shar'.
+
+`no-common'
+ `-3' in `wdiff'.
+
+`no-create'
+ `-c' in `touch'.
+
+`no-defines'
+ `-D' in `etags'.
+
+`no-deleted'
+ `-1' in `wdiff'.
+
+`no-dereference'
+ `-d' in `cp'.
+
+`no-inserted'
+ `-2' in `wdiff'.
+
+`no-keep-going'
+ `-S' in Make.
+
+`no-lines'
+ `-l' in Bison.
+
+`no-piping'
+ `-P' in `shar'.
+
+`no-prof'
+ `-e' in `gprof'.
+
+`no-regex'
+ `-R' in `etags'.
+
+`no-sort'
+ `-p' in `nm'.
+
+`no-split'
+ Used in `makeinfo'.
+
+`no-static'
+ `-a' in `gprof'.
+
+`no-time'
+ `-E' in `gprof'.
+
+`no-timestamp'
+ `-m' in `shar'.
+
+`no-validate'
+ Used in `makeinfo'.
+
+`no-warn'
+ Used in various programs to inhibit warnings.
+
+`node'
+ `-n' in `info'.
+
+`nodename'
+ `-n' in `uname'.
+
+`nonmatching'
+ `-f' in `cpio'.
+
+`nstuff'
+ `-n' in `objdump'.
+
+`null'
+ `-0' in `xargs'.
+
+`number'
+ `-n' in `cat'.
+
+`number-nonblank'
+ `-b' in `cat'.
+
+`numeric-sort'
+ `-n' in `nm'.
+
+`numeric-uid-gid'
+ `-n' in `cpio' and `ls'.
+
+`nx'
+ Used in GDB.
+
+`old-archive'
+ `-o' in `tar'.
+
+`old-file'
+ `-o' in Make.
+
+`one-file-system'
+ `-l' in `tar', `cp', and `du'.
+
+`only-file'
+ `-o' in `ptx'.
+
+`only-prof'
+ `-f' in `gprof'.
+
+`only-time'
+ `-F' in `gprof'.
+
+`output'
+ In various programs, specify the output file name.
+
+`output-prefix'
+ `-o' in `shar'.
+
+`override'
+ `-o' in `rm'.
+
+`overwrite'
+ `-c' in `unshar'.
+
+`owner'
+ `-o' in `install'.
+
+`paginate'
+ `-l' in `diff'.
+
+`paragraph-indent'
+ Used in `makeinfo'.
+
+`parents'
+ `-p' in `mkdir' and `rmdir'.
+
+`pass-all'
+ `-p' in `ul'.
+
+`pass-through'
+ `-p' in `cpio'.
+
+`port'
+ `-P' in `finger'.
+
+`portability'
+ `-c' in `cpio' and `tar'.
+
+`posix'
+ Used in `gawk'.
+
+`prefix-builtins'
+ `-P' in `m4'.
+
+`prefix'
+ `-f' in `csplit'.
+
+`preserve'
+ Used in `tar' and `cp'.
+
+`preserve-environment'
+ `-p' in `su'.
+
+`preserve-modification-time'
+ `-m' in `cpio'.
+
+`preserve-order'
+ `-s' in `tar'.
+
+`preserve-permissions'
+ `-p' in `tar'.
+
+`print'
+ `-l' in `diff'.
+
+`print-chars'
+ `-L' in `cmp'.
+
+`print-data-base'
+ `-p' in Make.
+
+`print-directory'
+ `-w' in Make.
+
+`print-file-name'
+ `-o' in `nm'.
+
+`print-symdefs'
+ `-s' in `nm'.
+
+`printer'
+ `-p' in `wdiff'.
+
+`prompt'
+ `-p' in `ed'.
+
+`query-user'
+ `-X' in `shar'.
+
+`question'
+ `-q' in Make.
+
+`quiet'
+ Used in many programs to inhibit the usual output. *Please note:*
+ every program accepting `--quiet' should accept `--silent' as a
+ synonym.
+
+`quiet-unshar'
+ `-Q' in `shar'
+
+`quote-name'
+ `-Q' in `ls'.
+
+`rcs'
+ `-n' in `diff'.
+
+`re-interval'
+ Used in `gawk'.
+
+`read-full-blocks'
+ `-B' in `tar'.
+
+`readnow'
+ Used in GDB.
+
+`recon'
+ `-n' in Make.
+
+`record-number'
+ `-R' in `tar'.
+
+`recursive'
+ Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
+
+`reference-limit'
+ Used in `makeinfo'.
+
+`references'
+ `-r' in `ptx'.
+
+`regex'
+ `-r' in `tac' and `etags'.
+
+`release'
+ `-r' in `uname'.
+
+`reload-state'
+ `-R' in `m4'.
+
+`relocation'
+ `-r' in `objdump'.
+
+`rename'
+ `-r' in `cpio'.
+
+`replace'
+ `-i' in `xargs'.
+
+`report-identical-files'
+ `-s' in `diff'.
+
+`reset-access-time'
+ `-a' in `cpio'.
+
+`reverse'
+ `-r' in `ls' and `nm'.
+
+`reversed-ed'
+ `-f' in `diff'.
+
+`right-side-defs'
+ `-R' in `ptx'.
+
+`same-order'
+ `-s' in `tar'.
+
+`same-permissions'
+ `-p' in `tar'.
+
+`save'
+ `-g' in `stty'.
+
+`se'
+ Used in GDB.
+
+`sentence-regexp'
+ `-S' in `ptx'.
+
+`separate-dirs'
+ `-S' in `du'.
+
+`separator'
+ `-s' in `tac'.
+
+`sequence'
+ Used by `recode' to chose files or pipes for sequencing passes.
+
+`shell'
+ `-s' in `su'.
+
+`show-all'
+ `-A' in `cat'.
+
+`show-c-function'
+ `-p' in `diff'.
+
+`show-ends'
+ `-E' in `cat'.
+
+`show-function-line'
+ `-F' in `diff'.
+
+`show-tabs'
+ `-T' in `cat'.
+
+`silent'
+ Used in many programs to inhibit the usual output. *Please note:*
+ every program accepting `--silent' should accept `--quiet' as a
+ synonym.
+
+`size'
+ `-s' in `ls'.
+
+`sort'
+ Used in `ls'.
+
+`source'
+ `-W source' in `gawk'.
+
+`sparse'
+ `-S' in `tar'.
+
+`speed-large-files'
+ `-H' in `diff'.
+
+`split-at'
+ `-E' in `unshar'.
+
+`split-size-limit'
+ `-L' in `shar'.
+
+`squeeze-blank'
+ `-s' in `cat'.
+
+`start-delete'
+ `-w' in `wdiff'.
+
+`start-insert'
+ `-y' in `wdiff'.
+
+`starting-file'
+ Used in `tar' and `diff' to specify which file within a directory
+ to start processing with.
+
+`statistics'
+ `-s' in `wdiff'.
+
+`stdin-file-list'
+ `-S' in `shar'.
+
+`stop'
+ `-S' in Make.
+
+`strict'
+ `-s' in `recode'.
+
+`strip'
+ `-s' in `install'.
+
+`strip-all'
+ `-s' in `strip'.
+
+`strip-debug'
+ `-S' in `strip'.
+
+`submitter'
+ `-s' in `shar'.
+
+`suffix'
+ `-S' in `cp', `ln', `mv'.
+
+`suffix-format'
+ `-b' in `csplit'.
+
+`sum'
+ `-s' in `gprof'.
+
+`summarize'
+ `-s' in `du'.
+
+`symbolic'
+ `-s' in `ln'.
+
+`symbols'
+ Used in GDB and `objdump'.
+
+`synclines'
+ `-s' in `m4'.
+
+`sysname'
+ `-s' in `uname'.
+
+`tabs'
+ `-t' in `expand' and `unexpand'.
+
+`tabsize'
+ `-T' in `ls'.
+
+`terminal'
+ `-T' in `tput' and `ul'. `-t' in `wdiff'.
+
+`text'
+ `-a' in `diff'.
+
+`text-files'
+ `-T' in `shar'.
+
+`time'
+ Used in `ls' and `touch'.
+
+`to-stdout'
+ `-O' in `tar'.
+
+`total'
+ `-c' in `du'.
+
+`touch'
+ `-t' in Make, `ranlib', and `recode'.
+
+`trace'
+ `-t' in `m4'.
+
+`traditional'
+ `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
+ and `ptx'.
+
+`tty'
+ Used in GDB.
+
+`typedefs'
+ `-t' in `ctags'.
+
+`typedefs-and-c++'
+ `-T' in `ctags'.
+
+`typeset-mode'
+ `-t' in `ptx'.
+
+`uncompress'
+ `-z' in `tar'.
+
+`unconditional'
+ `-u' in `cpio'.
+
+`undefine'
+ `-U' in `m4'.
+
+`undefined-only'
+ `-u' in `nm'.
+
+`update'
+ `-u' in `cp', `ctags', `mv', `tar'.
+
+`usage'
+ Used in `gawk'; same as `--help'.
+
+`uuencode'
+ `-B' in `shar'.
+
+`vanilla-operation'
+ `-V' in `shar'.
+
+`verbose'
+ Print more information about progress. Many programs support this.
+
+`verify'
+ `-W' in `tar'.
+
+`version'
+ Print the version number.
+
+`version-control'
+ `-V' in `cp', `ln', `mv'.
+
+`vgrind'
+ `-v' in `ctags'.
+
+`volume'
+ `-V' in `tar'.
+
+`what-if'
+ `-W' in Make.
+
+`whole-size-limit'
+ `-l' in `shar'.
+
+`width'
+ `-w' in `ls' and `ptx'.
+
+`word-regexp'
+ `-W' in `ptx'.
+
+`writable'
+ `-T' in `who'.
+
+`zeros'
+ `-z' in `gprof'.
+
+\1f
+File: standards.info, Node: Memory Usage, Prev: User Interfaces, Up: Program Behavior
+
+Memory Usage
+============
+
+ If it typically uses just a few meg of memory, don't bother making
+any effort to reduce memory usage. For example, if it is impractical
+for other reasons to operate on files more than a few meg long, it is
+reasonable to read entire input files into core to operate on them.
+
+ However, for programs such as `cat' or `tail', that can usefully
+operate on very large files, it is important to avoid using a technique
+that would artificially limit the size of files it can handle. If a
+program works by lines and could be applied to arbitrary user-supplied
+input files, it should keep only a line in memory, because this is not
+very hard and users will want to be able to operate on input files that
+are bigger than will fit in core all at once.
+
+ If your program creates complicated data structures, just make them
+in core and give a fatal error if `malloc' returns zero.
+
+\1f
+File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
+
+Making The Best Use of C
+************************
+
+ This node provides advice on how best to use the C language when
+writing GNU software.
+
+* Menu:
+
+* Formatting:: Formatting Your Source Code
+* Comments:: Commenting Your Work
+* Syntactic Conventions:: Clean Use of C Constructs
+* Names:: Naming Variables and Functions
+* System Portability:: Portability between different operating systems
+* CPU Portability:: Supporting the range of CPU types
+* System Functions:: Portability and "standard" library functions
+* Internationalization:: Techniques for internationalization
+
+\1f
+File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
+
+Formatting Your Source Code
+===========================
+
+ It is important to put the open-brace that starts the body of a C
+function in column zero, and avoid putting any other open-brace or
+open-parenthesis or open-bracket in column zero. Several tools look
+for open-braces in column zero to find the beginnings of C functions.
+These tools will not work on code not formatted that way.
+
+ It is also important for function definitions to start the name of
+the function in column zero. This helps people to search for function
+definitions, and may also help certain tools recognize them. Thus, the
+proper format is this:
+
+ static char *
+ concat (s1, s2) /* Name starts in column zero here */
+ char *s1, *s2;
+ { /* Open brace in column zero here */
+ ...
+ }
+
+or, if you want to use ANSI C, format the definition like this:
+
+ static char *
+ concat (char *s1, char *s2)
+ {
+ ...
+ }
+
+ In ANSI C, if the arguments don't fit nicely on one line, split it
+like this:
+
+ int
+ lots_of_args (int an_integer, long a_long, short a_short,
+ double a_double, float a_float)
+ ...
+
+ For the body of the function, we prefer code formatted like this:
+
+ if (x < foo (y, z))
+ haha = bar[4] + 5;
+ else
+ {
+ while (z)
+ {
+ haha += foo (z, z);
+ z--;
+ }
+ return ++x + bar ();
+ }
+
+ We find it easier to read a program when it has spaces before the
+open-parentheses and after the commas. Especially after the commas.
+
+ When you split an expression into multiple lines, split it before an
+operator, not after one. Here is the right way:
+
+ if (foo_this_is_long && bar > win (x, y, z)
+ && remaining_condition)
+
+ Try to avoid having two operators of different precedence at the same
+level of indentation. For example, don't write this:
+
+ mode = (inmode[j] == VOIDmode
+ || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
+ ? outmode[j] : inmode[j]);
+
+ Instead, use extra parentheses so that the indentation shows the
+nesting:
+
+ mode = ((inmode[j] == VOIDmode
+ || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
+ ? outmode[j] : inmode[j]);
+
+ Insert extra parentheses so that Emacs will indent the code properly.
+For example, the following indentation looks nice if you do it by hand,
+but Emacs would mess it up:
+
+ v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
+
+ But adding a set of parentheses solves the problem:
+
+ v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
+ + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
+
+ Format do-while statements like this:
+
+ do
+ {
+ a = foo (a);
+ }
+ while (a > 0);
+
+ Please use formfeed characters (control-L) to divide the program into
+pages at logical places (but not within a function). It does not matter
+just how long the pages are, since they do not have to fit on a printed
+page. The formfeeds should appear alone on lines by themselves.
+
+\1f
+File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
+
+Commenting Your Work
+====================
+
+ Every program should start with a comment saying briefly what it is
+for. Example: `fmt - filter for simple filling of text'.
+
+ Please put a comment on each function saying what the function does,
+what sorts of arguments it gets, and what the possible values of
+arguments mean and are used for. It is not necessary to duplicate in
+words the meaning of the C argument declarations, if a C type is being
+used in its customary fashion. If there is anything nonstandard about
+its use (such as an argument of type `char *' which is really the
+address of the second character of a string, not the first), or any
+possible values that would not work the way one would expect (such as,
+that strings containing newlines are not guaranteed to work), be sure
+to say so.
+
+ Also explain the significance of the return value, if there is one.
+
+ Please put two spaces after the end of a sentence in your comments,
+so that the Emacs sentence commands will work. Also, please write
+complete sentences and capitalize the first word. If a lower-case
+identifier comes at the beginning of a sentence, don't capitalize it!
+Changing the spelling makes it a different identifier. If you don't
+like starting a sentence with a lower case letter, write the sentence
+differently (e.g., "The identifier lower-case is ...").
+
+ The comment on a function is much clearer if you use the argument
+names to speak about the argument values. The variable name itself
+should be lower case, but write it in upper case when you are speaking
+about the value rather than the variable itself. Thus, "the inode
+number NODE_NUM" rather than "an inode".
+
+ There is usually no purpose in restating the name of the function in
+the comment before it, because the reader can see that for himself.
+There might be an exception when the comment is so long that the
+function itself would be off the bottom of the screen.
+
+ There should be a comment on each static variable as well, like this:
+
+ /* Nonzero means truncate lines in the display;
+ zero means continue them. */
+ int truncate_lines;
+
+ Every `#endif' should have a comment, except in the case of short
+conditionals (just a few lines) that are not nested. The comment should
+state the condition of the conditional that is ending, *including its
+sense*. `#else' should have a comment describing the condition *and
+sense* of the code that follows. For example:
+
+ #ifdef foo
+ ...
+ #else /* not foo */
+ ...
+ #endif /* not foo */
+
+but, by contrast, write the comments this way for a `#ifndef':
+
+ #ifndef foo
+ ...
+ #else /* foo */
+ ...
+ #endif /* foo */
+
+\1f
+File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
+
+Clean Use of C Constructs
+=========================
+
+ Please explicitly declare all arguments to functions. Don't omit
+them just because they are `int's.
+
+ Declarations of external functions and functions to appear later in
+the source file should all go in one place near the beginning of the
+file (somewhere before the first function definition in the file), or
+else should go in a header file. Don't put `extern' declarations inside
+functions.
+
+ It used to be common practice to use the same local variables (with
+names like `tem') over and over for different values within one
+function. Instead of doing this, it is better declare a separate local
+variable for each distinct purpose, and give it a name which is
+meaningful. This not only makes programs easier to understand, it also
+facilitates optimization by good compilers. You can also move the
+declaration of each local variable into the smallest scope that includes
+all its uses. This makes the program even cleaner.
+
+ Don't use local variables or parameters that shadow global
+identifiers.
+
+ Don't declare multiple variables in one declaration that spans lines.
+Start a new declaration on each line, instead. For example, instead of
+this:
+
+ int foo,
+ bar;
+
+write either this:
+
+ int foo, bar;
+
+or this:
+
+ int foo;
+ int bar;
+
+(If they are global variables, each should have a comment preceding it
+anyway.)
+
+ When you have an `if'-`else' statement nested in another `if'
+statement, always put braces around the `if'-`else'. Thus, never write
+like this:
+
+ if (foo)
+ if (bar)
+ win ();
+ else
+ lose ();
+
+always like this:
+
+ if (foo)
+ {
+ if (bar)
+ win ();
+ else
+ lose ();
+ }
+
+ If you have an `if' statement nested inside of an `else' statement,
+either write `else if' on one line, like this,
+
+ if (foo)
+ ...
+ else if (bar)
+ ...
+
+with its `then'-part indented like the preceding `then'-part, or write
+the nested `if' within braces like this:
+
+ if (foo)
+ ...
+ else
+ {
+ if (bar)
+ ...
+ }
+
+ Don't declare both a structure tag and variables or typedefs in the
+same declaration. Instead, declare the structure tag separately and
+then use it to declare the variables or typedefs.
+
+ Try to avoid assignments inside `if'-conditions. For example, don't
+write this:
+
+ if ((foo = (char *) malloc (sizeof *foo)) == 0)
+ fatal ("virtual memory exhausted");
+
+instead, write this:
+
+ foo = (char *) malloc (sizeof *foo);
+ if (foo == 0)
+ fatal ("virtual memory exhausted");
+
+ Don't make the program ugly to placate `lint'. Please don't insert
+any casts to `void'. Zero without a cast is perfectly fine as a null
+pointer constant, except when calling a varargs function.
+
+\1f
+File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
+
+Naming Variables and Functions
+==============================
+
+ Please use underscores to separate words in a name, so that the Emacs
+word commands can be useful within them. Stick to lower case; reserve
+upper case for macros and `enum' constants, and for name-prefixes that
+follow a uniform convention.
+
+ For example, you should use names like `ignore_space_change_flag';
+don't use names like `iCantReadThis'.
+
+ Variables that indicate whether command-line options have been
+specified should be named after the meaning of the option, not after
+the option-letter. A comment should state both the exact meaning of
+the option and its letter. For example,
+
+ /* Ignore changes in horizontal whitespace (-b). */
+ int ignore_space_change_flag;
+
+ When you want to define names with constant integer values, use
+`enum' rather than `#define'. GDB knows about enumeration constants.
+
+ Use file names of 14 characters or less, to avoid creating gratuitous
+problems on older System V systems. You can use the program `doschk'
+to test for this. `doschk' also tests for potential name conflicts if
+the files were loaded onto an MS-DOS file system--something you may or
+may not care about.
+
+\1f
+File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
+
+Portability between System Types
+================================
+
+ In the Unix world, "portability" refers to porting to different Unix
+versions. For a GNU program, this kind of portability is desirable, but
+not paramount.
+
+ The primary purpose of GNU software is to run on top of the GNU
+kernel, compiled with the GNU C compiler, on various types of CPU. The
+amount and kinds of variation among GNU systems on different CPUs will
+be comparable to the variation among Linux-based GNU systems or among
+BSD systems today. So the kinds of portability that are absolutely
+necessary are quite limited.
+
+ But many users do run GNU software on non-GNU Unix or Unix-like
+systems. So supporting a variety of Unix-like systems is desirable,
+although not paramount.
+
+ The easiest way to achieve portability to most Unix-like systems is
+to use Autoconf. It's unlikely that your program needs to know more
+information about the host platform than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
+
+ Avoid using the format of semi-internal data bases (e.g.,
+directories) when there is a higher-level alternative (`readdir').
+
+ As for systems that are not like Unix, such as MSDOS, Windows, the
+Macintosh, VMS, and MVS, supporting them is usually so much work that it
+is better if you don't.
+
+ The planned GNU kernel is not finished yet, but you can tell which
+facilities it will provide by looking at the GNU C Library Manual. The
+GNU kernel is based on Mach, so the features of Mach will also be
+available. However, if you use Mach features, you'll probably have
+trouble debugging your program today.
+
--- /dev/null
+This is Info file ../info/standards.info, produced by Makeinfo version
+1.68 from the input file standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
+Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
+
+Portability between CPUs
+========================
+
+ Even GNU systems will differ because of differences among CPU
+types--for example, difference in byte ordering and alignment
+requirements. It is absolutely essential to handle these differences.
+However, don't make any effort to cater to the possibility that an
+`int' will be less than 32 bits. We don't support 16-bit machines in
+GNU.
+
+ Don't assume that the address of an `int' object is also the address
+of its least-significant byte. This is false on big-endian machines.
+Thus, don't make the following mistake:
+
+ int c;
+ ...
+ while ((c = getchar()) != EOF)
+ write(file_descriptor, &c, 1);
+
+ When calling functions, you need not worry about the difference
+between pointers of various types, or between pointers and integers.
+On most machines, there's no difference anyway. As for the few
+machines where there is a difference, all of them support ANSI C, so
+you can use prototypes (conditionalized to be active only in ANSI C) to
+make the code work on those systems.
+
+ In certain cases, it is ok to pass integer and pointer arguments
+indiscriminately to the same function, and use no prototype on any
+system. For example, many GNU programs have error-reporting functions
+that pass their arguments along to `printf' and friends:
+
+ error (s, a1, a2, a3)
+ char *s;
+ int a1, a2, a3;
+ {
+ fprintf (stderr, "error: ");
+ fprintf (stderr, s, a1, a2, a3);
+ }
+
+In practice, this works on all machines, and it is much simpler than any
+"correct" alternative. Be sure *not* to use a prototype for such
+functions.
+
+ However, avoid casting pointers to integers unless you really need
+to. These assumptions really reduce portability, and in most programs
+they are easy to avoid. In the cases where casting pointers to
+integers is essential--such as, a Lisp interpreter which stores type
+information as well as an address in one word--it is ok to do so, but
+you'll have to make explicit provisions to handle different word sizes.
+
+\1f
+File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
+
+Calling System Functions
+========================
+
+ C implementations differ substantially. ANSI C reduces but does not
+eliminate the incompatibilities; meanwhile, many users wish to compile
+GNU software with pre-ANSI compilers. This chapter gives
+recommendations for how to use the more or less standard C library
+functions to avoid unnecessary loss of portability.
+
+ * Don't use the value of `sprintf'. It returns the number of
+ characters written on some systems, but not on all systems.
+
+ * Don't declare system functions explicitly.
+
+ Almost any declaration for a system function is wrong on some
+ system. To minimize conflicts, leave it to the system header
+ files to declare system functions. If the headers don't declare a
+ function, let it remain undeclared.
+
+ While it may seem unclean to use a function without declaring it,
+ in practice this works fine for most system library functions on
+ the systems where this really happens; thus, the disadvantage is
+ only theoretical. By contrast, actual declarations have
+ frequently caused actual conflicts.
+
+ * If you must declare a system function, don't specify the argument
+ types. Use an old-style declaration, not an ANSI prototype. The
+ more you specify about the function, the more likely a conflict.
+
+ * In particular, don't unconditionally declare `malloc' or `realloc'.
+
+ Most GNU programs use those functions just once, in functions
+ conventionally named `xmalloc' and `xrealloc'. These functions
+ call `malloc' and `realloc', respectively, and check the results.
+
+ Because `xmalloc' and `xrealloc' are defined in your program, you
+ can declare them in other files without any risk of type conflict.
+
+ On most systems, `int' is the same length as a pointer; thus, the
+ calls to `malloc' and `realloc' work fine. For the few
+ exceptional systems (mostly 64-bit machines), you can use
+ *conditionalized* declarations of `malloc' and `realloc'--or put
+ these declarations in configuration files specific to those
+ systems.
+
+ * The string functions require special treatment. Some Unix systems
+ have a header file `string.h'; others have `strings.h'. Neither
+ file name is portable. There are two things you can do: use
+ Autoconf to figure out which file to include, or don't include
+ either file.
+
+ * If you don't include either strings file, you can't get
+ declarations for the string functions from the header file in the
+ usual way.
+
+ That causes less of a problem than you might think. The newer ANSI
+ string functions should be avoided anyway because many systems
+ still don't support them. The string functions you can use are
+ these:
+
+ strcpy strncpy strcat strncat
+ strlen strcmp strncmp
+ strchr strrchr
+
+ The copy and concatenate functions work fine without a declaration
+ as long as you don't use their values. Using their values without
+ a declaration fails on systems where the width of a pointer
+ differs from the width of `int', and perhaps in other cases. It
+ is trivial to avoid using their values, so do that.
+
+ The compare functions and `strlen' work fine without a declaration
+ on most systems, possibly all the ones that GNU software runs on.
+ You may find it necessary to declare them *conditionally* on a few
+ systems.
+
+ The search functions must be declared to return `char *'. Luckily,
+ there is no variation in the data type they return. But there is
+ variation in their names. Some systems give these functions the
+ names `index' and `rindex'; other systems use the names `strchr'
+ and `strrchr'. Some systems support both pairs of names, but
+ neither pair works on all systems.
+
+ You should pick a single pair of names and use it throughout your
+ program. (Nowadays, it is better to choose `strchr' and `strrchr'
+ for new programs, since those are the standard ANSI names.)
+ Declare both of those names as functions returning `char *'. On
+ systems which don't support those names, define them as macros in
+ terms of the other pair. For example, here is what to put at the
+ beginning of your file (or in a header) if you want to use the
+ names `strchr' and `strrchr' throughout:
+
+ #ifndef HAVE_STRCHR
+ #define strchr index
+ #endif
+ #ifndef HAVE_STRRCHR
+ #define strrchr rindex
+ #endif
+
+ char *strchr ();
+ char *strrchr ();
+
+ Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
+defined in systems where the corresponding functions exist. One way to
+get them properly defined is to use Autoconf.
+
+\1f
+File: standards.info, Node: Internationalization, Prev: System Functions, Up: Writing C
+
+Internationalization
+====================
+
+ GNU has a library called GNU gettext that makes it easy to translate
+the messages in a program into various languages. You should use this
+library in every program. Use English for the messages as they appear
+in the program, and let gettext provide the way to translate them into
+other languages.
+
+ Using GNU gettext involves putting a call to the `gettext' macro
+around each string that might need translation--like this:
+
+ printf (gettext ("Processing file `%s'..."));
+
+This permits GNU gettext to replace the string `"Processing file
+`%s'..."' with a translated version.
+
+ Once a program uses gettext, please make a point of writing calls to
+`gettext' when you add new strings that call for translation.
+
+ Using GNU gettext in a package involves specifying a "text domain
+name" for the package. The text domain name is used to separate the
+translations for this package from the translations for other packages.
+Normally, the text domain name should be the same as the name of the
+package--for example, `fileutils' for the GNU file utilities.
+
+ To enable gettext to work, avoid writing code that makes assumptions
+about the structure of words. Don't construct words from parts. Here
+is an example of what not to do:
+
+ prinf ("%d file%s processed", nfiles,
+ nfiles > 1 ? "s" : "");
+
+The problem with that example is that it assumes that plurals are made
+by adding `s'. If you apply gettext to the format string, like this,
+
+ prinf (gettext ("%d file%s processed"), nfiles,
+ nfiles > 1 ? "s" : "");
+
+the message can use different words, but it will still be forced to use
+`s' for the plural. Here is a better way:
+
+ prinf ((nfiles > 1 ? "%d files processed"
+ : "%d file processed"),
+ nfiles);
+
+This way, you can apply gettext to each of the two strings
+independently:
+
+ prinf ((nfiles > 1 ? gettext ("%d files processed")
+ : gettext ("%d file processed")),
+ nfiles);
+
+This can handle any language, no matter how it forms the plural of the
+word for "file."
+
+\1f
+File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
+
+Documenting Programs
+********************
+
+* Menu:
+
+* GNU Manuals:: Writing proper manuals.
+* Manual Structure Details:: Specific structure conventions.
+* NEWS File:: NEWS files supplement manuals.
+* Change Logs:: Recording Changes
+* Man Pages:: Man pages are secondary.
+* Reading other Manuals:: How far you can go in learning
+ from other manuals.
+
+\1f
+File: standards.info, Node: GNU Manuals, Next: Manual Structure Details, Up: Documentation
+
+GNU Manuals
+===========
+
+ The preferred way to document part of the GNU system is to write a
+manual in the Texinfo formatting language. See the Texinfo manual,
+either the hardcopy, or the on-line version available through `info' or
+the Emacs Info subsystem (`C-h i').
+
+ The manual should document all of the program's command-line options
+and all of its commands. It should give examples of their use. But
+don't organize the manual as a list of features. Instead, organize it
+logically, by subtopics. Address the goals that a user will have in
+mind, and explain how to accomplish them.
+
+ In general, a GNU manual should serve both as tutorial and reference.
+It should be set up for convenient access to each topic through Info,
+and for reading straight through (appendixes aside). A GNU manual
+should give a good introduction to a beginner reading through from the
+start, and should also provide all the details that hackers want.
+
+ That is not as hard as it first sounds. Arrange each chapter as a
+logical breakdown of its topic, but order the sections, and write their
+text, so that reading the chapter straight through makes sense. Do
+likewise when structuring the book into chapters, and when structuring a
+section into paragraphs. The watchword is, *at each point, address the
+most fundamental and important issue raised by the preceding text.*
+
+ If necessary, add extra chapters at the beginning of the manual which
+are purely tutorial and cover the basics of the subject. These provide
+the framework for a beginner to understand the rest of the manual. The
+Bison manual provides a good example of how to do this.
+
+ Don't use Unix man pages as a model for how to write GNU
+documentation; they are a bad example to follow.
+
+ Please do not use the term "pathname" that is used in Unix
+documentation; use "file name" (two words) instead. We use the term
+"path" only for search paths, which are lists of file names.
+
+\1f
+File: standards.info, Node: Manual Structure Details, Next: NEWS File, Prev: GNU Manuals, Up: Documentation
+
+Manual Structure Details
+========================
+
+ The title page of the manual should state the version of the program
+to which the manual applies. The Top node of the manual should also
+contain this information. If the manual is changing more frequently
+than or independent of the program, also state a version number for the
+manual in both of these places.
+
+ The manual should have a node named `PROGRAM Invocation' or
+`Invoking PROGRAM', where PROGRAM stands for the name of the program
+being described, as you would type it in the shell to run the program.
+This node (together with its subnodes, if any) should describe the
+program's command line arguments and how to run it (the sort of
+information people would look in a man page for). Start with an
+`@example' containing a template for all the options and arguments that
+the program uses.
+
+ Alternatively, put a menu item in some menu whose item name fits one
+of the above patterns. This identifies the node which that item points
+to as the node for this purpose, regardless of the node's actual name.
+
+ There will be automatic features for specifying a program name and
+quickly reading just this part of its manual.
+
+ If one manual describes several programs, it should have such a node
+for each program described.
+
+\1f
+File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Manual Structure Details, Up: Documentation
+
+The NEWS File
+=============
+
+ In addition to its manual, the package should have a file named
+`NEWS' which contains a list of user-visible changes worth mentioning.
+In each new release, add items to the front of the file and identify
+the version they pertain to. Don't discard old items; leave them in
+the file after the newer items. This way, a user upgrading from any
+previous version can see what is new.
+
+ If the `NEWS' file gets very long, move some of the older items into
+a file named `ONEWS' and put a note at the end referring the user to
+that file.
+
+\1f
+File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
+
+Change Logs
+===========
+
+ Keep a change log to describe all the changes made to program source
+files. The purpose of this is so that people investigating bugs in the
+future will know about the changes that might have introduced the bug.
+Often a new bug can be found by looking at what was recently changed.
+More importantly, change logs can help eliminate conceptual
+inconsistencies between different parts of a program; they can give you
+a history of how the conflicting concepts arose.
+
+ A change log file is normally called `ChangeLog' and covers an
+entire directory. Each directory can have its own change log, or a
+directory can use the change log of its parent directory-it's up to you.
+
+ Another alternative is to record change log information with a
+version control system such as RCS or CVS. This can be converted
+automatically to a `ChangeLog' file.
+
+ The easiest way to add an entry to `ChangeLog' is with the Emacs
+command `M-x add-change-log-entry'. An entry should have an asterisk,
+the name of the changed file, and then in parentheses the name of the
+changed functions, variables or whatever, followed by a colon. Then
+describe the changes you made to that function or variable.
+
+ Separate unrelated entries with blank lines. When two entries
+represent parts of the same change, so that they work together, then
+don't put blank lines between them. Then you can omit the file name
+and the asterisk when successive entries are in the same file.
+
+ Here are some examples:
+
+ * register.el (insert-register): Return nil.
+ (jump-to-register): Likewise.
+
+ * sort.el (sort-subr): Return nil.
+
+ * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
+ Restart the tex shell if process is gone or stopped.
+ (tex-shell-running): New function.
+
+ * expr.c (store_one_arg): Round size up for move_block_to_reg.
+ (expand_call): Round up when emitting USE insns.
+ * stmt.c (assign_parms): Round size up for move_block_from_reg.
+
+ It's important to name the changed function or variable in full.
+Don't abbreviate function or variable names, and don't combine them.
+Subsequent maintainers will often search for a function name to find
+all the change log entries that pertain to it; if you abbreviate the
+name, they won't find it when they search. For example, some people
+are tempted to abbreviate groups of function names by writing `*
+register.el ({insert,jump-to}-register)'; this is not a good idea,
+since searching for `jump-to-register' or `insert-register' would not
+find the entry.
+
+ There's no need to describe the full purpose of the changes or how
+they work together. It is better to put such explanations in comments
+in the code. That's why just "New function" is enough; there is a
+comment with the function in the source to explain what it does.
+
+ However, sometimes it is useful to write one line to describe the
+overall purpose of a large batch of changes.
+
+ You can think of the change log as a conceptual "undo list" which
+explains how earlier versions were different from the current version.
+People can see the current version; they don't need the change log to
+tell them what is in it. What they want from a change log is a clear
+explanation of how the earlier version differed.
+
+ When you change the calling sequence of a function in a simple
+fashion, and you change all the callers of the function, there is no
+need to make individual entries for all the callers. Just write in the
+entry for the function being called, "All callers changed."
+
+ When you change just comments or doc strings, it is enough to write
+an entry for the file, without mentioning the functions. Write just,
+"Doc fix."
+
+ There's no need to make change log entries for documentation files.
+This is because documentation is not susceptible to bugs that are hard
+to fix. Documentation does not consist of parts that must interact in a
+precisely engineered fashion. To correct an error, you need not know
+the history of the erroneous passage; it is enough to compare the
+passage with the way the program actually works.
+
+\1f
+File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
+
+Man Pages
+=========
+
+ In the GNU project, man pages are secondary. It is not necessary or
+expected for every GNU program to have a man page, but some of them do.
+It's your choice whether to include a man page in your program.
+
+ When you make this decision, consider that supporting a man page
+requires continual effort each time the program is changed. The time
+you spend on the man page is time taken away from more useful work.
+
+ For a simple program which changes little, updating the man page may
+be a small job. Then there is little reason not to include a man page,
+if you have one.
+
+ For a large program that changes a great deal, updating a man page
+may be a substantial burden. If a user offers to donate a man page,
+you may find this gift costly to accept. It may be better to refuse
+the man page unless the same person agrees to take full responsibility
+for maintaining it--so that you can wash your hands of it entirely. If
+this volunteer later ceases to do the job, then don't feel obliged to
+pick it up yourself; it may be better to withdraw the man page from the
+distribution until someone else agrees to update it.
+
+ When a program changes only a little, you may feel that the
+discrepancies are small enough that the man page remains useful without
+updating. If so, put a prominent note near the beginning of the man
+page explaining that you don't maintain it and that the Texinfo manual
+is more authoritative. The note should say how to access the Texinfo
+documentation.
+
+\1f
+File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
+
+Reading other Manuals
+=====================
+
+ There may be non-free books or documentation files that describe the
+program you are documenting.
+
+ It is ok to use these documents for reference, just as the author of
+a new algebra textbook can read other books on algebra. A large portion
+of any non-fiction book consists of facts, in this case facts about how
+a certain program works, and these facts are necessarily the same for
+everyone who writes about the subject. But be careful not to copy your
+outline structure, wording, tables or examples from preexisting non-free
+documentation. Copying from free documentation may be ok; please check
+with the FSF about the individual case.
+
+\1f
+File: standards.info, Node: Managing Releases, Prev: Documentation, Up: Top
+
+The Release Process
+*******************
+
+ Making a release is more than just bundling up your source files in a
+tar file and putting it up for FTP. You should set up your software so
+that it can be configured to run on a variety of systems. Your Makefile
+should conform to the GNU standards described below, and your directory
+layout should also conform to the standards discussed below. Doing so
+makes it easy to include your package into the larger framework of all
+GNU software.
+
+* Menu:
+
+* Configuration:: How Configuration Should Work
+* Makefile Conventions:: Makefile Conventions
+* Releases:: Making Releases
+
+\1f
+File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
+
+How Configuration Should Work
+=============================
+
+ Each GNU distribution should come with a shell script named
+`configure'. This script is given arguments which describe the kind of
+machine and system you want to compile the program for.
+
+ The `configure' script must record the configuration options so that
+they affect compilation.
+
+ One way to do this is to make a link from a standard name such as
+`config.h' to the proper configuration file for the chosen system. If
+you use this technique, the distribution should *not* contain a file
+named `config.h'. This is so that people won't be able to build the
+program without configuring it first.
+
+ Another thing that `configure' can do is to edit the Makefile. If
+you do this, the distribution should *not* contain a file named
+`Makefile'. Instead, it should include a file `Makefile.in' which
+contains the input used for editing. Once again, this is so that people
+won't be able to build the program without configuring it first.
+
+ If `configure' does write the `Makefile', then `Makefile' should
+have a target named `Makefile' which causes `configure' to be rerun,
+setting up the same configuration that was set up last time. The files
+that `configure' reads should be listed as dependencies of `Makefile'.
+
+ All the files which are output from the `configure' script should
+have comments at the beginning explaining that they were generated
+automatically using `configure'. This is so that users won't think of
+trying to edit them by hand.
+
+ The `configure' script should write a file named `config.status'
+which describes which configuration options were specified when the
+program was last configured. This file should be a shell script which,
+if run, will recreate the same configuration.
+
+ The `configure' script should accept an option of the form
+`--srcdir=DIRNAME' to specify the directory where sources are found (if
+it is not the current directory). This makes it possible to build the
+program in a separate directory, so that the actual source directory is
+not modified.
+
+ If the user does not specify `--srcdir', then `configure' should
+check both `.' and `..' to see if it can find the sources. If it finds
+the sources in one of these places, it should use them from there.
+Otherwise, it should report that it cannot find the sources, and should
+exit with nonzero status.
+
+ Usually the easy way to support `--srcdir' is by editing a
+definition of `VPATH' into the Makefile. Some rules may need to refer
+explicitly to the specified source directory. To make this possible,
+`configure' can add to the Makefile a variable named `srcdir' whose
+value is precisely the specified directory.
+
+ The `configure' script should also take an argument which specifies
+the type of system to build the program for. This argument should look
+like this:
+
+ CPU-COMPANY-SYSTEM
+
+ For example, a Sun 3 might be `m68k-sun-sunos4.1'.
+
+ The `configure' script needs to be able to decode all plausible
+alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
+would be a valid alias. For many programs, `vax-dec-ultrix' would be
+an alias for `vax-dec-bsd', simply because the differences between
+Ultrix and BSD are rarely noticeable, but a few programs might need to
+distinguish them.
+
+ There is a shell script called `config.sub' that you can use as a
+subroutine to validate system types and canonicalize aliases.
+
+ Other options are permitted to specify in more detail the software
+or hardware present on the machine, and include or exclude optional
+parts of the package:
+
+`--enable-FEATURE[=PARAMETER]'
+ Configure the package to build and install an optional user-level
+ facility called FEATURE. This allows users to choose which
+ optional features to include. Giving an optional PARAMETER of
+ `no' should omit FEATURE, if it is built by default.
+
+ No `--enable' option should *ever* cause one feature to replace
+ another. No `--enable' option should ever substitute one useful
+ behavior for another useful behavior. The only proper use for
+ `--enable' is for questions of whether to build part of the program
+ or exclude it.
+
+`--with-PACKAGE'
+ The package PACKAGE will be installed, so configure this package
+ to work with PACKAGE.
+
+ Possible values of PACKAGE include `x', `x-toolkit', `gnu-as' (or
+ `gas'), `gnu-ld', `gnu-libc', and `gdb'.
+
+ Do not use a `--with' option to specify the file name to use to
+ find certain files. That is outside the scope of what `--with'
+ options are for.
+
+`--nfp'
+ The target machine has no floating point processor.
+
+`--gas'
+ The target machine assembler is GAS, the GNU assembler. This is
+ obsolete; users should use `--with-gnu-as' instead.
+
+`--x'
+ The target machine has the X Window System installed. This is
+ obsolete; users should use `--with-x' instead.
+
+ All `configure' scripts should accept all of these "detail" options,
+whether or not they make any difference to the particular package at
+hand. In particular, they should accept any option that starts with
+`--with-' or `--enable-'. This is so users will be able to configure
+an entire GNU source tree at once with a single set of options.
+
+ You will note that the categories `--with-' and `--enable-' are
+narrow: they *do not* provide a place for any sort of option you might
+think of. That is deliberate. We want to limit the possible
+configuration options in GNU software. We do not want GNU programs to
+have idiosyncratic configuration options.
+
+ Packages that perform part of the compilation process may support
+cross-compilation. In such a case, the host and target machines for
+the program may be different. The `configure' script should normally
+treat the specified type of system as both the host and the target,
+thus producing a program which works for the same type of machine that
+it runs on.
+
+ The way to build a cross-compiler, cross-assembler, or what have
+you, is to specify the option `--host=HOSTTYPE' when running
+`configure'. This specifies the host system without changing the type
+of target system. The syntax for HOSTTYPE is the same as described
+above.
+
+ Bootstrapping a cross-compiler requires compiling it on a machine
+other than the host it will run on. Compilation packages accept a
+configuration option `--build=HOSTTYPE' for specifying the
+configuration on which you will compile them, in case that is different
+from the host.
+
+ Programs for which cross-operation is not meaningful need not accept
+the `--host' option, because configuring an entire operating system for
+cross-operation is not a meaningful thing.
+
+ Some programs have ways of configuring themselves automatically. If
+your program is set up to do this, your `configure' script can simply
+ignore most of its arguments.
+
+\1f
+File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
+
+Makefile Conventions
+====================
+
+ This node describes conventions for writing the Makefiles for GNU
+programs.
+
+* Menu:
+
+* Makefile Basics:: General Conventions for Makefiles
+* Utilities in Makefiles:: Utilities in Makefiles
+* Command Variables:: Variables for Specifying Commands
+* Directory Variables:: Variables for Installation Directories
+* Standard Targets:: Standard Targets for Users
+
+\1f
+File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
+
+General Conventions for Makefiles
+---------------------------------
+
+ Every Makefile should contain this line:
+
+ SHELL = /bin/sh
+
+to avoid trouble on systems where the `SHELL' variable might be
+inherited from the environment. (This is never a problem with GNU
+`make'.)
+
+ Different `make' programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior. So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+ .SUFFIXES:
+ .SUFFIXES: .c .o
+
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
+ Don't assume that `.' is in the path for command execution. When
+you need to run programs that are a part of your package during the
+make, please make sure that it uses `./' if the program is built as
+part of the make or `$(srcdir)/' if the file is an unchanging part of
+the source code. Without one of these prefixes, the current search
+path is used.
+
+ The distinction between `./' and `$(srcdir)/' is important when
+using the `--srcdir' option to `configure'. A rule of the form:
+
+ foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+
+will fail when the current directory is not the source directory,
+because `foo.man' and `sedscript' are not in the current directory.
+
+ When using GNU `make', relying on `VPATH' to find the source file
+will work in the case where there is a single dependency file, since
+the `make' automatic variable `$<' will represent the source file
+wherever it is. (Many versions of `make' set `$<' only in implicit
+rules.) A Makefile target like
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+
+should instead be written as
+
+ foo.o : bar.c
+ $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
+
+in order to allow `VPATH' to work correctly. When the target has
+multiple dependencies, using an explicit `$(srcdir)' is the easiest way
+to make the rule work well. For example, the target above for `foo.1'
+is best written as:
+
+ foo.1 : foo.man sedscript
+ sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
+
+ Try to make the build and installation targets, at least (and all
+their subtargets) work correctly with a parallel `make'.
+
+\1f
+File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
+
+Utilities in Makefiles
+----------------------
+
+ Write the Makefile commands (and any shell scripts, such as
+`configure') to run in `sh', not in `csh'. Don't use any special
+features of `ksh' or `bash'.
+
+ The `configure' script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+ cat cmp cp echo egrep expr false grep
+ ln mkdir mv pwd rm rmdir sed test touch true
+
+ Stick to the generally supported options for these programs. For
+example, don't use `mkdir -p', convenient as it may be, because most
+systems don't support it.
+
+ It is a good idea to avoid creating symbolic links in makefiles,
+since a few systems don't support them.
+
+ The Makefile rules for building and installation can also use
+compilers and related programs, but should do so via `make' variables
+so that the user can substitute alternatives. Here are some of the
+programs we mean:
+
+ ar bison cc flex install ld lex
+ make makeinfo ranlib texi2dvi yacc
+
+ Use the following `make' variables:
+
+ $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX)
+ $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
+
+ When you use `ranlib', you should make sure nothing bad happens if
+the system does not have `ranlib'. Arrange to ignore an error from
+that command, and print a message before the command to tell the user
+that failure of the `ranlib' command does not mean a problem. (The
+Autoconf `AC_PROG_RANLIB' macro can help with this.)
+
+ If you use symbolic links, you should implement a fallback for
+systems that don't have symbolic links.
+
+ It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities
+exist.
+
+\1f
+File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
+
+Variables for Specifying Commands
+---------------------------------
+
+ Makefiles should provide variables for overriding certain commands,
+options, and so on.
+
+ In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named `BISON' whose default
+value is set with `BISON = bison', and refer to it with `$(BISON)'
+whenever you need to use Bison.
+
+ File management utilities such as `ln', `rm', `mv', and so on, need
+not be referred to through variables in this way, since users don't
+need to replace them with other programs.
+
+ Each program-name variable should come with an options variable that
+is used to supply options to the program. Append `FLAGS' to the
+program-name variable name to get the options variable name--for
+example, `BISONFLAGS'. (The name `CFLAGS' is an exception to this
+rule, but we keep it because it is standard.) Use `CPPFLAGS' in any
+compilation command that runs the preprocessor, and use `LDFLAGS' in
+any compilation command that does linking as well as in any direct use
+of `ld'.
+
+ If there are C compiler options that *must* be used for proper
+compilation of certain files, do not include them in `CFLAGS'. Users
+expect to be able to specify `CFLAGS' freely themselves. Instead,
+arrange to pass the necessary options to the C compiler independently
+of `CFLAGS', by writing them explicitly in the compilation commands or
+by defining an implicit rule, like this:
+
+ CFLAGS = -g
+ ALL_CFLAGS = -I. $(CFLAGS)
+ .c.o:
+ $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+
+ Do include the `-g' option in `CFLAGS', because that is not
+*required* for proper compilation. You can consider it a default that
+is only recommended. If the package is set up so that it is compiled
+with GCC by default, then you might as well include `-O' in the default
+value of `CFLAGS' as well.
+
+ Put `CFLAGS' last in the compilation command, after other variables
+containing compiler options, so the user can use `CFLAGS' to override
+the others.
+
+ Every Makefile should define the variable `INSTALL', which is the
+basic command for installing a file into the system.
+
+ Every Makefile should also define the variables `INSTALL_PROGRAM'
+and `INSTALL_DATA'. (The default for each of these should be
+`$(INSTALL)'.) Then it should use those variables as the commands for
+actual installation, for executables and nonexecutables respectively.
+Use these variables as follows:
+
+ $(INSTALL_PROGRAM) foo $(bindir)/foo
+ $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
+
+\1f
+File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
+
+Variables for Installation Directories
+--------------------------------------
+
+ Installation directories should always be named by variables, so it
+is easy to install in a nonstandard place. The standard names for these
+variables are described below. They are based on a standard filesystem
+layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
+other modern operating systems.
+
+ These two variables set the root for the installation. All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
+
+`prefix'
+ A prefix used in constructing the default values of the variables
+ listed below. The default value of `prefix' should be
+ `/usr/local'. When building the complete GNU system, the prefix
+ will be empty and `/usr' will be a symbolic link to `/'. (If you
+ are using Autoconf, write it as `@prefix@'.)
+
+`exec_prefix'
+ A prefix used in constructing the default values of some of the
+ variables listed below. The default value of `exec_prefix' should
+ be `$(prefix)'. (If you are using Autoconf, write it as
+ `@exec_prefix@'.)
+
+ Generally, `$(exec_prefix)' is used for directories that contain
+ machine-specific files (such as executables and subroutine
+ libraries), while `$(prefix)' is used directly for other
+ directories.
+
+ Executable programs are installed in one of the following
+directories.
+
+`bindir'
+ The directory for installing executable programs that users can
+ run. This should normally be `/usr/local/bin', but write it as
+ `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
+ `@bindir@'.)
+
+`sbindir'
+ The directory for installing executable programs that can be run
+ from the shell, but are only generally useful to system
+ administrators. This should normally be `/usr/local/sbin', but
+ write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
+ write it as `@sbindir@'.)
+
+`libexecdir'
+ The directory for installing executable programs to be run by other
+ programs rather than by users. This directory should normally be
+ `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
+ (If you are using Autoconf, write it as `@libexecdir@'.)
+
+ Data files used by the program during its execution are divided into
+categories in two ways.
+
+ * Some files are normally modified by programs; others are never
+ normally modified (though users may edit some of these).
+
+ * Some files are architecture-independent and can be shared by all
+ machines at a site; some are architecture-dependent and can be
+ shared only by machines of the same kind and operating system;
+ others may never be shared between two machines.
+
+ This makes for six different possibilities. However, we want to
+discourage the use of architecture-dependent files, aside from object
+files and libraries. It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
+
+ Therefore, here are the variables Makefiles should use to specify
+directories:
+
+`datadir'
+ The directory for installing read-only architecture independent
+ data files. This should normally be `/usr/local/share', but write
+ it as `$(prefix)/share'. (If you are using Autoconf, write it as
+ `@datadir@'.) As a special exception, see `$(infodir)' and
+ `$(includedir)' below.
+
+`sysconfdir'
+ The directory for installing read-only data files that pertain to a
+ single machine-that is to say, files for configuring a host.
+ Mailer and network configuration files, `/etc/passwd', and so
+ forth belong here. All the files in this directory should be
+ ordinary ASCII text files. This directory should normally be
+ `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
+ using Autoconf, write it as `@sysconfdir@'.)
+
+ Do not install executables in this directory (they probably belong
+ in `$(libexecdir)' or `$(sbindir)'). Also do not install files
+ that are modified in the normal course of their use (programs
+ whose purpose is to change the configuration of the system
+ excluded). Those probably belong in `$(localstatedir)'.
+
+`sharedstatedir'
+ The directory for installing architecture-independent data files
+ which the programs modify while they run. This should normally be
+ `/usr/local/com', but write it as `$(prefix)/com'. (If you are
+ using Autoconf, write it as `@sharedstatedir@'.)
+
+`localstatedir'
+ The directory for installing data files which the programs modify
+ while they run, and that pertain to one specific machine. Users
+ should never need to modify files in this directory to configure
+ the package's operation; put such configuration information in
+ separate files that go in `$(datadir)' or `$(sysconfdir)'.
+ `$(localstatedir)' should normally be `/usr/local/var', but write
+ it as `$(prefix)/var'. (If you are using Autoconf, write it as
+ `@localstatedir@'.)
+
+`libdir'
+ The directory for object files and libraries of object code. Do
+ not install executables here, they probably ought to go in
+ `$(libexecdir)' instead. The value of `libdir' should normally be
+ `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
+ are using Autoconf, write it as `@libdir@'.)
+
+`infodir'
+ The directory for installing the Info files for this package. By
+ default, it should be `/usr/local/info', but it should be written
+ as `$(prefix)/info'. (If you are using Autoconf, write it as
+ `@infodir@'.)
+
+`includedir'
+ The directory for installing header files to be included by user
+ programs with the C `#include' preprocessor directive. This
+ should normally be `/usr/local/include', but write it as
+ `$(prefix)/include'. (If you are using Autoconf, write it as
+ `@includedir@'.)
+
+ Most compilers other than GCC do not look for header files in
+ `/usr/local/include'. So installing the header files this way is
+ only useful with GCC. Sometimes this is not a problem because some
+ libraries are only really intended to work with GCC. But some
+ libraries are intended to work with other compilers. They should
+ install their header files in two places, one specified by
+ `includedir' and one specified by `oldincludedir'.
+
+`oldincludedir'
+ The directory for installing `#include' header files for use with
+ compilers other than GCC. This should normally be `/usr/include'.
+ (If you are using Autoconf, you can write it as `@oldincludedir@'.)
+
+ The Makefile commands should check whether the value of
+ `oldincludedir' is empty. If it is, they should not try to use
+ it; they should cancel the second installation of the header files.
+
+ A package should not replace an existing header in this directory
+ unless the header came from the same package. Thus, if your Foo
+ package provides a header file `foo.h', then it should install the
+ header file in the `oldincludedir' directory if either (1) there
+ is no `foo.h' there or (2) the `foo.h' that exists came from the
+ Foo package.
+
+ To tell whether `foo.h' came from the Foo package, put a magic
+ string in the file--part of a comment--and `grep' for that string.
+
+ Unix-style man pages are installed in one of the following:
+
+`mandir'
+ The top-level directory for installing the man pages (if any) for
+ this package. It will normally be `/usr/local/man', but you should
+ write it as `$(prefix)/man'. (If you are using Autoconf, write it
+ as `@mandir@'.)
+
+`man1dir'
+ The directory for installing section 1 man pages. Write it as
+ `$(mandir)/man1'.
+
+`man2dir'
+ The directory for installing section 2 man pages. Write it as
+ `$(mandir)/man2'
+
+`...'
+ *Don't make the primary documentation for any GNU software be a
+ man page. Write a manual in Texinfo instead. Man pages are just
+ for the sake of people running GNU software on Unix, which is a
+ secondary application only.*
+
+`manext'
+ The file name extension for the installed man page. This should
+ contain a period followed by the appropriate digit; it should
+ normally be `.1'.
+
+`man1ext'
+ The file name extension for installed section 1 man pages.
+
+`man2ext'
+ The file name extension for installed section 2 man pages.
+
+`...'
+ Use these names instead of `manext' if the package needs to
+ install man pages in more than one section of the manual.
+
+ And finally, you should set the following variable:
+
+`srcdir'
+ The directory for the sources being compiled. The value of this
+ variable is normally inserted by the `configure' shell script.
+ (If you are using Autconf, use `srcdir = @srcdir@'.)
+
+ For example:
+
+ # Common prefix for installation directories.
+ # NOTE: This directory must exist when you start the install.
+ prefix = /usr/local
+ exec_prefix = $(prefix)
+ # Where to put the executable for the command `gcc'.
+ bindir = $(exec_prefix)/bin
+ # Where to put the directories used by the compiler.
+ libexecdir = $(exec_prefix)/libexec
+ # Where to put the Info files.
+ infodir = $(prefix)/info
+
+ If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the `install' rule to create these subdirectories.
+
+ Do not expect the user to include the subdirectory name in the value
+of any of the variables listed above. The idea of having a uniform set
+of variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+
--- /dev/null
+This is Info file ../info/standards.info, produced by Makeinfo version
+1.68 from the input file standards.texi.
+
+START-INFO-DIR-ENTRY
+* Standards: (standards). GNU coding standards.
+END-INFO-DIR-ENTRY
+
+ GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
+Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: standards.info, Node: Standard Targets, Prev: Directory Variables, Up: Makefile Conventions
+
+Standard Targets for Users
+--------------------------
+
+ All GNU programs should have the following targets in their
+Makefiles:
+
+`all'
+ Compile the entire program. This should be the default target.
+ This target need not rebuild any documentation files; Info files
+ should normally be included in the distribution, and DVI files
+ should be made only when explicitly asked for.
+
+ By default, the Make rules should compile and link with `-g', so
+ that executable programs have debugging symbols. Users who don't
+ mind being helpless can strip the executables later if they wish.
+
+`install'
+ Compile the program and copy the executables, libraries, and so on
+ to the file names where they should reside for actual use. If
+ there is a simple test to verify that a program is properly
+ installed, this target should run that test.
+
+ Do not strip executables when installing them. Devil-may-care
+ users can use the `install-strip' target to do that.
+
+ If possible, write the `install' target rule so that it does not
+ modify anything in the directory where the program was built,
+ provided `make all' has just been done. This is convenient for
+ building the program under one user name and installing it under
+ another.
+
+ The commands should create all the directories in which files are
+ to be installed, if they don't already exist. This includes the
+ directories specified as the values of the variables `prefix' and
+ `exec_prefix', as well as all subdirectories that are needed. One
+ way to do this is by means of an `installdirs' target as described
+ below.
+
+ Use `-' before any command for installing a man page, so that
+ `make' will ignore any errors. This is in case there are systems
+ that don't have the Unix man page documentation system installed.
+
+ The way to install Info files is to copy them into `$(infodir)'
+ with `$(INSTALL_DATA)' (*note Command Variables::.), and then run
+ the `install-info' program if it is present. `install-info' is a
+ program that edits the Info `dir' file to add or update the menu
+ entry for the given Info file; it is part of the Texinfo package.
+ Here is a sample rule to install an Info file:
+
+ $(infodir)/foo.info: foo.info
+ # There may be a newer info file in . than in srcdir.
+ -if test -f foo.info; then d=.; \
+ else d=$(srcdir); fi; \
+ $(INSTALL_DATA) $$d/foo.info $@; \
+ # Run install-info only if it exists.
+ # Use `if' instead of just prepending `-' to the
+ # line so we notice real errors from install-info.
+ # We use `$(SHELL) -c' because some shells do not
+ # fail gracefully when there is an unknown command.
+ if $(SHELL) -c 'install-info --version' \
+ >/dev/null 2>&1; then \
+ install-info --dir-file=$(infodir)/dir \
+ $(infodir)/foo.info; \
+ else true; fi
+
+`uninstall'
+ Delete all the installed files that the `install' target would
+ create (but not the noninstalled files such as `make all' would
+ create).
+
+ This rule should not modify the directories where compilation is
+ done, only the directories where files are installed.
+
+`install-strip'
+ Like `install', but strip the executable files while installing
+ them. The definition of this target can be very simple:
+
+ install-strip:
+ $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
+ install
+
+ Normally we do not recommend stripping an executable unless you
+ are sure the program has no bugs. However, it can be reasonable
+ to install a stripped executable for actual execution while saving
+ the unstripped executable elsewhere in case there is a bug.
+
+`clean'
+ Delete all files from the current directory that are normally
+ created by building the program. Don't delete the files that
+ record the configuration. Also preserve files that could be made
+ by building, but normally aren't because the distribution comes
+ with them.
+
+ Delete `.dvi' files here if they are not part of the distribution.
+
+`distclean'
+ Delete all files from the current directory that are created by
+ configuring or building the program. If you have unpacked the
+ source and built the program without creating any other files,
+ `make distclean' should leave only the files that were in the
+ distribution.
+
+`mostlyclean'
+ Like `clean', but may refrain from deleting a few files that people
+ normally don't want to recompile. For example, the `mostlyclean'
+ target for GCC does not delete `libgcc.a', because recompiling it
+ is rarely necessary and takes a lot of time.
+
+`maintainer-clean'
+ Delete almost everything from the current directory that can be
+ reconstructed with this Makefile. This typically includes
+ everything deleted by `distclean', plus more: C source files
+ produced by Bison, tags tables, Info files, and so on.
+
+ The reason we say "almost everything" is that running the command
+ `make maintainer-clean' should not delete `configure' even if
+ `configure' can be remade using a rule in the Makefile. More
+ generally, `make maintainer-clean' should not delete anything that
+ needs to exist in order to run `configure' and then begin to build
+ the program. This is the only exception; `maintainer-clean' should
+ delete everything else that can be rebuilt.
+
+ The `maintainer-clean' target is intended to be used by a
+ maintainer of the package, not by ordinary users. You may need
+ special tools to reconstruct some of the files that `make
+ maintainer-clean' deletes. Since these files are normally
+ included in the distribution, we don't take care to make them easy
+ to reconstruct. If you find you need to unpack the full
+ distribution again, don't blame us.
+
+ To help make users aware of this, the commands for the special
+ `maintainer-clean' target should start with these two:
+
+ @echo 'This command is intended for maintainers to use; it'
+ @echo 'deletes files that may need special tools to rebuild.'
+
+`TAGS'
+ Update a tags table for this program.
+
+`info'
+ Generate any Info files needed. The best way to write the rules
+ is as follows:
+
+ info: foo.info
+
+ foo.info: foo.texi chap1.texi chap2.texi
+ $(MAKEINFO) $(srcdir)/foo.texi
+
+ You must define the variable `MAKEINFO' in the Makefile. It should
+ run the `makeinfo' program, which is part of the Texinfo
+ distribution.
+
+`dvi'
+ Generate DVI files for all Texinfo documentation. For example:
+
+ dvi: foo.dvi
+
+ foo.dvi: foo.texi chap1.texi chap2.texi
+ $(TEXI2DVI) $(srcdir)/foo.texi
+
+ You must define the variable `TEXI2DVI' in the Makefile. It should
+ run the program `texi2dvi', which is part of the Texinfo
+ distribution.(1) Alternatively, write just the dependencies, and
+ allow GNU `make' to provide the command.
+
+`dist'
+ Create a distribution tar file for this program. The tar file
+ should be set up so that the file names in the tar file start with
+ a subdirectory name which is the name of the package it is a
+ distribution for. This name can include the version number.
+
+ For example, the distribution tar file of GCC version 1.40 unpacks
+ into a subdirectory named `gcc-1.40'.
+
+ The easiest way to do this is to create a subdirectory
+ appropriately named, use `ln' or `cp' to install the proper files
+ in it, and then `tar' that subdirectory.
+
+ Compress the tar file with `gzip'. For example, the actual
+ distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
+
+ The `dist' target should explicitly depend on all non-source files
+ that are in the distribution, to make sure they are up to date in
+ the distribution. *Note Making Releases: Releases.
+
+`check'
+ Perform self-tests (if any). The user must build the program
+ before running the tests, but need not install the program; you
+ should write the self-tests so that they work when the program is
+ built but not installed.
+
+ The following targets are suggested as conventional names, for
+programs in which they are useful.
+
+`installcheck'
+ Perform installation tests (if any). The user must build and
+ install the program before running the tests. You should not
+ assume that `$(bindir)' is in the search path.
+
+`installdirs'
+ It's useful to add a target named `installdirs' to create the
+ directories where files are installed, and their parent
+ directories. There is a script called `mkinstalldirs' which is
+ convenient for this; you can find it in the Texinfo package. You
+ can use a rule like this:
+
+ # Make sure all installation directories (e.g. $(bindir))
+ # actually exist by making them if necessary.
+ installdirs: mkinstalldirs
+ $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+ $(libdir) $(infodir) \
+ $(mandir)
+
+ This rule should not modify the directories where compilation is
+ done. It should do nothing but create installation directories.
+
+ ---------- Footnotes ----------
+
+ (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
+not distributed with Texinfo.
+
+\1f
+File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
+
+Making Releases
+===============
+
+ Package the distribution of Foo version 69.96 in a gzipped tar file
+named `foo-69.96.tar.gz'. It should unpack into a subdirectory named
+`foo-69.96'.
+
+ Building and installing the program should never modify any of the
+files contained in the distribution. This means that all the files
+that form part of the program in any way must be classified into "source
+files" and "non-source files". Source files are written by humans and
+never changed automatically; non-source files are produced from source
+files by programs under the control of the Makefile.
+
+ Naturally, all the source files must be in the distribution. It is
+okay to include non-source files in the distribution, provided they are
+up-to-date and machine-independent, so that building the distribution
+normally will never modify them. We commonly include non-source files
+produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
+unnecessary dependencies between our distributions, so that users can
+install whichever packages they want to install.
+
+ Non-source files that might actually be modified by building and
+installing the program should *never* be included in the distribution.
+So if you do distribute non-source files, always make sure they are up
+to date when you make a new distribution.
+
+ Make sure that the directory into which the distribution unpacks (as
+well as any subdirectories) are all world-writable (octal mode 777).
+This is so that old versions of `tar' which preserve the ownership and
+permissions of the files from the tar archive will be able to extract
+all the files even if the user is unprivileged.
+
+ Make sure that all the files in the distribution are world-readable.
+
+ Make sure that no file name in the distribution is more than 14
+characters long. Likewise, no file created by building the program
+should have a name longer than 14 characters. The reason for this is
+that some systems adhere to a foolish interpretation of the POSIX
+standard, and refuse to open a longer name, rather than truncating as
+they did in the past.
+
+ Don't include any symbolic links in the distribution itself. If the
+tar file contains symbolic links, then people cannot even unpack it on
+systems that don't support symbolic links. Also, don't use multiple
+names for one file in different directories, because certain file
+systems cannot handle this and that prevents unpacking the distribution.
+
+ Try to make sure that all the file names will be unique on MS-DOS. A
+name on MS-DOS consists of up to 8 characters, optionally followed by a
+period and up to three characters. MS-DOS will truncate extra
+characters both before and after the period. Thus, `foobarhacker.c'
+and `foobarhacker.o' are not ambiguous; they are truncated to
+`foobarha.c' and `foobarha.o', which are distinct.
+
+ Include in your distribution a copy of the `texinfo.tex' you used to
+test print any `*.texinfo' or `*.texi' files.
+
+ Likewise, if your program uses small GNU software packages like
+regex, getopt, obstack, or termcap, include them in the distribution
+file. Leaving them out would make the distribution file a little
+smaller at the expense of possible inconvenience to a user who doesn't
+know what other files to get.
+
+
--- /dev/null
+This is Info file ../info/term.info, produced by Makeinfo version 1.68
+from the input file term.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Term mode: (term). Emacs terminal emulator mode.
+END-INFO-DIR-ENTRY
+
+\1f
+File: term.info, Node: Top, Prev: (DIR)
+
+Terminal emulator mode
+**********************
+
+ This is some notes about the term Emacs mode.
+
+* Menu:
+
+* term mode::
+
+\1f
+File: term.info, Node: term mode, Prev: Top, Up: Top
+
+Term Mode
+*********
+
+* Menu:
+
+* Overview::
+* Connecting to remote computers::
+* Paging::
+* Terminal escapes::
+
+ The `term' package includes the major modes `term', `shell', and
+`gud' (for running gbd or another debugger). It is a replacement for
+the comint mode of Emacs 19, as well as shell, gdb, terminal, and
+telnet modes. The package works best with recent releases of Emacs 19,
+but will also work reasonably well with Emacs 18 as well as Lucid Emacs
+19.
+
+ The file `nshell.el' is a wrapper to use unless term mode is built
+into Emacs. If works around some of the missing in older Emacs
+versions. To use it, edit the paths in `nshell.el', appropriately, and
+then `M-x load-file nshell.el RET'. This will also load in replacement
+shell and gud modes.
+
+\1f
+File: term.info, Node: Overview, Next: Connecting to remote computers, Up: term mode
+
+Overview
+========
+
+ The `term' mode is used to control a program (an "inferior process").
+It sends most keyboard input characters to the program, and displays
+output from the program in the buffer. This is similar to the
+traditional comint mode, and modes derived from it (such as shell and
+gdb modes). You can do with the new term-based shell the same sort of
+things you could do with the old shell mode, using more or less the
+same interface. However, the new mode is more flexible, and works
+somewhat differently.
+
+* Menu:
+
+* Output from the inferior::
+* subbuffer:: The sub-buffer
+* altsubbuffer:: The alternate sub-buffer
+* Input to the inferior::
+
+\1f
+File: term.info, Node: Output from the inferior, Next: subbuffer, Up: Overview
+
+Output from the inferior
+------------------------
+
+ In typical usage, output from the inferior is added to the end of
+the buffer. If needed, the window will be scrolled, just like a
+regular terminal. (Only one line at a time will be scrolled, just like
+regular terminals, and in contrast to the old shell mode.) Thus the
+buffer becomes a log of your interaction with the inferior, just like
+the old shell mode.
+
+ Like a real terminal, term maintains a "cursor position." This is
+the `process-mark' of the inferior process. If the process-mark is not
+at the end of the buffer, output from the inferior will overwrite
+existing text in the buffer. This is like a real terminal, but unlike
+the old shell mode (which inserts the output, instead of overwriting).
+
+ Some programs (such as Emacs itself) need to control the appearance
+on the screen in detail. They do this by sending special control
+codes. The exact control codes needed 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. (In contrast,
+the old shell mode doesn't handle terminal control codes at all.)
+
+ See <...> for the specific control codes.
+
+\1f
+File: term.info, Node: subbuffer, Next: altsubbuffer, Prev: Output from the inferior, Up: Overview
+
+The sub-buffer
+--------------
+
+ A program that talks to terminal expects the terminal to have a
+fixed size. If the program is talking a terminal emulator program such
+as `xterm', that size can be changed (if the xterm window is re-sized),
+but programs still assume a logical terminal that has a fixed size
+independent of the amount of output transmitted by the programs.
+
+ To programs that use it, the Emacs terminal emulator acts as if it
+too has a fixed size. The "sub-buffer" is the part of a `term'-mode
+buffer that corresponds to a "normal" terminal. Most of the time
+(unless you explicitly scroll the window displaying the buffer), the
+sub-buffer is the part of the buffer that is displayed in a window.
+
+ The sub-buffer is defined in terms of three buffer-local-variable:
+
+ - Variable: term-height
+ The height of the sub-buffer, in screen lines.
+
+ - Variable: term-width
+ The width of the sub-buffer, in screen columns.
+
+ - Variable: term-home-marker
+ The "home" position, that is the top left corner of the sub-buffer.
+
+ The sub-buffer is assumed to be the end part of the buffer; the
+`term-home-marker' should never be more than `term-height' screen lines
+from the end of the buffer.
+
+\1f
+File: term.info, Node: altsubbuffer, Next: Input to the inferior, Prev: subbuffer, Up: Overview
+
+The alternate sub-buffer
+------------------------
+
+ When a "graphical" program finishes, it is nice to restore the
+screen state to what it was before the program started. Many people
+are used to this behavior from `xterm', and its also offered by the
+`term' emulator.
+
+ - Function: term-switch-to-alternate-sub-buffer SET
+ If SET is true, and we're not already using the alternate
+ sub-buffer, switch to it. What this means is that the
+ `term-home-marker' is saved (in the variable
+ `term-saved-home-marker'), and the `term-home-marker' is set to
+ the end of the buffer.
+
+ If SET is false and we're using the alternate sub-buffer, switch
+ back to the saved sub-buffer. What this means is that the
+ (current, alternate) sub-buffer is deleted (using `(delete-region
+ term-home-marker (point-max))'), and then the `term-home-marker'
+ is restored (from `term-saved-home-marker').
+
+\1f
+File: term.info, Node: Input to the inferior, Prev: altsubbuffer, Up: Overview
+
+Input to the inferior
+---------------------
+
+ Characters typed by the user are sent to the inferior. How this is
+done depends on whether the `term' buffer is in "character" mode or
+"line" mode. (A `term' buffer can also be in "pager" mode. This is
+discussed <later>.) Which of these is currently active is specified in
+the mode line. The difference between them is the key-bindings
+available.
+
+ In character mode, one character (by default <C-c>) is special, and
+is a prefix for various commands. All other characters are sent
+directly to the inferior process, with no interpretation by Emacs.
+Character mode looks and feels like a real terminal, or a conventional
+terminal emulator such as xterm.
+
+ In line mode, key commands mostly have standard Emacs actions.
+Regulars characters insert themselves into the buffer. When return is
+typed, the entire current line of the buffer (except possibly the
+prompt) is sent to the inferior process. Line mode is basically the
+original shell mode from earlier Emacs versions.
+
+ To switch from line mode to character mode type `C-c c'. To switch
+from character mode to line mode type `C-c l'.
+
+ In either mode, "echoing" of user input is handled by the inferior.
+Therefor, in line mode after an input line at the end of the buffer is
+sent to the inferior, it is deleted from the buffer. This is so that
+the inferior can echo the input, if it wishes (which it normally does).
+
+\1f
+File: term.info, Node: Connecting to remote computers, Next: Paging, Prev: Overview, Up: term mode
+
+Connecting to remote computers
+==============================
+
+ If you want to login to a remove computer, you can do that just as
+you would expect, using whatever commands you would normally use.
+
+ (This is worth emphasizing, because earlier versions of `shell' mode
+would not work properly if you tried to log in to some other computer,
+because of the way echoing was handled. That is why there was a
+separate `telnet' mode to partially compensate for these problems. The
+`telnet' mode is no longer needed, and is basically obsolete.)
+
+ A program that asks you for a password will normally suppress
+echoing of the password, so the password will not show up in the buffer.
+This will happen just as if you were using a real terminal, if the
+buffer is in char mode. If it is in line mode, the password will be
+temporarily visible, but will be erased when you hit return. (This
+happens automatically; there is no special password processing.)
+
+ When you log in to a different machine, you need to specify the type
+of terminal your using. If you are talking to a Bourne-compatible
+shell, and your system understands the `TERMCAP' variable, you can use
+the command `M-x shell-send-termcap', which sends a string specifying
+the terminal type and size. (This command is also useful after the
+window has changed size.)
+
+ If you need to specify the terminal type manually, you can try the
+terminal types "ansi" or "vt100".
+
+ You can of course run gdb on that remote computer. One useful
+trick: If you invoke gdb with the `--fullname' option, it will send
+special commands to Emacs that will cause Emacs to pop up the source
+files you're debugging. This will work whether or not gdb is running
+on a different computer than Emacs, assuming can access the source
+files specified by gdb.
+
+\1f
+File: term.info, Node: Paging, Next: Terminal escapes, Prev: Connecting to remote computers, Up: term mode
+
+Paging
+======
+
+ When the pager is enabled, Emacs will "pause" after each screenful
+of output (since the last input sent to the inferior). It will enter
+"pager" mode, which feels a lot like the "more" program: Typing a
+space requests another screenful of output. Other commands request
+more or less output, or scroll backwards in the `term' buffer. In
+pager mode, type `h' or `?' to display a help message listing all the
+available pager mode commands.
+
+ In either character or line mode, type `C-c p' to enable paging, and
+`C-c D' to disable it.
+
+\1f
+File: term.info, Node: Terminal escapes, Prev: Paging, Up: term mode
+
+Terminal Escape sequences
+=========================
+
+ A program that does "graphics" on a terminal controls the terminal
+by sending strings called "terminal escape sequences" that the terminal
+(or terminal emulator) interprets as special commands. The `term' mode
+includes a terminal emulator that understands standard ANSI escape
+sequences, originally popularized by VT100 terminals, and now used by
+the `xterm' program and most modern terminal emulator software.
+
+* Menu:
+
+* Cursor motion:: Escape sequences to move the cursor
+* Erasing:: Escape commands for erasing text
+* Inserting and deleting:: Escape sequences to insert and delete text
+* Scrolling:: Escape sequences to scroll part of the visible window
+* Command hook::
+* Miscellaneous escapes::
+
+ printing chars
+
+ tab
+
+ LF
+
+\1f
+File: term.info, Node: Cursor motion, Next: Erasing, Up: Terminal escapes
+
+Escape sequences to move the cursor
+-----------------------------------
+
+`RETURN'
+ Moves to the beginning of the current screen line.
+
+`C-b'
+ Moves backwards one column. (Tabs are broken up if needed.)
+
+`Esc [ R ; C H'
+ Move to screen row R, screen column C, where (R=1) is the top row,
+ and (C=1) is the leftmost column. Defaults are R=1 and C=1.
+
+`Esc [ N A'
+ Move N (default 1) screen lines up.
+
+`Esc [ N B'
+ Move N (default 1) screen lines down.
+
+`Esc [ N C'
+ Move N (default 1) columns right.
+
+`Esc [ N D'
+ Move N (default 1) columns left.
+
+\1f
+File: term.info, Node: Erasing, Next: Inserting and deleting, Prev: Cursor motion, Up: Terminal escapes
+
+Escape commands for erasing text
+--------------------------------
+
+ These commands "erase" part of the sub-buffer. Erasing means
+replacing by white space; it is not the same as deleting. The relative
+screen positions of things that are not erased remain unchanged with
+each other, as does the relative cursor position.
+
+`E [ J'
+ Erase from cursor to end of screen.
+
+`E [ 0 J'
+ Same as E [ J.
+
+`E [ 1 J'
+ Erase from home position to point.
+
+`E [ 2 J'
+ Erase whole sub-buffer.
+
+`E [ K'
+ Erase from point to end of screen line.
+
+`E [ 0 K'
+ Same as E [ K.
+
+`E [ 1 K'
+ Erase from beginning of screen line to point.
+
+`E [ 2 K'
+ Erase whole screen line.
+
+\1f
+File: term.info, Node: Inserting and deleting, Next: Scrolling, Prev: Erasing, Up: Terminal escapes
+
+Escape sequences to insert and delete text
+------------------------------------------
+
+`Esc [ N L'
+ Insert N (default 1) blank lines.
+
+`Esc [ N M'
+ Delete N (default 1) lines.
+
+`Esc [ N P'
+ Delete N (default 1) characters.
+
+`Esc [ N @'
+ Insert N (default 1) spaces.
+
+\1f
+File: term.info, Node: Scrolling, Next: Command hook, Prev: Inserting and deleting, Up: Terminal escapes
+
+Escape sequences to scroll part of the visible window
+-----------------------------------------------------
+
+`Esc D'
+ Scroll forward one screen line.
+
+`Esc M'
+ Scroll backwards one screen line.
+
+`Esc [ T ; B r'
+ Set the scrolling region to be from lines T down to line B
+ inclusive, where line 1 is the topmost line.
+
+\1f
+File: term.info, Node: Command hook, Next: Miscellaneous escapes, Prev: Scrolling, Up: Terminal escapes
+
+Command hook
+------------
+
+ If `C-z' is seen, any text up to a following <LF> is scanned. The
+text in between (not counting the initial C-z or the final LF) is
+passed to the function that is the value of `term-command-hook'.
+
+ The default value of the `term-command-hook' variable is the
+function `term-command-hook', which handles the following:
+
+`C-z C-z FILENAME:LINENUMBER:IGNORED LF'
+ Set term-pending-frame to `(cons "FILENAME" LINENUMBER)'. When
+ the buffer is displayed in the current window, show the FILENAME
+ in the other window, and show an arrow at LINENUMBER. Gdb emits
+ these strings when invoked with the flag -fullname. This is used
+ by gdb mode; you can also invoke gdb with this flag from shell
+ mode.
+
+`C-z / DIRNAME LF'
+ Set the directory of the term buffer to DIRNAME
+
+`C-z ! LEXPR LF'
+ Read and evaluate LEXPR as a Lisp expression. The result is
+ ignored.
+
+\1f
+File: term.info, Node: Miscellaneous escapes, Prev: Command hook, Up: Terminal escapes
+
+Miscellaneous escapes
+---------------------
+
+`C-g (Bell)'
+ Calls `(beep t)'.
+
+`Esc 7'
+ Save cursor.
+
+`Esc 8'
+ Restore cursor.
+
+`Esc [ 47 h'
+ Switch to the alternate sub-buffer,
+
+`Esc [ 47 l'
+ Switch back to the regular sub-buffer,
+
+
+\1f
+Tag Table:
+Node: Top\7f227
+Node: term mode\7f393
+Node: Overview\7f1216
+Node: Output from the inferior\7f1966
+Node: subbuffer\7f3546
+Node: altsubbuffer\7f4869
+Node: Input to the inferior\7f5894
+Node: Connecting to remote computers\7f7414
+Node: Paging\7f9319
+Node: Terminal escapes\7f9989
+Node: Cursor motion\7f10857
+Node: Erasing\7f11517
+Node: Inserting and deleting\7f12312
+Node: Scrolling\7f12702
+Node: Command hook\7f13148
+Node: Miscellaneous escapes\7f14184
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/termcap.info, produced by Makeinfo version
+1.68 from the input file termcap.texi.
+
+START-INFO-DIR-ENTRY
+* Termcap: (termcap). Termcap library of the GNU system.
+END-INFO-DIR-ENTRY
+
+ This file documents the termcap library of the GNU system.
+
+ Copyright (C) 1988 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+\1f
+Indirect:
+termcap.info-1: 985
+termcap.info-2: 49255
+termcap.info-3: 92578
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f985
+Node: Introduction\7f1630
+Node: Library\7f3357
+Node: Preparation\7f4374
+Node: Find\7f5573
+Node: Interrogate\7f9121
+Node: Initialize\7f14429
+Node: Padding\7f16069
+Node: Why Pad\7f16730
+Node: Describe Padding\7f18374
+Node: Output Padding\7f19849
+Node: Parameters\7f23464
+Node: Encode Parameters\7f25123
+Node: Using Parameters\7f31228
+Node: tparam\7f31817
+Node: tgoto\7f33882
+Node: Data Base\7f36437
+Node: Format\7f37315
+Node: Capability Format\7f39406
+Node: Naming\7f42459
+Node: Inheriting\7f47028
+Node: Capabilities\7f49255
+Node: Basic\7f52097
+Node: Screen Size\7f55941
+Node: Cursor Motion\7f57681
+Node: Wrapping\7f67338
+Node: Scrolling\7f70163
+Node: Windows\7f75183
+Node: Clearing\7f75917
+Node: Insdel Line\7f77681
+Node: Insdel Char\7f82593
+Node: Standout\7f92578
+Node: Underlining\7f101637
+Node: Cursor Visibility\7f104056
+Node: Bell\7f104804
+Node: Keypad\7f105353
+Node: Meta Key\7f110074
+Node: Initialization\7f111028
+Node: Pad Specs\7f113392
+Node: Status Line\7f115445
+Node: Half-Line\7f117329
+Node: Printer\7f118131
+Node: Summary\7f119810
+Node: Var Index\7f130016
+Node: Cap Index\7f130740
+Node: Index\7f137931
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/termcap.info, produced by Makeinfo version
+1.68 from the input file termcap.texi.
+
+START-INFO-DIR-ENTRY
+* Termcap: (termcap). Termcap library of the GNU system.
+END-INFO-DIR-ENTRY
+
+ This file documents the termcap library of the GNU system.
+
+ Copyright (C) 1988 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+\1f
+File: termcap.info, Node: Top, Next: Introduction, Prev: (DIR), Up: (DIR)
+
+* Menu:
+
+* Introduction::What is termcap? Why this manual?
+* Library:: The termcap library functions.
+* Data Base:: What terminal descriptions in `/etc/termcap' look like.
+* Capabilities::Definitions of the individual terminal capabilities:
+ how to write them in descriptions, and how to use
+ their values to do display updating.
+* Summary:: Brief table of capability names and their meanings.
+* Var Index:: Index of C functions and variables.
+* Cap Index:: Index of termcap capabilities.
+* Index:: Concept index.
+
+\1f
+File: termcap.info, Node: Introduction, Next: Library, Prev: Top, Up: Top
+
+Introduction
+************
+
+ "Termcap" is a library and data base that enables programs to use
+display terminals in a terminal-independent manner. It originated in
+Berkeley Unix.
+
+ The termcap data base describes the capabilities of hundreds of
+different display terminals in great detail. Some examples of the
+information recorded for a terminal could include how many columns wide
+it is, what string to send to move the cursor to an arbitrary position
+(including how to encode the row and column numbers), how to scroll the
+screen up one or several lines, and how much padding is needed for such
+a scrolling operation.
+
+ The termcap library is provided for easy access this data base in
+programs that want to do terminal-independent character-based display
+output.
+
+ This manual describes the GNU version of the termcap library, which
+has some extensions over the Unix version. All the extensions are
+identified as such, so this manual also tells you how to use the Unix
+termcap.
+
+ The GNU version of the termcap library is available free as source
+code, for use in free programs, and runs on Unix and VMS systems (at
+least). You can find it in the GNU Emacs distribution in the files
+`termcap.c' and `tparam.c'.
+
+ This manual was written for the GNU project, whose goal is to
+develop a complete free operating system upward-compatible with Unix
+for user programs. The project is approximately two thirds complete.
+For more information on the GNU project, including the GNU Emacs editor
+and the mostly-portable optimizing C compiler, send one dollar to
+
+ Free Software Foundation
+ 675 Mass Ave
+ Cambridge, MA 02139
+
+\1f
+File: termcap.info, Node: Library, Next: Data Base, Prev: Introduction, Up: Top
+
+The Termcap Library
+*******************
+
+ The termcap library is the application programmer's interface to the
+termcap data base. It contains functions for the following purposes:
+
+ * Finding the description of the user's terminal type (`tgetent').
+
+ * Interrogating the description for information on various topics
+ (`tgetnum', `tgetflag', `tgetstr').
+
+ * Computing and performing padding (`tputs').
+
+ * Encoding numeric parameters such as cursor positions into the
+ terminal-specific form required for display commands (`tparam',
+ `tgoto').
+
+* Menu:
+
+* Preparation:: Preparing to use the termcap library.
+* Find:: Finding the description of the terminal being used.
+* Interrogate:: Interrogating the description for particular capabilities.
+* Initialize:: Initialization for output using termcap.
+* Padding:: Outputting padding.
+* Parameters:: Encoding parameters such as cursor positions.
+
+\1f
+File: termcap.info, Node: Preparation, Next: Find, Prev: Library, Up: Library
+
+Preparing to Use the Termcap Library
+====================================
+
+ To use the termcap library in a program, you need two kinds of
+preparation:
+
+ * The compiler needs declarations of the functions and variables in
+ the library.
+
+ On GNU systems, it suffices to include the header file `termcap.h'
+ in each source file that uses these functions and variables.
+
+ On Unix systems, there is often no such header file. Then you must
+ explictly declare the variables as external. You can do likewise
+ for the functions, or let them be implicitly declared and cast
+ their values from type `int' to the appropriate type.
+
+ We illustrate the declarations of the individual termcap library
+ functions with ANSI C prototypes because they show how to pass the
+ arguments. If you are not using the GNU C compiler, you probably
+ cannot use function prototypes, so omit the argument types and
+ names from your declarations.
+
+ * The linker needs to search the library. Usually either
+ `-ltermcap' or `-ltermlib' as an argument when linking will do
+ this.
+
+\1f
+File: termcap.info, Node: Find, Next: Interrogate, Prev: Preparation, Up: Library
+
+Finding a Terminal Description: `tgetent'
+=========================================
+
+ An application program that is going to use termcap must first look
+up the description of the terminal type in use. This is done by calling
+`tgetent', whose declaration in ANSI Standard C looks like:
+
+ int tgetent (char *BUFFER, char *TERMTYPE);
+
+This function finds the description and remembers it internally so that
+you can interrogate it about specific terminal capabilities (*note
+Interrogate::.).
+
+ The argument TERMTYPE is a string which is the name for the type of
+terminal to look up. Usually you would obtain this from the environment
+variable `TERM' using `getenv ("TERM")'.
+
+ If you are using the GNU version of termcap, you can alternatively
+ask `tgetent' to allocate enough space. Pass a null pointer for
+BUFFER, and `tgetent' itself allocates the storage using `malloc'. In
+this case the returned value on success is the address of the storage,
+cast to `int'. But normally there is no need for you to look at the
+address. Do not free the storage yourself.
+
+ With the Unix version of termcap, you must allocate space for the
+description yourself and pass the address of the space as the argument
+BUFFER. There is no way you can tell how much space is needed, so the
+convention is to allocate a buffer 2048 characters long and assume that
+is enough. (Formerly the convention was to allocate 1024 characters and
+assume that was enough. But one day, for one kind of terminal, that was
+not enough.)
+
+ No matter how the space to store the description has been obtained,
+termcap records its address internally for use when you later
+interrogate the description with `tgetnum', `tgetstr' or `tgetflag'. If
+the buffer was allocated by termcap, it will be freed by termcap too if
+you call `tgetent' again. If the buffer was provided by you, you must
+make sure that its contents remain unchanged for as long as you still
+plan to interrogate the description.
+
+ The return value of `tgetent' is -1 if there is some difficulty
+accessing the data base of terminal types, 0 if the data base is
+accessible but the specified type is not defined in it, and some other
+value otherwise.
+
+ Here is how you might use the function `tgetent':
+
+ #ifdef unix
+ static char term_buffer[2048];
+ #else
+ #define term_buffer 0
+ #endif
+
+ init_terminal_data ()
+ {
+ char *termtype = getenv ("TERM");
+ int success;
+
+ if (termtype == 0)
+ fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
+
+ success = tgetent (term_buffer, termtype);
+ if (success < 0)
+ fatal ("Could not access the termcap data base.\n");
+ if (success == 0)
+ fatal ("Terminal type `%s' is not defined.\n", termtype);
+ }
+
+Here we assume the function `fatal' prints an error message and exits.
+
+ If the environment variable `TERMCAP' is defined, its value is used
+to override the terminal type data base. The function `tgetent' checks
+the value of `TERMCAP' automatically. If the value starts with `/'
+then it is taken as a file name to use as the data base file, instead
+of `/etc/termcap' which is the standard data base. If the value does
+not start with `/' then it is itself used as the terminal description,
+provided that the terminal type TERMTYPE is among the types it claims
+to apply to. *Note Data Base::, for information on the format of a
+terminal description.
+
+\1f
+File: termcap.info, Node: Interrogate, Next: Initialize, Prev: Find, Up: Library
+
+Interrogating the Terminal Description
+======================================
+
+ Each piece of information recorded in a terminal description is
+called a "capability". Each defined terminal capability has a
+two-letter code name and a specific meaning. For example, the number
+of columns is named `co'. *Note Capabilities::, for definitions of all
+the standard capability names.
+
+ Once you have found the proper terminal description with `tgetent'
+(*note Find::.), your application program must "interrogate" it for
+various terminal capabilities. You must specify the two-letter code of
+the capability whose value you seek.
+
+ Capability values can be numeric, boolean (capability is either
+present or absent) or strings. Any particular capability always has
+the same value type; for example, `co' always has a numeric value,
+while `am' (automatic wrap at margin) is always a flag, and `cm'
+(cursor motion command) always has a string value. The documentation
+of each capability says which type of value it has.
+
+ There are three functions to use to get the value of a capability,
+depending on the type of value the capability has. Here are their
+declarations in ANSI C:
+
+ int tgetnum (char *NAME);
+ int tgetflag (char *NAME);
+ char *tgetstr (char *NAME, char **AREA);
+
+`tgetnum'
+ Use `tgetnum' to get a capability value that is numeric. The
+ argument NAME is the two-letter code name of the capability. If
+ the capability is present, `tgetnum' returns the numeric value
+ (which is nonnegative). If the capability is not mentioned in the
+ terminal description, `tgetnum' returns -1.
+
+`tgetflag'
+ Use `tgetflag' to get a boolean value. If the capability NAME is
+ present in the terminal description, `tgetflag' returns 1;
+ otherwise, it returns 0.
+
+`tgetstr'
+ Use `tgetstr' to get a string value. It returns a pointer to a
+ string which is the capability value, or a null pointer if the
+ capability is not present in the terminal description.
+
+ There are two ways `tgetstr' can find space to store the string
+ value:
+
+ * You can ask `tgetstr' to allocate the space. Pass a null
+ pointer for the argument AREA, and `tgetstr' will use
+ `malloc' to allocate storage big enough for the value.
+ Termcap will never free this storage or refer to it again; you
+ should free it when you are finished with it.
+
+ This method is more robust, since there is no need to guess
+ how much space is needed. But it is supported only by the GNU
+ termcap library.
+
+ * You can provide the space. Provide for the argument AREA the
+ address of a pointer variable of type `char *'. Before
+ calling `tgetstr', initialize the variable to point at
+ available space. Then `tgetstr' will store the string value
+ in that space and will increment the pointer variable to
+ point after the space that has been used. You can use the
+ same pointer variable for many calls to `tgetstr'.
+
+ There is no way to determine how much space is needed for a
+ single string, and no way for you to prevent or handle
+ overflow of the area you have provided. However, you can be
+ sure that the total size of all the string values you will
+ obtain from the terminal description is no greater than the
+ size of the description (unless you get the same capability
+ twice). You can determine that size with `strlen' on the
+ buffer you provided to `tgetent'. See below for an example.
+
+ Providing the space yourself is the only method supported by
+ the Unix version of termcap.
+
+ Note that you do not have to specify a terminal type or terminal
+description for the interrogation functions. They automatically use the
+description found by the most recent call to `tgetent'.
+
+ Here is an example of interrogating a terminal description for
+various capabilities, with conditionals to select between the Unix and
+GNU methods of providing buffer space.
+
+ char *tgetstr ();
+
+ char *cl_string, *cm_string;
+ int height;
+ int width;
+ int auto_wrap;
+
+ char PC; /* For tputs. */
+ char *BC; /* For tgoto. */
+ char *UP;
+
+ interrogate_terminal ()
+ {
+ #ifdef UNIX
+ /* Here we assume that an explicit term_buffer
+ was provided to tgetent. */
+ char *buffer
+ = (char *) malloc (strlen (term_buffer));
+ #define BUFFADDR &buffer
+ #else
+ #define BUFFADDR 0
+ #endif
+
+ char *temp;
+
+ /* Extract information we will use. */
+ cl_string = tgetstr ("cl", BUFFADDR);
+ cm_string = tgetstr ("cm", BUFFADDR);
+ auto_wrap = tgetflag ("am");
+ height = tgetnum ("li");
+ width = tgetnum ("co");
+
+ /* Extract information that termcap functions use. */
+ temp = tgetstr ("pc", BUFFADDR);
+ PC = temp ? *temp : 0;
+ BC = tgetstr ("le", BUFFADDR);
+ UP = tgetstr ("up", BUFFADDR);
+ }
+
+*Note Padding::, for information on the variable `PC'. *Note Using
+Parameters::, for information on `UP' and `BC'.
+
+\1f
+File: termcap.info, Node: Initialize, Next: Padding, Prev: Interrogate, Up: Library
+
+Initialization for Use of Termcap
+=================================
+
+ Before starting to output commands to a terminal using termcap, an
+application program should do two things:
+
+ * Initialize various global variables which termcap library output
+ functions refer to. These include `PC' and `ospeed' for padding
+ (*note Output Padding::.) and `UP' and `BC' for cursor motion
+ (*note tgoto::.).
+
+ * Tell the kernel to turn off alteration and padding of
+ horizontal-tab characters sent to the terminal.
+
+ To turn off output processing in Berkeley Unix you would use `ioctl'
+with code `TIOCLSET' to set the bit named `LLITOUT', and clear the bits
+`ANYDELAY' using `TIOCSETN'. In POSIX or System V, you must clear the
+bit named `OPOST'. Refer to the system documentation for details.
+
+ If you do not set the terminal flags properly, some older terminals
+will not work. This is because their commands may contain the
+characters that normally signify newline, carriage return and
+horizontal tab--characters which the kernel thinks it ought to modify
+before output.
+
+ When you change the kernel's terminal flags, you must arrange to
+restore them to their normal state when your program exits. This
+implies that the program must catch fatal signals such as `SIGQUIT' and
+`SIGINT' and restore the old terminal flags before actually terminating.
+
+ Modern terminals' commands do not use these special characters, so
+if you do not care about problems with old terminals, you can leave the
+kernel's terminal flags unaltered.
+
+\1f
+File: termcap.info, Node: Padding, Next: Parameters, Prev: Initialize, Up: Library
+
+Padding
+=======
+
+ "Padding" means outputting null characters following a terminal
+display command that takes a long time to execute. The terminal
+description says which commands require padding and how much; the
+function `tputs', described below, outputs a terminal command while
+extracting from it the padding information, and then outputs the
+padding that is necessary.
+
+* Menu:
+
+* Why Pad:: Explanation of padding.
+* Describe Padding:: The data base says how much padding a terminal needs.
+* Output Padding:: Using `tputs' to output the needed padding.
+
+\1f
+File: termcap.info, Node: Why Pad, Next: Describe Padding, Prev: Padding, Up: Padding
+
+Why Pad, and How
+----------------
+
+ Most types of terminal have commands that take longer to execute
+than they do to send over a high-speed line. For example, clearing the
+screen may take 20msec once the entire command is received. During
+that time, on a 9600 bps line, the terminal could receive about 20
+additional output characters while still busy clearing the screen.
+Every terminal has a certain amount of buffering capacity to remember
+output characters that cannot be processed yet, but too many slow
+commands in a row can cause the buffer to fill up. Then any additional
+output that cannot be processed immediately will be lost.
+
+ To avoid this problem, we normally follow each display command with
+enough useless charaters (usually null characters) to fill up the time
+that the display command needs to execute. This does the job if the
+terminal throws away null characters without using up space in the
+buffer (which most terminals do). If enough padding is used, no output
+can ever be lost. The right amount of padding avoids loss of output
+without slowing down operation, since the time used to transmit padding
+is time that nothing else could be done.
+
+ The number of padding characters needed for an operation depends on
+the line speed. In fact, it is proportional to the line speed. A 9600
+baud line transmits about one character per msec, so the clear screen
+command in the example above would need about 20 characters of padding.
+At 1200 baud, however, only about 3 characters of padding are needed
+to fill up 20msec.
+
+\1f
+File: termcap.info, Node: Describe Padding, Next: Output Padding, Prev: Why Pad, Up: Padding
+
+Specifying Padding in a Terminal Description
+--------------------------------------------
+
+ In the terminal description, the amount of padding required by each
+display command is recorded as a sequence of digits at the front of the
+command. These digits specify the padding time in msec. They can be
+followed optionally by a decimal point and one more digit, which is a
+number of tenths of msec.
+
+ Sometimes the padding needed by a command depends on the cursor
+position. For example, the time taken by an "insert line" command is
+usually proportional to the number of lines that need to be moved down
+or cleared. An asterisk (`*') following the padding time says that the
+time should be multiplied by the number of screen lines affected by the
+command.
+
+ :al=1.3*\E[L:
+
+is used to describe the "insert line" command for a certain terminal.
+The padding required is 1.3 msec per line affected. The command itself
+is `<ESC> [ L'.
+
+ The padding time specified in this way tells `tputs' how many pad
+characters to output. *Note Output Padding::.
+
+ Two special capability values affect padding for all commands.
+These are the `pc' and `pb'. The variable `pc' specifies the character
+to pad with, and `pb' the speed below which no padding is needed. The
+defaults for these variables, a null character and 0, are correct for
+most terminals. *Note Pad Specs::.
+
+\1f
+File: termcap.info, Node: Output Padding, Prev: Describe Padding, Up: Padding
+
+Performing Padding with `tputs'
+-------------------------------
+
+ Use the termcap function `tputs' to output a string containing an
+optional padding spec of the form described above (*note Describe
+Padding::.). The function `tputs' strips off and decodes the padding
+spec, outputs the rest of the string, and then outputs the appropriate
+padding. Here is its declaration in ANSI C:
+
+ char PC;
+ short ospeed;
+
+ int tputs (char *STRING, int NLINES, int (*OUTFUN) ());
+
+ Here STRING is the string (including padding spec) to be output;
+NLINES is the number of lines affected by the operation, which is used
+to multiply the amount of padding if the padding spec ends with a `*'.
+Finally, OUTFUN is a function (such as `fputchar') that is called to
+output each character. When actually called, OUTFUN should expect one
+argument, a character.
+
+ The operation of `tputs' is controlled by two global variables,
+`ospeed' and `PC'. The value of `ospeed' is supposed to be the
+terminal output speed, encoded as in the `ioctl' system call which gets
+the speed information. This is needed to compute the number of padding
+characters. The value of `PC' is the character used for padding.
+
+ You are responsible for storing suitable values into these variables
+before using `tputs'. The value stored into the `PC' variable should be
+taken from the `pc' capability in the terminal description (*note Pad
+Specs::.). Store zero in `PC' if there is no `pc' capability.
+
+ The argument NLINES requires some thought. Normally, it should be
+the number of lines whose contents will be cleared or moved by the
+command. For cursor motion commands, or commands that do editing
+within one line, use the value 1. For most commands that affect
+multiple lines, such as `al' (insert a line) and `cd' (clear from the
+cursor to the end of the screen), NLINES should be the screen height
+minus the current vertical position (origin 0). For multiple insert
+and scroll commands such as `AL' (insert multiple lines), that same
+value for NLINES is correct; the number of lines being inserted is not
+correct.
+
+ If a "scroll window" feature is used to reduce the number of lines
+affected by a command, the value of NLINES should take this into
+account. This is because the delay time required depends on how much
+work the terminal has to do, and the scroll window feature reduces the
+work. *Note Scrolling::.
+
+ Commands such as `ic' and `dc' (insert or delete characters) are
+problematical because the padding needed by these commands is
+proportional to the number of characters affected, which is the number
+of columns from the cursor to the end of the line. It would be nice to
+have a way to specify such a dependence, and there is no need for
+dependence on vertical position in these commands, so it is an obvious
+idea to say that for these commands NLINES should really be the number
+of columns affected. However, the definition of termcap clearly says
+that NLINES is always the number of lines affected, even in this case,
+where it is always 1. It is not easy to change this rule now, because
+too many programs and terminal descriptions have been written to follow
+it.
+
+ Because NLINES is always 1 for the `ic' and `dc' strings, there is
+no reason for them to use `*', but some of them do. These should be
+corrected by deleting the `*'. If, some day, such entries have
+disappeared, it may be possible to change to a more useful convention
+for the NLINES argument for these operations without breaking any
+programs.
+
+\1f
+File: termcap.info, Node: Parameters, Prev: Padding, Up: Library
+
+Filling In Parameters
+=====================
+
+ Some terminal control strings require numeric "parameters". For
+example, when you move the cursor, you need to say what horizontal and
+vertical positions to move it to. The value of the terminal's `cm'
+capability, which says how to move the cursor, cannot simply be a
+string of characters; it must say how to express the cursor position
+numbers and where to put them within the command.
+
+ The specifications of termcap include conventions as to which
+string-valued capabilities require parameters, how many parameters, and
+what the parameters mean; for example, it defines the `cm' string to
+take two parameters, the vertical and horizontal positions, with 0,0
+being the upper left corner. These conventions are described where the
+individual commands are documented.
+
+ Termcap also defines a language used within the capability
+definition for specifying how and where to encode the parameters for
+output. This language uses character sequences starting with `%'.
+(This is the same idea as `printf', but the details are different.)
+The language for parameter encoding is described in this section.
+
+ A program that is doing display output calls the functions `tparam'
+or `tgoto' to encode parameters according to the specifications. These
+functions produce a string containing the actual commands to be output
+(as well a padding spec which must be processed with `tputs'; *note
+Padding::.).
+
+* Menu:
+
+* Encode Parameters:: The language for encoding parameters.
+* Using Parameters:: Outputting a string command with parameters.
+
+\1f
+File: termcap.info, Node: Encode Parameters, Next: Using Parameters, Prev: Parameters, Up: Parameters
+
+Describing the Encoding
+-----------------------
+
+ A terminal command string that requires parameters contains special
+character sequences starting with `%' to say how to encode the
+parameters. These sequences control the actions of `tparam' and
+`tgoto'.
+
+ The parameters values passed to `tparam' or `tgoto' are considered
+to form a vector. A pointer into this vector determines the next
+parameter to be processed. Some of the `%'-sequences encode one
+parameter and advance the pointer to the next parameter. Other
+`%'-sequences alter the pointer or alter the parameter values without
+generating output.
+
+ For example, the `cm' string for a standard ANSI terminal is written
+as `\E[%i%d;%dH'. (`\E' stands for <ESC>.) `cm' by convention always
+requires two parameters, the vertical and horizontal goal positions, so
+this string specifies the encoding of two parameters. Here `%i'
+increments the two values supplied, and each `%d' encodes one of the
+values in decimal. If the cursor position values 20,58 are encoded
+with this string, the result is `\E[21;59H'.
+
+ First, here are the `%'-sequences that generate output. Except for
+`%%', each of them encodes one parameter and advances the pointer to
+the following parameter.
+
+`%%'
+ Output a single `%'. This is the only way to represent a literal
+ `%' in a terminal command with parameters. `%%' does not use up a
+ parameter.
+
+`%d'
+ As in `printf', output the next parameter in decimal.
+
+`%2'
+ Like `%02d' in `printf': output the next parameter in decimal, and
+ always use at least two digits.
+
+`%3'
+ Like `%03d' in `printf': output the next parameter in decimal, and
+ always use at least three digits. Note that `%4' and so on are
+ *not* defined.
+
+`%.'
+ Output the next parameter as a single character whose ASCII code is
+ the parameter value. Like `%c' in `printf'.
+
+`%+CHAR'
+ Add the next parameter to the character CHAR, and output the
+ resulting character. For example, `%+ ' represents 0 as a space,
+ 1 as `!', etc.
+
+ The following `%'-sequences specify alteration of the parameters
+(their values, or their order) rather than encoding a parameter for
+output. They generate no output; they are used only for their side
+effects on the parameters. Also, they do not advance the "next
+parameter" pointer except as explicitly stated. Only `%i', `%r' and
+`%>' are defined in standard Unix termcap. The others are GNU
+extensions.
+
+`%i'
+ Increment the next two parameters. This is used for terminals that
+ expect cursor positions in origin 1. For example, `%i%d,%d' would
+ output two parameters with `1' for 0, `2' for 1, etc.
+
+`%r'
+ Interchange the next two parameters. This is used for terminals
+ whose cursor positioning command expects the horizontal position
+ first.
+
+`%s'
+ Skip the next parameter. Do not output anything.
+
+`%b'
+ Back up one parameter. The last parameter used will become once
+ again the next parameter to be output, and the next output command
+ will use it. Using `%b' more than once, you can back up any
+ number of parameters, and you can refer to each parameter any
+ number of times.
+
+`%>C1C2'
+ Conditionally increment the next parameter. Here C1 and C2 are
+ characters which stand for their ASCII codes as numbers. If the
+ next parameter is greater than the ASCII code of C1, the ASCII
+ code of C2 is added to it.
+
+`%a OP TYPE POS'
+ Perform arithmetic on the next parameter, do not use it up, and do
+ not output anything. Here OP specifies the arithmetic operation,
+ while TYPE and POS together specify the other operand.
+
+ Spaces are used above to separate the operands for clarity; the
+ spaces don't appear in the data base, where this sequence is
+ exactly five characters long.
+
+ The character OP says what kind of arithmetic operation to
+ perform. It can be any of these characters:
+
+ `='
+ assign a value to the next parameter, ignoring its old value.
+ The new value comes from the other operand.
+
+ `+'
+ add the other operand to the next parameter.
+
+ `-'
+ subtract the other operand from the next parameter.
+
+ `*'
+ multiply the next parameter by the other operand.
+
+ `/'
+ divide the next parameter by the other operand.
+
+ The "other operand" may be another parameter's value or a constant;
+ the character TYPE says which. It can be:
+
+ `p'
+ Use another parameter. The character POS says which
+ parameter to use. Subtract 64 from its ASCII code to get the
+ position of the desired parameter relative to this one. Thus,
+ the character `A' as POS means the parameter after the next
+ one; the character `?' means the parameter before the next
+ one.
+
+ `c'
+ Use a constant value. The character POS specifies the value
+ of the constant. The 0200 bit is cleared out, so that 0200
+ can be used to represent zero.
+
+ The following `%'-sequences are special purpose hacks to compensate
+for the weird designs of obscure terminals. They modify the next
+parameter or the next two parameters but do not generate output and do
+not use up any parameters. `%m' is a GNU extension; the others are
+defined in standard Unix termcap.
+
+`%n'
+ Exclusive-or the next parameter with 0140, and likewise the
+ parameter after next.
+
+`%m'
+ Complement all the bits of the next parameter and the parameter
+ after next.
+
+`%B'
+ Encode the next parameter in BCD. It alters the value of the
+ parameter by adding six times the quotient of the parameter by ten.
+ Here is a C statement that shows how the new value is computed:
+
+ PARM = (PARM / 10) * 16 + PARM % 10;
+
+`%D'
+ Transform the next parameter as needed by Delta Data terminals.
+ This involves subtracting twice the remainder of the parameter by
+ 16.
+
+ PARM -= 2 * (PARM % 16);
+
+\1f
+File: termcap.info, Node: Using Parameters, Prev: Encode Parameters, Up: Parameters
+
+Sending Display Commands with Parameters
+----------------------------------------
+
+ The termcap library functions `tparam' and `tgoto' serve as the
+analog of `printf' for terminal string parameters. The newer function
+`tparam' is a GNU extension, more general but missing from Unix
+termcap. The original parameter-encoding function is `tgoto', which is
+preferable for cursor motion.
+
+* Menu:
+
+* tparam:: The general case, for GNU termcap only.
+* tgoto:: The special case of cursor motion.
+
+\1f
+File: termcap.info, Node: tparam, Next: tgoto, Prev: Using Parameters, Up: Using Parameters
+
+`tparam'
+........
+
+ The function `tparam' can encode display commands with any number of
+parameters and allows you to specify the buffer space. It is the
+preferred function for encoding parameters for all but the `cm'
+capability. Its ANSI C declaration is as follows:
+
+ char *tparam (char *CTLSTRING, char *BUFFER, int SIZE, int PARM1,...)
+
+ The arguments are a control string CTLSTRING (the value of a terminal
+capability, presumably), an output buffer BUFFER and SIZE, and any
+number of integer parameters to be encoded. The effect of `tparam' is
+to copy the control string into the buffer, encoding parameters
+according to the `%' sequences in the control string.
+
+ You describe the output buffer by its address, BUFFER, and its size
+in bytes, SIZE. If the buffer is not big enough for the data to be
+stored in it, `tparam' calls `malloc' to get a larger buffer. In
+either case, `tparam' returns the address of the buffer it ultimately
+uses. If the value equals BUFFER, your original buffer was used.
+Otherwise, a new buffer was allocated, and you must free it after you
+are done with printing the results. If you pass zero for SIZE and
+BUFFER, `tparam' always allocates the space with `malloc'.
+
+ All capabilities that require parameters also have the ability to
+specify padding, so you should use `tputs' to output the string
+produced by `tparam'. *Note Padding::. Here is an example.
+
+ {
+ char *buf;
+ char buffer[40];
+
+ buf = tparam (command, buffer, 40, parm);
+ tputs (buf, 1, fputchar);
+ if (buf != buffer)
+ free (buf);
+ }
+
+ If a parameter whose value is zero is encoded with `%.'-style
+encoding, the result is a null character, which will confuse `tputs'.
+This would be a serious problem, but luckily `%.' encoding is used only
+by a few old models of terminal, and only for the `cm' capability. To
+solve the problem, use `tgoto' rather than `tparam' to encode the `cm'
+capability.
+
+\1f
+File: termcap.info, Node: tgoto, Prev: tparam, Up: Using Parameters
+
+`tgoto'
+.......
+
+ The special case of cursor motion is handled by `tgoto'. There are
+two reasons why you might choose to use `tgoto':
+
+ * For Unix compatibility, because Unix termcap does not have
+ `tparam'.
+
+ * For the `cm' capability, since `tgoto' has a special feature to
+ avoid problems with null characters, tabs and newlines on certain
+ old terminal types that use `%.' encoding for that capability.
+
+ Here is how `tgoto' might be declared in ANSI C:
+
+ char *tgoto (char *CSTRING, int HPOS, int VPOS)
+
+ There are three arguments, the terminal description's `cm' string and
+the two cursor position numbers; `tgoto' computes the parametrized
+string in an internal static buffer and returns the address of that
+buffer. The next time you use `tgoto' the same buffer will be reused.
+
+ Parameters encoded with `%.' encoding can generate null characters,
+tabs or newlines. These might cause trouble: the null character because
+`tputs' would think that was the end of the string, the tab because the
+kernel or other software might expand it into spaces, and the newline
+becaue the kernel might add a carriage-return, or padding characters
+normally used for a newline. To prevent such problems, `tgoto' is
+careful to avoid these characters. Here is how this works: if the
+target cursor position value is such as to cause a problem (that is to
+say, zero, nine or ten), `tgoto' increments it by one, then compensates
+by appending a string to move the cursor back or up one position.
+
+ The compensation strings to use for moving back or up are found in
+global variables named `BC' and `UP'. These are actual external C
+variables with upper case names; they are declared `char *'. It is up
+to you to store suitable values in them, normally obtained from the
+`le' and `up' terminal capabilities in the terminal description with
+`tgetstr'. Alternatively, if these two variables are both zero, the
+feature of avoiding nulls, tabs and newlines is turned off.
+
+ It is safe to use `tgoto' for commands other than `cm' only if you
+have stored zero in `BC' and `UP'.
+
+ Note that `tgoto' reverses the order of its operands: the horizontal
+position comes before the vertical position in the arguments to
+`tgoto', even though the vertical position comes before the horizontal
+in the parameters of the `cm' string. If you use `tgoto' with a
+command such as `AL' that takes one parameter, you must pass the
+parameter to `tgoto' as the "vertical position".
+
+\1f
+File: termcap.info, Node: Data Base, Next: Capabilities, Prev: Library, Up: Top
+
+The Format of the Data Base
+***************************
+
+ The termcap data base of terminal descriptions is stored in the file
+`/etc/termcap'. It contains terminal descriptions, blank lines, and
+comments.
+
+ A terminal description starts with one or more names for the
+terminal type. The information in the description is a series of
+"capability names" and values. The capability names have standard
+meanings (*note Capabilities::.) and their values describe the terminal.
+
+* Menu:
+
+* Format:: Overall format of a terminal description.
+* Capability Format:: Format of capabilities within a description.
+* Naming:: Naming conventions for terminal types.
+* Inheriting:: Inheriting part of a description from
+ a related terminal type.
+
+\1f
+File: termcap.info, Node: Format, Next: Capability Format, Prev: Data Base, Up: Data Base
+
+Terminal Description Format
+===========================
+
+ Aside from comments (lines starting with `#', which are ignored),
+each nonblank line in the termcap data base is a terminal description.
+A terminal description is nominally a single line, but it can be split
+into multiple lines by inserting the two characters `\ newline'. This
+sequence is ignored wherever it appears in a description.
+
+ The preferred way to split the description is between capabilities:
+insert the four characters `: \ newline tab' immediately before any
+colon. This allows each sub-line to start with some indentation. This
+works because, after the `\ newline' are ignored, the result is `: tab
+:'; the first colon ends the preceding capability and the second colon
+starts the next capability. If you split with `\ newline' alone, you
+may not add any indentation after them.
+
+ Here is a real example of a terminal description:
+
+ dw|vt52|DEC vt52:\
+ :cr=^M:do=^J:nl=^J:bl=^G:\
+ :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
+ :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
+ :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
+
+ Each terminal description begins with several names for the terminal
+type. The names are separated by `|' characters, and a colon ends the
+last name. The first name should be two characters long; it exists
+only for the sake of very old Unix systems and is never used in modern
+systems. The last name should be a fully verbose name such as "DEC
+vt52" or "Ann Arbor Ambassador with 48 lines". The other names should
+include whatever the user ought to be able to specify to get this
+terminal type, such as `vt52' or `aaa-48'. *Note Naming::, for
+information on how to choose terminal type names.
+
+ After the terminal type names come the terminal capabilities,
+separated by colons and with a colon after the last one. Each
+capability has a two-letter name, such as `cm' for "cursor motion
+string" or `li' for "number of display lines".
+
+\1f
+File: termcap.info, Node: Capability Format, Next: Naming, Prev: Format, Up: Data Base
+
+Writing the Capabilities
+========================
+
+ There are three kinds of capabilities: flags, numbers, and strings.
+Each kind has its own way of being written in the description. Each
+defined capability has by convention a particular kind of value; for
+example, `li' always has a numeric value and `cm' always a string value.
+
+ A flag capability is thought of as having a boolean value: the value
+is true if the capability is present, false if not. When the
+capability is present, just write its name between two colons.
+
+ A numeric capability has a value which is a nonnegative number.
+Write the capability name, a `#', and the number, between two colons.
+For example, `...:li#48:...' is how you specify the `li' capability for
+48 lines.
+
+ A string-valued capability has a value which is a sequence of
+characters. Usually these are the characters used to perform some
+display operation. Write the capability name, a `=', and the
+characters of the value, between two colons. For example,
+`...:cm=\E[%i%d;%dH:...' is how the cursor motion command for a
+standard ANSI terminal would be specified.
+
+ Special characters in the string value can be expressed using
+`\'-escape sequences as in C; in addition, `\E' stands for <ESC>. `^'
+is also a kind of escape character; `^' followed by CHAR stands for the
+control-equivalent of CHAR. Thus, `^a' stands for the character
+control-a, just like `\001'. `\' and `^' themselves can be represented
+as `\\' and `\^'.
+
+ To include a colon in the string, you must write `\072'. You might
+ask, "Why can't `\:' be used to represent a colon?" The reason is that
+the interrogation functions do not count slashes while looking for a
+capability. Even if `:ce=ab\:cd:' were interpreted as giving the `ce'
+capability the value `ab:cd', it would also appear to define `cd' as a
+flag.
+
+ The string value will often contain digits at the front to specify
+padding (*note Padding::.) and/or `%'-sequences within to specify how
+to encode parameters (*note Parameters::.). Although these things are
+not to be output literally to the terminal, they are considered part of
+the value of the capability. They are special only when the string
+value is processed by `tputs', `tparam' or `tgoto'. By contrast, `\'
+and `^' are considered part of the syntax for specifying the characters
+in the string.
+
+ Let's look at the VT52 example again:
+
+ dw|vt52|DEC vt52:\
+ :cr=^M:do=^J:nl=^J:bl=^G:\
+ :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
+ :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
+ :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
+
+ Here we see the numeric-valued capabilities `co' and `li', the flags
+`bs' and `pt', and many string-valued capabilities. Most of the
+strings start with <ESC> represented as `\E'. The rest contain control
+characters represented using `^'. The meanings of the individual
+capabilities are defined elsewhere (*note Capabilities::.).
+
+\1f
+File: termcap.info, Node: Naming, Next: Inheriting, Prev: Capability Format, Up: Data Base
+
+Terminal Type Name Conventions
+==============================
+
+ There are conventions for choosing names of terminal types. For one
+thing, all letters should be in lower case. The terminal type for a
+terminal in its most usual or most fundamental mode of operation should
+not have a hyphen in it.
+
+ If the same terminal has other modes of operation which require
+different terminal descriptions, these variant descriptions are given
+names made by adding suffixes with hyphens. Such alternate descriptions
+are used for two reasons:
+
+ * When the terminal has a switch that changes its behavior. Since
+ the computer cannot tell how the switch is set, the user must tell
+ the computer by choosing the appropriate terminal type name.
+
+ For example, the VT-100 has a setup flag that controls whether the
+ cursor wraps at the right margin. If this flag is set to "wrap",
+ you must use the terminal type `vt100-am'. Otherwise you must use
+ `vt100-nam'. Plain `vt100' is defined as a synonym for either
+ `vt100-am' or `vt100-nam' depending on the preferences of the
+ local site.
+
+ The standard suffix `-am' stands for "automatic margins".
+
+ * To give the user a choice in how to use the terminal. This is done
+ when the terminal has a switch that the computer normally controls.
+
+ For example, the Ann Arbor Ambassador can be configured with many
+ screen sizes ranging from 20 to 60 lines. Fewer lines make bigger
+ characters but more lines let you see more of what you are editing.
+ As a result, users have different preferences. Therefore, termcap
+ provides terminal types for many screen sizes. If you choose type
+ `aaa-30', the terminal will be configured to use 30 lines; if you
+ choose `aaa-48', 48 lines will be used, and so on.
+
+ Here is a list of standard suffixes and their conventional meanings:
+
+`-w'
+ Short for "wide". This is a mode that gives the terminal more
+ columns than usual. This is normally a user option.
+
+`-am'
+ "Automatic margins". This is an alternate description for use when
+ the terminal's margin-wrap switch is on; it contains the `am'
+ flag. The implication is that normally the switch is off and the
+ usual description for the terminal says that the switch is off.
+
+`-nam'
+ "No automatic margins". The opposite of `-am', this names an
+ alternative description which lacks the `am' flag. This implies
+ that the terminal is normally operated with the margin-wrap switch
+ turned on, and the normal description of the terminal says so.
+
+`-na'
+ "No arrows". This terminal description initializes the terminal to
+ keep its arrow keys in local mode. This is a user option.
+
+`-rv'
+ "Reverse video". This terminal description causes text output for
+ normal video to appear as reverse, and text output for reverse
+ video to come out as normal. Often this description differs from
+ the usual one by interchanging the two strings which turn reverse
+ video on and off.
+
+ This is a user option; you can choose either the "reverse video"
+ variant terminal type or the normal terminal type, and termcap will
+ obey.
+
+`-s'
+ "Status". Says to enable use of a status line which ordinary
+ output does not touch (*note Status Line::.).
+
+ Some terminals have a special line that is used only as a status
+ line. For these terminals, there is no need for an `-s' variant;
+ the status line commands should be defined by default. On other
+ terminals, enabling a status line means removing one screen line
+ from ordinary use and reducing the effective screen height. For
+ these terminals, the user can choose the `-s' variant type to
+ request use of a status line.
+
+`-NLINES'
+ Says to operate with NLINES lines on the screen, for terminals
+ such as the Ambassador which provide this as an option. Normally
+ this is a user option; by choosing the terminal type, you control
+ how many lines termcap will use.
+
+`-NPAGESp'
+ Says that the terminal has NPAGES pages worth of screen memory,
+ for terminals where this is a hardware option.
+
+`-unk'
+ Says that description is not for direct use, but only for
+ reference in `tc' capabilities. Such a description is a kind of
+ subroutine, because it describes the common characteristics of
+ several variant descriptions that would use other suffixes in
+ place of `-unk'.
+
+\1f
+File: termcap.info, Node: Inheriting, Prev: Naming, Up: Data Base
+
+Inheriting from Related Descriptions
+====================================
+
+ When two terminal descriptions are similar, their identical parts do
+not need to be given twice. Instead, one of the two can be defined in
+terms of the other, using the `tc' capability. We say that one
+description "refers to" the other, or "inherits from" the other.
+
+ The `tc' capability must be the last one in the terminal description,
+and its value is a string which is the name of another terminal type
+which is referred to. For example,
+
+ N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
+ :ti=\E[2J\E[30;0;0;30p:\
+ :te=\E[60;0;0;30p\E[30;1H\E[J:\
+ :li#30:tc=aaa-unk:
+
+defines the terminal type `aaa-30' (also known as plain `aaa') in terms
+of `aaa-unk', which defines everything about the Ambassador that is
+independent of screen height. The types `aaa-36', `aaa-48' and so on
+for other screen heights are likewise defined to inherit from `aaa-unk'.
+
+ The capabilities overridden by `aaa-30' include `li', which says how
+many lines there are, and `ti' and `te', which configure the terminal
+to use that many lines.
+
+ The effective terminal description for type `aaa' consists of the
+text shown above followed by the text of the description of `aaa-unk'.
+The `tc' capability is handled automatically by `tgetent', which finds
+the description thus referenced and combines the two descriptions
+(*note Find::.). Therefore, only the implementor of the terminal
+descriptions needs to think about using `tc'. Users and application
+programmers do not need to be concerned with it.
+
+ Since the reference terminal description is used last, capabilities
+specified in the referring description override any specifications of
+the same capabilities in the reference description.
+
+ The referring description can cancel out a capability without
+specifying any new value for it by means of a special trick. Write the
+capability in the referring description, with the character `@' after
+the capability name, as follows:
+
+ NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
+ :am@:tc=aaa-30:
+
--- /dev/null
+This is Info file ../info/termcap.info, produced by Makeinfo version
+1.68 from the input file termcap.texi.
+
+START-INFO-DIR-ENTRY
+* Termcap: (termcap). Termcap library of the GNU system.
+END-INFO-DIR-ENTRY
+
+ This file documents the termcap library of the GNU system.
+
+ Copyright (C) 1988 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+\1f
+File: termcap.info, Node: Capabilities, Next: Summary, Prev: Data Base, Up: Top
+
+Definitions of the Terminal Capabilities
+****************************************
+
+ This section is divided into many subsections, each for one aspect of
+use of display terminals. For writing a display program, you usually
+need only check the subsections for the operations you want to use.
+For writing a terminal description, you must read each subsection and
+fill in the capabilities described there.
+
+ String capabilities that are display commands may require numeric
+parameters (*note Parameters::.). Most such capabilities do not use
+parameters. When a capability requires parameters, this is explicitly
+stated at the beginning of its definition. In simple cases, the first
+or second sentence of the definition mentions all the parameters, in
+the order they should be given, using a name in upper case for each
+one. For example, the `rp' capability is a command that requires two
+parameters; its definition begins as follows:
+
+ String of commands to output a graphic character C, repeated N
+ times.
+
+ In complex cases or when there are many parameters, they are
+described explicitly.
+
+ When a capability is described as obsolete, this means that programs
+should not be written to look for it, but terminal descriptions should
+still be written to provide it.
+
+ When a capability is described as very obsolete, this means that it
+should be omitted from terminal descriptions as well.
+
+* Menu:
+
+* Basic:: Basic characteristics.
+* Screen Size:: Screen size, and what happens when it changes.
+* Cursor Motion:: Various ways to move the cursor.
+* Scrolling:: Pushing text up and down on the screen.
+* Wrapping:: What happens if you write a character in the last column.
+* Windows:: Limiting the part of the window that output affects.
+* Clearing:: Erasing one or many lines.
+* Insdel Line:: Making new blank lines in mid-screen; deleting lines.
+* Insdel Char:: Inserting and deleting characters within a line.
+* Standout:: Highlighting some of the text.
+* Underlining:: Underlining some of the text.
+* Cursor Visibility:: Making the cursor more or less easy to spot.
+* Bell:: Attracts user's attention; not localized on the screen.
+* Keypad:: Recognizing when function keys or arrows are typed.
+* Meta Key:: <META> acts like an extra shift key.
+* Initialization:: Commands used to initialize or reset the terminal.
+* Pad Specs:: Info for the kernel on how much padding is needed.
+* Status Line:: A status line displays "background" information.
+* Half-Line:: Moving by half-lines, for superscripts and subscripts.
+* Printer:: Controlling auxiliary printers of display terminals.
+
+\1f
+File: termcap.info, Node: Basic, Next: Screen Size, Prev: Capabilities, Up: Capabilities
+
+Basic Characteristics
+=====================
+
+ This section documents the capabilities that describe the basic and
+nature of the terminal, and also those that are relevant to the output
+of graphic characters.
+
+`os'
+ Flag whose presence means that the terminal can overstrike. This
+ means that outputting a graphic character does not erase whatever
+ was present in the same character position before. The terminals
+ that can overstrike include printing terminals, storage tubes (all
+ obsolete nowadays), and many bit-map displays.
+
+`eo'
+ Flag whose presence means that outputting a space can erase an
+ overstrike. If this is not present and overstriking is supported,
+ output of a space has no effect except to move the cursor.
+
+`gn'
+ Flag whose presence means that this terminal type is a generic type
+ which does not really describe any particular terminal. Generic
+ types are intended for use as the default type assigned when the
+ user connects to the system, with the intention that the user
+ should specify what type he really has. One example of a generic
+ type is the type `network'.
+
+ Since the generic type cannot say how to do anything interesting
+ with the terminal, termcap-using programs will always find that the
+ terminal is too weak to be supported if the user has failed to
+ specify a real terminal type in place of the generic one. The
+ `gn' flag directs these programs to use a different error message:
+ "You have not specified your real terminal type", rather than
+ "Your terminal is not powerful enough to be used".
+
+`hc'
+ Flag whose presence means this is a hardcopy terminal.
+
+`rp'
+ String of commands to output a graphic character C, repeated N
+ times. The first parameter value is the ASCII code for the desired
+ character, and the second parameter is the number of times to
+ repeat the character. Often this command requires padding
+ proportional to the number of times the character is repeated.
+ This effect can be had by using parameter arithmetic with
+ `%'-sequences to compute the amount of padding, then generating
+ the result as a number at the front of the string so that `tputs'
+ will treat it as padding.
+
+`hz'
+ Flag whose presence means that the ASCII character `~' cannot be
+ output on this terminal because it is used for display commands.
+
+ Programs handle this flag by checking all text to be output and
+ replacing each `~' with some other character(s). If this is not
+ done, the screen will be thoroughly garbled.
+
+ The old Hazeltine terminals that required such treatment are
+ probably very rare today, so you might as well not bother to
+ support this flag.
+
+`CC'
+ String whose presence means the terminal has a settable command
+ character. The value of the string is the default command
+ character (which is usually <ESC>).
+
+ All the strings of commands in the terminal description should be
+ written to use the default command character. If you are writing
+ an application program that changes the command character, use the
+ `CC' capability to figure out how to translate all the display
+ commands to work with the new command character.
+
+ Most programs have no reason to look at the `CC' capability.
+
+`xb'
+ Flag whose presence identifies Superbee terminals which are unable
+ to transmit the characters <ESC> and `Control-C'. Programs which
+ support this flag are supposed to check the input for the code
+ sequences sent by the <F1> and <F2> keys, and pretend that <ESC>
+ or `Control-C' (respectively) had been read. But this flag is
+ obsolete, and not worth supporting.
+
+\1f
+File: termcap.info, Node: Screen Size, Next: Cursor Motion, Prev: Basic, Up: Capabilities
+
+Screen Size
+===========
+
+ A terminal description has two capabilities, `co' and `li', that
+describe the screen size in columns and lines. But there is more to
+the question of screen size than this.
+
+ On some operating systems the "screen" is really a window and the
+effective width can vary. On some of these systems, `tgetnum' uses the
+actual width of the window to decide what value to return for the `co'
+capability, overriding what is actually written in the terminal
+description. On other systems, it is up to the application program to
+check the actual window width using a system call. For example, on BSD
+4.3 systems, the system call `ioctl' with code `TIOCGWINSZ' will tell
+you the current screen size.
+
+ On all window systems, termcap is powerless to advise the application
+program if the user resizes the window. Application programs must deal
+with this possibility in a system-dependent fashion. On some systems
+the C shell handles part of the problem by detecting changes in window
+size and setting the `TERMCAP' environment variable appropriately.
+This takes care of application programs that are started subsequently.
+It does not help application programs already running.
+
+ On some systems, including BSD 4.3, all programs using a terminal get
+a signal named `SIGWINCH' whenever the screen size changes. Programs
+that use termcap should handle this signal by using `ioctl TIOCGWINSZ'
+to learn the new screen size.
+
+`co'
+ Numeric value, the width of the screen in character positions.
+ Even hardcopy terminals normally have a `co' capability.
+
+`li'
+ Numeric value, the height of the screen in lines.
+
+\1f
+File: termcap.info, Node: Cursor Motion, Next: Wrapping, Prev: Screen Size, Up: Capabilities
+
+Cursor Motion
+=============
+
+ Termcap assumes that the terminal has a "cursor", a spot on the
+screen where a visible mark is displayed, and that most display
+commands take effect at the position of the cursor. It follows that
+moving the cursor to a specified location is very important.
+
+ There are many terminal capabilities for different cursor motion
+operations. A terminal description should define as many as possible,
+but most programs do not need to use most of them. One capability,
+`cm', moves the cursor to an arbitrary place on the screen; this by
+itself is sufficient for any application as long as there is no need to
+support hardcopy terminals or certain old, weak displays that have only
+relative motion commands. Use of other cursor motion capabilities is an
+optimization, enabling the program to output fewer characters in some
+common cases.
+
+ If you plan to use the relative cursor motion commands in an
+application program, you must know what the starting cursor position
+is. To do this, you must keep track of the cursor position and update
+the records each time anything is output to the terminal, including
+graphic characters. In addition, it is necessary to know whether the
+terminal wraps after writing in the rightmost column. *Note Wrapping::.
+
+ One other motion capability needs special mention: `nw' moves the
+cursor to the beginning of the following line, perhaps clearing all the
+starting line after the cursor, or perhaps not clearing at all. This
+capability is a least common denominator that is probably supported
+even by terminals that cannot do most other things such as `cm' or `do'.
+Even hardcopy terminals can support `nw'.
+
+`cm'
+ String of commands to position the cursor at line L, column C.
+ Both parameters are origin-zero, and are defined relative to the
+ screen, not relative to display memory.
+
+ All display terminals except a few very obsolete ones support `cm',
+ so it is acceptable for an application program to refuse to
+ operate on terminals lacking `cm'.
+
+`ho'
+ String of commands to move the cursor to the upper left corner of
+ the screen (this position is called the "home position"). In
+ terminals where the upper left corner of the screen is not the
+ same as the beginning of display memory, this command must go to
+ the upper left corner of the screen, not the beginning of display
+ memory.
+
+ Every display terminal supports this capability, and many
+ application programs refuse to operate if the `ho' capability is
+ missing.
+
+`ll'
+ String of commands to move the cursor to the lower left corner of
+ the screen. On some terminals, moving up from home position does
+ this, but programs should never assume that will work. Just
+ output the `ll' string (if it is provided); if moving to home
+ position and then moving up is the best way to get there, the `ll'
+ command will do that.
+
+`cr'
+ String of commands to move the cursor to the beginning of the line
+ it is on. If this capability is not specified, many programs
+ assume they can use the ASCII carriage return character for this.
+
+`le'
+ String of commands to move the cursor left one column. Unless the
+ `bw' flag capability is specified, the effect is undefined if the
+ cursor is at the left margin; do not use this command there. If
+ `bw' is present, this command may be used at the left margin, and
+ it wraps the cursor to the last column of the preceding line.
+
+`nd'
+ String of commands to move the cursor right one column. The
+ effect is undefined if the cursor is at the right margin; do not
+ use this command there, not even if `am' is present.
+
+`up'
+ String of commands to move the cursor vertically up one line. The
+ effect of sending this string when on the top line is undefined;
+ programs should never use it that way.
+
+`do'
+ String of commands to move the cursor vertically down one line.
+ The effect of sending this string when on the bottom line is
+ undefined; programs should never use it that way.
+
+ The original idea was that this string would not contain a newline
+ character and therefore could be used without disabling the
+ kernel's usual habit of converting of newline into a
+ carriage-return newline sequence. But many terminal descriptions
+ do use newline in the `do' string, so this is not possible; a
+ program which sends the `do' string must disable output conversion
+ in the kernel (*note Initialize::.).
+
+`bw'
+ Flag whose presence says that `le' may be used in column zero to
+ move to the last column of the preceding line. If this flag is
+ not present, `le' should not be used in column zero.
+
+`nw'
+ String of commands to move the cursor to start of next line,
+ possibly clearing rest of line (following the cursor) before
+ moving.
+
+`DO', `UP', `LE', `RI'
+ Strings of commands to move the cursor N lines down vertically, up
+ vertically, or N columns left or right. Do not attempt to move
+ past any edge of the screen with these commands; the effect of
+ trying that is undefined. Only a few terminal descriptions provide
+ these commands, and most programs do not use them.
+
+`CM'
+ String of commands to position the cursor at line L, column C,
+ relative to display memory. Both parameters are origin-zero.
+ This capability is present only in terminals where there is a
+ difference between screen-relative and memory-relative addressing,
+ and not even in all such terminals.
+
+`ch'
+ String of commands to position the cursor at column C in the same
+ line it is on. This is a special case of `cm' in which the
+ vertical position is not changed. The `ch' capability is provided
+ only when it is faster to output than `cm' would be in this
+ special case. Programs should not assume most display terminals
+ have `ch'.
+
+`cv'
+ String of commands to position the cursor at line L in the same
+ column. This is a special case of `cm' in which the horizontal
+ position is not changed. The `cv' capability is provided only
+ when it is faster to output than `cm' would be in this special
+ case. Programs should not assume most display terminals have `cv'.
+
+`sc'
+ String of commands to make the terminal save the current cursor
+ position. Only the last saved position can be used. If this
+ capability is present, `rc' should be provided also. Most
+ terminals have neither.
+
+`rc'
+ String of commands to make the terminal restore the last saved
+ cursor position. If this capability is present, `sc' should be
+ provided also. Most terminals have neither.
+
+`ff'
+ String of commands to advance to the next page, for a hardcopy
+ terminal.
+
+`ta'
+ String of commands to move the cursor right to the next hardware
+ tab stop column. Missing if the terminal does not have any kind of
+ hardware tabs. Do not send this command if the kernel's terminal
+ modes say that the kernel is expanding tabs into spaces.
+
+`bt'
+ String of commands to move the cursor left to the previous hardware
+ tab stop column. Missing if the terminal has no such ability; many
+ terminals do not. Do not send this command if the kernel's
+ terminal modes say that the kernel is expanding tabs into spaces.
+
+ The following obsolete capabilities should be included in terminal
+descriptions when appropriate, but should not be looked at by new
+programs.
+
+`nc'
+ Flag whose presence means the terminal does not support the ASCII
+ carriage return character as `cr'. This flag is needed because
+ old programs assume, when the `cr' capability is missing, that
+ ASCII carriage return can be used for the purpose. We use `nc' to
+ tell the old programs that carriage return may not be used.
+
+ New programs should not assume any default for `cr', so they need
+ not look at `nc'. However, descriptions should contain `nc'
+ whenever they do not contain `cr'.
+
+`xt'
+ Flag whose presence means that the ASCII tab character may not be
+ used for cursor motion. This flag exists because old programs
+ assume, when the `ta' capability is missing, that ASCII tab can be
+ used for the purpose. We use `xt' to tell the old programs not to
+ use tab.
+
+ New programs should not assume any default for `ta', so they need
+ not look at `xt' in connection with cursor motion. Note that `xt'
+ also has implications for standout mode (*note Standout::.). It
+ is obsolete in regard to cursor motion but not in regard to
+ standout.
+
+ In fact, `xt' means that the terminal is a Teleray 1061.
+
+`bc'
+ Very obsolete alternative name for the `le' capability.
+
+`bs'
+ Flag whose presence means that the ASCII character backspace may be
+ used to move the cursor left. Obsolete; look at `le' instead.
+
+`nl'
+ Obsolete capability which is a string that can either be used to
+ move the cursor down or to scroll. The same string must scroll
+ when used on the bottom line and move the cursor when used on any
+ other line. New programs should use `do' or `sf', and ignore `nl'.
+
+ If there is no `nl' capability, some old programs assume they can
+ use the newline character for this purpose. These programs follow
+ a bad practice, but because they exist, it is still desirable to
+ define the `nl' capability in a terminal description if the best
+ way to move down is *not* a newline.
+
+\1f
+File: termcap.info, Node: Wrapping, Next: Scrolling, Prev: Cursor Motion, Up: Capabilities
+
+Wrapping
+========
+
+ "Wrapping" means moving the cursor from the right margin to the left
+margin of the following line. Some terminals wrap automatically when a
+graphic character is output in the last column, while others do not.
+Most application programs that use termcap need to know whether the
+terminal wraps. There are two special flag capabilities to describe
+what the terminal does when a graphic character is output in the last
+column.
+
+`am'
+ Flag whose presence means that writing a character in the last
+ column causes the cursor to wrap to the beginning of the next line.
+
+ If `am' is not present, writing in the last column leaves the
+ cursor at the place where the character was written.
+
+ Writing in the last column of the last line should be avoided on
+ terminals with `am', as it may or may not cause scrolling to occur
+ (*note Scrolling::.). Scrolling is surely not what you would
+ intend.
+
+ If your program needs to check the `am' flag, then it also needs
+ to check the `xn' flag which indicates that wrapping happens in a
+ strange way. Many common terminals have the `xn' flag.
+
+`xn'
+ Flag whose presence means that the cursor wraps in a strange way.
+ At least two distinct kinds of strange behavior are known; the
+ termcap data base does not contain anything to distinguish the two.
+
+ On Concept-100 terminals, output in the last column wraps the
+ cursor almost like an ordinary `am' terminal. But if the next
+ thing output is a newline, it is ignored.
+
+ DEC VT-100 terminals (when the wrap switch is on) do a different
+ strange thing: the cursor wraps only if the next thing output is
+ another graphic character. In fact, the wrap occurs when the
+ following graphic character is received by the terminal, before the
+ character is placed on the screen.
+
+ On both of these terminals, after writing in the last column a
+ following graphic character will be displayed in the first column
+ of the following line. But the effect of relative cursor motion
+ characters such as newline or backspace at such a time depends on
+ the terminal. The effect of erase or scrolling commands also
+ depends on the terminal. You can't assume anything about what
+ they will do on a terminal that has `xn'. So, to be safe, you
+ should never do these things at such a time on such a terminal.
+
+ To be sure of reliable results on a terminal which has the `xn'
+ flag, output a `cm' absolute positioning command after writing in
+ the last column. Another safe thing to do is to output
+ carriage-return newline, which will leave the cursor at the
+ beginning of the following line.
+
+\1f
+File: termcap.info, Node: Scrolling, Next: Windows, Prev: Wrapping, Up: Capabilities
+
+Scrolling
+=========
+
+ "Scrolling" means moving the contents of the screen up or down one or
+more lines. Moving the contents up is "forward scrolling"; moving them
+down is "reverse scrolling".
+
+ Scrolling happens after each line of output during ordinary output
+on most display terminals. But in an application program that uses
+termcap for random-access output, scrolling happens only when
+explicitly requested with the commands in this section.
+
+ Some terminals have a "scroll region" feature. This lets you limit
+the effect of scrolling to a specified range of lines. Lines outside
+the range are unaffected when scrolling happens. The scroll region
+feature is available if either `cs' or `cS' is present.
+
+`sf'
+ String of commands to scroll the screen one line up, assuming it is
+ output with the cursor at the beginning of the bottom line.
+
+`sr'
+ String of commands to scroll the screen one line down, assuming it
+ is output with the cursor at the beginning of the top line.
+
+`SF'
+ String of commands to scroll the screen N lines up, assuming it is
+ output with the cursor at the beginning of the bottom line.
+
+`SR'
+ String of commands to scroll the screen N line down, assuming it
+ is output with the cursor at the beginning of the top line.
+
+`cs'
+ String of commands to set the scroll region. This command takes
+ two parameters, START and END, which are the line numbers
+ (origin-zero) of the first line to include in the scroll region
+ and of the last line to include in it. When a scroll region is
+ set, scrolling is limited to the specified range of lines; lines
+ outside the range are not affected by scroll commands.
+
+ Do not try to move the cursor outside the scroll region. The
+ region remains set until explicitly removed. To remove the scroll
+ region, use another `cs' command specifying the full height of the
+ screen.
+
+ The cursor position is undefined after the `cs' command is set, so
+ position the cursor with `cm' immediately afterward.
+
+`cS'
+ String of commands to set the scroll region using parameters in
+ different form. The effect is the same as if `cs' were used.
+ Four parameters are required:
+
+ 1. Total number of lines on the screen.
+
+ 2. Number of lines above desired scroll region.
+
+ 3. Number of lines below (outside of) desired scroll region.
+
+ 4. Total number of lines on the screen, the same as the first
+ parameter.
+
+ This capability is a GNU extension that was invented to allow the
+ Ann Arbor Ambassador's scroll-region command to be described; it
+ could also be done by putting non-Unix `%'-sequences into a `cs'
+ string, but that would have confused Unix programs that used the
+ `cs' capability with the Unix termcap. Currently only GNU Emacs
+ uses the `cS' capability.
+
+`ns'
+ Flag which means that the terminal does not normally scroll for
+ ordinary sequential output. For modern terminals, this means that
+ outputting a newline in ordinary sequential output with the cursor
+ on the bottom line wraps to the top line. For some obsolete
+ terminals, other things may happen.
+
+ The terminal may be able to scroll even if it does not normally do
+ so. If the `sf' capability is provided, it can be used for
+ scrolling regardless of `ns'.
+
+`da'
+ Flag whose presence means that lines scrolled up off the top of the
+ screen may come back if scrolling down is done subsequently.
+
+ The `da' and `db' flags do not, strictly speaking, affect how to
+ scroll. But programs that scroll usually need to clear the lines
+ scrolled onto the screen, if these flags are present.
+
+`db'
+ Flag whose presence means that lines scrolled down off the bottom
+ of the screen may come back if scrolling up is done subsequently.
+
+`lm'
+ Numeric value, the number of lines of display memory that the
+ terminal has. A value of zero means that the terminal has more
+ display memory than can fit on the screen, but no fixed number of
+ lines. (The number of lines may depend on the amount of text in
+ each line.)
+
+ Any terminal description that defines `SF' should also define `sf';
+likewise for `SR' and `sr'. However, many terminals can only scroll by
+one line at a time, so it is common to find `sf' and not `SF', or `sr'
+without `SR'.
+
+ Therefore, all programs that use the scrolling facilities should be
+prepared to work with `sf' in the case that `SF' is absent, and
+likewise with `sr'. On the other hand, an application program that
+uses only `sf' and not `SF' is acceptable, though slow on some
+terminals.
+
+ When outputting a scroll command with `tputs', the NLINES argument
+should be the total number of lines in the portion of the screen being
+scrolled. Very often these commands require padding proportional to
+this number of lines. *Note Padding::.
+
+\1f
+File: termcap.info, Node: Windows, Next: Clearing, Prev: Scrolling, Up: Capabilities
+
+Windows
+=======
+
+ A "window", in termcap, is a rectangular portion of the screen to
+which all display operations are restricted. Wrapping, clearing,
+scrolling, insertion and deletion all operate as if the specified
+window were all the screen there was.
+
+`wi'
+ String of commands to set the terminal output screen window. This
+ string requires four parameters, all origin-zero:
+ 1. The first line to include in the window.
+
+ 2. The last line to include in the window.
+
+ 3. The first column to include in the window.
+
+ 4. The last column to include in the window.
+
+ Most terminals do not support windows.
+
+\1f
+File: termcap.info, Node: Clearing, Next: Insdel Line, Prev: Windows, Up: Capabilities
+
+Clearing Parts of the Screen
+============================
+
+ There are several terminal capabilities for clearing parts of the
+screen to blank. All display terminals support the `cl' string, and
+most display terminals support all of these capabilities.
+
+`cl'
+ String of commands to clear the entire screen and position the
+ cursor at the upper left corner.
+
+`cd'
+ String of commands to clear the line the cursor is on, and all the
+ lines below it, down to the bottom of the screen. This command
+ string should be used only with the cursor in column zero; their
+ effect is undefined if the cursor is elsewhere.
+
+`ce'
+ String of commands to clear from the cursor to the end of the
+ current line.
+
+`ec'
+ String of commands to clear N characters, starting with the
+ character that the cursor is on. This command string is expected
+ to leave the cursor position unchanged. The parameter N should
+ never be large enough to reach past the right margin; the effect
+ of such a large parameter would be undefined.
+
+ Clear to end of line (`ce') is extremely important in programs that
+maintain an updating display. Nearly all display terminals support this
+operation, so it is acceptable for a an application program to refuse to
+work if `ce' is not present. However, if you do not want this
+limitation, you can accomplish clearing to end of line by outputting
+spaces until you reach the right margin. In order to do this, you must
+know the current horizontal position. Also, this technique assumes
+that writing a space will erase. But this happens to be true on all
+the display terminals that fail to support `ce'.
+
+\1f
+File: termcap.info, Node: Insdel Line, Next: Insdel Char, Prev: Clearing, Up: Capabilities
+
+Insert/Delete Line
+==================
+
+ "Inserting a line" means creating a blank line in the middle of the
+screen, and pushing the existing lines of text apart. In fact, the
+lines above the insertion point do not change, while the lines below
+move down, and one is normally lost at the bottom of the screen.
+
+ "Deleting a line" means causing the line to disappear from the
+screen, closing up the gap by moving the lines below it upward. A new
+line appears at the bottom of the screen. Usually this line is blank,
+but on terminals with the `db' flag it may be a line previously moved
+off the screen bottom by scrolling or line insertion.
+
+ Insertion and deletion of lines is useful in programs that maintain
+an updating display some parts of which may get longer or shorter.
+They are also useful in editors for scrolling parts of the screen, and
+for redisplaying after lines of text are killed or inserted.
+
+ Many terminals provide commands to insert or delete a single line at
+the cursor position. Some provide the ability to insert or delete
+several lines with one command, using the number of lines to insert or
+delete as a parameter. Always move the cursor to column zero before
+using any of these commands.
+
+`al'
+ String of commands to insert a blank line before the line the
+ cursor is on. The existing line, and all lines below it, are
+ moved down. The last line in the screen (or in the scroll region,
+ if one is set) disappears and in most circumstances is discarded.
+ It may not be discarded if the `db' is present (*note
+ Scrolling::.).
+
+ The cursor must be at the left margin before this command is used.
+ This command does not move the cursor.
+
+`dl'
+ String of commands to delete the line the cursor is on. The
+ following lines move up, and a blank line appears at the bottom of
+ the screen (or bottom of the scroll region). If the terminal has
+ the `db' flag, a nonblank line previously pushed off the screen
+ bottom may reappear at the bottom.
+
+ The cursor must be at the left margin before this command is used.
+ This command does not move the cursor.
+
+`AL'
+ String of commands to insert N blank lines before the line that
+ the cursor is on. It is like `al' repeated N times, except that
+ it is as fast as one `al'.
+
+`DL'
+ String of commands to delete N lines starting with the line that
+ the cursor is on. It is like `dl' repeated N times, except that
+ it is as fast as one `dl'.
+
+ Any terminal description that defines `AL' should also define `al';
+likewise for `DL' and `dl'. However, many terminals can only insert or
+delete one line at a time, so it is common to find `al' and not `AL',
+or `dl' without `DL'.
+
+ Therefore, all programs that use the insert and delete facilities
+should be prepared to work with `al' in the case that `AL' is absent,
+and likewise with `dl'. On the other hand, it is acceptable to write
+an application that uses only `al' and `dl' and does not look for `AL'
+or `DL' at all.
+
+ If a terminal does not support line insertion and deletion directly,
+but does support a scroll region, the effect of insertion and deletion
+can be obtained with scrolling. However, it is up to the individual
+user program to check for this possibility and use the scrolling
+commands to get the desired result. It is fairly important to implement
+this alternate strategy, since it is the only way to get the effect of
+line insertion and deletion on the popular VT100 terminal.
+
+ Insertion and deletion of lines is affected by the scroll region on
+terminals that have a settable scroll region. This is useful when it is
+desirable to move any few consecutive lines up or down by a few lines.
+*Note Scrolling::.
+
+ The line pushed off the bottom of the screen is not lost if the
+terminal has the `db' flag capability; instead, it is pushed into
+display memory that does not appear on the screen. This is the same
+thing that happens when scrolling pushes a line off the bottom of the
+screen. Either reverse scrolling or deletion of a line can bring the
+apparently lost line back onto the bottom of the screen. If the
+terminal has the scroll region feature as well as `db', the pushed-out
+line really is lost if a scroll region is in effect.
+
+ When outputting an insert or delete command with `tputs', the NLINES
+argument should be the total number of lines from the cursor to the
+bottom of the screen (or scroll region). Very often these commands
+require padding proportional to this number of lines. *Note Padding::.
+
+ For `AL' and `DL' the NLINES argument should *not* depend on the
+number of lines inserted or deleted; only the total number of lines
+affected. This is because it is just as fast to insert two or N lines
+with `AL' as to insert one line with `al'.
+
+\1f
+File: termcap.info, Node: Insdel Char, Next: Standout, Prev: Insdel Line, Up: Capabilities
+
+Insert/Delete Character
+=======================
+
+ "Inserting a character" means creating a blank space in the middle
+of a line, and pushing the rest of the line rightward. The character
+in the rightmost column is lost.
+
+ "Deleting a character" means causing the character to disappear from
+the screen, closing up the gap by moving the rest of the line leftward.
+A blank space appears in the rightmost column.
+
+ Insertion and deletion of characters is useful in programs that
+maintain an updating display some parts of which may get longer or
+shorter. It is also useful in editors for redisplaying the results of
+editing within a line.
+
+ Many terminals provide commands to insert or delete a single
+character at the cursor position. Some provide the ability to insert
+or delete several characters with one command, using the number of
+characters to insert or delete as a parameter.
+
+ Many terminals provide an insert mode in which outputting a graphic
+character has the added effect of inserting a position for that
+character. A special command string is used to enter insert mode and
+another is used to exit it. The reason for designing a terminal with
+an insert mode rather than an insert command is that inserting
+character positions is usually followed by writing characters into
+them. With insert mode, this is as fast as simply writing the
+characters, except for the fixed overhead of entering and leaving
+insert mode. However, when the line speed is great enough, padding may
+be required for the graphic characters output in insert mode.
+
+ Some terminals require you to enter insert mode and then output a
+special command for each position to be inserted. Or they may require
+special commands to be output before or after each graphic character to
+be inserted.
+
+ Deletion of characters is usually accomplished by a straightforward
+command to delete one or several positions; but on some terminals, it
+is necessary to enter a special delete mode before using the delete
+command, and leave delete mode afterward. Sometimes delete mode and
+insert mode are the same mode.
+
+ Some terminals make a distinction between character positions in
+which a space character has been output and positions which have been
+cleared. On these terminals, the effect of insert or delete character
+runs to the first cleared position rather than to the end of the line.
+In fact, the effect may run to more than one line if there is no
+cleared position to stop the shift on the first line. These terminals
+are identified by the `in' flag capability.
+
+ On terminals with the `in' flag, the technique of skipping over
+characters that you know were cleared, and then outputting text later
+on in the same line, causes later insert and delete character
+operations on that line to do nonstandard things. A program that has
+any chance of doing this must check for the `in' flag and must be
+careful to write explicit space characters into the intermediate
+columns when `in' is present.
+
+ A plethora of terminal capabilities are needed to describe all of
+this complexity. Here is a list of them all. Following the list, we
+present an algorithm for programs to use to take proper account of all
+of these capabilities.
+
+`im'
+ String of commands to enter insert mode.
+
+ If the terminal has no special insert mode, but it can insert
+ characters with a special command, `im' should be defined with a
+ null value, because the `vi' editor assumes that insertion of a
+ character is impossible if `im' is not provided.
+
+ New programs should not act like `vi'. They should pay attention
+ to `im' only if it is defined.
+
+`ei'
+ String of commands to leave insert mode. This capability must be
+ present if `im' is.
+
+ On a few old terminals the same string is used to enter and exit
+ insert mode. This string turns insert mode on if it was off, and
+ off if it was on. You can tell these terminals because the `ei'
+ string equals the `im' string. If you want to support these
+ terminals, you must always remember accurately whether insert mode
+ is in effect. However, these terminals are obsolete, and it is
+ reasonable to refuse to support them. On all modern terminals, you
+ can safely output `ei' at any time to ensure that insert mode is
+ turned off.
+
+`ic'
+ String of commands to insert one character position at the cursor.
+ The cursor does not move.
+
+ If outputting a graphic character while in insert mode is
+ sufficient to insert the character, then the `ic' capability
+ should be defined with a null value.
+
+ If your terminal offers a choice of ways to insert--either use
+ insert mode or use a special command--then define `im' and do not
+ define `ic', since this gives the most efficient operation when
+ several characters are to be inserted. *Do not* define both
+ strings, for that means that *both* must be used each time
+ insertion is done.
+
+`ip'
+ String of commands to output following an inserted graphic
+ character in insert mode. Often it is used just for a padding
+ spec, when padding is needed after an inserted character (*note
+ Padding::.).
+
+`IC'
+ String of commands to insert N character positions at and after
+ the cursor. It has the same effect as repeating the `ic' string
+ and a space, N times.
+
+ If `IC' is provided, application programs may use it without first
+ entering insert mode.
+
+`mi'
+ Flag whose presence means it is safe to move the cursor while in
+ insert mode and assume the terminal remains in insert mode.
+
+`in'
+ Flag whose presence means that the terminal distinguishes between
+ character positions in which space characters have been output and
+ positions which have been cleared.
+
+ An application program can assume that the terminal can do character
+insertion if *any one of* the capabilities `IC', `im', `ic' or `ip' is
+provided.
+
+ To insert N blank character positions, move the cursor to the place
+to insert them and follow this algorithm:
+
+ 1. If an `IC' string is provided, output it with parameter N and you
+ are finished. Otherwise (or if you don't want to bother to look
+ for an `IC' string) follow the remaining steps.
+
+ 2. Output the `im' string, if there is one, unless the terminal is
+ already in insert mode.
+
+ 3. Repeat steps 4 through 6, N times.
+
+ 4. Output the `ic' string if any.
+
+ 5. Output a space.
+
+ 6. Output the `ip' string if any.
+
+ 7. Output the `ei' string, eventually, to exit insert mode. There is
+ no need to do this right away. If the `mi' flag is present, you
+ can move the cursor and the cursor will remain in insert mode;
+ then you can do more insertion elsewhere without reentering insert
+ mode.
+
+ To insert N graphic characters, position the cursor and follow this
+algorithm:
+
+ 1. If an `IC' string is provided, output it with parameter N, then
+ output the graphic characters, and you are finished. Otherwise
+ (or if you don't want to bother to look for an `IC' string) follow
+ the remaining steps.
+
+ 2. Output the `im' string, if there is one, unless the terminal is
+ already in insert mode.
+
+ 3. For each character to be output, repeat steps 4 through 6.
+
+ 4. Output the `ic' string if any.
+
+ 5. Output the next graphic character.
+
+ 6. Output the `ip' string if any.
+
+ 7. Output the `ei' string, eventually, to exit insert mode. There is
+ no need to do this right away. If the `mi' flag is present, you
+ can move the cursor and the cursor will remain in insert mode;
+ then you can do more insertion elsewhere without reentering insert
+ mode.
+
+ Note that this is not the same as the original Unix termcap
+specifications in one respect: it assumes that the `IC' string can be
+used without entering insert mode. This is true as far as I know, and
+it allows you be able to avoid entering and leaving insert mode, and
+also to be able to avoid the inserted-character padding after the
+characters that go into the inserted positions.
+
+ Deletion of characters is less complicated; deleting one column is
+done by outputting the `dc' string. However, there may be a delete
+mode that must be entered with `dm' in order to make `dc' work.
+
+`dc'
+ String of commands to delete one character position at the cursor.
+ If `dc' is not present, the terminal cannot delete characters.
+
+`DC'
+ String of commands to delete N characters starting at the cursor.
+ It has the same effect as repeating the `dc' string N times. Any
+ terminal description that has `DC' also has `dc'.
+
+`dm'
+ String of commands to enter delete mode. If not present, there is
+ no delete mode, and `dc' can be used at any time (assuming there is
+ a `dc').
+
+`ed'
+ String of commands to exit delete mode. This must be present if
+ `dm' is.
+
+ To delete N character positions, position the cursor and follow these
+steps:
+
+ 1. If the `DC' string is present, output it with parameter N and you
+ are finished. Otherwise, follow the remaining steps.
+
+ 2. Output the `dm' string, unless you know the terminal is already in
+ delete mode.
+
+ 3. Output the `dc' string N times.
+
+ 4. Output the `ed' string eventually. If the flag capability `mi' is
+ present, you can move the cursor and do more deletion without
+ leaving and reentering delete mode.
+
+ As with the `IC' string, we have departed from the original termcap
+specifications by assuming that `DC' works without entering delete mode
+even though `dc' would not.
+
+ If the `dm' and `im' capabilities are both present and have the same
+value, it means that the terminal has one mode for both insertion and
+deletion. It is useful for a program to know this, because then it can
+do insertions after deletions, or vice versa, without leaving
+insert/delete mode and reentering it.
+
--- /dev/null
+This is Info file ../info/termcap.info, produced by Makeinfo version
+1.68 from the input file termcap.texi.
+
+START-INFO-DIR-ENTRY
+* Termcap: (termcap). Termcap library of the GNU system.
+END-INFO-DIR-ENTRY
+
+ This file documents the termcap library of the GNU system.
+
+ Copyright (C) 1988 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+\1f
+File: termcap.info, Node: Standout, Next: Underlining, Prev: Insdel Char, Up: Capabilities
+
+Standout and Appearance Modes
+=============================
+
+ "Appearance modes" are modifications to the ways characters are
+displayed. Typical appearance modes include reverse video, dim, bright,
+blinking, underlined, invisible, and alternate character set. Each
+kind of terminal supports various among these, or perhaps none.
+
+ For each type of terminal, one appearance mode or combination of
+them that looks good for highlighted text is chosen as the "standout
+mode". The capabilities `so' and `se' say how to enter and leave
+standout mode. Programs that use appearance modes only to highlight
+some text generally use the standout mode so that they can work on as
+many terminals as possible. Use of specific appearance modes other
+than "underlined" and "alternate character set" is rare.
+
+ Terminals that implement appearance modes fall into two general
+classes as to how they do it.
+
+ In some terminals, the presence or absence of any appearance mode is
+recorded separately for each character position. In these terminals,
+each graphic character written is given the appearance modes current at
+the time it is written, and keeps those modes until it is erased or
+overwritten. There are special commands to turn the appearance modes
+on or off for characters to be written in the future.
+
+ In other terminals, the change of appearance modes is represented by
+a marker that belongs to a certain screen position but affects all
+following screen positions until the next marker. These markers are
+traditionally called "magic cookies".
+
+ The same capabilities (`so', `se', `mb' and so on) for turning
+appearance modes on and off are used for both magic-cookie terminals
+and per-character terminals. On magic cookie terminals, these give the
+commands to write the magic cookies. On per-character terminals, they
+change the current modes that affect future output and erasure. Some
+simple applications can use these commands without knowing whether or
+not they work by means of cookies.
+
+ However, a program that maintains and updates a display needs to know
+whether the terminal uses magic cookies, and exactly what their effect
+is. This information comes from the `sg' capability.
+
+ The `sg' capability is a numeric capability whose presence indicates
+that the terminal uses magic cookies for appearance modes. Its value is
+the number of character positions that a magic cookie occupies. Usually
+the cookie occupies one or more character positions on the screen, and
+these character positions are displayed as blank, but in some terminals
+the cookie has zero width.
+
+ The `sg' capability describes both the magic cookie to turn standout
+on and the cookie to turn it off. This makes the assumption that both
+kinds of cookie have the same width on the screen. If that is not true,
+the narrower cookie must be "widened" with spaces until it has the same
+width as the other.
+
+ On some magic cookie terminals, each line always starts with normal
+display; in other words, the scope of a magic cookie never extends over
+more than one line. But on other terminals, one magic cookie affects
+all the lines below it unless explicitly canceled. Termcap does not
+define any way to distinguish these two ways magic cookies can work.
+To be safe, it is best to put a cookie at the beginning of each line.
+
+ On some per-character terminals, standout mode or other appearance
+modes may be canceled by moving the cursor. On others, moving the
+cursor has no effect on the state of the appearance modes. The latter
+class of terminals are given the flag capability `ms' ("can move in
+standout"). All programs that might have occasion to move the cursor
+while appearance modes are turned on must check for this flag; if it is
+not present, they should reset appearance modes to normal before doing
+cursor motion.
+
+ A program that has turned on only standout mode should use `se' to
+reset the standout mode to normal. A program that has turned on only
+alternate character set mode should use `ae' to return it to normal.
+If it is possible that any other appearance modes are turned on, use the
+`me' capability to return them to normal.
+
+ Note that the commands to turn on one appearance mode, including `so'
+and `mb' ... `mr', if used while some other appearance modes are turned
+on, may combine the two modes on some terminals but may turn off the
+mode previously enabled on other terminals. This is because some
+terminals do not have a command to set or clear one appearance mode
+without changing the others. Programs should not attempt to use
+appearance modes in combination except with `sa', and when switching
+from one single mode to another should always turn off the previously
+enabled mode and then turn on the new desired mode.
+
+ On some old terminals, the `so' and `se' commands may be the same
+command, which has the effect of turning standout on if it is off, or
+off it is on. It is therefore risky for a program to output extra `se'
+commands for good measure. Fortunately, all these terminals are
+obsolete.
+
+ Programs that update displays in which standout-text may be replaced
+with non-standout text must check for the `xs' flag. In a per-character
+terminal, this flag says that the only way to remove standout once
+written is to clear that portion of the line with the `ce' string or
+something even more powerful (*note Clearing::.); just writing new
+characters at those screen positions will not change the modes in
+effect there. In a magic cookie terminal, `xs' says that the only way
+to remove a cookie is to clear a portion of the line that includes the
+cookie; writing a different cookie at the same position does not work.
+
+ Such programs must also check for the `xt' flag, which means that the
+terminal is a Teleray 1061. On this terminal it is impossible to
+position the cursor at the front of a magic cookie, so the only two
+ways to remove a cookie are (1) to delete the line it is on or (2) to
+position the cursor at least one character before it (possibly on a
+previous line) and output the `se' string, which on these terminals
+finds and removes the next `so' magic cookie on the screen. (It may
+also be possible to remove a cookie which is not at the beginning of a
+line by clearing that line.) The `xt' capability also has implications
+for the use of tab characters, but in that regard it is obsolete (*note
+Cursor Motion::.).
+
+`so'
+ String of commands to enter standout mode.
+
+`se'
+ String of commands to leave standout mode.
+
+`sg'
+ Numeric capability, the width on the screen of the magic cookie.
+ This capability is absent in terminals that record appearance modes
+ character by character.
+
+`ms'
+ Flag whose presence means that it is safe to move the cursor while
+ the appearance modes are not in the normal state. If this flag is
+ absent, programs should always reset the appearance modes to
+ normal before moving the cursor.
+
+`xs'
+ Flag whose presence means that the only way to reset appearance
+ modes already on the screen is to clear to end of line. On a
+ per-character terminal, you must clear the area where the modes
+ are set. On a magic cookie terminal, you must clear an area
+ containing the cookie. See the discussion above.
+
+`xt'
+ Flag whose presence means that the cursor cannot be positioned
+ right in front of a magic cookie, and that `se' is a command to
+ delete the next magic cookie following the cursor. See discussion
+ above.
+
+`mb'
+ String of commands to enter blinking mode.
+
+`md'
+ String of commands to enter double-bright mode.
+
+`mh'
+ String of commands to enter half-bright mode.
+
+`mk'
+ String of commands to enter invisible mode.
+
+`mp'
+ String of commands to enter protected mode.
+
+`mr'
+ String of commands to enter reverse-video mode.
+
+`me'
+ String of commands to turn off all appearance modes, including
+ standout mode and underline mode. On some terminals it also turns
+ off alternate character set mode; on others, it may not. This
+ capability must be present if any of `mb' ... `mr' is present.
+
+`as'
+ String of commands to turn on alternate character set mode. This
+ mode assigns some or all graphic characters an alternate picture
+ on the screen. There is no standard as to what the alternate
+ pictures look like.
+
+`ae'
+ String of commands to turn off alternate character set mode.
+
+`sa'
+ String of commands to turn on an arbitrary combination of
+ appearance modes. It accepts 9 parameters, each of which controls
+ a particular kind of appearance mode. A parameter should be 1 to
+ turn its appearance mode on, or zero to turn that mode off. Most
+ terminals do not support the `sa' capability, even among those
+ that do have various appearance modes.
+
+ The nine parameters are, in order, STANDOUT, UNDERLINE, REVERSE,
+ BLINK, HALF-BRIGHT, DOUBLE-BRIGHT, BLANK, PROTECT, ALT CHAR SET.
+
+\1f
+File: termcap.info, Node: Underlining, Next: Cursor Visibility, Prev: Standout, Up: Capabilities
+
+Underlining
+===========
+
+ Underlining on most terminals is a kind of appearance mode, much like
+standout mode. Therefore, it may be implemented using magic cookies or
+as a flag in the terminal whose current state affects each character
+that is output. *Note Standout::, for a full explanation.
+
+ The `ug' capability is a numeric capability whose presence indicates
+that the terminal uses magic cookies for underlining. Its value is the
+number of character positions that a magic cookie for underlining
+occupies; it is used for underlining just as `sg' is used for standout.
+Aside from the simplest applications, it is impossible to use
+underlining correctly without paying attention to the value of `ug'.
+
+`us'
+ String of commands to turn on underline mode or to output a magic
+ cookie to start underlining.
+
+`ue'
+ String of commands to turn off underline mode or to output a magic
+ cookie to stop underlining.
+
+`ug'
+ Width of magic cookie that represents a change of underline mode;
+ or missing, if the terminal does not use a magic cookie for this.
+
+`ms'
+ Flag whose presence means that it is safe to move the cursor while
+ the appearance modes are not in the normal state. Underlining is
+ an appearance mode. If this flag is absent, programs should
+ always turn off underlining before moving the cursor.
+
+ There are two other, older ways of doing underlining: there can be a
+command to underline a single character, or the output of `_', the
+ASCII underscore character, as an overstrike could cause a character to
+be underlined. New programs need not bother to handle these
+capabilities unless the author cares strongly about the obscure
+terminals which support them. However, terminal descriptions should
+provide these capabilities when appropriate.
+
+`uc'
+ String of commands to underline the character under the cursor, and
+ move the cursor right.
+
+`ul'
+ Flag whose presence means that the terminal can underline by
+ overstriking an underscore character (`_'); some terminals can do
+ this even though they do not support overstriking in general. An
+ implication of this flag is that when outputting new text to
+ overwrite old text, underscore characters must be treated
+ specially lest they underline the old text instead.
+
+\1f
+File: termcap.info, Node: Cursor Visibility, Next: Bell, Prev: Underlining, Up: Capabilities
+
+Cursor Visibility
+=================
+
+ Some terminals have the ability to make the cursor invisible, or to
+enhance it. Enhancing the cursor is often done by programs that plan
+to use the cursor to indicate to the user a position of interest that
+may be anywhere on the screen--for example, the Emacs editor enhances
+the cursor on entry. Such programs should always restore the cursor to
+normal on exit.
+
+`vs'
+ String of commands to enhance the cursor.
+
+`vi'
+ String of commands to make the cursor invisible.
+
+`ve'
+ String of commands to return the cursor to normal.
+
+ If you define either `vs' or `vi', you must also define `ve'.
+
+\1f
+File: termcap.info, Node: Bell, Next: Keypad, Prev: Cursor Visibility, Up: Capabilities
+
+Bell
+====
+
+ Here we describe commands to make the terminal ask for the user to
+pay attention to it.
+
+`bl'
+ String of commands to cause the terminal to make an audible sound.
+ If this capability is absent, the terminal has no way to make a
+ suitable sound.
+
+`vb'
+ String of commands to cause the screen to flash to attract
+ attention ("visible bell"). If this capability is absent, the
+ terminal has no way to do such a thing.
+
+\1f
+File: termcap.info, Node: Keypad, Next: Meta Key, Prev: Bell, Up: Capabilities
+
+Keypad and Function Keys
+========================
+
+ Many terminals have arrow and function keys that transmit specific
+character sequences to the computer. Since the precise sequences used
+depend on the terminal, termcap defines capabilities used to say what
+the sequences are. Unlike most termcap string-valued capabilities,
+these are not strings of commands to be sent to the terminal, rather
+strings that are received from the terminal.
+
+ Programs that expect to use keypad keys should check, initially, for
+a `ks' capability and send it, to make the keypad actually transmit.
+Such programs should also send the `ke' string when exiting.
+
+`ks'
+ String of commands to make the function keys transmit. If this
+ capability is not provided, but the others in this section are,
+ programs may assume that the function keys always transmit.
+
+`ke'
+ String of commands to make the function keys work locally. This
+ capability is provided only if `ks' is.
+
+`kl'
+ String of input characters sent by typing the left-arrow key. If
+ this capability is missing, you cannot expect the terminal to have
+ a left-arrow key that transmits anything to the computer.
+
+`kr'
+ String of input characters sent by typing the right-arrow key.
+
+`ku'
+ String of input characters sent by typing the up-arrow key.
+
+`kd'
+ String of input characters sent by typing the down-arrow key.
+
+`kh'
+ String of input characters sent by typing the "home-position" key.
+
+`K1' ... `K5'
+ Strings of input characters sent by the five other keys in a 3-by-3
+ array that includes the arrow keys, if the keyboard has such a
+ 3-by-3 array. Note that one of these keys may be the
+ "home-position" key, in which case one of these capabilities will
+ have the same value as the `kh' key.
+
+`k0'
+ String of input characters sent by function key 10 (or 0, if the
+ terminal has one labeled 0).
+
+`k1' ... `k9'
+ Strings of input characters sent by function keys 1 through 9,
+ provided for those function keys that exist.
+
+`kn'
+ Number: the number of numbered function keys, if there are more
+ than 10.
+
+`l0' ... `l9'
+ Strings which are the labels appearing on the keyboard on the keys
+ described by the capabilities `k0' ... `l9'. These capabilities
+ should be left undefined if the labels are `f0' or `f10' and `f1'
+ ... `f9'.
+
+`kH'
+ String of input characters sent by the "home down" key, if there is
+ one.
+
+`kb'
+ String of input characters sent by the "backspace" key, if there is
+ one.
+
+`ka'
+ String of input characters sent by the "clear all tabs" key, if
+ there is one.
+
+`kt'
+ String of input characters sent by the "clear tab stop this column"
+ key, if there is one.
+
+`kC'
+ String of input characters sent by the "clear screen" key, if
+ there is one.
+
+`kD'
+ String of input characters sent by the "delete character" key, if
+ there is one.
+
+`kL'
+ String of input characters sent by the "delete line" key, if there
+ is one.
+
+`kM'
+ String of input characters sent by the "exit insert mode" key, if
+ there is one.
+
+`kE'
+ String of input characters sent by the "clear to end of line" key,
+ if there is one.
+
+`kS'
+ String of input characters sent by the "clear to end of screen"
+ key, if there is one.
+
+`kI'
+ String of input characters sent by the "insert character" or "enter
+ insert mode" key, if there is one.
+
+`kA'
+ String of input characters sent by the "insert line" key, if there
+ is one.
+
+`kN'
+ String of input characters sent by the "next page" key, if there is
+ one.
+
+`kP'
+ String of input characters sent by the "previous page" key, if
+ there is one.
+
+`kF'
+ String of input characters sent by the "scroll forward" key, if
+ there is one.
+
+`kR'
+ String of input characters sent by the "scroll reverse" key, if
+ there is one.
+
+`kT'
+ String of input characters sent by the "set tab stop in this
+ column" key, if there is one.
+
+`ko'
+ String listing the other function keys the terminal has. This is a
+ very obsolete way of describing the same information found in the
+ `kH' ... `kT' keys. The string contains a list of two-character
+ termcap capability names, separated by commas. The meaning is
+ that for each capability name listed, the terminal has a key which
+ sends the string which is the value of that capability. For
+ example, the value `:ko=cl,ll,sf,sr:' says that the terminal has
+ four function keys which mean "clear screen", "home down", "scroll
+ forward" and "scroll reverse".
+
+\1f
+File: termcap.info, Node: Meta Key, Next: Initialization, Prev: Keypad, Up: Capabilities
+
+Meta Key
+========
+
+ A Meta key is a key on the keyboard that modifies each character you
+type by controlling the 0200 bit. This bit is on if and only if the
+Meta key is held down when the character is typed. Characters typed
+using the Meta key are called Meta characters. Emacs uses Meta
+characters as editing commands.
+
+`km'
+ Flag whose presence means that the terminal has a Meta key.
+
+`mm'
+ String of commands to enable the functioning of the Meta key.
+
+`mo'
+ String of commands to disable the functioning of the Meta key.
+
+ If the terminal has `km' but does not have `mm' and `mo', it means
+that the Meta key always functions. If it has `mm' and `mo', it means
+that the Meta key can be turned on or off. Send the `mm' string to
+turn it on, and the `mo' string to turn it off. I do not know why one
+would ever not want it to be on.
+
+\1f
+File: termcap.info, Node: Initialization, Next: Pad Specs, Prev: Meta Key, Up: Capabilities
+
+Initialization
+==============
+
+`ti'
+ String of commands to put the terminal into whatever special modes
+ are needed or appropriate for programs that move the cursor
+ nonsequentially around the screen. Programs that use termcap to do
+ full-screen display should output this string when they start up.
+
+`te'
+ String of commands to undo what is done by the `ti' string.
+ Programs that output the `ti' string on entry should output this
+ string when they exit.
+
+`is'
+ String of commands to initialize the terminal for each login
+ session.
+
+`if'
+ String which is the name of a file containing the string of
+ commands to initialize the terminal for each session of use.
+ Normally `is' and `if' are not both used.
+
+`i1'
+`i3'
+ Two more strings of commands to initialize the terminal for each
+ login session. The `i1' string (if defined) is output before `is'
+ or `if', and the `i3' string (if defined) is output after.
+
+ The reason for having three separate initialization strings is to
+ make it easier to define a group of related terminal types with
+ slightly different initializations. Define two or three of the
+ strings in the basic type; then the other types can override one
+ or two of the strings.
+
+`rs'
+ String of commands to reset the terminal from any strange mode it
+ may be in. Normally this includes the `is' string (or other
+ commands with the same effects) and more. What would go in the
+ `rs' string but not in the `is' string are annoying or slow
+ commands to bring the terminal back from strange modes that nobody
+ would normally use.
+
+`it'
+ Numeric value, the initial spacing between hardware tab stop
+ columns when the terminal is powered up. Programs to initialize
+ the terminal can use this to decide whether there is a need to set
+ the tab stops. If the initial width is 8, well and good; if it is
+ not 8, then the tab stops should be set; if they cannot be set,
+ the kernel is told to convert tabs to spaces, and other programs
+ will observe this and do likewise.
+
+`ct'
+ String of commands to clear all tab stops.
+
+`st'
+ String of commands to set tab stop at current cursor column on all
+ lines.
+
+\1f
+File: termcap.info, Node: Pad Specs, Next: Status Line, Prev: Initialization, Up: Capabilities
+
+Padding Capabilities
+====================
+
+ There are two terminal capabilities that exist just to explain the
+proper way to obey the padding specifications in all the command string
+capabilities. One, `pc', must be obeyed by all termcap-using programs.
+
+`pb'
+ Numeric value, the lowest baud rate at which padding is actually
+ needed. Programs may check this and refrain from doing any
+ padding at lower speeds.
+
+`pc'
+ String of commands for padding. The first character of this
+ string is to be used as the pad character, instead of using null
+ characters for padding. If `pc' is not provided, use null
+ characters. Every program that uses termcap must look up this
+ capability and use it to set the variable `PC' that is used by
+ `tputs'. *Note Padding::.
+
+ Some termcap capabilities exist just to specify the amount of
+padding that the kernel should give to cursor motion commands used in
+ordinary sequential output.
+
+`dC'
+ Numeric value, the number of msec of padding needed for the
+ carriage-return character.
+
+`dN'
+ Numeric value, the number of msec of padding needed for the newline
+ (linefeed) character.
+
+`dB'
+ Numeric value, the number of msec of padding needed for the
+ backspace character.
+
+`dF'
+ Numeric value, the number of msec of padding needed for the
+ formfeed character.
+
+`dT'
+ Numeric value, the number of msec of padding needed for the tab
+ character.
+
+ In some systems, the kernel uses the above capabilities; in other
+systems, the kernel uses the paddings specified in the string
+capabilities `cr', `sf', `le', `ff' and `ta'. Descriptions of
+terminals which require such padding should contain the `dC' ... `dT'
+capabilities and also specify the appropriate padding in the
+corresponding string capabilities. Since no modern terminals require
+padding for ordinary sequential output, you probably won't need to do
+either of these things.
+
+\1f
+File: termcap.info, Node: Status Line, Next: Half-Line, Prev: Pad Specs, Up: Capabilities
+
+Status Line
+===========
+
+ A "status line" is a line on the terminal that is not used for
+ordinary display output but instead used for a special message. The
+intended use is for a continuously updated description of what the
+user's program is doing, and that is where the name "status line" comes
+from, but in fact it could be used for anything. The distinguishing
+characteristic of a status line is that ordinary output to the terminal
+does not affect it; it changes only if the special status line commands
+of this section are used.
+
+`hs'
+ Flag whose presence means that the terminal has a status line. If
+ a terminal description specifies that there is a status line, it
+ must provide the `ts' and `fs' capabilities.
+
+`ts'
+ String of commands to move the terminal cursor into the status
+ line. Usually these commands must specifically record the old
+ cursor position for the sake of the `fs' string.
+
+`fs'
+ String of commands to move the cursor back from the status line to
+ its previous position (outside the status line).
+
+`es'
+ Flag whose presence means that other display commands work while
+ writing the status line. In other words, one can clear parts of
+ it, insert or delete characters, move the cursor within it using
+ `ch' if there is a `ch' capability, enter and leave standout mode,
+ and so on.
+
+`ds'
+ String of commands to disable the display of the status line. This
+ may be absent, if there is no way to disable the status line
+ display.
+
+`ws'
+ Numeric value, the width of the status line. If this capability is
+ absent in a terminal that has a status line, it means the status
+ line is the same width as the other lines.
+
+ Note that the value of `ws' is sometimes as small as 8.
+
+\1f
+File: termcap.info, Node: Half-Line, Next: Printer, Prev: Status Line, Up: Capabilities
+
+Half-Line Motion
+================
+
+ Some terminals have commands for moving the cursor vertically by
+half-lines, useful for outputting subscripts and superscripts. Mostly
+it is hardcopy terminals that have such features.
+
+`hu'
+ String of commands to move the cursor up half a line. If the
+ terminal is a display, it is your responsibility to avoid moving
+ up past the top line; however, most likely the terminal that
+ supports this is a hardcopy terminal and there is nothing to be
+ concerned about.
+
+`hd'
+ String of commands to move the cursor down half a line. If the
+ terminal is a display, it is your responsibility to avoid moving
+ down past the bottom line, etc.
+
+\1f
+File: termcap.info, Node: Printer, Prev: Half-Line, Up: Capabilities
+
+Controlling Printers Attached to Terminals
+==========================================
+
+ Some terminals have attached hardcopy printer ports. They may be
+able to copy the screen contents to the printer; they may also be able
+to redirect output to the printer. Termcap does not have anything to
+tell the program whether the redirected output appears also on the
+screen; it does on some terminals but not all.
+
+`ps'
+ String of commands to cause the contents of the screen to be
+ printed. If it is absent, the screen contents cannot be printed.
+
+`po'
+ String of commands to redirect further output to the printer.
+
+`pf'
+ String of commands to terminate redirection of output to the
+ printer. This capability must be present in the description if
+ `po' is.
+
+`pO'
+ String of commands to redirect output to the printer for next N
+ characters of output, regardless of what they are. Redirection
+ will end automatically after N characters of further output. Until
+ then, nothing that is output can end redirection, not even the
+ `pf' string if there is one. The number N should not be more than
+ 255.
+
+ One use of this capability is to send non-text byte sequences
+ (such as bit-maps) to the printer.
+
+ Most terminals with printers do not support all of `ps', `po' and
+`pO'; any one or two of them may be supported. To make a program that
+can send output to all kinds of printers, it is necessary to check for
+all three of these capabilities, choose the most convenient of the ones
+that are provided, and use it in its own appropriate fashion.
+
+\1f
+File: termcap.info, Node: Summary, Next: Var Index, Prev: Capabilities, Up: Top
+
+Summary of Capability Names
+***************************
+
+ Here are all the terminal capability names in alphabetical order
+with a brief description of each. For cross references to their
+definitions, see the index of capability names (*note Cap Index::.).
+
+`ae'
+ String to turn off alternate character set mode.
+
+`al'
+ String to insert a blank line before the cursor.
+
+`AL'
+ String to insert N blank lines before the cursor.
+
+`am'
+ Flag: output to last column wraps cursor to next line.
+
+`as'
+ String to turn on alternate character set mode.like.
+
+`bc'
+ Very obsolete alternative name for the `le' capability.
+
+`bl'
+ String to sound the bell.
+
+`bs'
+ Obsolete flag: ASCII backspace may be used for leftward motion.
+
+`bt'
+ String to move the cursor left to the previous hardware tab stop
+ column.
+
+`bw'
+ Flag: `le' at left margin wraps to end of previous line.
+
+`CC'
+ String to change terminal's command character.
+
+`cd'
+ String to clear the line the cursor is on, and following lines.
+
+`ce'
+ String to clear from the cursor to the end of the line.
+
+`ch'
+ String to position the cursor at column C in the same line.
+
+`cl'
+ String to clear the entire screen and put cursor at upper left
+ corner.
+
+`cm'
+ String to position the cursor at line L, column C.
+
+`CM'
+ String to position the cursor at line L, column C, relative to
+ display memory.
+
+`co'
+ Number: width of the screen.
+
+`cr'
+ String to move cursor sideways to left margin.
+
+`cs'
+ String to set the scroll region.
+
+`cS'
+ Alternate form of string to set the scroll region.
+
+`ct'
+ String to clear all tab stops.
+
+`cv'
+ String to position the cursor at line L in the same column.
+
+`da'
+ Flag: data scrolled off top of screen may be scrolled back.
+
+`db'
+ Flag: data scrolled off bottom of screen may be scrolled back.
+
+`dB'
+ Obsolete number: msec of padding needed for the backspace
+ character.
+
+`dc'
+ String to delete one character position at the cursor.
+
+`dC'
+ Obsolete number: msec of padding needed for the carriage-return
+ character.
+
+`DC'
+ String to delete N characters starting at the cursor.
+
+`dF'
+ Obsolete number: msec of padding needed for the formfeed character.
+
+`dl'
+ String to delete the line the cursor is on.
+
+`DL'
+ String to delete N lines starting with the cursor's line.
+
+`dm'
+ String to enter delete mode.
+
+`dN'
+ Obsolete number: msec of padding needed for the newline character.
+
+`do'
+ String to move the cursor vertically down one line.
+
+`DO'
+ String to move cursor vertically down N lines.
+
+`ds'
+ String to disable the display of the status line.
+
+`dT'
+ Obsolete number: msec of padding needed for the tab character.
+
+`ec'
+ String of commands to clear N characters at cursor.
+
+`ed'
+ String to exit delete mode.
+
+`ei'
+ String to leave insert mode.
+
+`eo'
+ Flag: output of a space can erase an overstrike.
+
+`es'
+ Flag: other display commands work while writing the status line.
+
+`ff'
+ String to advance to the next page, for a hardcopy terminal.
+
+`fs'
+ String to move the cursor back from the status line to its
+ previous position (outside the status line).
+
+`gn'
+ Flag: this terminal type is generic, not real.
+
+`hc'
+ Flag: hardcopy terminal.
+
+`hd'
+ String to move the cursor down half a line.
+
+`ho'
+ String to position cursor at upper left corner.
+
+`hs'
+ Flag: the terminal has a status line.
+
+`hu'
+ String to move the cursor up half a line.
+
+`hz'
+ Flag: terminal cannot accept `~' as output.
+
+`i1'
+ String to initialize the terminal for each login session.
+
+`i3'
+ String to initialize the terminal for each login session.
+
+`ic'
+ String to insert one character position at the cursor.
+
+`IC'
+ String to insert N character positions at the cursor.
+
+`if'
+ String naming a file of commands to initialize the terminal.
+
+`im'
+ String to enter insert mode.
+
+`in'
+ Flag: outputting a space is different from moving over empty
+ positions.
+
+`ip'
+ String to output following an inserted character in insert mode.
+
+`is'
+ String to initialize the terminal for each login session.
+
+`it'
+ Number: initial spacing between hardware tab stop columns.
+
+`k0'
+ String of input sent by function key 0 or 10.
+
+`k1 ... k9'
+ Strings of input sent by function keys 1 through 9.
+
+`K1 ... K5'
+ Strings sent by the five other keys in 3-by-3 array with arrows.
+
+`ka'
+ String of input sent by the "clear all tabs" key.
+
+`kA'
+ String of input sent by the "insert line" key.
+
+`kb'
+ String of input sent by the "backspace" key.
+
+`kC'
+ String of input sent by the "clear screen" key.
+
+`kd'
+ String of input sent by typing the down-arrow key.
+
+`kD'
+ String of input sent by the "delete character" key.
+
+`ke'
+ String to make the function keys work locally.
+
+`kE'
+ String of input sent by the "clear to end of line" key.
+
+`kF'
+ String of input sent by the "scroll forward" key.
+
+`kh'
+ String of input sent by typing the "home-position" key.
+
+`kH'
+ String of input sent by the "home down" key.
+
+`kI'
+ String of input sent by the "insert character" or "enter insert
+ mode" key.
+
+`kl'
+ String of input sent by typing the left-arrow key.
+
+`kL'
+ String of input sent by the "delete line" key.
+
+`km'
+ Flag: the terminal has a Meta key.
+
+`kM'
+ String of input sent by the "exit insert mode" key.
+
+`kn'
+ Numeric value, the number of numbered function keys.
+
+`kN'
+ String of input sent by the "next page" key.
+
+`ko'
+ Very obsolete string listing the terminal's named function keys.
+
+`kP'
+ String of input sent by the "previous page" key.
+
+`kr'
+ String of input sent by typing the right-arrow key.
+
+`kR'
+ String of input sent by the "scroll reverse" key.
+
+`ks'
+ String to make the function keys transmit.
+
+`kS'
+ String of input sent by the "clear to end of screen" key.
+
+`kt'
+ String of input sent by the "clear tab stop this column" key.
+
+`kT'
+ String of input sent by the "set tab stop in this column" key.
+
+`ku'
+ String of input sent by typing the up-arrow key.
+
+`l0'
+ String on keyboard labelling function key 0 or 10.
+
+`l1 ... l9'
+ Strings on keyboard labelling function keys 1 through 9.
+
+`le'
+ String to move the cursor left one column.
+
+`LE'
+ String to move cursor left N columns.
+
+`li'
+ Number: height of the screen.
+
+`ll'
+ String to position cursor at lower left corner.
+
+`lm'
+ Number: lines of display memory.
+
+`mb'
+ String to enter blinking mode.
+
+`md'
+ String to enter double-bright mode.
+
+`me'
+ String to turn off all appearance modes
+
+`mh'
+ String to enter half-bright mode.
+
+`mi'
+ Flag: cursor motion in insert mode is safe.
+
+`mk'
+ String to enter invisible mode.
+
+`mm'
+ String to enable the functioning of the Meta key.
+
+`mo'
+ String to disable the functioning of the Meta key.
+
+`mp'
+ String to enter protected mode.
+
+`mr'
+ String to enter reverse-video mode.
+
+`ms'
+ Flag: cursor motion in standout mode is safe.
+
+`nc'
+ Obsolete flag: do not use ASCII carriage-return on this terminal.
+
+`nd'
+ String to move the cursor right one column.
+
+`nl'
+ Obsolete alternative name for the `do' and `sf' capabilities.
+
+`ns'
+ Flag: the terminal does not normally scroll for sequential output.
+
+`nw'
+ String to move to start of next line, possibly clearing rest of
+ old line.
+
+`os'
+ Flag: terminal can overstrike.
+
+`pb'
+ Number: the lowest baud rate at which padding is actually needed.
+
+`pc'
+ String containing character for padding.
+
+`pf'
+ String to terminate redirection of output to the printer.
+
+`po'
+ String to redirect further output to the printer.
+
+`pO'
+ String to redirect N characters ofoutput to the printer.
+
+`ps'
+ String to print the screen on the attached printer.
+
+`rc'
+ String to move to last saved cursor position.
+
+`RI'
+ String to move cursor right N columns.
+
+`rp'
+ String to output character C repeated N times.
+
+`rs'
+ String to reset the terminal from any strange modes.
+
+`sa'
+ String to turn on an arbitrary combination of appearance modes.
+
+`sc'
+ String to save the current cursor position.
+
+`se'
+ String to leave standout mode.
+
+`sf'
+ String to scroll the screen one line up.
+
+`SF'
+ String to scroll the screen N lines up.
+
+`sg'
+ Number: width of magic standout cookie. Absent if magic cookies
+ are not used.
+
+`so'
+ String to enter standout mode.
+
+`sr'
+ String to scroll the screen one line down.
+
+`SR'
+ String to scroll the screen N line down.
+
+`st'
+ String to set tab stop at current cursor column on all lines.
+ programs.
+
+`ta'
+ String to move the cursor right to the next hardware tab stop
+ column.
+
+`te'
+ String to return terminal to settings for sequential output.
+
+`ti'
+ String to initialize terminal for random cursor motion.
+
+`ts'
+ String to move the terminal cursor into the status line.
+
+`uc'
+ String to underline one character and move cursor right.
+
+`ue'
+ String to turn off underline mode
+
+`ug'
+ Number: width of underlining magic cookie. Absent if underlining
+ doesn't use magic cookies.
+
+`ul'
+ Flag: underline by overstriking with an underscore.
+
+`up'
+ String to move the cursor vertically up one line.
+
+`UP'
+ String to move cursor vertically up N lines.
+
+`us'
+ String to turn on underline mode
+
+`vb'
+ String to make the screen flash.
+
+`ve'
+ String to return the cursor to normal.
+
+`vi'
+ String to make the cursor invisible.
+
+`vs'
+ String to enhance the cursor.
+
+`wi'
+ String to set the terminal output screen window.
+
+`ws'
+ Number: the width of the status line.
+
+`xb'
+ Flag: superbee terminal.
+
+`xn'
+ Flag: cursor wraps in a strange way.
+
+`xs'
+ Flag: clearing a line is the only way to clear the appearance
+ modes of positions in that line (or, only way to remove magic
+ cookies on that line).
+
+`xt'
+ Flag: Teleray 1061; several strange characteristics.
+
+\1f
+File: termcap.info, Node: Var Index, Next: Cap Index, Prev: Summary, Up: Top
+
+Variable and Function Index
+***************************
+
+* Menu:
+
+* BC: tgoto.
+* ospeed: Output Padding.
+* PC: Output Padding.
+* tgetent: Find.
+* tgetflag: Interrogate.
+* tgetnum: Interrogate.
+* tgetstr: Interrogate.
+* tgoto: tgoto.
+* tparam: tparam.
+* tputs: Output Padding.
+* UP: tgoto.
+
+\1f
+File: termcap.info, Node: Cap Index, Next: Index, Prev: Var Index, Up: Top
+
+Capability Index
+****************
+
+* Menu:
+
+* ae: Standout.
+* AL: Insdel Line.
+* al: Insdel Line.
+* am: Wrapping.
+* as: Standout.
+* bc: Cursor Motion.
+* bl: Bell.
+* bs: Cursor Motion.
+* bt: Cursor Motion.
+* bw: Cursor Motion.
+* CC: Basic.
+* cd: Clearing.
+* ce: Clearing.
+* ch: Cursor Motion.
+* cl: Clearing.
+* cm: Cursor Motion.
+* CM: Cursor Motion.
+* co: Screen Size.
+* cr: Cursor Motion.
+* cS: Scrolling.
+* cs: Scrolling.
+* ct: Initialization.
+* cv: Cursor Motion.
+* da: Scrolling.
+* dB: Pad Specs.
+* db: Scrolling.
+* dC: Pad Specs.
+* DC: Insdel Char.
+* dc: Insdel Char.
+* dF: Pad Specs.
+* DL: Insdel Line.
+* dl: Insdel Line.
+* dm: Insdel Char.
+* dN: Pad Specs.
+* DO: Cursor Motion.
+* do: Cursor Motion.
+* ds: Status Line.
+* dT: Pad Specs.
+* ec: Clearing.
+* ed: Insdel Char.
+* ei: Insdel Char.
+* eo: Basic.
+* es: Status Line.
+* ff: Cursor Motion.
+* fs: Status Line.
+* gn: Basic.
+* hc: Basic.
+* hd: Half-Line.
+* ho: Cursor Motion.
+* hs: Status Line.
+* hu: Half-Line.
+* hz: Basic.
+* i1: Initialization.
+* i3: Initialization.
+* IC: Insdel Char.
+* ic: Insdel Char.
+* if: Initialization.
+* im: Insdel Char.
+* in: Insdel Char.
+* ip: Insdel Char.
+* is: Initialization.
+* it: Initialization.
+* K1...K5: Keypad.
+* k1...k9: Keypad.
+* kA...kT: Keypad.
+* ka...ku: Keypad.
+* km: Meta Key.
+* l0...l9: Keypad.
+* le: Cursor Motion.
+* LE: Cursor Motion.
+* li: Screen Size.
+* ll: Cursor Motion.
+* lm: Scrolling.
+* mb: Standout.
+* md: Standout.
+* me: Standout.
+* mh: Standout.
+* mi: Insdel Char.
+* mk: Standout.
+* mm: Meta Key.
+* mo: Meta Key.
+* mp: Standout.
+* mr: Standout.
+* ms <1>: Standout.
+* ms: Underlining.
+* nc: Cursor Motion.
+* nd: Cursor Motion.
+* nl: Cursor Motion.
+* ns: Scrolling.
+* nw: Cursor Motion.
+* os: Basic.
+* pb: Pad Specs.
+* pc: Pad Specs.
+* pf: Printer.
+* pO: Printer.
+* po: Printer.
+* ps: Printer.
+* rc: Cursor Motion.
+* RI: Cursor Motion.
+* rp: Basic.
+* rs: Initialization.
+* sa: Standout.
+* sc: Cursor Motion.
+* se: Standout.
+* sf: Scrolling.
+* SF: Scrolling.
+* sg: Standout.
+* so: Standout.
+* sr: Scrolling.
+* SR: Scrolling.
+* st: Initialization.
+* ta: Cursor Motion.
+* te: Initialization.
+* ti: Initialization.
+* ts: Status Line.
+* uc: Underlining.
+* ue: Underlining.
+* ug: Underlining.
+* ul: Underlining.
+* up: Cursor Motion.
+* UP: Cursor Motion.
+* us: Underlining.
+* vb: Bell.
+* ve: Cursor Visibility.
+* vi: Cursor Visibility.
+* vs: Cursor Visibility.
+* wi: Windows.
+* ws: Status Line.
+* xb: Basic.
+* xn: Wrapping.
+* xs: Standout.
+* xt <1>: Cursor Motion.
+* xt: Standout.
+
+\1f
+File: termcap.info, Node: Index, Prev: Cap Index, Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* %: Encode Parameters.
+* appearance modes: Standout.
+* bell: Bell.
+* clearing the screen: Clearing.
+* command character: Basic.
+* cursor motion: Cursor Motion.
+* delete character: Insdel Char.
+* delete line: Insdel Line.
+* delete mode: Insdel Char.
+* description format: Format.
+* erasing: Clearing.
+* generic terminal type: Basic.
+* home position: Cursor Motion.
+* inheritance: Inheriting.
+* initialization: Initialization.
+* insert character: Insdel Char.
+* insert line: Insdel Line.
+* insert mode: Insdel Char.
+* line speed: Output Padding.
+* magic cookie: Standout.
+* meta key: Meta Key.
+* names of terminal types: Naming.
+* overstrike: Basic.
+* padding <1>: Padding.
+* padding: Pad Specs.
+* parameters: Parameters.
+* printer: Printer.
+* repeat output: Basic.
+* reset: Initialization.
+* screen size <1>: Screen Size.
+* screen size: Naming.
+* scrolling: Scrolling.
+* standout: Standout.
+* status line: Status Line.
+* Superbee: Basic.
+* tab stops: Initialization.
+* termcap: Introduction.
+* terminal flags (kernel): Initialize.
+* underlining: Underlining.
+* visibility: Cursor Visibility.
+* visible bell: Bell.
+* window: Windows.
+* wrapping <1>: Naming.
+* wrapping: Wrapping.
+
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+Indirect:
+texinfo.info-1: 1510
+texinfo.info-2: 48723
+texinfo.info-3: 96698
+texinfo.info-4: 146082
+texinfo.info-5: 196057
+texinfo.info-6: 245140
+texinfo.info-7: 294058
+texinfo.info-8: 343872
+texinfo.info-9: 393199
+texinfo.info-10: 435577
+texinfo.info-11: 481692
+texinfo.info-12: 519851
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f1510
+Node: Copying\7f23823
+Node: Overview\7f25828
+Node: Overview-Footnotes\7f27256
+Node: Using Texinfo\7f27792
+Node: Info Files\7f30275
+Node: Info Files-Footnotes\7f34310
+Node: Printed Books\7f34557
+Node: Printed Books-Footnotes\7f37228
+Node: Formatting Commands\7f37512
+Node: Formatting Commands-Footnotes\7f40338
+Node: Conventions\7f41040
+Node: Comments\7f43602
+Node: Minimum\7f45025
+Node: Six Parts\7f47211
+Node: Short Sample\7f48723
+Node: Acknowledgements\7f52858
+Node: Texinfo Mode\7f53693
+Node: Texinfo Mode Overview\7f55065
+Node: Emacs Editing\7f55841
+Node: Inserting\7f57971
+Node: Showing the Structure\7f62252
+Node: Updating Nodes and Menus\7f64779
+Node: Updating Commands\7f65852
+Node: Updating Requirements\7f71913
+Node: Other Updating Commands\7f74210
+Node: Info Formatting\7f77478
+Node: Printing\7f78736
+Node: Texinfo Mode Summary\7f81082
+Node: Beginning a File\7f85836
+Node: Four Parts\7f86727
+Node: Sample Beginning\7f88197
+Node: Header\7f89817
+Node: First Line\7f91169
+Node: Start of Header\7f92158
+Node: setfilename\7f92872
+Node: settitle\7f94808
+Node: setchapternewpage\7f96698
+Node: paragraphindent\7f99459
+Node: End of Header\7f100941
+Node: Info Summary and Permissions\7f101780
+Node: Titlepage & Copyright Page\7f102799
+Node: titlepage\7f104405
+Node: titlepage-Footnotes\7f106686
+Node: titlefont center sp\7f107026
+Node: title subtitle author\7f108252
+Node: Copyright & Permissions\7f110524
+Node: end titlepage\7f112525
+Node: headings on off\7f114231
+Node: The Top Node\7f116276
+Node: Title of Top Node\7f117431
+Node: Master Menu Parts\7f118684
+Node: Software Copying Permissions\7f120921
+Node: Ending a File\7f122089
+Node: Printing Indices & Menus\7f122937
+Node: Contents\7f125239
+Node: File End\7f127579
+Node: Structuring\7f128252
+Node: Tree Structuring\7f129910
+Node: Structuring Command Types\7f131353
+Node: makeinfo top\7f133679
+Node: chapter\7f134212
+Node: unnumbered & appendix\7f135236
+Node: majorheading & chapheading\7f136075
+Node: section\7f136896
+Node: unnumberedsec appendixsec heading\7f137660
+Node: subsection\7f138649
+Node: unnumberedsubsec appendixsubsec subheading\7f139221
+Node: subsubsection\7f140174
+Node: Raise/lower sections\7f141724
+Node: Nodes\7f143859
+Node: Two Paths\7f144796
+Node: Node Menu Illustration\7f146082
+Node: node\7f149777
+Node: Node Names\7f152473
+Node: Writing a Node\7f153549
+Node: Node Line Tips\7f155567
+Node: Node Line Requirements\7f156361
+Node: First Node\7f157962
+Node: makeinfo top command\7f159408
+Node: Top Node Summary\7f160587
+Node: makeinfo Pointer Creation\7f162037
+Node: Menus\7f163284
+Node: Menus-Footnotes\7f164222
+Node: Menu Location\7f164573
+Node: Writing a Menu\7f166250
+Node: Menu Parts\7f167216
+Node: Less Cluttered Menu Entry\7f168374
+Node: Menu Example\7f168999
+Node: Other Info Files\7f170520
+Node: Cross References\7f172376
+Node: References\7f173333
+Node: Cross Reference Commands\7f175080
+Node: Cross Reference Parts\7f176139
+Node: xref\7f178975
+Node: Reference Syntax\7f179774
+Node: One Argument\7f181429
+Node: Two Arguments\7f182441
+Node: Three Arguments\7f183556
+Node: Four and Five Arguments\7f185947
+Node: Top Node Naming\7f188359
+Node: ref\7f189369
+Node: pxref\7f190759
+Node: inforef\7f193141
+Node: uref\7f194434
+Node: Marking Text\7f195433
+Node: Indicating\7f196057
+Node: Useful Highlighting\7f197962
+Node: code\7f199351
+Node: kbd\7f202389
+Node: key\7f204259
+Node: samp\7f205592
+Node: var\7f207179
+Node: file\7f208972
+Node: dfn\7f209579
+Node: cite\7f210489
+Node: url\7f210943
+Node: email\7f211507
+Node: Emphasis\7f212319
+Node: emph & strong\7f213219
+Node: Smallcaps\7f214205
+Node: Fonts\7f215532
+Node: Customized Highlighting\7f216620
+Node: Customized Highlighting-Footnotes\7f219434
+Node: Quotations and Examples\7f219654
+Node: Block Enclosing Commands\7f221276
+Node: quotation\7f223301
+Node: example\7f224391
+Node: noindent\7f226446
+Node: Lisp Example\7f227911
+Node: Lisp Example-Footnotes\7f228612
+Node: smallexample & smalllisp\7f228802
+Node: display\7f230827
+Node: format\7f231459
+Node: exdent\7f231920
+Node: flushleft & flushright\7f233000
+Node: cartouche\7f234266
+Node: Lists and Tables\7f235033
+Node: Introducing Lists\7f235709
+Node: itemize\7f237371
+Node: enumerate\7f239518
+Node: Two-column Tables\7f242017
+Node: table\7f242706
+Node: ftable vtable\7f245140
+Node: itemx\7f246241
+Node: Multi-column Tables\7f247252
+Node: Multitable Column Widths\7f247923
+Node: Multitable Rows\7f249377
+Node: Indices\7f251250
+Node: Index Entries\7f252401
+Node: Predefined Indices\7f253534
+Node: Indexing Commands\7f254531
+Node: Combining Indices\7f259072
+Node: syncodeindex\7f260435
+Node: synindex\7f262097
+Node: New Indices\7f262622
+Node: Insertions\7f264448
+Node: Braces Atsigns\7f265632
+Node: Inserting An Atsign\7f266184
+Node: Inserting Braces\7f266458
+Node: Inserting Space\7f266821
+Node: Not Ending a Sentence\7f267325
+Node: Ending a Sentence\7f268679
+Node: Multiple Spaces\7f269808
+Node: dmn\7f271028
+Node: Inserting Accents\7f272236
+Node: Dots Bullets\7f274212
+Node: dots\7f275035
+Node: bullet\7f275559
+Node: TeX and copyright\7f275956
+Node: tex\7f276523
+Node: copyright symbol\7f276939
+Node: pounds\7f277199
+Node: minus\7f277563
+Node: math\7f278485
+Node: Glyphs\7f279214
+Node: Glyphs Summary\7f280327
+Node: result\7f280955
+Node: expansion\7f281440
+Node: Print Glyph\7f282396
+Node: Error Glyph\7f283273
+Node: Equivalence\7f284106
+Node: Point Glyph\7f284794
+Node: Images\7f286351
+Node: Breaks\7f288018
+Node: Break Commands\7f289449
+Node: Line Breaks\7f290290
+Node: - and hyphenation\7f291308
+Node: w\7f292559
+Node: sp\7f293272
+Node: page\7f293681
+Node: group\7f294058
+Node: need\7f295801
+Node: Definition Commands\7f296531
+Node: Def Cmd Template\7f298102
+Node: Optional Arguments\7f301099
+Node: deffnx\7f302687
+Node: Def Cmds in Detail\7f303642
+Node: Functions Commands\7f304752
+Node: Variables Commands\7f307757
+Node: Typed Functions\7f309843
+Node: Typed Variables\7f313385
+Node: Abstract Objects\7f315368
+Node: Data Types\7f320593
+Node: Def Cmd Conventions\7f321848
+Node: Sample Function Definition\7f322411
+Node: Footnotes\7f325295
+Node: Footnotes-Footnotes\7f325682
+Node: Footnote Commands\7f326028
+Node: Footnote Commands-Footnotes\7f327524
+Node: Footnote Styles\7f327642
+Node: Conditionals\7f330228
+Node: Conditional Commands\7f331039
+Node: Conditional Not Commands\7f332532
+Node: Raw Formatter Commands\7f333277
+Node: set clear value\7f335107
+Node: ifset ifclear\7f335908
+Node: value\7f339087
+Node: value Example\7f340499
+Node: Macros\7f342077
+Node: Defining Macros\7f342783
+Node: Invoking Macros\7f343872
+Node: Format/Print Hardcopy\7f344978
+Node: Use TeX\7f346815
+Node: Format with tex/texindex\7f347443
+Node: Format with texi2dvi\7f351086
+Node: Print with lpr\7f351677
+Node: Within Emacs\7f352531
+Node: Texinfo Mode Printing\7f353450
+Node: Compile-Command\7f356860
+Node: Requirements Summary\7f357748
+Node: Preparing for TeX\7f359061
+Node: Overfull hboxes\7f361850
+Node: smallbook\7f363409
+Node: A4 Paper\7f364929
+Node: Cropmarks and Magnification\7f366155
+Node: Create an Info File\7f368097
+Node: makeinfo advantages\7f369400
+Node: Invoking makeinfo\7f370316
+Node: makeinfo options\7f371004
+Node: Pointer Validation\7f376493
+Node: makeinfo in Emacs\7f377837
+Node: texinfo-format commands\7f380395
+Node: Batch Formatting\7f381667
+Node: Tag and Split Files\7f382883
+Node: Install an Info File\7f386237
+Node: Directory file\7f387055
+Node: New Info File\7f388923
+Node: Other Info Directories\7f389984
+Node: Installing Dir Entries\7f393199
+Node: Invoking install-info\7f395192
+Node: Command List\7f397607
+Node: Tips\7f435577
+Node: Sample Texinfo File\7f446987
+Node: Sample Permissions\7f449105
+Node: Inserting Permissions\7f450148
+Node: ifinfo Permissions\7f452454
+Node: Titlepage Permissions\7f454075
+Node: Include Files\7f455337
+Node: Using Include Files\7f456424
+Node: texinfo-multiple-files-update\7f458379
+Node: Include File Requirements\7f460740
+Node: Sample Include File\7f461985
+Node: Include Files Evolution\7f463504
+Node: Headings\7f465475
+Node: Headings Introduced\7f466112
+Node: Heading Format\7f468000
+Node: Heading Choice\7f470452
+Node: Custom Headings\7f471824
+Node: Catching Mistakes\7f476152
+Node: makeinfo Preferred\7f477441
+Node: Debugging with Info\7f478346
+Node: Debugging with TeX\7f481692
+Node: Using texinfo-show-structure\7f485973
+Node: Using occur\7f489072
+Node: Running Info-Validate\7f490609
+Node: Using Info-validate\7f491670
+Node: Unsplit\7f493512
+Node: Tagifying\7f494558
+Node: Splitting\7f495410
+Node: Refilling Paragraphs\7f497026
+Node: Refilling Paragraphs-Footnotes\7f498679
+Node: Command Syntax\7f498930
+Node: Obtaining TeX\7f501887
+Node: Command and Variable Index\7f503999
+Node: Concept Index\7f519851
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
+
+Texinfo
+*******
+
+ Texinfo is a documentation system that uses a single source file to
+produce both on-line information and printed output.
+
+ The first part of this master menu lists the major nodes in this Info
+document, including the @-command and concept indices. The rest of the
+menu lists all the lower level nodes in the document.
+
+ This is Edition 3.12 of the Texinfo documentation, 27 February 1998.
+
+* Menu:
+
+* Copying:: Your rights.
+* Overview:: Texinfo in brief.
+* Texinfo Mode:: How to use Texinfo mode.
+* Beginning a File:: What is at the beginning of a Texinfo file?
+* Ending a File:: What is at the end of a Texinfo file?
+* Structuring:: How to create chapters, sections, subsections,
+ appendices, and other parts.
+* Nodes:: How to write nodes.
+* Menus:: How to write menus.
+* Cross References:: How to write cross references.
+* Marking Text:: How to mark words and phrases as code,
+ keyboard input, meta-syntactic
+ variables, and the like.
+* Quotations and Examples:: How to write quotations, examples, etc.
+* Lists and Tables:: How to write lists and tables.
+* Indices:: How to create indices.
+* Insertions:: How to insert @-signs, braces, etc.
+* Breaks:: How to force and prevent line and page breaks.
+* Definition Commands:: How to describe functions and the like
+ in a uniform manner.
+* Footnotes:: How to write footnotes.
+* Conditionals:: How to specify text for either TeX or Info.
+* Macros:: Defining new Texinfo commands.
+* Format/Print Hardcopy:: How to convert a Texinfo file to a file
+ for printing and how to print that file.
+* Create an Info File:: Convert a Texinfo file into an Info file.
+* Install an Info File:: Make an Info file accessible to users.
+* Command List:: All the Texinfo @-commands.
+* Tips:: Hints on how to write a Texinfo document.
+* Sample Texinfo File:: A sample Texinfo file to look at.
+* Sample Permissions:: Tell readers they have the right to copy
+ and distribute.
+* Include Files:: How to incorporate other Texinfo files.
+* Headings:: How to write page headings and footings.
+* Catching Mistakes:: How to find formatting mistakes.
+* Refilling Paragraphs:: All about paragraph refilling.
+* Command Syntax:: A description of @-Command syntax.
+* Obtaining TeX:: How to Obtain TeX.
+* Command and Variable Index:: A menu containing commands and variables.
+* Concept Index:: A menu covering many topics.
+
+
+ -- The Detailed Node Listing --
+
+Overview of Texinfo
+
+* Using Texinfo:: Create a conventional printed book
+ or an Info file.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @-commands are used for formatting.
+* Conventions:: General rules for writing a Texinfo file.
+* Comments:: How to write comments and mark regions that
+ the formatting commands will ignore.
+* Minimum:: What a Texinfo file must have.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* Acknowledgements::
+
+Using Texinfo Mode
+
+* Texinfo Mode Overview:: How Texinfo mode can help you.
+* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
+ purpose editing features.
+* Inserting:: How to insert frequently used @-commands.
+* Showing the Structure:: How to show the structure of a file.
+* Updating Nodes and Menus:: How to update or create new nodes and menus.
+* Info Formatting:: How to format for Info.
+* Printing:: How to format and print part or all of a file.
+* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
+
+Updating Nodes and Menus
+
+* Updating Commands:: Five major updating commands.
+* Updating Requirements:: How to structure a Texinfo file for
+ using the updating command.
+* Other Updating Commands:: How to indent descriptions, insert
+ missing nodes lines, and update
+ nodes in sequence.
+
+Beginning a Texinfo File
+
+* Four Parts:: Four parts begin a Texinfo file.
+* Sample Beginning:: Here is a sample beginning for a Texinfo file.
+* Header:: The very beginning of a Texinfo file.
+* Info Summary and Permissions:: Summary and copying permissions for Info.
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* The Top Node:: Creating the `Top' node and master menu.
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
+
+The Texinfo File Header
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: An option to specify paragraph indentation.
+* End of Header:: Formatting a region requires this.
+
+The Title and Copyright Pages
+
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The `@titlefont', `@center',
+ and `@sp' commands.
+* title subtitle author:: The `@title', `@subtitle',
+ and `@author' commands.
+* Copyright & Permissions:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
+
+The `Top' Node and Master Menu
+
+* Title of Top Node:: Sketch what the file is about.
+* Master Menu Parts:: A master menu has three or more parts.
+
+Ending a Texinfo File
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
+
+Chapter Structuring
+
+* Tree Structuring:: A manual is like an upside down tree ...
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The `@top' command, part of the `Top' node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+Nodes
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: How to write a node, in detail.
+* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
+
+The `@node' Command
+
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an `@node' line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the `@top' command.
+* Top Node Summary:: Write a brief description for readers.
+
+Menus
+
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+Cross References
+
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* xref:: Begin a reference with `See' ...
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
+
+`@xref'
+
+* Reference Syntax:: What a reference looks like and requires.
+* One Argument:: `@xref' with one argument.
+* Two Arguments:: `@xref' with two arguments.
+* Three Arguments:: `@xref' with three arguments.
+* Four and Five Arguments:: `@xref' with four and five arguments.
+
+Marking Words and Phrases
+
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
+
+Indicating Definitions, Commands, etc.
+
+* Useful Highlighting:: Highlighting provides useful information.
+* code:: How to indicate code.
+* kbd:: How to show keyboard input.
+* key:: How to specify keys.
+* samp:: How to show a literal sequence of characters.
+* var:: How to indicate a metasyntactic variable.
+* file:: How to indicate the name of a file.
+* dfn:: How to specify a definition.
+* cite:: How to refer to a book that is not in Info.
+* url:: How to indicate a world wide web reference.
+* email:: How to indicate an electronic mail address.
+
+Emphasizing Text
+
+* emph & strong:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
+* Customized Highlighting:: How to define highlighting commands.
+
+Quotations and Examples
+
+* Block Enclosing Commands:: Use different constructs for
+ different purposes.
+* quotation:: How to write a quotation.
+* example:: How to write an example in a fixed-width font.
+* noindent:: How to prevent paragraph indentation.
+* Lisp Example:: How to illustrate Lisp code.
+* smallexample & smalllisp:: Forms for the `@smallbook' option.
+* display:: How to write an example in the current font.
+* format:: How to write an example that does not narrow
+ the margins.
+* exdent:: How to undo the indentation of a line.
+* flushleft & flushright:: How to push text flushleft or flushright.
+* cartouche:: How to draw cartouches around examples.
+
+Lists and Tables
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* enumerate:: How to construct a numbered list.
+* Two-column Tables:: How to construct a two-column table.
+* Multi-column Tables:: How to construct generalized tables.
+
+Making a Two-column Table
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+Multi-column Tables
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+Creating Indices
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+Combining Indices
+
+* syncodeindex:: How to merge two indices, using `@code'
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
+
+Special Insertions
+
+* Braces Atsigns:: How to insert braces, `@'.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the TeX logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Images:: How to include graphics.
+
+Inserting @ and Braces
+
+* Inserting An Atsign:: How to insert `@'.
+* Inserting Braces:: How to insert `{' and `}'.
+
+Inserting Space
+
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
+
+Inserting Ellipsis, Dots, and Bullets
+
+* dots:: How to insert dots ...
+* bullet:: How to insert a bullet.
+
+Inserting TeX and the Copyright Symbol
+
+* tex:: How to insert the TeX logo.
+* copyright symbol:: How to use `@copyright'{}.
+
+Glyphs for Examples
+
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
+
+Glyphs Summary
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+Making and Preventing Breaks
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell TeX about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+Definition Commands
+
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
+
+The Definition Commands
+
+* Functions Commands:: Commands for functions and similar entities.
+* Variables Commands:: Commands for variables and similar entities.
+* Typed Functions:: Commands for functions in typed languages.
+* Typed Variables:: Commands for variables in typed languages.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
+
+Footnotes
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+Conditionally Visible Text
+
+* Conditional Commands:: Specifying text for HTML, Info, or TeX.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
+* Raw Formatter Commands:: Using raw TeX or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
+
+`@set', `@clear', and `@value'
+
+* ifset ifclear:: Format a region if a flag is set.
+* value:: Replace a flag with a string.
+* value Example:: An easy way to update edition information.
+
+Macros: Defining New Texinfo Commands
+
+* Defining Macros:: Both defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+
+Format and Print Hardcopy
+
+* Use TeX:: Use TeX to format for hardcopy.
+* Format with tex/texindex:: How to format in a shell.
+* Format with texi2dvi:: A simpler way to use the shell.
+* Print with lpr:: How to print.
+* Within Emacs:: How to format and print from an Emacs shell.
+* Texinfo Mode Printing:: How to format and print in Texinfo mode.
+* Compile-Command:: How to print using Emacs's compile command.
+* Requirements Summary:: TeX formatting requirements summary.
+* Preparing for TeX:: What you need to do to use TeX.
+* Overfull hboxes:: What are and what to do with overfull hboxes.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on European A4 paper.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
+
+Creating an Info File
+
+* makeinfo advantages:: `makeinfo' provides better error checking.
+* Invoking makeinfo:: How to run `makeinfo' from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run `makeinfo' from Emacs.
+* texinfo-format commands:: Two Info formatting commands written
+ in Emacs Lisp are an alternative
+ to `makeinfo'.
+* Batch Formatting:: How to format for Info in Emacs Batch mode.
+* Tag and Split Files:: How tagged and split files help Info
+ to run better.
+
+Installing an Info File
+
+* Directory file:: The top level menu for all Info files.
+* New Info File:: Listing a new info file.
+* Other Info Directories:: How to specify Info files that are
+ located in other directories.
+* Installing Dir Entries:: How to specify what menu entry to add
+ to the Info directory.
+* Invoking install-info:: `install-info' options.
+
+Sample Permissions
+
+* Inserting Permissions:: How to put permissions in your document.
+* ifinfo Permissions:: Sample `ifinfo' copying permissions.
+* Titlepage Permissions:: Sample Titlepage copying permissions.
+
+Include Files
+
+* Using Include Files:: How to use the `@include' command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What `texinfo-multiple-files-update' expects.
+* Sample Include File:: A sample outer file with included files
+ within it; and a sample included file.
+* Include Files Evolution:: How use of the `@include' command
+ has changed over time.
+
+Page Headings
+
+* Headings Introduced:: Conventions for using page headings.
+* Heading Format:: Standard page heading formats.
+* Heading Choice:: How to specify the type of page heading.
+* Custom Headings:: How to create your own headings and footings.
+
+Formatting Mistakes
+
+* makeinfo Preferred:: `makeinfo' finds errors.
+* Debugging with Info:: How to catch errors with Info formatting.
+* Debugging with TeX:: How to catch errors with TeX formatting.
+* Using texinfo-show-structure:: How to use `texinfo-show-structure'.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
+
+Finding Badly Referenced Nodes
+
+* Using Info-validate:: How to run `Info-validate'.
+* Unsplit:: How to create an unsplit file.
+* Tagifying:: How to tagify a file.
+* Splitting:: How to split a file manually.
+
+How to Obtain TeX
+
+\1f
+File: texinfo.info, Node: Copying, Next: Overview, Prev: Top, Up: Top
+
+Texinfo Copying Conditions
+**************************
+
+ The programs currently being distributed that relate to Texinfo
+include portions of GNU Emacs, plus other separate programs (including
+`makeinfo', `info', `texindex', and `texinfo.tex'). These programs are
+"free"; this means that everyone is free to use them and free to
+redistribute them on a free basis. The Texinfo-related programs are
+not in the public domain; they are copyrighted and there are
+restrictions on their distribution, but these restrictions are designed
+to permit everything that a good cooperating citizen would want to do.
+What is not allowed is to try to prevent others from further sharing
+any version of these programs that they might get from you.
+
+ Specifically, we want to make sure that you have the right to give
+away copies of the programs that relate to Texinfo, that you receive
+source code or else can get it if you want it, that you can change these
+programs or use pieces of them in new free programs, and that you know
+you can do these things.
+
+ To make sure that everyone has such rights, we have to forbid you to
+deprive anyone else of these rights. For example, if you distribute
+copies of the Texinfo related programs, you must give the recipients all
+the rights that you have. You must make sure that they, too, receive or
+can get the source code. And you must tell them their rights.
+
+ Also, for our own protection, we must make certain that everyone finds
+out that there is no warranty for the programs that relate to Texinfo.
+If these programs are modified by someone else and passed on, we want
+their recipients to know that what they have is not what we distributed,
+so that any problems introduced by others will not reflect on our
+reputation.
+
+ The precise conditions of the licenses for the programs currently
+being distributed that relate to Texinfo are found in the General Public
+Licenses that accompany them.
+
+\1f
+File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: Top
+
+Overview of Texinfo
+*******************
+
+ "Texinfo"(1) (*note Overview-Footnotes::) is a documentation system
+that uses a single source file to produce both on-line information and
+printed output. This means that instead of writing two different
+documents, one for the on-line help or other on-line information and
+the other for a typeset manual or other printed work, you need write
+only one document. When the work is revised, you need revise only one
+document. (You can read the on-line information, known as an "Info
+file", with an Info documentation-reading program.)
+
+* Menu:
+
+* Using Texinfo:: Create a conventional printed book
+ or an Info file.
+* Info Files:: What is an Info file?
+* Printed Books:: Characteristics of a printed book or manual.
+* Formatting Commands:: @-commands are used for formatting.
+* Conventions:: General rules for writing a Texinfo file.
+* Comments:: How to write comments and mark regions that
+ the formatting commands will ignore.
+* Minimum:: What a Texinfo file must have.
+* Six Parts:: Usually, a Texinfo file has six parts.
+* Short Sample:: A short sample Texinfo file.
+* Acknowledgements::
+
+\1f
+File: texinfo.info, Node: Overview-Footnotes, Up: Overview
+
+ (1) Note that the first syllable of "Texinfo" is pronounced like
+"speck", not "hex". This odd pronunciation is derived from, but is not
+the same as, the pronunciation of TeX. In the word TeX, the `X' is
+actually the Greek letter "chi" rather than the English letter "ex".
+Pronounce TeX as if the `X' were the last sound in the name `Bach'; but
+pronounce Texinfo as if the `x' were a `k'. Spell "Texinfo" with a
+capital "T" and write the other letters in lower case.
+
+\1f
+File: texinfo.info, Node: Using Texinfo, Next: Info Files, Prev: Overview, Up: Overview
+
+Using Texinfo
+=============
+
+ Using Texinfo, you can create a printed document with the normal
+features of a book, including chapters, sections, cross references, and
+indices. From the same Texinfo source file, you can create a
+menu-driven, on-line Info file with nodes, menus, cross references, and
+indices. You can, if you wish, make the chapters and sections of the
+printed document correspond to the nodes of the on-line information;
+and you use the same cross references and indices for both the Info
+file and the printed work. `The GNU Emacs Manual' is a good example of
+a Texinfo file, as is this manual.
+
+ To make a printed document, you process a Texinfo source file with the
+TeX typesetting program. This creates a DVI file that you can typeset
+and print as a book or report. (Note that the Texinfo language is
+completely different from TeX's usual language, plain TeX.) If you do
+not have TeX, but do have `troff' or `nroff', you can use the
+`texi2roff' program instead.
+
+ To make an Info file, you process a Texinfo source file with the
+`makeinfo' utility or Emacs's `texinfo-format-buffer' command; this
+creates an Info file that you can install on-line.
+
+ TeX and `texi2roff' work with many types of printers; similarly, Info
+works with almost every type of computer terminal. This power makes
+Texinfo a general purpose system, but brings with it a constraint,
+which is that a Texinfo file may contain only the customary
+"typewriter" characters (letters, numbers, spaces, and punctuation
+marks) but no special graphics.
+
+ A Texinfo file is a plain ASCII file containing text and "@-commands"
+(words preceded by an `@') that tell the typesetting and formatting
+programs what to do. You may edit a Texinfo file with any text editor;
+but it is especially convenient to use GNU Emacs since that editor has
+a special mode, called Texinfo mode, that provides various
+Texinfo-related features. (*Note Texinfo Mode::.)
+
+ Before writing a Texinfo source file, you should become familiar with
+the Info documentation reading program and learn about nodes, menus,
+cross references, and the rest. (*note info: (info)Top, for more
+information.)
+
+ You can use Texinfo to create both on-line help and printed manuals;
+moreover, Texinfo is freely redistributable. For these reasons, Texinfo
+is the format in which documentation for GNU utilities and libraries is
+written.
+
+\1f
+File: texinfo.info, Node: Info Files, Next: Printed Books, Prev: Using Texinfo, Up: Overview
+
+Info files
+==========
+
+ An Info file is a Texinfo file formatted so that the Info
+documentation reading program can operate on it. (`makeinfo' and
+`texinfo-format-buffer' are two commands that convert a Texinfo file
+into an Info file.)
+
+ Info files are divided into pieces called "nodes", each of which
+contains the discussion of one topic. Each node has a name, and
+contains both text for the user to read and pointers to other nodes,
+which are identified by their names. The Info program displays one node
+at a time, and provides commands with which the user can move to other
+related nodes.
+
+ *note info: (info)Top, for more information about using Info.
+
+ Each node of an Info file may have any number of child nodes that
+describe subtopics of the node's topic. The names of child nodes are
+listed in a "menu" within the parent node; this allows you to use
+certain Info commands to move to one of the child nodes. Generally, an
+Info file is organized like a book. If a node is at the logical level
+of a chapter, its child nodes are at the level of sections; likewise,
+the child nodes of sections are at the level of subsections.
+
+ All the children of any one parent are linked together in a
+bidirectional chain of `Next' and `Previous' pointers. The `Next'
+pointer provides a link to the next section, and the `Previous' pointer
+provides a link to the previous section. This means that all the nodes
+that are at the level of sections within a chapter are linked together.
+Normally the order in this chain is the same as the order of the
+children in the parent's menu. Each child node records the parent node
+name as its `Up' pointer. The last child has no `Next' pointer, and the
+first child has the parent both as its `Previous' and as its `Up'
+pointer.(1) (*note Info Files-Footnotes::)
+
+ The book-like structuring of an Info file into nodes that correspond
+to chapters, sections, and the like is a matter of convention, not a
+requirement. The `Up', `Previous', and `Next' pointers of a node can
+point to any other nodes, and a menu can contain any other nodes.
+Thus, the node structure can be any directed graph. But it is usually
+more comprehensible to follow a structure that corresponds to the
+structure of chapters and sections in a printed book or report.
+
+ In addition to menus and to `Next', `Previous', and `Up' pointers,
+Info provides pointers of another kind, called references, that can be
+sprinkled throughout the text. This is usually the best way to
+represent links that do not fit a hierarchical structure.
+
+ Usually, you will design a document so that its nodes match the
+structure of chapters and sections in the printed output. But
+occasionally there are times when this is not right for the material
+being discussed. Therefore, Texinfo uses separate commands to specify
+the node structure for the Info file and the section structure for the
+printed output.
+
+ Generally, you enter an Info file through a node that by convention is
+named `Top'. This node normally contains just a brief summary of the
+file's purpose, and a large menu through which the rest of the file is
+reached. From this node, you can either traverse the file
+systematically by going from node to node, or you can go to a specific
+node listed in the main menu, or you can search the index menus and then
+go directly to the node that has the information you want.
+Alternatively, with the standalone Info program, you can specify
+specific menu items on the command line (*note Top: (info)Top.).
+
+ If you want to read through an Info file in sequence, as if it were a
+printed manual, you can hit <SPC> repeatedly, or you get the whole file
+with the advanced Info command `g *'. (*note Advanced Info commands:
+(info)Expert.)
+
+ The `dir' file in the `info' directory serves as the departure point
+for the whole Info system. From it, you can reach the `Top' nodes of
+each of the documents in a complete Info system.
+
+\1f
+File: texinfo.info, Node: Info Files-Footnotes, Up: Info Files
+
+ (1) In some documents, the first child has no `Previous' pointer.
+Occasionally, the last child has the node name of the next following
+higher level node as its `Next' pointer.
+
+\1f
+File: texinfo.info, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview
+
+Printed Books
+=============
+
+ A Texinfo file can be formatted and typeset as a printed book or
+manual. To do this, you need TeX, a powerful, sophisticated typesetting
+program written by Donald Knuth.(1) (*note Printed Books-Footnotes::)
+
+ A Texinfo-based book is similar to any other typeset, printed work: it
+can have a title page, copyright page, table of contents, and preface,
+as well as chapters, numbered or unnumbered sections and subsections,
+page headers, cross references, footnotes, and indices.
+
+ You can use Texinfo to write a book without ever having the intention
+of converting it into on-line information. You can use Texinfo for
+writing a printed novel, and even to write a printed memo, although
+this latter application is not recommended since electronic mail is so
+much easier.
+
+ TeX is a general purpose typesetting program. Texinfo provides a
+file called `texinfo.tex' that contains information (definitions or
+"macros") that TeX uses when it typesets a Texinfo file.
+(`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX
+commands, which TeX can then process to create the typeset document.)
+`texinfo.tex' contains the specifications for printing a document.
+
+ Most often, documents are printed on 8.5 inch by 11 inch pages (216mm
+by 280mm; this is the default size), but you can also print for 7 inch
+by 9.25 inch pages (178mm by 235mm; the `@smallbook' size) or on
+European A4 size paper (`@afourpaper'). (*Note Printing "Small" Books:
+smallbook. Also, see *Note Printing on A4 Paper: A4 Paper.)
+
+ By changing the parameters in `texinfo.tex', you can change the size
+of the printed document. In addition, you can change the style in
+which the printed document is formatted; for example, you can change the
+sizes and fonts used, the amount of indentation for each paragraph, the
+degree to which words are hyphenated, and the like. By changing the
+specifications, you can make a book look dignified, old and serious, or
+light-hearted, young and cheery.
+
+ TeX is freely distributable. It is written in a superset of Pascal
+called WEB and can be compiled either in Pascal or (by using a
+conversion program that comes with the TeX distribution) in C. (*Note
+TeX Mode: (xemacs)TeX Mode, for information about TeX.)
+
+ TeX is very powerful and has a great many features. Because a
+Texinfo file must be able to present information both on a
+character-only terminal in Info form and in a typeset book, the
+formatting commands that Texinfo supports are necessarily limited.
+
+ *Note How to Obtain TeX: Obtaining TeX.
+
+\1f
+File: texinfo.info, Node: Printed Books-Footnotes, Up: Printed Books
+
+ (1) You can also use the `texi2roff' program if you do not have TeX;
+since Texinfo is designed for use with TeX, `texi2roff' is not
+described here. `texi2roff' is not part of the standard GNU
+distribution.
+
+\1f
+File: texinfo.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview
+
+@-commands
+==========
+
+ In a Texinfo file, the commands that tell TeX how to typeset the
+printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
+create an Info file are preceded by `@'; they are called "@-commands".
+For example, `@node' is the command to indicate a node and `@chapter'
+is the command to indicate the start of a chapter.
+
+ *Please note:* All the @-commands, with the exception of the
+ `@TeX{}' command, must be written entirely in lower case.
+
+ The Texinfo @-commands are a strictly limited set of constructs. The
+strict limits make it possible for Texinfo files to be understood both
+by TeX and by the code that converts them into Info files. You can
+display Info files on any terminal that displays alphabetic and numeric
+characters. Similarly, you can print the output generated by TeX on a
+wide variety of printers.
+
+ Depending on what they do or what arguments(1) (*note Formatting
+Commands-Footnotes::) they take, you need to write @-commands on lines
+of their own or as part of sentences:
+
+ * Write a command such as `@noindent' at the beginning of a line as
+ the only text on the line. (`@noindent' prevents the beginning of
+ the next line from being indented as the beginning of a paragraph.)
+
+ * Write a command such as `@chapter' at the beginning of a line
+ followed by the command's arguments, in this case the chapter
+ title, on the rest of the line. (`@chapter' creates chapter
+ titles.)
+
+ * Write a command such as `@dots{}' wherever you wish but usually
+ within a sentence. (`@dots{}' creates dots ...)
+
+ * Write a command such as `@code{SAMPLE-CODE}' wherever you wish
+ (but usually within a sentence) with its argument, SAMPLE-CODE in
+ this example, between the braces. (`@code' marks text as being
+ code.)
+
+ * Write a command such as `@example' at the beginning of a line of
+ its own; write the body-text on following lines; and write the
+ matching `@end' command, `@end example' in this case, at the
+ beginning of a line of its own after the body-text. (`@example'
+ ... `@end example' indents and typesets body-text as an example.)
+
+As a general rule, a command requires braces if it mingles among other
+text; but it does not need braces if it starts a line of its own. The
+non-alphabetic commands, such as `@:', are exceptions to the rule; they
+do not need braces.
+
+ As you gain experience with Texinfo, you will rapidly learn how to
+write the different commands: the different ways to write commands make
+it easier to write and read Texinfo files than if all commands followed
+exactly the same syntax. (For details about @-command syntax, see
+*Note @-Command Syntax: Command Syntax.)
+
+\1f
+File: texinfo.info, Node: Formatting Commands-Footnotes, Up: Formatting Commands
+
+ (1) The word "argument" comes from the way it is used in mathematics
+and does not refer to a disputation between two people; it refers to the
+information presented to the command. According to the `Oxford English
+Dictionary', the word derives from the Latin for "to make clear,
+prove"; thus it came to mean `the evidence offered as proof', which is
+to say, `the information offered', which led to its mathematical
+meaning. In its other thread of derivation, the word came to mean `to
+assert in a manner against which others may make counter assertions',
+which led to the meaning of `argument' as a disputation.
+
+\1f
+File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview
+
+General Syntactic Conventions
+=============================
+
+ All printable ASCII characters except `@', `{' and `}' can appear in
+a Texinfo file and stand for themselves. `@' is the escape character
+which introduces commands. `{' and `}' should be used only to surround
+arguments to certain commands. To put one of these special characters
+into the document, put an `@' character in front of it, like this:
+`@@', `@{', and `@}'.
+
+ It is customary in TeX to use doubled single-quote characters to
+begin and end quotations: ` ` and ' ' (but without a space between the
+two single-quote characters). This convention should be followed in
+Texinfo files. TeX converts doubled single-quote characters to left-
+and right-hand doubled quotation marks and Info converts doubled
+single-quote characters to ASCII double-quotes: ` ` and ' ' to " .
+
+ Use three hyphens in a row, `---', for a dash--like this. In TeX, a
+single or double hyphen produces a printed dash that is shorter than
+the usual typeset dash. Info reduces three hyphens to two for display
+on the screen.
+
+ To prevent a paragraph from being indented in the printed manual, put
+the command `@noindent' on a line by itself before the paragraph.
+
+ If you mark off a region of the Texinfo file with the `@iftex' and
+`@end iftex' commands, that region will appear only in the printed
+copy; in that region, you can use certain commands borrowed from plain
+TeX that you cannot use in Info. Likewise, if you mark off a region
+with the `@ifinfo' and `@end ifinfo' commands, that region will appear
+only in the Info file; in that region, you can use Info commands that
+you cannot use in TeX. Similarly for `@ifhtml ... @end ifhtml',
+`@ifnothtml ... @end ifnothtml', `@ifnotinfo ... @end ifnotinfo',
+`@ifnottex ... @end ifnottex', *Note Conditionals::.
+
+ *Caution:* Do not use tabs in a Texinfo file! TeX uses
+ variable-width fonts, which means that it cannot predefine a tab
+ to work in all circumstances. Consequently, TeX treats tabs like
+ single spaces, and that is not what they look like. Furthermore,
+ `makeinfo' does nothing special with tabs, and thus a tab character
+ in your input file may appear differently in the output.
+
+ To avoid this problem, Texinfo mode causes GNU Emacs to insert
+ multiple spaces when you press the <TAB> key.
+
+ Also, you can run `untabify' in Emacs to convert tabs in a region
+ to multiple spaces.
+
+ Don't use tabs.
+
+\1f
+File: texinfo.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview
+
+Comments
+========
+
+ You can write comments in a Texinfo file that will not appear in
+either the Info file or the printed manual by using the `@comment'
+command (which may be abbreviated to `@c'). Such comments are for the
+person who reads the Texinfo file. All the text on a line that follows
+either `@comment' or `@c' is a comment; the rest of the line does not
+appear in either the Info file or the printed manual. (Often, you can
+write the `@comment' or `@c' in the middle of a line, and only the text
+that follows after the `@comment' or `@c' command does not appear; but
+some commands, such as `@settitle' and `@setfilename', work on a whole
+line. You cannot use `@comment' or `@c' in a line beginning with such
+a command.)
+
+ You can write long stretches of text that will not appear in either
+the Info file or the printed manual by using the `@ignore' and `@end
+ignore' commands. Write each of these commands on a line of its own,
+starting each command at the beginning of the line. Text between these
+two commands does not appear in the processed output. You can use
+`@ignore' and `@end ignore' for writing comments. Often, `@ignore' and
+`@end ignore' is used to enclose a part of the copying permissions that
+applies to the Texinfo source file of a document, but not to the Info
+or printed version of the document.
+
+\1f
+File: texinfo.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview
+
+What a Texinfo File Must Have
+=============================
+
+ By convention, the names of Texinfo files end with one of the
+extensions `.texinfo', `.texi', or `.tex'. The longer extension is
+preferred since it describes more clearly to a human reader the nature
+of the file. The shorter extensions are for operating systems that
+cannot handle long file names.
+
+ In order to be made into a printed manual and an Info file, a Texinfo
+file *must* begin with lines like this:
+
+ \input texinfo
+ @setfilename INFO-FILE-NAME
+ @settitle NAME-OF-MANUAL
+
+The contents of the file follow this beginning, and then you *must* end
+a Texinfo file with a line like this:
+
+ @bye
+
+The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
+which tells TeX how to translate the Texinfo @-commands into TeX
+typesetting commands. (Note the use of the backslash, `\'; this is
+correct for TeX.) The `@setfilename' line provides a name for the Info
+file and tells TeX to open auxiliary files. The `@settitle' line
+specifies a title for the page headers (or footers) of the printed
+manual.
+
+ The `@bye' line at the end of the file on a line of its own tells the
+formatters that the file is ended and to stop formatting.
+
+ Usually, you will not use quite such a spare format, but will include
+mode setting and start-of-header and end-of-header lines at the
+beginning of a Texinfo file, like this:
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename INFO-FILE-NAME
+ @settitle NAME-OF-MANUAL
+ @c %**end of header
+
+In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
+mode when you edit the file.
+
+ The `@c' lines which surround the `@setfilename' and `@settitle'
+lines are optional, but you need them in order to run TeX or Info on
+just part of the file. (*Note Start of Header::, for more information.)
+
+ Furthermore, you will usually provide a Texinfo file with a title
+page, indices, and the like. But the minimum, which can be useful for
+short documents, is just the three lines at the beginning and the one
+line at the end.
+
+\1f
+File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview
+
+Six Parts of a Texinfo File
+===========================
+
+ Generally, a Texinfo file contains more than the minimal beginning
+and end--it usually contains six parts:
+
+1. Header
+ The "Header" names the file, tells TeX which definitions' file to
+ use, and performs other "housekeeping" tasks.
+
+2. Summary Description and Copyright
+ The "Summary Description and Copyright" segment describes the
+ document and contains the copyright notice and copying permissions
+ for the Info file. The segment must be enclosed between `@ifinfo'
+ and `@end ifinfo' commands so that the formatters place it only in
+ the Info file.
+
+3. Title and Copyright
+ The "Title and Copyright" segment contains the title and copyright
+ pages and copying permissions for the printed manual. The segment
+ must be enclosed between `@titlepage' and `@end titlepage'
+ commands. The title and copyright page appear only in the printed
+ manual.
+
+4. `Top' Node and Master Menu
+ The "Master Menu" contains a complete menu of all the nodes in the
+ whole Info file. It appears only in the Info file, in the `Top'
+ node.
+
+5. Body
+ The "Body" of the document may be structured like a traditional
+ book or encyclopedia or it may be free form.
+
+6. End
+ The "End" contains commands for printing indices and generating
+ the table of contents, and the `@bye' command on a line of its own.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Tips, Next: Sample Texinfo File, Prev: Command List, Up: Top
+
+Tips and Hints
+**************
+
+ Here are some tips for writing Texinfo documentation:
+
+ * Write in the present tense, not in the past or the future.
+
+ * Write actively! For example, write "We recommend that ..." rather
+ than "It is recommended that ...".
+
+ * Use 70 or 72 as your fill column. Longer lines are hard to read.
+
+ * Include a copyright notice and copying permissions.
+
+Index, Index, Index!
+....................
+
+ Write many index entries, in different ways. Readers like indices;
+they are helpful and convenient.
+
+ Although it is easiest to write index entries as you write the body of
+the text, some people prefer to write entries afterwards. In either
+case, write an entry before the paragraph to which it applies. This
+way, an index entry points to the first page of a paragraph that is
+split across pages.
+
+ Here are more hints we have found valuable:
+
+ * Write each index entry differently, so each entry refers to a
+ different place in the document.
+
+ * Write index entries only where a topic is discussed significantly.
+ For example, it is not useful to index "debugging information" in
+ a chapter on reporting bugs. Someone who wants to know about
+ debugging information will certainly not find it in that chapter.
+
+ * Consistently capitalize the first word of every concept index
+ entry, or else consistently use lower case. Terse entries often
+ call for lower case; longer entries for capitalization. Whichever
+ case convention you use, please use one or the other consistently!
+ Mixing the two styles looks bad.
+
+ * Always capitalize or use upper case for those words in an index for
+ which this is proper, such as names of countries or acronyms.
+ Always use the appropriate case for case-sensitive names, such as
+ those in C or Lisp.
+
+ * Write the indexing commands that refer to a whole section
+ immediately after the section command, and write the indexing
+ commands that refer to the paragraph before the paragraph.
+
+ In the example that follows, a blank line comes after the index
+ entry for "Leaping":
+
+ @section The Dog and the Fox
+ @cindex Jumping, in general
+ @cindex Leaping
+
+ @cindex Dog, lazy, jumped over
+ @cindex Lazy dog jumped over
+ @cindex Fox, jumps over dog
+ @cindex Quick fox jumps over dog
+ The quick brown fox jumps over the lazy dog.
+
+ (Note that the example shows entries for the same concept that are
+ written in different ways--`Lazy dog', and `Dog, lazy'--so readers
+ can look up the concept in different ways.)
+
+Blank Lines
+...........
+
+ * Insert a blank line between a sectioning command and the first
+ following sentence or paragraph, or between the indexing commands
+ associated with the sectioning command and the first following
+ sentence or paragraph, as shown in the tip on indexing.
+ Otherwise, a formatter may fold title and paragraph together.
+
+ * Always insert a blank line before an `@table' command and after an
+ `@end table' command; but never insert a blank line after an
+ `@table' command or before an `@end table' command.
+
+ For example,
+
+ Types of fox:
+
+ @table @samp
+ @item Quick
+ Jump over lazy dogs.
+
+ @item Brown
+ Also jump over lazy dogs.
+ @end table
+ @noindent
+ On the other hand, ...
+
+ Insert blank lines before and after `@itemize' ... `@end itemize'
+ and `@enumerate' ... `@end enumerate' in the same way.
+
+Complete Phrases
+................
+
+ Complete phrases are easier to read than ...
+
+ * Write entries in an itemized list as complete sentences; or at
+ least, as complete phrases. Incomplete expressions ... awkward
+ ... like this.
+
+ * Write the prefatory sentence or phrase for a multi-item list or
+ table as a complete expression. Do not write "You can set:";
+ instead, write "You can set these variables:". The former
+ expression sounds cut off.
+
+Editions, Dates and Versions
+............................
+
+ Write the edition and version numbers and date in three places in
+every manual:
+
+ 1. In the first `@ifinfo' section, for people reading the Texinfo
+ file.
+
+ 2. In the `@titlepage' section, for people reading the printed manual.
+
+ 3. In the `Top' node, for people reading the Info file.
+
+Also, it helps to write a note before the first `@ifinfo' section to
+explain what you are doing.
+
+For example:
+
+ @c ===> NOTE! <==
+ @c Specify the edition and version numbers and date
+ @c in *three* places:
+ @c 1. First ifinfo section 2. title page 3. top node
+ @c To find the locations, search for !!set
+
+ @ifinfo
+ @c !!set edition, date, version
+ This is Edition 4.03, January 1992,
+ of the @cite{GDB Manual} for GDB Version 4.3.
+ ...
+
+--or use `@set' and `@value' (*note `@value' Example: value Example.).
+
+Definition Commands
+...................
+
+ Definition commands are `@deffn', `@defun', `@defmac', and the like,
+and enable you to write descriptions in a uniform format.
+
+ * Write just one definition command for each entity you define with a
+ definition command. The automatic indexing feature creates an
+ index entry that leads the reader to the definition.
+
+ * Use `@table' ... `@end table' in an appendix that contains a
+ summary of functions, not `@deffn' or other definition commands.
+
+Capitalization
+..............
+
+ * Capitalize "Texinfo"; it is a name. Do not write the `x' or `i'
+ in upper case.
+
+ * Capitalize "Info"; it is a name.
+
+ * Write TeX using the `@TeX{}' command. Note the uppercase `T' and
+ `X'. This command causes the formatters to typeset the name
+ according to the wishes of Donald Knuth, who wrote TeX.
+
+Spaces
+......
+
+ Do not use spaces to format a Texinfo file, except inside of
+`@example' ... `@end example' and similar commands.
+
+ For example, TeX fills the following:
+
+ @kbd{C-x v}
+ @kbd{M-x vc-next-action}
+ Perform the next logical operation
+ on the version-controlled file
+ corresponding to the current buffer.
+
+so it looks like this:
+
+ `C-x v' `M-x vc-next-action' Perform the next logical operation on
+ the version-controlled file corresponding to the current buffer.
+
+In this case, the text should be formatted with `@table', `@item', and
+`@itemx', to create a table.
+
+@code, @samp, @var, and `---'
+.............................
+
+ * Use `@code' around Lisp symbols, including command names. For
+ example,
+
+ The main function is @code{vc-next-action}, ...
+
+ * Avoid putting letters such as `s' immediately after an `@code'.
+ Such letters look bad.
+
+ * Use `@var' around meta-variables. Do not write angle brackets
+ around them.
+
+ * Use three hyphens in a row, `---', to indicate a long dash. TeX
+ typesets these as a long dash and the Info formatters reduce three
+ hyphens to two.
+
+Periods Outside of Quotes
+.........................
+
+ Place periods and other punctuation marks *outside* of quotations,
+unless the punctuation is part of the quotation. This practice goes
+against publishing conventions in the United States, but enables the
+reader to distinguish between the contents of the quotation and the
+whole passage.
+
+ For example, you should write the following sentence with the period
+outside the end quotation marks:
+
+ Evidently, `au' is an abbreviation for ``author''.
+
+since `au' does *not* serve as an abbreviation for `author.' (with a
+period following the word).
+
+Introducing New Terms
+.....................
+
+ * Introduce new terms so that a reader who does not know them can
+ understand them from context; or write a definition for the term.
+
+ For example, in the following, the terms "check in", "register" and
+ "delta" are all appearing for the first time; the example sentence
+ should be rewritten so they are understandable.
+
+ The major function assists you in checking in a file to your
+ version control system and registering successive sets of
+ changes to it as deltas.
+
+ * Use the `@dfn' command around a word being introduced, to indicate
+ that the reader should not expect to know the meaning already, and
+ should expect to learn the meaning from this passage.
+
+@pxref
+......
+
+ Absolutely never use `@pxref' except in the special context for which
+it is designed: inside parentheses, with the closing parenthesis
+following immediately after the closing brace. One formatter
+automatically inserts closing punctuation and the other does not. This
+means that the output looks right both in printed output and in an Info
+file, but only when the command is used inside parentheses.
+
+Invoking from a Shell
+.....................
+
+ You can invoke programs such as Emacs, GCC, and `gawk' from a shell.
+The documentation for each program should contain a section that
+describes this. Unfortunately, if the node names and titles for these
+sections are all different, readers find it hard to search for the
+section.
+
+ Name such sections with a phrase beginning with the word
+`Invoking ...', as in `Invoking Emacs'; this way users can find the
+section easily.
+
+ANSI C Syntax
+.............
+
+ When you use `@example' to describe a C function's calling
+conventions, use the ANSI C syntax, like this:
+
+ void dld_init (char *@var{path});
+
+And in the subsequent discussion, refer to the argument values by
+writing the same argument names, again highlighted with `@var'.
+
+ Avoid the obsolete style that looks like this:
+
+ #include <dld.h>
+
+ dld_init (path)
+ char *path;
+
+ Also, it is best to avoid writing `#include' above the declaration
+just to indicate that the function is declared in a header file. The
+practice may give the misimpression that the `#include' belongs near
+the declaration of the function. Either state explicitly which header
+file holds the declaration or, better yet, name the header file used
+for a group of functions at the beginning of the section that describes
+the functions.
+
+Bad Examples
+............
+
+ Here are several examples of bad writing to avoid:
+
+ In this example, say, " ... you must `@dfn'{check in} the new
+version." That flows better.
+
+ When you are done editing the file, you must perform a
+ `@dfn'{check in}.
+
+ In the following example, say, "... makes a unified interface such as
+VC mode possible."
+
+ SCCS, RCS and other version-control systems all perform similar
+ functions in broadly similar ways (it is this resemblance which
+ makes a unified control mode like this possible).
+
+ And in this example, you should specify what `it' refers to:
+
+ If you are working with other people, it assists in coordinating
+ everyone's changes so they do not step on each other.
+
+And Finally ...
+...............
+
+ * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
+ in the name `Bach'. But pronounce Texinfo as in `speck':
+ "teckinfo".
+
+ * Write notes for yourself at the very end of a Texinfo file after
+ the `@bye'. None of the formatters process text after the `@bye';
+ it is as if the text were within `@ignore' ... `@end ignore'.
+
+\1f
+File: texinfo.info, Node: Sample Texinfo File, Next: Sample Permissions, Prev: Tips, Up: Top
+
+A Sample Texinfo File
+*********************
+
+ Here is a complete, short sample Texinfo file, without any commentary.
+You can see this file, with comments, in the first chapter. *Note A
+Short Sample Texinfo File: Short Sample.
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename sample.info
+ @settitle Sample Document
+ @c %**end of header
+
+ @setchapternewpage odd
+
+ @ifinfo
+ This is a short example of a complete Texinfo file.
+
+ Copyright 1990 Free Software Foundation, Inc.
+ @end ifinfo
+
+ @titlepage
+ @sp 10
+ @comment The title is printed in a large font.
+ @center @titlefont{Sample Title}
+
+ @c The following two commands start the copyright page.
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 1990 Free Software Foundation, Inc.
+ @end titlepage
+
+ @node Top, First Chapter, , (dir)
+ @comment node-name, next, previous, up
+
+ @menu
+ * First Chapter:: The first chapter is the
+ only chapter in this sample.
+ * Concept Index:: This index has two entries.
+ @end menu
+
+ @node First Chapter, Concept Index, Top, Top
+ @comment node-name, next, previous, up
+ @chapter First Chapter
+ @cindex Sample index entry
+
+ This is the contents of the first chapter.
+ @cindex Another sample index entry
+
+ Here is a numbered list.
+
+ @enumerate
+ @item
+ This is the first item.
+
+ @item
+ This is the second item.
+ @end enumerate
+
+ The @code{makeinfo} and @code{texinfo-format-buffer}
+ commands transform a Texinfo file such as this into
+ an Info file; and @TeX{} typesets it for a printed
+ manual.
+
+ @node Concept Index, , First Chapter, Top
+ @comment node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @contents
+ @bye
+
+\1f
+File: texinfo.info, Node: Sample Permissions, Next: Include Files, Prev: Sample Texinfo File, Up: Top
+
+Sample Permissions
+******************
+
+ Texinfo files should contain sections that tell the readers that they
+have the right to copy and distribute the Texinfo file, the Info file,
+and the printed manual.
+
+ Also, if you are writing a manual about software, you should explain
+that the software is free and either include the GNU General Public
+License (GPL) or provide a reference to it. *Note Distribution:
+(xemacs)Distrib, for an example of the text that could be used in the
+software "Distribution", "General Public License", and "NO WARRANTY"
+sections of a document. *Note Texinfo Copying Conditions: Copying, for
+an example of a brief explanation of how the copying conditions provide
+you with rights.
+
+* Menu:
+
+* Inserting Permissions:: How to put permissions in your document.
+* ifinfo Permissions:: Sample `ifinfo' copying permissions.
+* Titlepage Permissions:: Sample Titlepage copying permissions.
+
+\1f
+File: texinfo.info, Node: Inserting Permissions, Next: ifinfo Permissions, Prev: Sample Permissions, Up: Sample Permissions
+
+Inserting Permissions
+=====================
+
+ In a Texinfo file, the first `@ifinfo' section usually begins with a
+line that says what the file documents. This is what a person reading
+the unprocessed Texinfo file or using the advanced Info command `g *'
+sees first. *note Advanced Info commands: (info)Expert, for more
+information. (A reader using the regular Info commands usually starts
+reading at the first node and skips this first section, which is not in
+a node.)
+
+ In the `@ifinfo' section, the summary sentence is followed by a
+copyright notice and then by the copying permission notice. One of the
+copying permission paragraphs is enclosed in `@ignore' and `@end
+ignore' commands. This paragraph states that the Texinfo file can be
+processed through TeX and printed, provided the printed manual carries
+the proper copying permission notice. This paragraph is not made part
+of the Info file since it is not relevant to the Info file; but it is a
+mandatory part of the Texinfo file since it permits people to process
+the Texinfo file in TeX and print the results.
+
+ In the printed manual, the Free Software Foundation copying permission
+notice follows the copyright notice and publishing information and is
+located within the region delineated by the `@titlepage' and `@end
+titlepage' commands. The copying permission notice is exactly the same
+as the notice in the `@ifinfo' section except that the paragraph
+enclosed in `@ignore' and `@end ignore' commands is not part of the
+notice.
+
+ To make it simple to insert a permission notice into each section of
+the Texinfo file, sample permission notices for each section are
+reproduced in full below.
+
+ Note that you may need to specify the correct name of a section
+mentioned in the permission notice. For example, in `The GDB Manual',
+the name of the section referring to the General Public License is
+called the "GDB General Public License", but in the sample shown below,
+that section is referred to generically as the "GNU General Public
+License". If the Texinfo file does not carry a copy of the General
+Public License, leave out the reference to it, but be sure to include
+the rest of the sentence.
+
+\1f
+File: texinfo.info, Node: ifinfo Permissions, Next: Titlepage Permissions, Prev: Inserting Permissions, Up: Sample Permissions
+
+`ifinfo' Copying Permissions
+============================
+
+ In the `@ifinfo' section of a Texinfo file, the standard Free
+Software Foundation permission notice reads as follows:
+
+ This file documents ...
+
+ Copyright 1998 Free Software Foundation, Inc.
+
+ Permission is granted to make and distribute verbatim
+ copies of this manual provided the copyright notice and
+ this permission notice are preserved on all copies.
+
+ @ignore
+ Permission is granted to process this file through TeX
+ and print the results, provided the printed document
+ carries a copying permission notice identical to this
+ one except for the removal of this paragraph (this
+ paragraph not being relevant to the printed manual).
+
+ @end ignore
+ Permission is granted to copy and distribute modified
+ versions of this manual under the conditions for
+ verbatim copying, provided also that the sections
+ entitled ``Copying'' and ``GNU General Public License''
+ are included exactly as in the original, and provided
+ that the entire resulting derived work is distributed
+ under the terms of a permission notice identical to this
+ one.
+
+ Permission is granted to copy and distribute
+ translations of this manual into another language,
+ under the above conditions for modified versions,
+ except that this permission notice may be stated in a
+ translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions
+
+Titlepage Copying Permissions
+=============================
+
+ In the `@titlepage' section of a Texinfo file, the standard Free
+Software Foundation copying permission notice follows the copyright
+notice and publishing information. The standard phrasing is as follows:
+
+ Permission is granted to make and distribute verbatim
+ copies of this manual provided the copyright notice and
+ this permission notice are preserved on all copies.
+
+ Permission is granted to copy and distribute modified
+ versions of this manual under the conditions for
+ verbatim copying, provided also that the sections
+ entitled ``Copying'' and ``GNU General Public License''
+ are included exactly as in the original, and provided
+ that the entire resulting derived work is distributed
+ under the terms of a permission notice identical to this
+ one.
+
+ Permission is granted to copy and distribute
+ translations of this manual into another language,
+ under the above conditions for modified versions,
+ except that this permission notice may be stated in a
+ translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top
+
+Include Files
+*************
+
+ When TeX or an Info formatting command sees an `@include' command in
+a Texinfo file, it processes the contents of the file named by the
+command and incorporates them into the DVI or Info file being created.
+Index entries from the included file are incorporated into the indices
+of the output file.
+
+ Include files let you keep a single large document as a collection of
+conveniently small parts.
+
+* Menu:
+
+* Using Include Files:: How to use the `@include' command.
+* texinfo-multiple-files-update:: How to create and update nodes and
+ menus when using included files.
+* Include File Requirements:: What `texinfo-multiple-files-update' expects.
+* Sample Include File:: A sample outer file with included files
+ within it; and a sample included file.
+* Include Files Evolution:: How use of the `@include' command
+ has changed over time.
+
+\1f
+File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Prev: Include Files, Up: Include Files
+
+How to Use Include Files
+========================
+
+ To include another file within a Texinfo file, write the `@include'
+command at the beginning of a line and follow it on the same line by
+the name of a file to be included. For example:
+
+ @include buffers.texi
+
+ An included file should simply be a segment of text that you expect to
+be included as is into the overall or "outer" Texinfo file; it should
+not contain the standard beginning and end parts of a Texinfo file. In
+particular, you should not start an included file with a line saying
+`\input texinfo'; if you do, that phrase is inserted into the output
+file as is. Likewise, you should not end an included file with an
+`@bye' command; nothing after `@bye' is formatted.
+
+ In the past, you were required to write an `@setfilename' line at the
+beginning of an included file, but no longer. Now, it does not matter
+whether you write such a line. If an `@setfilename' line exists in an
+included file, it is ignored.
+
+ Conventionally, an included file begins with an `@node' line that is
+followed by an `@chapter' line. Each included file is one chapter.
+This makes it easy to use the regular node and menu creating and
+updating commands to create the node pointers and menus within the
+included file. However, the simple Emacs node and menu creating and
+updating commands do not work with multiple Texinfo files. Thus you
+cannot use these commands to fill in the `Next', `Previous', and `Up'
+pointers of the `@node' line that begins the included file. Also, you
+cannot use the regular commands to create a master menu for the whole
+file. Either you must insert the menus and the `Next', `Previous', and
+`Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
+command, `texinfo-multiple-files-update', that is designed for
+`@include' files.
+
+\1f
+File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files
+
+`texinfo-multiple-files-update'
+===============================
+
+ GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update'
+command. This command creates or updates `Next', `Previous', and `Up'
+pointers of included files as well as those in the outer or overall
+Texinfo file, and it creates or updates a main menu in the outer file.
+Depending whether you call it with optional arguments, the command
+updates only the pointers in the first `@node' line of the included
+files or all of them:
+
+`M-x texinfo-multiple-files-update'
+ Called without any arguments:
+
+ - Create or update the `Next', `Previous', and `Up' pointers of
+ the first `@node' line in each file included in an outer or
+ overall Texinfo file.
+
+ - Create or update the `Top' level node pointers of the outer or
+ overall file.
+
+ - Create or update a main menu in the outer file.
+
+`C-u M-x texinfo-multiple-files-update'
+ Called with `C-u' as a prefix argument:
+
+ - Create or update pointers in the first `@node' line in each
+ included file.
+
+ - Create or update the `Top' level node pointers of the outer
+ file.
+
+ - Create and insert a master menu in the outer file. The
+ master menu is made from all the menus in all the included
+ files.
+
+`C-u 8 M-x texinfo-multiple-files-update'
+ Called with a numeric prefix argument, such as `C-u 8':
+
+ - Create or update *all* the `Next', `Previous', and `Up'
+ pointers of all the included files.
+
+ - Create or update *all* the menus of all the included files.
+
+ - Create or update the `Top' level node pointers of the outer or
+ overall file.
+
+ - And then create a master menu in the outer file. This is
+ similar to invoking `texinfo-master-menu' with an argument
+ when you are working with just one file.
+
+ Note the use of the prefix argument in interactive use: with a regular
+prefix argument, just `C-u', the `texinfo-multiple-files-update'
+command inserts a master menu; with a numeric prefix argument, such as
+`C-u 8', the command updates *every* pointer and menu in *all* the
+files and then inserts a master menu.
+
+\1f
+File: texinfo.info, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files
+
+Include File Requirements
+=========================
+
+ If you plan to use the `texinfo-multiple-files-update' command, the
+outer Texinfo file that lists included files within it should contain
+nothing but the beginning and end parts of a Texinfo file, and a number
+of `@include' commands listing the included files. It should not even
+include indices, which should be listed in an included file of their
+own.
+
+ Moreover, each of the included files must contain exactly one highest
+level node (conventionally, `@chapter' or equivalent), and this node
+must be the first node in the included file. Furthermore, each of
+these highest level nodes in each included file must be at the same
+hierarchical level in the file structure. Usually, each is an
+`@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally,
+each included file contains one, and only one, chapter or
+equivalent-level node.
+
+ The outer file should contain only *one* node, the `Top' node. It
+should *not* contain any nodes besides the single `Top' node. The
+`texinfo-multiple-files-update' command will not process them.
+
+\1f
+File: texinfo.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files
+
+Sample File with `@include'
+===========================
+
+ Here is an example of a complete outer Texinfo file with `@include'
+files within it before running `texinfo-multiple-files-update', which
+would insert a main or master menu:
+
+ \input texinfo @c -*-texinfo-*-
+ @setfilename include-example.info
+ @settitle Include Example
+
+ @setchapternewpage odd
+ @titlepage
+ @sp 12
+ @center @titlefont{Include Example}
+ @sp 2
+ @center by Whom Ever
+
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 1998 Free Software Foundation, Inc.
+ @end titlepage
+
+ @ifinfo
+ @node Top, First, , (dir)
+ @top Master Menu
+ @end ifinfo
+
+ @include foo.texinfo
+ @include bar.texinfo
+ @include concept-index.texinfo
+
+ @summarycontents
+ @contents
+
+ @bye
+
+ An included file, such as `foo.texinfo', might look like this:
+
+ @node First, Second, , Top
+ @chapter First Chapter
+
+ Contents of first chapter ...
+
+ The full contents of `concept-index.texinfo' might be as simple as
+this:
+
+ @node Concept Index, , Second, Top
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ The outer Texinfo source file for `The XEmacs Lisp Reference Manual'
+is named `elisp.texi'. This outer file contains a master menu with 417
+entries and a list of 41 `@include' files.
+
+\1f
+File: texinfo.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files
+
+Evolution of Include Files
+==========================
+
+ When Info was first created, it was customary to create many small
+Info files on one subject. Each Info file was formatted from its own
+Texinfo source file. This custom meant that Emacs did not need to make
+a large buffer to hold the whole of a large Info file when someone
+wanted information; instead, Emacs allocated just enough memory for the
+small Info file that contained the particular information sought. This
+way, Emacs could avoid wasting memory.
+
+ References from one file to another were made by referring to the file
+name as well as the node name. (*Note Referring to Other Info Files:
+Other Info Files. Also, see *Note `@xref' with Four and Five
+Arguments: Four and Five Arguments.)
+
+ Include files were designed primarily as a way to create a single,
+large printed manual out of several smaller Info files. In a printed
+manual, all the references were within the same document, so TeX could
+automatically determine the references' page numbers. The Info
+formatting commands used include files only for creating joint indices;
+each of the individual Texinfo files had to be formatted for Info
+individually. (Each, therefore, required its own `@setfilename' line.)
+
+ However, because large Info files are now split automatically, it is
+no longer necessary to keep them small.
+
+ Nowadays, multiple Texinfo files are used mostly for large documents,
+such as `The XEmacs Lisp Reference Manual', and for projects in which
+several different people write different sections of a document
+simultaneously.
+
+ In addition, the Info formatting commands have been extended to work
+with the `@include' command so as to create a single large Info file
+that is split into smaller files if necessary. This means that you can
+write menus and cross references without naming the different Texinfo
+files.
+
+\1f
+File: texinfo.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top
+
+Page Headings
+*************
+
+ Most printed manuals contain headings along the top of every page
+except the title and copyright pages. Some manuals also contain
+footings. (Headings and footings have no meaning to Info, which is not
+paginated.)
+
+* Menu:
+
+* Headings Introduced:: Conventions for using page headings.
+* Heading Format:: Standard page heading formats.
+* Heading Choice:: How to specify the type of page heading.
+* Custom Headings:: How to create your own headings and footings.
+
+\1f
+File: texinfo.info, Node: Headings Introduced, Next: Heading Format, Prev: Headings, Up: Headings
+
+Headings Introduced
+===================
+
+ Texinfo provides standard page heading formats for manuals that are
+printed on one side of each sheet of paper and for manuals that are
+printed on both sides of the paper. Typically, you will use these
+formats, but you can specify your own format if you wish.
+
+ In addition, you can specify whether chapters should begin on a new
+page, or merely continue the same page as the previous chapter; and if
+chapters begin on new pages, you can specify whether they must be
+odd-numbered pages.
+
+ By convention, a book is printed on both sides of each sheet of paper.
+When you open a book, the right-hand page is odd-numbered, and chapters
+begin on right-hand pages--a preceding left-hand page is left blank if
+necessary. Reports, however, are often printed on just one side of
+paper, and chapters begin on a fresh page immediately following the end
+of the preceding chapter. In short or informal reports, chapters often
+do not begin on a new page at all, but are separated from the preceding
+text by a small amount of whitespace.
+
+ The `@setchapternewpage' command controls whether chapters begin on
+new pages, and whether one of the standard heading formats is used. In
+addition, Texinfo has several heading and footing commands that you can
+use to generate your own heading and footing formats.
+
+ In Texinfo, headings and footings are single lines at the tops and
+bottoms of pages; you cannot create multiline headings or footings.
+Each header or footer line is divided into three parts: a left part, a
+middle part, and a right part. Any part, or a whole line, may be left
+blank. Text for the left part of a header or footer line is set
+flushleft; text for the middle part is centered; and, text for the
+right part is set flushright.
+
+\1f
+File: texinfo.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings
+
+Standard Heading Formats
+========================
+
+ Texinfo provides two standard heading formats, one for manuals printed
+on one side of each sheet of paper, and the other for manuals printed
+on both sides of the paper.
+
+ By default, nothing is specified for the footing of a Texinfo file,
+so the footing remains blank.
+
+ The standard format for single-sided printing consists of a header
+line in which the left-hand part contains the name of the chapter, the
+central part is blank, and the right-hand part contains the page number.
+
+ A single-sided page looks like this:
+
+ _______________________
+ | |
+ | chapter page number |
+ | |
+ | Start of text ... |
+ | ... |
+ | |
+
+ The standard format for two-sided printing depends on whether the page
+number is even or odd. By convention, even-numbered pages are on the
+left- and odd-numbered pages are on the right. (TeX will adjust the
+widths of the left- and right-hand margins. Usually, widths are
+correct, but during double-sided printing, it is wise to check that
+pages will bind properly--sometimes a printer will produce output in
+which the even-numbered pages have a larger right-hand margin than the
+odd-numbered pages.)
+
+ In the standard double-sided format, the left part of the left-hand
+(even-numbered) page contains the page number, the central part is
+blank, and the right part contains the title (specified by the
+`@settitle' command). The left part of the right-hand (odd-numbered)
+page contains the name of the chapter, the central part is blank, and
+the right part contains the page number.
+
+ Two pages, side by side as in an open book, look like this:
+
+ _______________________ _______________________
+ | | | |
+ | page number title | | chapter page number |
+ | | | |
+ | Start of text ... | | More text ... |
+ | ... | | ... |
+ | | | |
+
+The chapter name is preceded by the word "Chapter", the chapter number
+and a colon. This makes it easier to keep track of where you are in the
+manual.
+
+\1f
+File: texinfo.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings
+
+Specifying the Type of Heading
+==============================
+
+ TeX does not begin to generate page headings for a standard Texinfo
+file until it reaches the `@end titlepage' command. Thus, the title
+and copyright pages are not numbered. The `@end titlepage' command
+causes TeX to begin to generate page headings according to a standard
+format specified by the `@setchapternewpage' command that precedes the
+`@titlepage' section.
+
+ There are four possibilities:
+
+No `@setchapternewpage' command
+ Cause TeX to specify the single-sided heading format, with chapters
+ on new pages. This is the same as `@setchapternewpage on'.
+
+`@setchapternewpage on'
+ Specify the single-sided heading format, with chapters on new
+ pages.
+
+`@setchapternewpage off'
+ Cause TeX to start a new chapter on the same page as the last page
+ of the preceding chapter, after skipping some vertical whitespace.
+ Also cause TeX to typeset for single-sided printing. (You can
+ override the headers format with the `@headings double' command;
+ see *Note The `@headings' Command: headings on off.)
+
+`@setchapternewpage odd'
+ Specify the double-sided heading format, with chapters on new
+ pages.
+
+Texinfo lacks an `@setchapternewpage even' command.
+
+\1f
+File: texinfo.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings
+
+How to Make Your Own Headings
+=============================
+
+ You can use the standard headings provided with Texinfo or specify
+your own. By default, Texinfo has no footers, so if you specify them,
+the available page size for the main text will be slightly reduced.
+
+ Texinfo provides six commands for specifying headings and footings.
+The `@everyheading' command and `@everyfooting' command generate page
+headers and footers that are the same for both even- and odd-numbered
+pages. The `@evenheading' command and `@evenfooting' command generate
+headers and footers for even-numbered (left-hand) pages; and the
+`@oddheading' command and `@oddfooting' command generate headers and
+footers for odd-numbered (right-hand) pages.
+
+ Write custom heading specifications in the Texinfo file immediately
+after the `@end titlepage' command. Enclose your specifications
+between `@iftex' and `@end iftex' commands since the
+`texinfo-format-buffer' command may not recognize them. Also, you must
+cancel the predefined heading commands with the `@headings off' command
+before defining your own specifications.
+
+ Here is how to tell TeX to place the chapter name at the left, the
+page number in the center, and the date at the right of every header
+for both even- and odd-numbered pages:
+
+ @iftex
+ @headings off
+ @everyheading @thischapter @| @thispage @| @today{}
+ @end iftex
+
+You need to divide the left part from the central part and the central
+part from the right part by inserting `@|' between parts. Otherwise,
+the specification command will not be able to tell where the text for
+one part ends and the next part begins.
+
+ Each part can contain text or @-commands. The text is printed as if
+the part were within an ordinary paragraph in the body of the page.
+The @-commands replace themselves with the page number, date, chapter
+name, or whatever.
+
+ Here are the six heading and footing commands:
+
+`@everyheading LEFT @| CENTER @| RIGHT'
+`@everyfooting LEFT @| CENTER @| RIGHT'
+ The `every' commands specify the format for both even- and
+ odd-numbered pages. These commands are for documents that are
+ printed on one side of each sheet of paper, or for documents in
+ which you want symmetrical headers or footers.
+
+`@evenheading LEFT @| CENTER @| RIGHT'
+`@oddheading LEFT @| CENTER @| RIGHT'
+`@evenfooting LEFT @| CENTER @| RIGHT'
+`@oddfooting LEFT @| CENTER @| RIGHT'
+ The `even' and `odd' commands specify the format for even-numbered
+ pages and odd-numbered pages. These commands are for books and
+ manuals that are printed on both sides of each sheet of paper.
+
+ Use the `@this...' series of @-commands to provide the names of
+chapters and sections and the page number. You can use the `@this...'
+commands in the left, center, or right portions of headers and footers,
+or anywhere else in a Texinfo file so long as they are between `@iftex'
+and `@end iftex' commands.
+
+ Here are the `@this...' commands:
+
+`@thispage'
+ Expands to the current page number.
+
+`@thischaptername'
+ Expands to the name of the current chapter.
+
+`@thischapter'
+ Expands to the number and name of the current chapter, in the
+ format `Chapter 1: Title'.
+
+`@thistitle'
+ Expands to the name of the document, as specified by the
+ `@settitle' command.
+
+`@thisfile'
+ For `@include' files only: expands to the name of the current
+ `@include' file. If the current Texinfo source file is not an
+ `@include' file, this command has no effect. This command does
+ *not* provide the name of the current Texinfo source file unless
+ it is an `@include' file. (*Note Include Files::, for more
+ information about `@include' files.)
+
+You can also use the `@today{}' command, which expands to the current
+date, in `1 Jan 1900' format.
+
+ Other @-commands and text are printed in a header or footer just as
+if they were in the body of a page. It is useful to incorporate text,
+particularly when you are writing drafts:
+
+ @iftex
+ @headings off
+ @everyheading @emph{Draft!} @| @thispage @| @thischapter
+ @everyfooting @| @| Version: 0.27: @today{}
+ @end iftex
+
+ Beware of overlong titles: they may overlap another part of the
+header or footer and blot it out.
+
+\1f
+File: texinfo.info, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top
+
+Formatting Mistakes
+*******************
+
+ Besides mistakes in the content of your documentation, there are two
+kinds of mistake you can make with Texinfo: you can make mistakes with
+@-commands, and you can make mistakes with the structure of the nodes
+and chapters.
+
+ Emacs has two tools for catching the @-command mistakes and two for
+catching structuring mistakes.
+
+ For finding problems with @-commands, you can run TeX or a region
+formatting command on the region that has a problem; indeed, you can
+run these commands on each region as you write it.
+
+ For finding problems with the structure of nodes and chapters, you
+can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
+command and you can use the `M-x Info-validate' command.
+
+* Menu:
+
+* makeinfo Preferred:: `makeinfo' finds errors.
+* Debugging with Info:: How to catch errors with Info formatting.
+* Debugging with TeX:: How to catch errors with TeX formatting.
+* Using texinfo-show-structure:: How to use `texinfo-show-structure'.
+* Using occur:: How to list all lines containing a pattern.
+* Running Info-Validate:: How to find badly referenced nodes.
+
+\1f
+File: texinfo.info, Node: makeinfo Preferred, Next: Debugging with Info, Prev: Catching Mistakes, Up: Catching Mistakes
+
+`makeinfo' Find Errors
+======================
+
+ The `makeinfo' program does an excellent job of catching errors and
+reporting them--far better than `texinfo-format-region' or
+`texinfo-format-buffer'. In addition, the various functions for
+automatically creating and updating node pointers and menus remove many
+opportunities for human error.
+
+ If you can, use the updating commands to create and insert pointers
+and menus. These prevent many errors. Then use `makeinfo' (or its
+Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
+to format your file and check for other errors. This is the best way
+to work with Texinfo. But if you cannot use `makeinfo', or your
+problem is very puzzling, then you may want to use the tools described
+in this appendix.
+
+\1f
+File: texinfo.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo Preferred, Up: Catching Mistakes
+
+Catching Errors with Info Formatting
+====================================
+
+ After you have written part of a Texinfo file, you can use the
+`texinfo-format-region' or the `makeinfo-region' command to see whether
+the region formats properly.
+
+ Most likely, however, you are reading this section because for some
+reason you cannot use the `makeinfo-region' command; therefore, the
+rest of this section presumes that you are using
+`texinfo-format-region'.
+
+ If you have made a mistake with an @-command, `texinfo-format-region'
+will stop processing at or after the error and display an error
+message. To see where in the buffer the error occurred, switch to the
+`*Info Region*' buffer; the cursor will be in a position that is after
+the location of the error. Also, the text will not be formatted after
+the place where the error occurred (or more precisely, where it was
+detected).
+
+ For example, if you accidentally end a menu with the command `@end
+menus' with an `s' on the end, instead of with `@end menu', you will
+see an error message that says:
+
+ @end menus is not handled by texinfo
+
+The cursor will stop at the point in the buffer where the error occurs,
+or not long after it. The buffer will look like this:
+
+ ---------- Buffer: *Info Region* ----------
+ * Menu:
+
+ * Using texinfo-show-structure:: How to use
+ `texinfo-show-structure'
+ to catch mistakes.
+ * Running Info-Validate:: How to check for
+ unreferenced nodes.
+ @end menus
+ -!-
+ ---------- Buffer: *Info Region* ----------
+
+ The `texinfo-format-region' command sometimes provides slightly odd
+error messages. For example, the following cross reference fails to
+format:
+
+ (@xref{Catching Mistakes, for more info.)
+
+In this case, `texinfo-format-region' detects the missing closing brace
+but displays a message that says `Unbalanced parentheses' rather than
+`Unbalanced braces'. This is because the formatting command looks for
+mismatches between braces as if they were parentheses.
+
+ Sometimes `texinfo-format-region' fails to detect mistakes. For
+example, in the following, the closing brace is swapped with the
+closing parenthesis:
+
+ (@xref{Catching Mistakes), for more info.}
+
+Formatting produces:
+ (*Note for more info.: Catching Mistakes)
+
+ The only way for you to detect this error is to realize that the
+reference should have looked like this:
+
+ (*Note Catching Mistakes::, for more info.)
+
+ Incidentally, if you are reading this node in Info and type `f <RET>'
+(`Info-follow-reference'), you will generate an error message that says:
+
+ No such node: "Catching Mistakes) The only way ...
+
+This is because Info perceives the example of the error as the first
+cross reference in this node and if you type a <RET> immediately after
+typing the Info `f' command, Info will attempt to go to the referenced
+node. If you type `f catch <TAB> <RET>', Info will complete the node
+name of the correctly written example and take you to the `Catching
+Mistakes' node. (If you try this, you can return from the `Catching
+Mistakes' node by typing `l' (`Info-last').)
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes
+
+Catching Errors with TeX Formatting
+===================================
+
+ You can also catch mistakes when you format a file with TeX.
+
+ Usually, you will want to do this after you have run
+`texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same
+file, because `texinfo-format-buffer' sometimes displays error messages
+that make more sense than TeX. (*Note Debugging with Info::, for more
+information.)
+
+ For example, TeX was run on a Texinfo file, part of which is shown
+here:
+
+ ---------- Buffer: texinfo.texi ----------
+ name of the Texinfo file as an extension. The
+ @samp{??} are `wildcards' that cause the shell to
+ substitute all the raw index files. (@xref{sorting
+ indices, for more information about sorting
+ indices.)@refill
+ ---------- Buffer: texinfo.texi ----------
+
+(The cross reference lacks a closing brace.) TeX produced the
+following output, after which it stopped:
+
+ ---------- Buffer: *tex-shell* ----------
+ Runaway argument?
+ {sorting indices, for more information about sorting
+ indices.) @refill @ETC.
+ ! Paragraph ended before @xref was complete.
+ <to be read again>
+ @par
+ l.27
+
+ ?
+ ---------- Buffer: *tex-shell* ----------
+
+ In this case, TeX produced an accurate and understandable error
+message:
+
+ Paragraph ended before @xref was complete.
+
+`@par' is an internal TeX command of no relevance to Texinfo. `l.27'
+means that TeX detected the problem on line 27 of the Texinfo file.
+The `?' is the prompt TeX uses in this circumstance.
+
+ Unfortunately, TeX is not always so helpful, and sometimes you must
+truly be a Sherlock Holmes to discover what went wrong.
+
+ In any case, if you run into a problem like this, you can do one of
+three things.
+
+ 1. You can tell TeX to continue running and ignore just this error by
+ typing <RET> at the `?' prompt.
+
+ 2. You can tell TeX to continue running and to ignore all errors as
+ best it can by typing `r <RET>' at the `?' prompt.
+
+ This is often the best thing to do. However, beware: the one error
+ may produce a cascade of additional error messages as its
+ consequences are felt through the rest of the file. To stop TeX
+ when it is producing such an avalanche of error messages, type
+ `C-c' (or `C-c C-c', if you are running a shell inside Emacs).
+
+ 3. You can tell TeX to stop this run by typing `x <RET>' at the `?'
+ prompt.
+
+ Please note that if you are running TeX inside Emacs, you need to
+switch to the shell buffer and line at which TeX offers the `?' prompt.
+
+ Sometimes TeX will format a file without producing error messages even
+though there is a problem. This usually occurs if a command is not
+ended but TeX is able to continue processing anyhow. For example, if
+you fail to end an itemized list with the `@end itemize' command, TeX
+will write a DVI file that you can print out. The only error message
+that TeX will give you is the somewhat mysterious comment that
+
+ (@end occurred inside a group at level 1)
+
+However, if you print the DVI file, you will find that the text of the
+file that follows the itemized list is entirely indented as if it were
+part of the last item in the itemized list. The error message is the
+way TeX says that it expected to find an `@end' command somewhere in
+the file; but that it could not determine where it was needed.
+
+ Another source of notoriously hard-to-find errors is a missing `@end
+group' command. If you ever are stumped by incomprehensible errors,
+look for a missing `@end group' command first.
+
+ If the Texinfo file lacks header lines, TeX may stop in the beginning
+of its run and display output that looks like the following. The `*'
+indicates that TeX is waiting for input.
+
+ This is TeX, Version 3.14159 (Web2c 7.0)
+ (test.texinfo [1])
+ *
+
+In this case, simply type `\end <RET>' after the asterisk. Then write
+the header lines in the Texinfo file and run the TeX command again.
+(Note the use of the backslash, `\'. TeX uses `\' instead of `@'; and
+in this circumstance, you are working directly with TeX, not with
+Texinfo.)
+
+\1f
+File: texinfo.info, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes
+
+Using `texinfo-show-structure'
+==============================
+
+ It is not always easy to keep track of the nodes, chapters, sections,
+and subsections of a Texinfo file. This is especially true if you are
+revising or adding to a Texinfo file that someone else has written.
+
+ In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
+lists all the lines that begin with the @-commands that specify the
+structure: `@chapter', `@section', `@appendix', and so on. With an
+argument (`C-u' as prefix argument, if interactive), the command also
+shows the `@node' lines. The `texinfo-show-structure' command is bound
+to `C-c C-s' in Texinfo mode, by default.
+
+ The lines are displayed in a buffer called the `*Occur*' buffer,
+indented by hierarchical level. For example, here is a part of what was
+produced by running `texinfo-show-structure' on this manual:
+
+ Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
+ unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
+ in buffer texinfo.texi.
+ ...
+ 4177:@chapter Nodes
+ 4198: @heading Two Paths
+ 4231: @section Node and Menu Illustration
+ 4337: @section The @code{@@node} Command
+ 4393: @subheading Choosing Node and Pointer Names
+ 4417: @subsection How to Write an @code{@@node} Line
+ 4469: @subsection @code{@@node} Line Tips
+ ...
+
+ This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
+with the `@section', `@subheading', and `@subsection' commands
+respectively. If you move your cursor into the `*Occur*' window, you
+can position the cursor over one of the lines and use the `C-c C-c'
+command (`occur-mode-goto-occurrence'), to jump to the corresponding
+spot in the Texinfo file. *Note Using Occur: (xemacs)Other Repeating
+Search, for more information about `occur-mode-goto-occurrence'.
+
+ The first line in the `*Occur*' window describes the "regular
+expression" specified by TEXINFO-HEADING-PATTERN. This regular
+expression is the pattern that `texinfo-show-structure' looks for.
+*Note Using Regular Expressions: (xemacs)Regexps, for more information.
+
+ When you invoke the `texinfo-show-structure' command, Emacs will
+display the structure of the whole buffer. If you want to see the
+structure of just a part of the buffer, of one chapter, for example,
+use the `C-x n n' (`narrow-to-region') command to mark the region.
+(*Note Narrowing: (xemacs)Narrowing.) This is how the example used
+above was generated. (To see the whole buffer again, use `C-x n w'
+(`widen').)
+
+ If you call `texinfo-show-structure' with a prefix argument by typing
+`C-u C-c C-s', it will list lines beginning with `@node' as well as the
+lines beginning with the @-sign commands for `@chapter', `@section',
+and the like.
+
+ You can remind yourself of the structure of a Texinfo file by looking
+at the list in the `*Occur*' window; and if you have mis-named a node
+or left out a section, you can correct the mistake.
+
+\1f
+File: texinfo.info, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes
+
+Using `occur'
+=============
+
+ Sometimes the `texinfo-show-structure' command produces too much
+information. Perhaps you want to remind yourself of the overall
+structure of a Texinfo file, and are overwhelmed by the detailed list
+produced by `texinfo-show-structure'. In this case, you can use the
+`occur' command directly. To do this, type
+
+ M-x occur
+
+and then, when prompted, type a "regexp", a regular expression for the
+pattern you want to match. (*Note Regular Expressions:
+(xemacs)Regexps.) The `occur' command works from the current location
+of the cursor in the buffer to the end of the buffer. If you want to
+run `occur' on the whole buffer, place the cursor at the beginning of
+the buffer.
+
+ For example, to see all the lines that contain the word `@chapter' in
+them, just type `@chapter'. This will produce a list of the chapters.
+It will also list all the sentences with `@chapter' in the middle of
+the line.
+
+ If you want to see only those lines that start with the word
+`@chapter', type `^@chapter' when prompted by `occur'. If you want to
+see all the lines that end with a word or phrase, end the last word
+with a `$'; for example, `catching mistakes$'. This can be helpful
+when you want to see all the nodes that are part of the same chapter or
+section and therefore have the same `Up' pointer.
+
+ *Note Using Occur: (xemacs)Other Repeating Search, for more
+information.
+
+\1f
+File: texinfo.info, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes
+
+Finding Badly Referenced Nodes
+==============================
+
+ You can use the `Info-validate' command to check whether any of the
+`Next', `Previous', `Up' or other node pointers fail to point to a
+node. This command checks that every node pointer points to an
+existing node. The `Info-validate' command works only on Info files,
+not on Texinfo files.
+
+ The `makeinfo' program validates pointers automatically, so you do
+not need to use the `Info-validate' command if you are using
+`makeinfo'. You only may need to use `Info-validate' if you are unable
+to run `makeinfo' and instead must create an Info file using
+`texinfo-format-region' or `texinfo-format-buffer', or if you write an
+Info file from scratch.
+
+* Menu:
+
+* Using Info-validate:: How to run `Info-validate'.
+* Unsplit:: How to create an unsplit file.
+* Tagifying:: How to tagify a file.
+* Splitting:: How to split a file manually.
+
+\1f
+File: texinfo.info, Node: Using Info-validate, Next: Unsplit, Prev: Running Info-Validate, Up: Running Info-Validate
+
+Running `Info-validate'
+-----------------------
+
+ To use `Info-validate', visit the Info file you wish to check and
+type:
+
+ M-x Info-validate
+
+(Note that the `Info-validate' command requires an upper case `I'. You
+may also need to create a tag table before running `Info-validate'.
+*Note Tagifying::.)
+
+ If your file is valid, you will receive a message that says "File
+appears valid". However, if you have a pointer that does not point to
+a node, error messages will be displayed in a buffer called `*problems
+in info file*'.
+
+ For example, `Info-validate' was run on a test file that contained
+only the first node of this manual. One of the messages said:
+
+ In node "Overview", invalid Next: Texinfo Mode
+
+This meant that the node called `Overview' had a `Next' pointer that
+did not point to anything (which was true in this case, since the test
+file had only one node in it).
+
+ Now suppose we add a node named `Texinfo Mode' to our test case but
+we do not specify a `Previous' for this node. Then we will get the
+following error message:
+
+ In node "Texinfo Mode", should have Previous: Overview
+
+This is because every `Next' pointer should be matched by a `Previous'
+(in the node where the `Next' points) which points back.
+
+ `Info-validate' also checks that all menu entries and cross references
+point to actual nodes.
+
+ Note that `Info-validate' requires a tag table and does not work with
+files that have been split. (The `texinfo-format-buffer' command
+automatically splits large files.) In order to use `Info-validate' on
+a large file, you must run `texinfo-format-buffer' with an argument so
+that it does not split the Info file; and you must create a tag table
+for the unsplit file.
+
+\1f
+File: texinfo.info, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate
+
+Creating an Unsplit File
+------------------------
+
+ You can run `Info-validate' only on a single Info file that has a tag
+table. The command will not work on the indirect subfiles that are
+generated when a master file is split. If you have a large file
+(longer than 70,000 bytes or so), you need to run the
+`texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
+it does not create indirect subfiles. You will also need to create a
+tag table for the Info file. After you have done this, you can run
+`Info-validate' and look for badly referenced nodes.
+
+ The first step is to create an unsplit Info file. To prevent
+`texinfo-format-buffer' from splitting a Texinfo file into smaller Info
+files, give a prefix to the `M-x texinfo-format-buffer' command:
+
+ C-u M-x texinfo-format-buffer
+
+or else
+
+ C-u C-c C-e C-b
+
+When you do this, Texinfo will not split the file and will not create a
+tag table for it.
+
+\1f
+File: texinfo.info, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate
+
+Tagifying a File
+----------------
+
+ After creating an unsplit Info file, you must create a tag table for
+it. Visit the Info file you wish to tagify and type:
+
+ M-x Info-tagify
+
+(Note the upper case `I' in `Info-tagify'.) This creates an Info file
+with a tag table that you can validate.
+
+ The third step is to validate the Info file:
+
+ M-x Info-validate
+
+(Note the upper case `I' in `Info-validate'.) In brief, the steps are:
+
+ C-u M-x texinfo-format-buffer
+ M-x Info-tagify
+ M-x Info-validate
+
+ After you have validated the node structure, you can rerun
+`texinfo-format-buffer' in the normal way so it will construct a tag
+table and split the file automatically, or you can make the tag table
+and split the file manually.
+
+\1f
+File: texinfo.info, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate
+
+Splitting a File Manually
+-------------------------
+
+ You should split a large file or else let the `texinfo-format-buffer'
+or `makeinfo-buffer' command do it for you automatically. (Generally
+you will let one of the formatting commands do this job for you. *Note
+Create an Info File::.)
+
+ The split-off files are called the indirect subfiles.
+
+ Info files are split to save memory. With smaller files, Emacs does
+not have make such a large buffer to hold the information.
+
+ If an Info file has more than 30 nodes, you should also make a tag
+table for it. *Note Using Info-validate::, for information about
+creating a tag table. (Again, tag tables are usually created
+automatically by the formatting command; you only need to create a tag
+table yourself if you are doing the job manually. Most likely, you
+will do this for a large, unsplit file on which you have run
+`Info-validate'.)
+
+ Visit the Info file you wish to tagify and split and type the two
+commands:
+
+ M-x Info-tagify
+ M-x Info-split
+
+(Note that the `I' in `Info' is upper case.)
+
+ When you use the `Info-split' command, the buffer is modified into a
+(small) Info file which lists the indirect subfiles. This file should
+be saved in place of the original visited file. The indirect subfiles
+are written in the same directory the original file is in, with names
+generated by appending `-' and a number to the original file name.
+
+ The primary file still functions as an Info file, but it contains just
+the tag table and a directory of subfiles.
+
+\1f
+File: texinfo.info, Node: Refilling Paragraphs, Next: Command Syntax, Prev: Catching Mistakes, Up: Top
+
+Refilling Paragraphs
+********************
+
+ The `@refill' command refills and, optionally, indents the first line
+of a paragraph.(1) (*note Refilling Paragraphs-Footnotes::) The
+`@refill' command is no longer important, but we describe it here
+because you once needed it. You will see it in many old Texinfo files.
+
+ Without refilling, paragraphs containing long @-constructs may look
+bad after formatting because the formatter removes @-commands and
+shortens some lines more than others. In the past, neither the
+`texinfo-format-region' command nor the `texinfo-format-buffer' command
+refilled paragraphs automatically. The `@refill' command had to be
+written at the end of every paragraph to cause these formatters to fill
+them. (Both TeX and `makeinfo' have always refilled paragraphs
+automatically.) Now, all the Info formatters automatically fill and
+indent those paragraphs that need to be filled and indented.
+
+ The `@refill' command causes `texinfo-format-region' and
+`texinfo-format-buffer' to refill a paragraph in the Info file *after*
+all the other processing has been done. For this reason, you can not
+use `@refill' with a paragraph containing either `@*' or `@w{ ... }'
+since the refilling action will override those two commands.
+
+ The `texinfo-format-region' and `texinfo-format-buffer' commands now
+automatically append `@refill' to the end of each paragraph that should
+be filled. They do not append `@refill' to the ends of paragraphs that
+contain `@*' or `@w{ ...}' and therefore do not refill or indent them.
+
+\1f
+File: texinfo.info, Node: Refilling Paragraphs-Footnotes, Up: Refilling Paragraphs
+
+ (1) Perhaps the command should have been called the
+`@refillandindent' command, but `@refill' is shorter and the name was
+chosen before indenting was possible.
+
+\1f
+File: texinfo.info, Node: Command Syntax, Next: Obtaining TeX, Prev: Refilling Paragraphs, Up: Top
+
+@-Command Syntax
+****************
+
+ The character `@' is used to start special Texinfo commands. (It has
+the same meaning that `\' has in plain TeX.) Texinfo has four types of
+@-command:
+
+1. Non-alphabetic commands.
+ These commands consist of an @ followed by a punctuation mark or
+ other character that is not part of the alphabet. Non-alphabetic
+ commands are almost always part of the text within a paragraph,
+ and never take any argument. The two characters (@ and the other
+ one) are complete in themselves; none is followed by braces. The
+ non-alphabetic commands are: `@.', `@:', `@*', `@SPACE', `@TAB',
+ `@NL', `@@', `@{', and `@}'.
+
+2. Alphabetic commands that do not require arguments.
+ These commands start with @ followed by a word followed by left-
+ and right-hand braces. These commands insert special symbols in
+ the document; they do not require arguments. For example,
+ `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
+ `@bullet{}' => `*'.
+
+3. Alphabetic commands that require arguments within braces.
+ These commands start with @ followed by a letter or a word,
+ followed by an argument within braces. For example, the command
+ `@dfn' indicates the introductory or defining use of a term; it is
+ used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
+ commands.'
+
+4. Alphabetic commands that occupy an entire line.
+ These commands occupy an entire line. The line starts with @,
+ followed by the name of the command (a word); for example,
+ `@center' or `@cindex'. If no argument is needed, the word is
+ followed by the end of the line. If there is an argument, it is
+ separated from the command name by a space. Braces are not used.
+
+ Thus, the alphabetic commands fall into classes that have different
+argument syntaxes. You cannot tell to which class a command belongs by
+the appearance of its name, but you can tell by the command's meaning:
+if the command stands for a glyph, it is in class 2 and does not
+require an argument; if it makes sense to use the command together with
+other text as part of a paragraph, the command is in class 3 and must
+be followed by an argument in braces; otherwise, it is in class 4 and
+uses the rest of the line as its argument.
+
+ The purpose of having a different syntax for commands of classes 3 and
+4 is to make Texinfo files easier to read, and also to help the GNU
+Emacs paragraph and filling commands work properly. There is only one
+exception to this rule: the command `@refill', which is always used at
+the end of a paragraph immediately following the final period or other
+punctuation character. `@refill' takes no argument and does *not*
+require braces. `@refill' never confuses the Emacs paragraph commands
+because it cannot appear at the beginning of a line.
+
+\1f
+File: texinfo.info, Node: Obtaining TeX, Next: Command and Variable Index, Prev: Command Syntax, Up: Top
+
+How to Obtain TeX
+*****************
+
+ TeX is freely redistributable. You can obtain TeX for Unix systems
+via anonymous ftp or on physical media. The core material consists of
+the Web2c TeX distribution (`http://tug.org/web2c').
+
+ Instructions for retrieval by anonymous ftp and information on other
+available distributions:
+ `ftp://tug.org/tex/unixtex.ftp'
+ `http://tug.org/unixtex.ftp'
+
+ The Free Software Foundation provides a core distribution on its
+Source Code CD-ROM suitable for printing Texinfo manuals; the
+University of Washington maintains and supports a tape distribution;
+the TeX Users Group co-sponsors a complete CD-ROM TeX distribution.
+
+ * For the FSF Source Code CD-ROM, please contact:
+
+ Free Software Foundation, Inc.
+ 59 Temple Place Suite 330
+ Boston, MA 02111-1307
+ USA
+
+ Telephone: +1-617-542-5942
+ Fax: (including Japan) +1-617-542-2652
+ Free Dial Fax (in Japan):
+ 0031-13-2473 (KDD)
+ 0066-3382-0158 (IDC)
+ Electronic mail: `gnu@gnu.org'
+
+ * To order a complete distribution on CD-ROM, please see
+ `http://tug.org/tex-live.html'. (This distribution is also
+ available by FTP; see the URL's above.)
+
+ * To order a full distribution from the University of Washington on
+ either a 1/4in 4-track QIC-24 cartridge or a 4mm DAT cartridge,
+ send $210 to:
+
+ Pierre A. MacKay
+ Denny Hall, Mail Stop DH-10
+ University of Washington
+ Seattle, WA 98195
+ USA
+ Telephone: +1-206-543-2268
+ Electronic mail: `mackay@cs.washington.edu'
+
+ Please make checks payable to the University of Washington.
+ Checks must be in U.S. dollars, drawn on a U.S. bank. Overseas
+ sites: please add to the base cost, if desired, $20.00 for
+ shipment via air parcel post, or $30.00 for shipment via courier.
+
+ Many other TeX distributions are available; see `http://tug.org/'.
+
+\1f
+File: texinfo.info, Node: Command and Variable Index, Next: Concept Index, Prev: Obtaining TeX, Up: Top
+
+Command and Variable Index
+**************************
+
+ This is an alphabetical list of all the @-commands, assorted Emacs
+Lisp functions, and several variables. To make the list easier to use,
+the commands are listed without their preceding `@'.
+
+* Menu:
+
+* ! (end of sentence): Ending a Sentence.
+* ": Inserting Accents.
+* ': Inserting Accents.
+* (newline): Multiple Spaces.
+* (space): Multiple Spaces.
+* (tab): Multiple Spaces.
+* * (force line break): Line Breaks.
+* ,: Inserting Accents.
+* -: - and hyphenation.
+* . (end of sentence): Ending a Sentence.
+* : (suppress widening): Not Ending a Sentence.
+* =: Inserting Accents.
+* ? (end of sentence): Ending a Sentence.
+* @ (single @): Inserting An Atsign.
+* ^: Inserting Accents.
+* `: Inserting Accents.
+* aa: Inserting Accents.
+* AA: Inserting Accents.
+* AE: Inserting Accents.
+* ae: Inserting Accents.
+* afourpaper: A4 Paper.
+* appendix: unnumbered & appendix.
+* appendixsec: unnumberedsec appendixsec heading.
+* appendixsection: unnumberedsec appendixsec heading.
+* appendixsubsec: unnumberedsubsec appendixsubsec subheading.
+* appendixsubsubsec: subsubsection.
+* apply: Sample Function Definition.
+* asis: table.
+* author: title subtitle author.
+* b (bold font): Fonts.
+* buffer-end: Def Cmd Template.
+* bullet: bullet.
+* bye <1>: File End.
+* bye: Ending a File.
+* c (comment): Comments.
+* cartouche: cartouche.
+* center: titlefont center sp.
+* centerchap: chapter.
+* chapheading: majorheading & chapheading.
+* chapter: chapter.
+* cindex: Indexing Commands.
+* cite: cite.
+* clear: ifset ifclear.
+* code: code.
+* columnfractions: Multitable Column Widths.
+* comment: Comments.
+* contents: Contents.
+* copyright <1>: Copyright & Permissions.
+* copyright: copyright symbol.
+* cropmarks: Cropmarks and Magnification.
+* defcodeindex: New Indices.
+* defcv: Abstract Objects.
+* deffn: Functions Commands.
+* deffnx: deffnx.
+* defindex: New Indices.
+* definfoenclose: Customized Highlighting.
+* defivar: Abstract Objects.
+* defmac: Functions Commands.
+* defmethod: Abstract Objects.
+* defop: Abstract Objects.
+* defopt: Variables Commands.
+* defspec: Functions Commands.
+* deftp: Data Types.
+* deftypefn: Typed Functions.
+* deftypefun: Typed Functions.
+* deftypevar: Typed Variables.
+* deftypevr: Typed Variables.
+* defun: Functions Commands.
+* defvar: Variables Commands.
+* defvr: Variables Commands.
+* dfn: dfn.
+* dircategory: Installing Dir Entries.
+* direntry: Installing Dir Entries.
+* display: display.
+* dmn: dmn.
+* dotaccent: Inserting Accents.
+* dotless: Inserting Accents.
+* dots: dots.
+* email: email.
+* emph: emph & strong.
+* end <1>: Introducing Lists.
+* end: Quotations and Examples.
+* end titlepage: end titlepage.
+* enumerate: enumerate.
+* evenfooting: Custom Headings.
+* evenheading: Custom Headings.
+* everyfooting: Custom Headings.
+* everyheading: Custom Headings.
+* example: example.
+* exclamdown: Inserting Accents.
+* exdent: exdent.
+* file: file.
+* filll: Copyright & Permissions.
+* finalout: Overfull hboxes.
+* findex: Indexing Commands.
+* flushleft: flushleft & flushright.
+* flushright: flushleft & flushright.
+* foobar: Optional Arguments.
+* footnote: Footnotes.
+* footnotestyle: Footnote Styles.
+* format: format.
+* forward-word: Def Cmd Template.
+* ftable: ftable vtable.
+* group: group.
+* H: Inserting Accents.
+* heading: unnumberedsec appendixsec heading.
+* headings: headings on off.
+* html: Raw Formatter Commands.
+* hyphenation: - and hyphenation.
+* i (italic font): Fonts.
+* ifclear: ifset ifclear.
+* ifhtml <1>: Raw Formatter Commands.
+* ifhtml: Conditional Commands.
+* ifinfo: Conditional Commands.
+* ifnothtml: Conditional Not Commands.
+* ifnotinfo: Conditional Not Commands.
+* ifnottex: Conditional Not Commands.
+* ifset: ifset ifclear.
+* iftex: Conditional Commands.
+* ignore: Comments.
+* image: Images.
+* include: Using Include Files.
+* Info-validate: Running Info-Validate.
+* inforef: inforef.
+* input (TeX command): Minimum.
+* isearch-backward: deffnx.
+* isearch-forward: deffnx.
+* item <1>: itemize.
+* item <2>: Multitable Rows.
+* item: table.
+* itemize: itemize.
+* itemx: itemx.
+* kbd: kbd.
+* kbdinputstyle: kbd.
+* key: key.
+* kindex: Indexing Commands.
+* L: Inserting Accents.
+* l: Inserting Accents.
+* lisp: Lisp Example.
+* lowersections: Raise/lower sections.
+* macro: Defining Macros.
+* mag (TeX command): Cropmarks and Magnification.
+* majorheading: majorheading & chapheading.
+* makeinfo-buffer: makeinfo in Emacs.
+* makeinfo-kill-job: makeinfo in Emacs.
+* makeinfo-recenter-output-buffer: makeinfo in Emacs.
+* makeinfo-region: makeinfo in Emacs.
+* math: math.
+* menu: Menus.
+* minus: minus.
+* multitable: Multi-column Tables.
+* need: need.
+* next-error: makeinfo in Emacs.
+* noindent: noindent.
+* o: Inserting Accents.
+* O: Inserting Accents.
+* occur: Using occur.
+* occur-mode-goto-occurrence: Showing the Structure.
+* oddfooting: Custom Headings.
+* oddheading: Custom Headings.
+* oe: Inserting Accents.
+* OE: Inserting Accents.
+* page: page.
+* paragraphindent: paragraphindent.
+* pindex: Indexing Commands.
+* pounds: pounds.
+* printindex: Printing Indices & Menus.
+* pxref: pxref.
+* questiondown: Inserting Accents.
+* quotation: quotation.
+* r (Roman font): Fonts.
+* raisesections: Raise/lower sections.
+* ref: ref.
+* refill: Refilling Paragraphs.
+* ringaccent: Inserting Accents.
+* samp: samp.
+* sc (small caps font): Smallcaps.
+* section: section.
+* set: ifset ifclear.
+* setchapternewpage: setchapternewpage.
+* setfilename: setfilename.
+* settitle: settitle.
+* shortcontents: Contents.
+* shorttitlepage: titlepage.
+* smallbook: smallbook.
+* smallexample: smallexample & smalllisp.
+* smalllisp: smallexample & smalllisp.
+* sp (line spacing): sp.
+* sp (titlepage line spacing): titlefont center sp.
+* ss: Inserting Accents.
+* strong: emph & strong.
+* subheading: unnumberedsubsec appendixsubsec subheading.
+* subsection: subsection.
+* subsubheading: subsubsection.
+* subsubsection: subsubsection.
+* subtitle: title subtitle author.
+* summarycontents: Contents.
+* syncodeindex: syncodeindex.
+* synindex: synindex.
+* t (typewriter font): Fonts.
+* table: Two-column Tables.
+* tex: Raw Formatter Commands.
+* tex (command): tex.
+* texinfo-all-menus-update: Updating Commands.
+* texinfo-every-node-update: Updating Commands.
+* texinfo-format-buffer <1>: texinfo-format commands.
+* texinfo-format-buffer: Info Formatting.
+* texinfo-format-region <1>: texinfo-format commands.
+* texinfo-format-region: Info Formatting.
+* texinfo-indent-menu-description: Other Updating Commands.
+* texinfo-insert-@code: Inserting.
+* texinfo-insert-@dfn: Inserting.
+* texinfo-insert-@end: Inserting.
+* texinfo-insert-@example: Inserting.
+* texinfo-insert-@item: Inserting.
+* texinfo-insert-@kbd: Inserting.
+* texinfo-insert-@node: Inserting.
+* texinfo-insert-@noindent: Inserting.
+* texinfo-insert-@samp: Inserting.
+* texinfo-insert-@table: Inserting.
+* texinfo-insert-@var: Inserting.
+* texinfo-insert-braces: Inserting.
+* texinfo-insert-node-lines: Other Updating Commands.
+* texinfo-make-menu: Updating Commands.
+* texinfo-master-menu: Updating Commands.
+* texinfo-multiple-files-update: texinfo-multiple-files-update.
+* texinfo-multiple-files-update (in brief): Other Updating Commands.
+* texinfo-sequential-node-update: Other Updating Commands.
+* texinfo-show-structure <1>: Showing the Structure.
+* texinfo-show-structure: Using texinfo-show-structure.
+* texinfo-start-menu-description: Inserting.
+* texinfo-tex-buffer: Printing.
+* texinfo-tex-print: Printing.
+* texinfo-tex-region: Printing.
+* texinfo-update-node: Updating Commands.
+* thischapter: Custom Headings.
+* thischaptername: Custom Headings.
+* thisfile: Custom Headings.
+* thispage: Custom Headings.
+* thistitle: Custom Headings.
+* tieaccent: Inserting Accents.
+* tindex: Indexing Commands.
+* title: title subtitle author.
+* titlefont: titlefont center sp.
+* titlepage: titlepage.
+* today: Custom Headings.
+* top (@-command): makeinfo top command.
+* u: Inserting Accents.
+* ubaraccent: Inserting Accents.
+* udotaccent: Inserting Accents.
+* unmacro: Defining Macros.
+* unnumbered: unnumbered & appendix.
+* unnumberedsec: unnumberedsec appendixsec heading.
+* unnumberedsubsec: unnumberedsubsec appendixsubsec subheading.
+* unnumberedsubsubsec: subsubsection.
+* up-list: Inserting.
+* uref: uref.
+* url: url.
+* v: Inserting Accents.
+* value: value.
+* var: var.
+* vindex: Indexing Commands.
+* vskip: Copyright & Permissions.
+* vtable: ftable vtable.
+* w (prevent line break): w.
+* xref: xref.
+* { (single {): Inserting Braces.
+* } (single }): Inserting Braces.
+* ~: Inserting Accents.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Concept Index, Prev: Command and Variable Index, Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* !: Inserting Accents.
+* (dir) as Up node of Top node: First Node.
+* -D VAR: makeinfo options.
+* -delete: Invoking install-info.
+* -dir-file=NAME: Invoking install-info.
+* -entry=TEXT: Invoking install-info.
+* -error-limit=LIMIT: makeinfo options.
+* -fill-column=WIDTH: makeinfo options.
+* -footnote-style=STYLE: makeinfo options.
+* -force: makeinfo options.
+* -help <1>: makeinfo options.
+* -help: Invoking install-info.
+* -I DIR: makeinfo options.
+* -info-dir=DIR: Invoking install-info.
+* -info-file=FILE: Invoking install-info.
+* -item=TEXT: Invoking install-info.
+* -no-headers: makeinfo options.
+* -no-number-footnotes: makeinfo options.
+* -no-pointer-validate: makeinfo options.
+* -no-split: makeinfo options.
+* -no-validate: makeinfo options.
+* -no-warn: makeinfo options.
+* -o FILE: makeinfo options.
+* -output=FILE: makeinfo options.
+* -P DIR: makeinfo options.
+* -paragraph-indent=INDENT: makeinfo options.
+* -quiet: Invoking install-info.
+* -reference-limit=LIMIT: makeinfo options.
+* -remove: Invoking install-info.
+* -section=SEC: Invoking install-info.
+* -verbose: makeinfo options.
+* -version <1>: Invoking install-info.
+* -version: makeinfo options.
+* .cshrc initialization file: Preparing for TeX.
+* .profile initialization file: Preparing for TeX.
+* ?: Inserting Accents.
+* @-command in nodename: Node Line Requirements.
+* @-command list: Command List.
+* @-command syntax: Command Syntax.
+* @-commands: Formatting Commands.
+* @include file sample: Sample Include File.
+* @menu parts: Menu Parts.
+* @node line writing: Writing a Node.
+* A4 paper, printing on: A4 Paper.
+* aa: Inserting Accents.
+* AA: Inserting Accents.
+* Abbreviations for keys: key.
+* Accents, inserting: Inserting Accents.
+* Acute accent: Inserting Accents.
+* Adding a new info file: New Info File.
+* AE: Inserting Accents.
+* ae: Inserting Accents.
+* Alphabetical @-command list: Command List.
+* Another Info directory: Other Info Directories.
+* Apostrophe in nodename: Node Line Requirements.
+* Arguments, repeated and optional: Optional Arguments.
+* Aspect ratio of images: Images.
+* Automatic pointer creation with makeinfo: makeinfo Pointer Creation.
+* Automatically insert nodes, menus: Updating Nodes and Menus.
+* Backslash, and macros: Invoking Macros.
+* Badly referenced nodes: Running Info-Validate.
+* Batch formatting for Info: Batch Formatting.
+* Beginning a Texinfo file: Beginning a File.
+* Beginning line of a Texinfo file: First Line.
+* Berry, Karl: Acknowledgements.
+* Big points: Images.
+* Black rectangle in hardcopy: Overfull hboxes.
+* Blank lines: sp.
+* Body of a macro: Defining Macros.
+* Book characteristics, printed: Printed Books.
+* Book, printing small: smallbook.
+* Box with rounded corners: cartouche.
+* Braces and argument syntax: Command Syntax.
+* Braces, inserting: Braces Atsigns.
+* Braces, when to use: Formatting Commands.
+* Breaks in a line: Line Breaks.
+* Breve accent: Inserting Accents.
+* Buffer formatting and printing: Printing.
+* Bullets, inserting: Dots Bullets.
+* Case in nodename: Node Line Requirements.
+* Catching errors with Info formatting: Debugging with Info.
+* Catching errors with TeX formatting: Debugging with TeX.
+* Catching mistakes: Catching Mistakes.
+* Cedilla accent: Inserting Accents.
+* Centimeters: Images.
+* Chapter structuring: Structuring.
+* Characteristics, printed books or manuals: Printed Books.
+* Chassell, Robert J.: Acknowledgements.
+* Check accent: Inserting Accents.
+* Checking for badly referenced nodes: Running Info-Validate.
+* Ciceros: Images.
+* Circumflex accent: Inserting Accents.
+* code, arg to @kbdinputstyle: kbd.
+* colon last in INFOPATH: Other Info Directories.
+* Column widths, defining for multitables: Multitable Column Widths.
+* Combining indices: Combining Indices.
+* Comma in nodename: Node Line Requirements.
+* Command definitions: Sample Function Definition.
+* Commands to insert special characters: Braces Atsigns.
+* Commands using raw HTML: Raw Formatter Commands.
+* Commands using raw TeX: Raw Formatter Commands.
+* Commands, inserting them: Inserting.
+* Comments: Comments.
+* Compile command for formatting: Compile-Command.
+* Conditionally visible text: Conditionals.
+* Conditions for copying Texinfo: Copying.
+* Contents, Table of: Contents.
+* Contents-like outline of file structure: Showing the Structure.
+* Conventions for writing definitions: Def Cmd Conventions.
+* Conventions, syntactic: Conventions.
+* Copying conditions: Copying.
+* Copying permissions: Sample Permissions.
+* Copying software: Software Copying Permissions.
+* Copyright page: Copyright & Permissions.
+* Correcting mistakes: Catching Mistakes.
+* Create nodes, menus automatically: Updating Nodes and Menus.
+* Creating an Info file: Create an Info File.
+* Creating an unsplit file: Unsplit.
+* Creating index entries: Indexing Commands.
+* Creating indices: Indices.
+* Creating pointers with makeinfo: makeinfo Pointer Creation.
+* Cropmarks for printing: Cropmarks and Magnification.
+* Cross reference parts: Cross Reference Parts.
+* Cross references: Cross References.
+* Cross references using @inforef: inforef.
+* Cross references using @pxref: pxref.
+* Cross references using @ref: ref.
+* Cross references using @xref: xref.
+* Customized highlighting: Customized Highlighting.
+* Customizing of TeX for Texinfo: Preparing for TeX.
+* Debugging the Texinfo structure: Catching Mistakes.
+* Debugging with Info formatting: Debugging with Info.
+* Debugging with TeX formatting: Debugging with TeX.
+* Defining indexing entries: Indexing Commands.
+* Defining macros: Defining Macros.
+* Defining new indices: New Indices.
+* Defining new Texinfo commands: Macros.
+* Definition commands: Definition Commands.
+* Definition conventions: Def Cmd Conventions.
+* Definition template: Def Cmd Template.
+* Definitions grouped together: deffnx.
+* Description for menu, start: Inserting.
+* Did^ot points: Images.
+* Different cross reference commands: Cross Reference Commands.
+* Dimension formatting: dmn.
+* Dimensions and image sizes: Images.
+* dir directory for Info installation: Install an Info File.
+* dir file listing: New Info File.
+* dir, created by install-info: Invoking install-info.
+* Display formatting: display.
+* distinct, arg to @kbdinputstyle: kbd.
+* Distorting images: Images.
+* Distribution: Software Copying Permissions.
+* Dot accent: Inserting Accents.
+* Dotless i, j: Inserting Accents.
+* Dots, inserting <1>: dots.
+* Dots, inserting: Dots Bullets.
+* Double-colon menu entries: Less Cluttered Menu Entry.
+* DVI file: Format with tex/texindex.
+* Ellipsis, inserting: Dots Bullets.
+* Emacs: Texinfo Mode.
+* Emacs shell, format, print from: Within Emacs.
+* Emphasizing text: Emphasis.
+* Emphasizing text, font for: emph & strong.
+* Enclosure command for Info: Customized Highlighting.
+* End node footnote style: Footnote Styles.
+* End of header line: End of Header.
+* End titlepage starts headings: end titlepage.
+* Ending a Sentence: Ending a Sentence.
+* Ending a Texinfo file: Ending a File.
+* Entries for an index: Indexing Commands.
+* Entries, making index: Index Entries.
+* Enumeration: enumerate.
+* epsf.tex: Images.
+* epsf.tex, installing: Preparing for TeX.
+* Equivalence, indicating it: Equivalence.
+* Error message, indicating it: Error Glyph.
+* Errors, parsing: makeinfo in Emacs.
+* Es-zet: Inserting Accents.
+* European A4 paper: A4 Paper.
+* Evaluation glyph: result.
+* Example for a small book: smallexample & smalllisp.
+* Example menu: Menu Example.
+* example, arg to @kbdinputstyle: kbd.
+* Examples, formatting them: example.
+* Expansion, indicating it: expansion.
+* File beginning: Beginning a File.
+* File ending: Ending a File.
+* File section structure, showing it: Showing the Structure.
+* Filling paragraphs: Refilling Paragraphs.
+* Final output: Overfull hboxes.
+* Finding badly referenced nodes: Running Info-Validate.
+* Fine-tuning, and hyphenation: - and hyphenation.
+* First line of a Texinfo file: First Line.
+* First node: First Node.
+* Floating accents, inserting: Inserting Accents.
+* Fonts for indices: syncodeindex.
+* Fonts for printing, not for Info: Fonts.
+* Footings: Headings.
+* Footnotes: Footnotes.
+* Format a dimension: dmn.
+* Format and print hardcopy: Format/Print Hardcopy.
+* Format and print in Texinfo mode: Texinfo Mode Printing.
+* Format with the compile command: Compile-Command.
+* Format, print from Emacs shell: Within Emacs.
+* Formats for images: Images.
+* Formatting a file for Info: Create an Info File.
+* Formatting commands: Formatting Commands.
+* Formatting examples: example.
+* Formatting for Info: Info Formatting.
+* Formatting for printing: Printing.
+* Formatting headings and footings: Headings.
+* Formatting requirements: Requirements Summary.
+* Formatting with tex and texindex: Format with tex/texindex.
+* Frequently used commands, inserting: Inserting.
+* Function definitions: Sample Function Definition.
+* General syntactic conventions: Conventions.
+* Generating menus with indices: Printing Indices & Menus.
+* German S: Inserting Accents.
+* Globbing: Format with tex/texindex.
+* Glyphs: Glyphs.
+* GNU Emacs: Texinfo Mode.
+* GNU Emacs shell, format, print from: Within Emacs.
+* Going to other Info files' nodes: Other Info Files.
+* Grave accent: Inserting Accents.
+* Group (hold text together vertically): group.
+* Grouping two definitions together: deffnx.
+* Hardcopy, printing it: Format/Print Hardcopy.
+* hboxes, overfull: Overfull hboxes.
+* Header for Texinfo files: Header.
+* Header of a Texinfo file: First Line.
+* Headings: Headings.
+* Headings, page, begin to appear: end titlepage.
+* Height of images: Images.
+* Highlighting text: Indicating.
+* Highlighting, customized: Customized Highlighting.
+* Hints: Tips.
+* Holding text together vertically: group.
+* HTML commands, using ordinary: Raw Formatter Commands.
+* Hungariam umlaut accent: Inserting Accents.
+* Hyphenation, helping TeX do: - and hyphenation.
+* Hyphenation, preventing: w.
+* i: Inserting Accents.
+* If text conditionally visible: Conditionals.
+* ifinfo permissions: ifinfo Permissions.
+* Ignored before @setfilename: setfilename.
+* Ignored text: Comments.
+* Image formats: Images.
+* Images, inserting: Images.
+* Inches: Images.
+* Include file requirements: Include File Requirements.
+* Include file sample: Sample Include File.
+* Include files: Include Files.
+* Include files, and section levels: Raise/lower sections.
+* Indentation undoing: exdent.
+* Indenting paragraphs: paragraphindent.
+* Index entries: Indexing Commands.
+* Index entries, making: Index Entries.
+* Index entry writing: Indexing Commands.
+* Index font types: Indexing Commands.
+* Indexing commands, predefined: Indexing Commands.
+* Indexing table entries automatically: ftable vtable.
+* Indicating commands, definitions, etc.: Indicating.
+* Indicating evaluation: result.
+* Indices: Indices.
+* Indices, combining them: Combining Indices.
+* Indices, defining new: New Indices.
+* Indices, printing and menus: Printing Indices & Menus.
+* Indices, sorting: Format/Print Hardcopy.
+* Indices, two letter names: syncodeindex.
+* Indirect subfiles: Tag and Split Files.
+* Info batch formatting: Batch Formatting.
+* Info file installation: Install an Info File.
+* Info file requires @setfilename: setfilename.
+* Info file, listing new one: New Info File.
+* Info file, splitting manually: Splitting.
+* Info files: Info Files.
+* Info formatting: Info Formatting.
+* Info installed in another directory: Other Info Directories.
+* Info validating a large file: Using Info-validate.
+* Info, creating an on-line file: Create an Info File.
+* Info-directory-list: Other Info Directories.
+* Info; other files' nodes: Other Info Files.
+* INFOPATH: Other Info Directories.
+* Initialization file for TeX input: Preparing for TeX.
+* Insert nodes, menus automatically: Updating Nodes and Menus.
+* Inserting @, braces: Braces Atsigns.
+* Inserting accents: Inserting Accents.
+* Inserting dots <1>: Dots Bullets.
+* Inserting dots: dots.
+* Inserting ellipsis: Dots Bullets.
+* Inserting frequently used commands: Inserting.
+* Inserting space: Inserting Space.
+* Inserting special characters and symbols: Insertions.
+* install-info: Invoking install-info.
+* Installing an Info file: Install an Info File.
+* Installing Info in another directory: Other Info Directories.
+* Introduction, as part of file: Software Copying Permissions.
+* Invoking macros: Invoking Macros.
+* Itemization: itemize.
+* j: Inserting Accents.
+* keyboard input: kbd.
+* Keys, recommended names: key.
+* Knuth, Donald: Printed Books.
+* l/: Inserting Accents.
+* L/: Inserting Accents.
+* Larger or smaller pages: Cropmarks and Magnification.
+* Less cluttered menu entry: Less Cluttered Menu Entry.
+* License agreement: Software Copying Permissions.
+* Line breaks: Line Breaks.
+* Line breaks, preventing: w.
+* Line length, column widths as fraction of: Multitable Column Widths.
+* Line spacing: sp.
+* Lisp example: Lisp Example.
+* Lisp example for a small book: smallexample & smalllisp.
+* List of @-commands: Command List.
+* Listing a new info file: New Info File.
+* Lists and tables, making: Lists and Tables.
+* Local variables: Compile-Command.
+* Location of menus: Menu Location.
+* Looking for badly referenced nodes: Running Info-Validate.
+* lpr (DVI print command): Print with lpr.
+* Macro definitions <1>: Sample Function Definition.
+* Macro definitions: Defining Macros.
+* Macro invocation: Invoking Macros.
+* Macron accent: Inserting Accents.
+* Macros: Macros.
+* Macros, undefining: Defining Macros.
+* Magnified printing: Cropmarks and Magnification.
+* mailto link: email.
+* makeinfo inside Emacs: makeinfo in Emacs.
+* makeinfo options: makeinfo options.
+* Making a printed manual: Format/Print Hardcopy.
+* Making a tag table automatically: Tag and Split Files.
+* Making a tag table manually: Unsplit.
+* Making cross references: Cross References.
+* Making line and page breaks: Breaks.
+* Making lists and tables: Lists and Tables.
+* Manual characteristics, printed: Printed Books.
+* Marking text within a paragraph: Marking Text.
+* Marking words and phrases: Marking Text.
+* Master menu: The Top Node.
+* Master menu parts: Master Menu Parts.
+* Mathematical expressions <1>: Raw Formatter Commands.
+* Mathematical expressions: math.
+* Menu description, start: Inserting.
+* Menu entries with two colons: Less Cluttered Menu Entry.
+* Menu example: Menu Example.
+* Menu location: Menu Location.
+* Menu parts: Menu Parts.
+* Menu writing: Writing a Menu.
+* Menus: Menus.
+* Menus generated with indices: Printing Indices & Menus.
+* META key: key.
+* Meta-syntactic chars for arguments: Optional Arguments.
+* Millimeters: Images.
+* Minimal requirements for formatting: Requirements Summary.
+* Minimal Texinfo file (requirements): Minimum.
+* Mistakes, catching: Catching Mistakes.
+* Mode, using Texinfo: Texinfo Mode.
+* Multiple spaces: Multiple Spaces.
+* Multitable column widths: Multitable Column Widths.
+* Multitable rows: Multitable Rows.
+* Must have in Texinfo file: Minimum.
+* Mutually recursive macros: Defining Macros.
+* Names for indices: syncodeindex.
+* Names of index files: Format with tex/texindex.
+* Names recommended for keys: key.
+* Naming a `Top' Node in references: Top Node Naming.
+* Need space at page bottom: need.
+* New index defining: New Indices.
+* New info file, listing it in dir file: New Info File.
+* New Texinfo commands, defining: Macros.
+* Node line requirements: Node Line Requirements.
+* Node line writing: Writing a Node.
+* Node, `Top': The Top Node.
+* Node, defined: node.
+* Nodename must be unique: Node Line Requirements.
+* Nodename, cannot contain: Node Line Requirements.
+* Nodes for menus are short: Menu Location.
+* Nodes in other Info files: Other Info Files.
+* Nodes, catching mistakes: Catching Mistakes.
+* Nodes, checking for badly referenced: Running Info-Validate.
+* Not ending a sentence: Not Ending a Sentence.
+* o/: Inserting Accents.
+* O/: Inserting Accents.
+* Obtaining TeX: Obtaining TeX.
+* Occurrences, listing with @occur: Using occur.
+* OE: Inserting Accents.
+* oe: Inserting Accents.
+* Optional and repeated arguments: Optional Arguments.
+* Options for makeinfo: makeinfo options.
+* Ordinary HTML commands, using: Raw Formatter Commands.
+* Ordinary TeX commands, using: Raw Formatter Commands.
+* Other Info files' nodes: Other Info Files.
+* Outline of file structure, showing it: Showing the Structure.
+* Overfull hboxes: Overfull hboxes.
+* Overview of Texinfo: Overview.
+* Page breaks: page.
+* Page delimiter in Texinfo mode: Showing the Structure.
+* Page headings: Headings.
+* Page numbering: Headings.
+* Page sizes for books: smallbook.
+* page-delimiter: Showing the Structure.
+* Pages, starting odd: setchapternewpage.
+* Paper size, European A4: A4 Paper.
+* Paragraph indentation: paragraphindent.
+* Paragraph, marking text within: Marking Text.
+* Parsing errors: makeinfo in Emacs.
+* Part of file formatting and printing: Printing.
+* Parts of a cross reference: Cross Reference Parts.
+* Parts of a master menu: Master Menu Parts.
+* Parts of a menu: Menu Parts.
+* Periods, inserting: Not Ending a Sentence.
+* Permissions: Sample Permissions.
+* Permissions, printed: Copyright & Permissions.
+* Picas: Images.
+* Pictures, inserting: Images.
+* Pinard, Franc,ois: Acknowledgements.
+* plain TeX: Raw Formatter Commands.
+* Point, indicating it in a buffer: Point Glyph.
+* Pointer creation with makeinfo: makeinfo Pointer Creation.
+* Pointer validation with makeinfo: Pointer Validation.
+* Points (dimension): Images.
+* Predefined indexing commands: Indexing Commands.
+* Predefined names for indices: syncodeindex.
+* Preparing to use TeX: Preparing for TeX.
+* Preventing line and page breaks: Breaks.
+* Previous node of Top node: First Node.
+* Print and format in Texinfo mode: Texinfo Mode Printing.
+* Print, format from Emacs shell: Within Emacs.
+* Printed book and manual characteristics: Printed Books.
+* Printed output, indicating it: Print Glyph.
+* Printed permissions: Copyright & Permissions.
+* Printing a region or buffer: Printing.
+* Printing an index: Printing Indices & Menus.
+* Printing cropmarks: Cropmarks and Magnification.
+* Problems, catching: Catching Mistakes.
+* Prototype row, column widths defined by: Multitable Column Widths.
+* Quotations: quotation.
+* Raising and lowering sections: Raise/lower sections.
+* Raw formatter commands: Raw Formatter Commands.
+* Recommended names for keys: key.
+* Rectangle, ugly, black in hardcopy: Overfull hboxes.
+* Recursion, mutual: Defining Macros.
+* References: Cross References.
+* References using @inforef: inforef.
+* References using @pxref: pxref.
+* References using @ref: ref.
+* References using @xref: xref.
+* Referring to other Info files: Other Info Files.
+* Refilling paragraphs: Refilling Paragraphs.
+* Region formatting and printing: Printing.
+* Region printing in Texinfo mode: Texinfo Mode Printing.
+* Repeated and optional arguments: Optional Arguments.
+* Required in Texinfo file: Minimum.
+* Requirements for formatting: Requirements Summary.
+* Requirements for include files: Include File Requirements.
+* Requirements for updating commands: Updating Requirements.
+* Result of an expression: result.
+* ridt.eps: Images.
+* Ring accent: Inserting Accents.
+* Rows, of a multitable: Multitable Rows.
+* Running an Info formatter: Info Formatting.
+* Running Info-validate: Using Info-validate.
+* Running makeinfo in Emacs: makeinfo in Emacs.
+* Sample @include file: Sample Include File.
+* Sample function definition: Sample Function Definition.
+* Sample Texinfo file: Short Sample.
+* Sample Texinfo file, no comments: Sample Texinfo File.
+* Scaled points: Images.
+* Section structure of a file, showing it: Showing the Structure.
+* Sections, raising and lowering: Raise/lower sections.
+* Sentence ending punctuation: Ending a Sentence.
+* Sentence non-ending punctuation: Not Ending a Sentence.
+* Separate footnote style: Footnote Styles.
+* Sharp S: Inserting Accents.
+* Shell formatting with tex and texindex: Format with tex/texindex.
+* Shell, format, print from: Within Emacs.
+* Shell, running makeinfo in: makeinfo in Emacs.
+* Short nodes for menus: Menu Location.
+* Showing the section structure of a file: Showing the Structure.
+* Showing the structure of a file: Using texinfo-show-structure.
+* Site-wide Texinfo configuration file: Preparing for TeX.
+* Size of printed book: smallbook.
+* slanted typewriter font, for @kbd: kbd.
+* Small book example: smallexample & smalllisp.
+* Small book size: smallbook.
+* Small caps font: Smallcaps.
+* Software copying permissions: Software Copying Permissions.
+* Sorting indices: Format/Print Hardcopy.
+* Spaces (blank lines): sp.
+* Spacing, inserting: Inserting Space.
+* Special characters, commands to insert: Braces Atsigns.
+* Special insertions: Insertions.
+* Special typesetting commands: Dots Bullets.
+* Specifying index entries: Indexing Commands.
+* Splitting an Info file manually: Splitting.
+* ss: Inserting Accents.
+* Stallman, Richard M.: Acknowledgements.
+* Start of header line: Start of Header.
+* Starting chapters: setchapternewpage.
+* Structure of a file, showing it: Showing the Structure.
+* Structure, catching mistakes in: Catching Mistakes.
+* Structuring of chapters: Structuring.
+* Subsection-like commands: unnumberedsubsec appendixsubsec subheading.
+* Subsub commands: subsubsection.
+* Syntactic conventions: Conventions.
+* Syntax, optional & repeated arguments: Optional Arguments.
+* tab: Multitable Rows.
+* Table of contents: Contents.
+* Tables and lists, making: Lists and Tables.
+* Tables with indexes: ftable vtable.
+* Tables, making multi-column: Multi-column Tables.
+* Tables, making two-column: Two-column Tables.
+* Tabs; don't use!: Conventions.
+* Tag table, making automatically: Tag and Split Files.
+* Tag table, making manually: Unsplit.
+* Template for a definition: Def Cmd Template.
+* TeX commands, using ordinary: Raw Formatter Commands.
+* TeX index sorting: Format/Print Hardcopy.
+* TeX input initialization: Preparing for TeX.
+* TeX, how to obtain: Obtaining TeX.
+* texi2dvi: Format with tex/texindex.
+* texi2dvi (shell script): Format with texi2dvi.
+* texindex <1>: Format/Print Hardcopy.
+* texindex: Format with tex/texindex.
+* Texinfo commands, defining new: Macros.
+* Texinfo file beginning: Beginning a File.
+* Texinfo file ending: Ending a File.
+* Texinfo file header: Header.
+* Texinfo file minimum: Minimum.
+* Texinfo file section structure, showing it: Showing the Structure.
+* Texinfo mode: Texinfo Mode.
+* Texinfo overview: Overview.
+* Texinfo printed book characteristics: Printed Books.
+* texinfo.cnf <1>: A4 Paper.
+* texinfo.cnf: setfilename.
+* texinfo.cnf installation: Preparing for TeX.
+* texinfo.tex, installing: Preparing for TeX.
+* TEXINPUTS: Preparing for TeX.
+* TEXINPUTS environment variable: Preparing for TeX.
+* Text, conditionally visible: Conditionals.
+* Thin space between number, dimension: dmn.
+* Tie-after accent: Inserting Accents.
+* Tilde accent: Inserting Accents.
+* Tips: Tips.
+* Title page: titlepage.
+* Titlepage end starts headings: end titlepage.
+* Titlepage permissions: Titlepage Permissions.
+* Top node: The Top Node.
+* Top node is first: First Node.
+* Top node naming for references: Top Node Naming.
+* Top node summary: Top Node Summary.
+* Tree structuring: Tree Structuring.
+* Two `First' Lines for @deffn: deffnx.
+* Two letter names for indices: syncodeindex.
+* Two named items for @table: itemx.
+* Two part menu entry: Less Cluttered Menu Entry.
+* Typesetting commands for dots, etc.: Dots Bullets.
+* Umlaut accent: Inserting Accents.
+* Uncluttered menu entry: Less Cluttered Menu Entry.
+* Undefining macros: Defining Macros.
+* Underbar accent: Inserting Accents.
+* Underdot accent: Inserting Accents.
+* Uniform resource locator, indicating: url.
+* Uniform resource locator, referring to: uref.
+* Unique nodename requirement: Node Line Requirements.
+* Unprocessed text: Comments.
+* Unsplit file creation: Unsplit.
+* Up node of Top node: First Node.
+* Updating nodes and menus: Updating Nodes and Menus.
+* Updating requirements: Updating Requirements.
+* URL, indicating: url.
+* URL, referring to: uref.
+* Usage tips: Tips.
+* user input: kbd.
+* User options, marking: Variables Commands.
+* User-defined Texinfo commands: Macros.
+* Validating a large file: Using Info-validate.
+* Validation of pointers: Pointer Validation.
+* Value of an expression, indicating: result.
+* version number, finding: Invoking install-info.
+* Vertical whitespace (vskip): Copyright & Permissions.
+* Vertically holding text together: group.
+* Visibility of conditional text: Conditionals.
+* Weisshaus, Melissa: Acknowledgements.
+* Whitespace, inserting <1>: Inserting Space.
+* Whitespace, inserting: Multiple Spaces.
+* Width of images: Images.
+* Widths, defining multitable column: Multitable Column Widths.
+* Wildcards: Format with tex/texindex.
+* Words and phrases, marking them: Marking Text.
+* Writing a menu: Writing a Menu.
+* Writing an @node line: Writing a Node.
+* Writing index entries: Indexing Commands.
+* Zuhn, David D.: Acknowledgements.
+
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview
+
+A Short Sample Texinfo File
+===========================
+
+ Here is a complete but very short Texinfo file, in six parts. The
+first three parts of the file, from `\input texinfo' through to `@end
+titlepage', look more intimidating than they are. Most of the material
+is standard boilerplate; when you write a manual, simply insert the
+names for your own manual in this segment. (*Note Beginning a File::.)
+
+In the following, the sample text is *indented*; comments on it are
+not. The complete file, without any comments, is shown in *Note Sample
+Texinfo File::.
+
+Part 1: Header
+--------------
+
+The header does not appear in either the Info file or the printed
+output. It sets various parameters, including the name of the Info
+file and the title used in the header.
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename sample.info
+ @settitle Sample Document
+ @c %**end of header
+
+ @setchapternewpage odd
+
+Part 2: Summary Description and Copyright
+-----------------------------------------
+
+The summary description and copyright segment does not appear in the
+printed document.
+
+ @ifinfo
+ This is a short example of a complete Texinfo file.
+
+ Copyright @copyright{} 1990 Free Software Foundation, Inc.
+ @end ifinfo
+
+Part 3: Titlepage and Copyright
+-------------------------------
+
+The titlepage segment does not appear in the Info file.
+
+ @titlepage
+ @sp 10
+ @comment The title is printed in a large font.
+ @center @titlefont{Sample Title}
+
+ @c The following two commands start the copyright page.
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} 1990 Free Software Foundation, Inc.
+ @end titlepage
+
+Part 4: `Top' Node and Master Menu
+----------------------------------
+
+The `Top' node contains the master menu for the Info file. Since a
+printed manual uses a table of contents rather than a menu, the master
+menu appears only in the Info file.
+
+ @node Top, First Chapter, , (dir)
+ @comment node-name, next, previous, up
+
+ @menu
+ * First Chapter:: The first chapter is the
+ only chapter in this sample.
+ * Concept Index:: This index has two entries.
+ @end menu
+
+Part 5: The Body of the Document
+---------------------------------
+
+The body segment contains all the text of the document, but not the
+indices or table of contents. This example illustrates a node and a
+chapter containing an enumerated list.
+
+ @node First Chapter, Concept Index, Top, Top
+ @comment node-name, next, previous, up
+ @chapter First Chapter
+ @cindex Sample index entry
+
+ This is the contents of the first chapter.
+ @cindex Another sample index entry
+
+ Here is a numbered list.
+
+ @enumerate
+ @item
+ This is the first item.
+
+ @item
+ This is the second item.
+ @end enumerate
+
+ The @code{makeinfo} and @code{texinfo-format-buffer}
+ commands transform a Texinfo file such as this into
+ an Info file; and @TeX{} typesets it for a printed
+ manual.
+
+Part 6: The End of the Document
+-------------------------------
+
+The end segment contains commands both for generating an index in a node
+and unnumbered chapter of its own and for generating the table of
+contents; and it contains the `@bye' command that marks the end of the
+document.
+
+ @node Concept Index, , First Chapter, Top
+ @comment node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @contents
+ @bye
+
+The Results
+-----------
+
+ Here is what the contents of the first chapter of the sample look
+like:
+
+ This is the contents of the first chapter.
+
+ Here is a numbered list.
+
+ 1. This is the first item.
+
+ 2. This is the second item.
+
+ The `makeinfo' and `texinfo-format-buffer' commands transform a
+ Texinfo file such as this into an Info file; and TeX typesets it
+ for a printed manual.
+
+\1f
+File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
+
+Acknowledgements
+================
+
+ Richard M. Stallman wrote Edition 1.0 of this manual.
+Robert J. Chassell revised and extended it, starting with Edition 1.1.
+Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
+starting with Edition 2.22.
+
+ Our thanks go out to all who helped improve this work, particularly to
+Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
+reported mistakes and obscurities; our special thanks go to Melissa
+Weisshaus for her frequent and often tedious reviews of nearly similar
+editions. Our mistakes are our own.
+
+ Please send suggestions and corrections to:
+
+ Internet address:
+ bug-texinfo@gnu.org
+
+Please include the manual's edition number and update date in your
+messages.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
+
+Using Texinfo Mode
+******************
+
+ You may edit a Texinfo file with any text editor you choose. A
+Texinfo file is no different from any other ASCII file. However, GNU
+Emacs comes with a special mode, called Texinfo mode, that provides
+Emacs commands and tools to help ease your work.
+
+ This chapter describes features of GNU Emacs' Texinfo mode but not any
+features of the Texinfo formatting language. If you are reading this
+manual straight through from the beginning, you may want to skim through
+this chapter briefly and come back to it after reading succeeding
+chapters which describe the Texinfo formatting language in detail.
+
+* Menu:
+
+* Texinfo Mode Overview:: How Texinfo mode can help you.
+* Emacs Editing:: Texinfo mode adds to GNU Emacs' general
+ purpose editing features.
+* Inserting:: How to insert frequently used @-commands.
+* Showing the Structure:: How to show the structure of a file.
+* Updating Nodes and Menus:: How to update or create new nodes and menus.
+* Info Formatting:: How to format for Info.
+* Printing:: How to format and print part or all of a file.
+* Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
+
+Texinfo Mode Overview
+=====================
+
+ Texinfo mode provides special features for working with Texinfo files:
+
+ * Insert frequently used @-commands.
+
+ * Automatically create `@node' lines.
+
+ * Show the structure of a Texinfo source file.
+
+ * Automatically create or update the `Next', `Previous', and `Up'
+ pointers of a node.
+
+ * Automatically create or update menus.
+
+ * Automatically create a master menu.
+
+ * Format a part or all of a file for Info.
+
+ * Typeset and print part or all of a file.
+
+ Perhaps the two most helpful features are those for inserting
+frequently used @-commands and for creating node pointers and menus.
+
+\1f
+File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
+
+The Usual GNU Emacs Editing Commands
+====================================
+
+ In most cases, the usual Text mode commands work the same in Texinfo
+mode as they do in Text mode. Texinfo mode adds new editing commands
+and tools to GNU Emacs' general purpose editing features. The major
+difference concerns filling. In Texinfo mode, the paragraph separation
+variable and syntax table are redefined so that Texinfo commands that
+should be on lines of their own are not inadvertently included in
+paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
+paragraph but not mix an indexing command on a line adjacent to it into
+the paragraph.
+
+ In addition, Texinfo mode sets the `page-delimiter' variable to the
+value of `texinfo-chapter-level-regexp'; by default, this is a regular
+expression matching the commands for chapters and their equivalents,
+such as appendices. With this value for the page delimiter, you can
+jump from chapter title to chapter title with the `C-x ]'
+(`forward-page') and `C-x [' (`backward-page') commands and narrow to a
+chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
+(xemacs)Pages, for details about the page commands.)
+
+ You may name a Texinfo file however you wish, but the convention is to
+end a Texinfo file name with one of the three extensions `.texinfo',
+`.texi', or `.tex'. A longer extension is preferred, since it is
+explicit, but a shorter extension may be necessary for operating
+systems that limit the length of file names. GNU Emacs automatically
+enters Texinfo mode when you visit a file with a `.texinfo' or `.texi'
+extension. Also, Emacs switches to Texinfo mode when you visit a file
+that has `-*-texinfo-*-' in its first line. If ever you are in another
+mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
+
+ Like all other Emacs features, you can customize or enhance Texinfo
+mode as you wish. In particular, the keybindings are very easy to
+change. The keybindings described here are the default or standard
+ones.
+
+\1f
+File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
+
+Inserting Frequently Used Commands
+==================================
+
+ Texinfo mode provides commands to insert various frequently used
+@-commands into the buffer. You can use these commands to save
+keystrokes.
+
+ The insert commands are invoked by typing `C-c' twice and then the
+first letter of the @-command:
+
+`C-c C-c c'
+`M-x texinfo-insert-@code'
+ Insert `@code{}' and put the cursor between the braces.
+
+`C-c C-c d'
+`M-x texinfo-insert-@dfn'
+ Insert `@dfn{}' and put the cursor between the braces.
+
+`C-c C-c e'
+`M-x texinfo-insert-@end'
+ Insert `@end' and attempt to insert the correct following word,
+ such as `example' or `table'. (This command does not handle
+ nested lists correctly, but inserts the word appropriate to the
+ immediately preceding list.)
+
+`C-c C-c i'
+`M-x texinfo-insert-@item'
+ Insert `@item' and put the cursor at the beginning of the next
+ line.
+
+`C-c C-c k'
+`M-x texinfo-insert-@kbd'
+ Insert `@kbd{}' and put the cursor between the braces.
+
+`C-c C-c n'
+`M-x texinfo-insert-@node'
+ Insert `@node' and a comment line listing the sequence for the
+ `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
+
+`C-c C-c o'
+`M-x texinfo-insert-@noindent'
+ Insert `@noindent' and put the cursor at the beginning of the next
+ line.
+
+`C-c C-c s'
+`M-x texinfo-insert-@samp'
+ Insert `@samp{}' and put the cursor between the braces.
+
+`C-c C-c t'
+`M-x texinfo-insert-@table'
+ Insert `@table' followed by a <SPC> and leave the cursor after the
+ <SPC>.
+
+`C-c C-c v'
+`M-x texinfo-insert-@var'
+ Insert `@var{}' and put the cursor between the braces.
+
+`C-c C-c x'
+`M-x texinfo-insert-@example'
+ Insert `@example' and put the cursor at the beginning of the next
+ line.
+
+`C-c C-c {'
+`M-x texinfo-insert-braces'
+ Insert `{}' and put the cursor between the braces.
+
+`C-c C-c }'
+`C-c C-c ]'
+`M-x up-list'
+ Move from between a pair of braces forward past the closing brace.
+ Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
+ however, more mnemonic; hence the two keybindings. (Also, you can
+ move out from between braces by typing `C-f'.)
+
+ To put a command such as `@code{...}' around an *existing* word,
+position the cursor in front of the word and type `C-u 1 C-c C-c c'.
+This makes it easy to edit existing plain text. The value of the
+prefix argument tells Emacs how many words following point to include
+between braces--`1' for one word, `2' for two words, and so on. Use a
+negative argument to enclose the previous word or words. If you do not
+specify a prefix argument, Emacs inserts the @-command string and
+positions the cursor between the braces. This feature works only for
+those @-commands that operate on a word or words within one line, such
+as `@kbd' and `@var'.
+
+ This set of insert commands was created after analyzing the frequency
+with which different @-commands are used in the `GNU Emacs Manual' and
+the `GDB Manual'. If you wish to add your own insert commands, you can
+bind a keyboard macro to a key, use abbreviations, or extend the code
+in `texinfo.el'.
+
+ `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
+that works differently from the other insert commands. It inserts a
+node's section or chapter title in the space for the description in a
+menu entry line. (A menu entry has three parts, the entry name, the
+node name, and the description. Only the node name is required, but a
+description helps explain what the node is about. *Note The Parts of a
+Menu: Menu Parts.)
+
+ To use `texinfo-start-menu-description', position point in a menu
+entry line and type `C-c C-c C-d'. The command looks for and copies
+the title that goes with the node name, and inserts the title as a
+description; it positions point at beginning of the inserted text so you
+can edit it. The function does not insert the title if the menu entry
+line already contains a description.
+
+ This command is only an aid to writing descriptions; it does not do
+the whole job. You must edit the inserted text since a title tends to
+use the same words as a node name but a useful description uses
+different words.
+
+\1f
+File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
+
+Showing the Section Structure of a File
+=======================================
+
+ You can show the section structure of a Texinfo file by using the
+`C-c C-s' command (`texinfo-show-structure'). This command shows the
+section structure of a Texinfo file by listing the lines that begin
+with the @-commands for `@chapter', `@section', and the like. It
+constructs what amounts to a table of contents. These lines are
+displayed in another buffer called the `*Occur*' buffer. In that
+buffer, you can position the cursor over one of the lines and use the
+`C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
+corresponding spot in the Texinfo file.
+
+`C-c C-s'
+`M-x texinfo-show-structure'
+ Show the `@chapter', `@section', and such lines of a Texinfo file.
+
+`C-c C-c'
+`M-x occur-mode-goto-occurrence'
+ Go to the line in the Texinfo file corresponding to the line under
+ the cursor in the `*Occur*' buffer.
+
+ If you call `texinfo-show-structure' with a prefix argument by typing
+`C-u C-c C-s', it will list not only those lines with the @-commands
+for `@chapter', `@section', and the like, but also the `@node' lines.
+(This is how the `texinfo-show-structure' command worked without an
+argument in the first version of Texinfo. It was changed because
+`@node' lines clutter up the `*Occur*' buffer and are usually not
+needed.) You can use `texinfo-show-structure' with a prefix argument
+to check whether the `Next', `Previous', and `Up' pointers of an
+`@node' line are correct.
+
+ Often, when you are working on a manual, you will be interested only
+in the structure of the current chapter. In this case, you can mark
+off the region of the buffer that you are interested in by using the
+`C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
+will work on only that region. To see the whole buffer again, use
+`C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more
+information about the narrowing commands.)
+
+ In addition to providing the `texinfo-show-structure' command,
+Texinfo mode sets the value of the page delimiter variable to match the
+chapter-level @-commands. This enables you to use the `C-x ]'
+(`forward-page') and `C-x [' (`backward-page') commands to move forward
+and backward by chapter, and to use the `C-x p' (`narrow-to-page')
+command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more
+information about the page commands.
+
+\1f
+File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
+
+Updating Nodes and Menus
+========================
+
+ Texinfo mode provides commands for automatically creating or updating
+menus and node pointers. The commands are called "update" commands
+because their most frequent use is for updating a Texinfo file after
+you have worked on it; but you can use them to insert the `Next',
+`Previous', and `Up' pointers into an `@node' line that has none and to
+create menus in a file that has none.
+
+ If you do not use the updating commands, you need to write menus and
+node pointers by hand, which is a tedious task.
+
+* Menu:
+
+* Updating Commands:: Five major updating commands.
+* Updating Requirements:: How to structure a Texinfo file for
+ using the updating command.
+* Other Updating Commands:: How to indent descriptions, insert
+ missing nodes lines, and update
+ nodes in sequence.
+
+\1f
+File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
+
+The Updating Commands
+---------------------
+
+ You can use the updating commands
+
+ * to insert or update the `Next', `Previous', and `Up' pointers of a
+ node,
+
+ * to insert or update the menu for a section, and
+
+ * to create a master menu for a Texinfo source file.
+
+ You can also use the commands to update all the nodes and menus in a
+region or in a whole Texinfo file.
+
+ The updating commands work only with conventional Texinfo files, which
+are structured hierarchically like books. In such files, a structuring
+command line must follow closely after each `@node' line, except for
+the `Top' `@node' line. (A "structuring command line" is a line
+beginning with `@chapter', `@section', or other similar command.)
+
+ You can write the structuring command line on the line that follows
+immediately after an `@node' line or else on the line that follows
+after a single `@comment' line or a single `@ifinfo' line. You cannot
+interpose more than one line between the `@node' line and the
+structuring command line; and you may interpose only an `@comment' line
+or an `@ifinfo' line.
+
+ Commands which work on a whole buffer require that the `Top' node be
+followed by a node with an `@chapter' or equivalent-level command.
+Note that the menu updating commands will not create a main or master
+menu for a Texinfo file that has only `@chapter'-level nodes! The menu
+updating commands only create menus *within* nodes for lower level
+nodes. To create a menu of chapters, you must provide a `Top' node.
+
+ The menu updating commands remove menu entries that refer to other
+Info files since they do not refer to nodes within the current buffer.
+This is a deficiency. Rather than use menu entries, you can use cross
+references to refer to other Info files. None of the updating commands
+affect cross references.
+
+ Texinfo mode has five updating commands that are used most often: two
+are for updating the node pointers or menu of a single node (or a
+region); two are for updating every node pointer and menu in a file;
+and one, the `texinfo-master-menu' command, is for creating a master
+menu for a complete file, and optionally, for updating every node and
+menu in the whole Texinfo file.
+
+ The `texinfo-master-menu' command is the primary command:
+
+`C-c C-u m'
+`M-x texinfo-master-menu'
+ Create or update a master menu that includes all the other menus
+ (incorporating the descriptions from pre-existing menus, if any).
+
+ With an argument (prefix argument, `C-u,' if interactive), first
+ create or update all the nodes and all the regular menus in the
+ buffer before constructing the master menu. (*Note The Top Node
+ and Master Menu: The Top Node, for more about a master menu.)
+
+ For `texinfo-master-menu' to work, the Texinfo file must have a
+ `Top' node and at least one subsequent node.
+
+ After extensively editing a Texinfo file, you can type the
+ following:
+
+ C-u M-x texinfo-master-menu
+ or
+ C-u C-c C-u m
+
+ This updates all the nodes and menus completely and all at once.
+
+ The other major updating commands do smaller jobs and are designed for
+the person who updates nodes and menus as he or she writes a Texinfo
+file.
+
+ The commands are:
+
+`C-c C-u C-n'
+`M-x texinfo-update-node'
+ Insert the `Next', `Previous', and `Up' pointers for the node that
+ point is within (i.e., for the `@node' line preceding point). If
+ the `@node' line has pre-existing `Next', `Previous', or `Up'
+ pointers in it, the old pointers are removed and new ones inserted.
+ With an argument (prefix argument, `C-u', if interactive), this
+ command updates all `@node' lines in the region (which is the text
+ between point and mark).
+
+`C-c C-u C-m'
+`M-x texinfo-make-menu'
+ Create or update the menu in the node that point is within. With
+ an argument (`C-u' as prefix argument, if interactive), the
+ command makes or updates menus for the nodes which are either
+ within or a part of the region.
+
+ Whenever `texinfo-make-menu' updates an existing menu, the
+ descriptions from that menu are incorporated into the new menu.
+ This is done by copying descriptions from the existing menu to the
+ entries in the new menu that have the same node names. If the
+ node names are different, the descriptions are not copied to the
+ new menu.
+
+`C-c C-u C-e'
+`M-x texinfo-every-node-update'
+ Insert or update the `Next', `Previous', and `Up' pointers for
+ every node in the buffer.
+
+`C-c C-u C-a'
+`M-x texinfo-all-menus-update'
+ Create or update all the menus in the buffer. With an argument
+ (`C-u' as prefix argument, if interactive), first insert or update
+ all the node pointers before working on the menus.
+
+ If a master menu exists, the `texinfo-all-menus-update' command
+ updates it; but the command does not create a new master menu if
+ none already exists. (Use the `texinfo-master-menu' command for
+ that.)
+
+ When working on a document that does not merit a master menu, you
+ can type the following:
+
+ C-u C-c C-u C-a
+ or
+ C-u M-x texinfo-all-menus-update
+
+ This updates all the nodes and menus.
+
+ The `texinfo-column-for-description' variable specifies the column to
+which menu descriptions are indented. By default, the value is 32
+although it is often useful to reduce it to as low as 24. You can set
+the variable with the `M-x edit-options' command (*note Editing
+Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
+command (*note Examining and Setting Variables: (xemacs)Examining.).
+
+ Also, the `texinfo-indent-menu-description' command may be used to
+indent existing menu descriptions to a specified column. Finally, if
+you wish, you can use the `texinfo-insert-node-lines' command to insert
+missing `@node' lines into a file. (*Note Other Updating Commands::,
+for more information.)
+
+\1f
+File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
+
+Updating Requirements
+---------------------
+
+ To use the updating commands, you must organize the Texinfo file
+hierarchically with chapters, sections, subsections, and the like.
+When you construct the hierarchy of the manual, do not `jump down' more
+than one level at a time: you can follow the `Top' node with a chapter,
+but not with a section; you can follow a chapter with a section, but
+not with a subsection. However, you may `jump up' any number of levels
+at one time--for example, from a subsection to a chapter.
+
+ Each `@node' line, with the exception of the line for the `Top' node,
+must be followed by a line with a structuring command such as
+`@chapter', `@section', or `@unnumberedsubsec'.
+
+ Each `@node' line/structuring-command line combination must look
+either like this:
+
+ @node Comments, Minimum, Conventions, Overview
+ @comment node-name, next, previous, up
+ @section Comments
+
+ or like this (without the `@comment' line):
+
+ @node Comments, Minimum, Conventions, Overview
+ @section Comments
+
+In this example, `Comments' is the name of both the node and the
+section. The next node is called `Minimum' and the previous node is
+called `Conventions'. The `Comments' section is within the `Overview'
+node, which is specified by the `Up' pointer. (Instead of an
+`@comment' line, you can write an `@ifinfo' line.)
+
+ If a file has a `Top' node, it must be called `top' or `Top' and be
+the first node in the file.
+
+ The menu updating commands create a menu of sections within a chapter,
+a menu of subsections within a section, and so on. This means that you
+must have a `Top' node if you want a menu of chapters.
+
+ Incidentally, the `makeinfo' command will create an Info file for a
+hierarchically organized Texinfo file that lacks `Next', `Previous' and
+`Up' pointers. Thus, if you can be sure that your Texinfo file will be
+formatted with `makeinfo', you have no need for the `update node'
+commands. (*Note Creating an Info File: Create an Info File, for more
+information about `makeinfo'.) However, both `makeinfo' and the
+`texinfo-format-...' commands require that you insert menus in the file.
+
+\1f
+File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
+
+Other Updating Commands
+-----------------------
+
+ In addition to the five major updating commands, Texinfo mode
+possesses several less frequently used updating commands:
+
+`M-x texinfo-insert-node-lines'
+ Insert `@node' lines before the `@chapter', `@section', and other
+ sectioning commands wherever they are missing throughout a region
+ in a Texinfo file.
+
+ With an argument (`C-u' as prefix argument, if interactive), the
+ `texinfo-insert-node-lines' command not only inserts `@node' lines
+ but also inserts the chapter or section titles as the names of the
+ corresponding nodes. In addition, it inserts the titles as node
+ names in pre-existing `@node' lines that lack names. Since node
+ names should be more concise than section or chapter titles, you
+ must manually edit node names so inserted.
+
+ For example, the following marks a whole buffer as a region and
+ inserts `@node' lines and titles throughout:
+
+ C-x h C-u M-x texinfo-insert-node-lines
+
+ (Note that this command inserts titles as node names in `@node'
+ lines; the `texinfo-start-menu-description' command (*note
+ Inserting Frequently Used Commands: Inserting.) inserts titles as
+ descriptions in menu entries, a different action. However, in both
+ cases, you need to edit the inserted text.)
+
+`M-x texinfo-multiple-files-update'
+ Update nodes and menus in a document built from several separate
+ files. With `C-u' as a prefix argument, create and insert a
+ master menu in the outer file. With a numeric prefix argument,
+ such as `C-u 2', first update all the menus and all the `Next',
+ `Previous', and `Up' pointers of all the included files before
+ creating and inserting a master menu in the outer file. The
+ `texinfo-multiple-files-update' command is described in the
+ appendix on `@include' files. *Note
+ texinfo-multiple-files-update::.
+
+`M-x texinfo-indent-menu-description'
+ Indent every description in the menu following point to the
+ specified column. You can use this command to give yourself more
+ space for descriptions. With an argument (`C-u' as prefix
+ argument, if interactive), the `texinfo-indent-menu-description'
+ command indents every description in every menu in the region.
+ However, this command does not indent the second and subsequent
+ lines of a multi-line description.
+
+`M-x texinfo-sequential-node-update'
+ Insert the names of the nodes immediately following and preceding
+ the current node as the `Next' or `Previous' pointers regardless
+ of those nodes' hierarchical level. This means that the `Next'
+ node of a subsection may well be the next chapter. Sequentially
+ ordered nodes are useful for novels and other documents that you
+ read through sequentially. (However, in Info, the `g *' command
+ lets you look through the file sequentially, so sequentially
+ ordered nodes are not strictly necessary.) With an argument
+ (prefix argument, if interactive), the
+ `texinfo-sequential-node-update' command sequentially updates all
+ the nodes in the region.
+
+\1f
+File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
+
+Formatting for Info
+===================
+
+ Texinfo mode provides several commands for formatting part or all of a
+Texinfo file for Info. Often, when you are writing a document, you
+want to format only part of a file--that is, a region.
+
+ You can use either the `texinfo-format-region' or the
+`makeinfo-region' command to format a region:
+
+`C-c C-e C-r'
+`M-x texinfo-format-region'
+`C-c C-m C-r'
+`M-x makeinfo-region'
+ Format the current region for Info.
+
+ You can use either the `texinfo-format-buffer' or the
+`makeinfo-buffer' command to format a whole buffer:
+
+`C-c C-e C-b'
+`M-x texinfo-format-buffer'
+`C-c C-m C-b'
+`M-x makeinfo-buffer'
+ Format the current buffer for Info.
+
+ For example, after writing a Texinfo file, you can type the following:
+
+ C-u C-c C-u m
+or
+ C-u M-x texinfo-master-menu
+
+This updates all the nodes and menus. Then type the following to create
+an Info file:
+
+ C-c C-m C-b
+or
+ M-x makeinfo-buffer
+
+ For TeX or the Info formatting commands to work, the file *must*
+include a line that has `@setfilename' in its header.
+
+ *Note Create an Info File::, for details about Info formatting.
+
+\1f
+File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
+
+Formatting and Printing
+=======================
+
+ Typesetting and printing a Texinfo file is a multi-step process in
+which you first create a file for printing (called a DVI file), and then
+print the file. Optionally, you may also create indices. To do this,
+you must run the `texindex' command after first running the `tex'
+typesetting command; and then you must run the `tex' command again. Or
+else run the `texi2dvi' command which automatically creates indices as
+needed (*note Format with texi2dvi::.).
+
+ Often, when you are writing a document, you want to typeset and print
+only part of a file to see what it will look like. You can use the
+`texinfo-tex-region' and related commands for this purpose. Use the
+`texinfo-tex-buffer' command to format all of a buffer.
+
+`C-c C-t C-b'
+`M-x texinfo-tex-buffer'
+ Run `texi2dvi' on the buffer. In addition to running TeX on the
+ buffer, this command automatically creates or updates indices as
+ needed.
+
+`C-c C-t C-r'
+`M-x texinfo-tex-region'
+ Run TeX on the region.
+
+`C-c C-t C-i'
+`M-x texinfo-texindex'
+ Run `texindex' to sort the indices of a Texinfo file formatted with
+ `texinfo-tex-region'. The `texinfo-tex-region' command does not
+ run `texindex' automatically; it only runs the `tex' typesetting
+ command. You must run the `texinfo-tex-region' command a second
+ time after sorting the raw index files with the `texindex'
+ command. (Usually, you do not format an index when you format a
+ region, only when you format a buffer. Now that the `texi2dvi'
+ command exists, there is little or no need for this command.)
+
+`C-c C-t C-p'
+`M-x texinfo-tex-print'
+ Print the file (or the part of the file) previously formatted with
+ `texinfo-tex-buffer' or `texinfo-tex-region'.
+
+ For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
+*must* start with a `\input texinfo' line and must include an
+`@settitle' line. The file must end with `@bye' on a line by itself.
+(When you use `texinfo-tex-region', you must surround the `@settitle'
+line with start-of-header and end-of-header lines.)
+
+ *Note Format/Print Hardcopy::, for a description of the other TeX
+related commands, such as `tex-show-print-queue'.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
+
+Texinfo Mode Summary
+====================
+
+ In Texinfo mode, each set of commands has default keybindings that
+begin with the same keys. All the commands that are custom-created for
+Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
+
+Insert Commands
+---------------
+
+ The insert commands are invoked by typing `C-c' twice and then the
+first letter of the @-command to be inserted. (It might make more
+sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
+is quick to type.)
+
+ C-c C-c c Insert `@code'.
+ C-c C-c d Insert `@dfn'.
+ C-c C-c e Insert `@end'.
+ C-c C-c i Insert `@item'.
+ C-c C-c n Insert `@node'.
+ C-c C-c s Insert `@samp'.
+ C-c C-c v Insert `@var'.
+ C-c C-c { Insert braces.
+ C-c C-c ]
+ C-c C-c } Move out of enclosing braces.
+
+ C-c C-c C-d Insert a node's section title
+ in the space for the description
+ in a menu entry line.
+
+Show Structure
+--------------
+
+ The `texinfo-show-structure' command is often used within a narrowed
+region.
+
+ C-c C-s List all the headings.
+
+The Master Update Command
+-------------------------
+
+ The `texinfo-master-menu' command creates a master menu; and can be
+used to update every node and menu in a file as well.
+
+ C-c C-u m
+ M-x texinfo-master-menu
+ Create or update a master menu.
+
+ C-u C-c C-u m With `C-u' as a prefix argument, first
+ create or update all nodes and regular
+ menus, and then create a master menu.
+
+Update Pointers
+---------------
+
+ The update pointer commands are invoked by typing `C-c C-u' and then
+either `C-n' for `texinfo-update-node' or `C-e' for
+`texinfo-every-node-update'.
+
+ C-c C-u C-n Update a node.
+ C-c C-u C-e Update every node in the buffer.
+
+Update Menus
+------------
+
+ Invoke the update menu commands by typing `C-c C-u' and then either
+`C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
+To update both nodes and menus at the same time, precede `C-c C-u C-a'
+with `C-u'.
+
+ C-c C-u C-m Make or update a menu.
+
+ C-c C-u C-a Make or update all
+ menus in a buffer.
+
+ C-u C-c C-u C-a With `C-u' as a prefix argument,
+ first create or update all nodes and
+ then create or update all menus.
+
+Format for Info
+---------------
+
+ The Info formatting commands that are written in Emacs Lisp are
+invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
+for the whole buffer.
+
+ The Info formatting commands that are written in C and based on the
+`makeinfo' program are invoked by typing `C-c C-m' and then either
+`C-r' for a region or `C-b' for the whole buffer.
+
+Use the `texinfo-format...' commands:
+
+ C-c C-e C-r Format the region.
+ C-c C-e C-b Format the buffer.
+
+Use `makeinfo':
+
+ C-c C-m C-r Format the region.
+ C-c C-m C-b Format the buffer.
+ C-c C-m C-l Recenter the `makeinfo' output buffer.
+ C-c C-m C-k Kill the `makeinfo' formatting job.
+
+Typeset and Print
+-----------------
+
+ The TeX typesetting and printing commands are invoked by typing `C-c
+C-t' and then another control command: `C-r' for `texinfo-tex-region',
+`C-b' for `texinfo-tex-buffer', and so on.
+
+ C-c C-t C-r Run TeX on the region.
+ C-c C-t C-b Run `texi2dvi' on the buffer.
+ C-c C-t C-i Run `texindex'.
+ C-c C-t C-p Print the DVI file.
+ C-c C-t C-q Show the print queue.
+ C-c C-t C-d Delete a job from the print queue.
+ C-c C-t C-k Kill the current TeX formatting job.
+ C-c C-t C-x Quit a currently stopped TeX formatting job.
+ C-c C-t C-l Recenter the output buffer.
+
+Other Updating Commands
+-----------------------
+
+ The `other updating commands' do not have standard keybindings because
+they are rarely used.
+
+ M-x texinfo-insert-node-lines
+ Insert missing `@node' lines in region.
+ With `C-u' as a prefix argument,
+ use section titles as node names.
+
+ M-x texinfo-multiple-files-update
+ Update a multi-file document.
+ With `C-u 2' as a prefix argument,
+ create or update all nodes and menus
+ in all included files first.
+
+ M-x texinfo-indent-menu-description
+ Indent descriptions.
+
+ M-x texinfo-sequential-node-update
+ Insert node pointers in strict sequence.
+
+\1f
+File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
+
+Beginning a Texinfo File
+************************
+
+ Certain pieces of information must be provided at the beginning of a
+Texinfo file, such as the name of the file and the title of the
+document.
+
+* Menu:
+
+* Four Parts:: Four parts begin a Texinfo file.
+* Sample Beginning:: Here is a sample beginning for a Texinfo file.
+* Header:: The very beginning of a Texinfo file.
+* Info Summary and Permissions:: Summary and copying permissions for Info.
+* Titlepage & Copyright Page:: Creating the title and copyright pages.
+* The Top Node:: Creating the `Top' node and master menu.
+* Software Copying Permissions:: Ensure that you and others continue to
+ have the right to use and share software.
+
+\1f
+File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
+
+Four Parts Begin a File
+=======================
+
+ Generally, the beginning of a Texinfo file has four parts:
+
+ 1. The header, delimited by special comment lines, that includes the
+ commands for naming the Texinfo file and telling TeX what
+ definitions file to use when processing the Texinfo file.
+
+ 2. A short statement of what the file is about, with a copyright
+ notice and copying permissions. This is enclosed in `@ifinfo' and
+ `@end ifinfo' commands so that the formatters place it only in the
+ Info file.
+
+ 3. A title page and copyright page, with a copyright notice and
+ copying permissions. This is enclosed between `@titlepage' and
+ `@end titlepage' commands. The title and copyright page appear
+ only in the printed manual.
+
+ 4. The `Top' node that contains a menu for the whole Info file. The
+ contents of this node appear only in the Info file.
+
+ Also, optionally, you may include the copying conditions for a program
+and a warranty disclaimer. The copying section will be followed by an
+introduction or else by the first chapter of the manual.
+
+ Since the copyright notice and copying permissions for the Texinfo
+document (in contrast to the copying permissions for a program) are in
+parts that appear only in the Info file or only in the printed manual,
+this information must be given twice.
+
+\1f
+File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
+
+Sample Texinfo File Beginning
+=============================
+
+ The following sample shows what is needed.
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename NAME-OF-INFO-FILE
+ @settitle NAME-OF-MANUAL
+ @setchapternewpage odd
+ @c %**end of header
+
+ @ifinfo
+ This file documents ...
+
+ Copyright YEAR COPYRIGHT-OWNER
+
+ Permission is granted to ...
+ @end ifinfo
+
+ @c This title page illustrates only one of the
+ @c two methods of forming a title page.
+
+ @titlepage
+ @title NAME-OF-MANUAL-WHEN-PRINTED
+ @subtitle SUBTITLE-IF-ANY
+ @subtitle SECOND-SUBTITLE
+ @author AUTHOR
+
+ @c The following two commands
+ @c start the copyright page.
+ @page
+ @vskip 0pt plus 1filll
+ Copyright @copyright{} YEAR COPYRIGHT-OWNER
+
+ Published by ...
+
+ Permission is granted to ...
+ @end titlepage
+
+ @node Top, Overview, , (dir)
+
+ @ifinfo
+ This document describes ...
+
+ This document applies to version ...
+ of the program named ...
+ @end ifinfo
+
+ @menu
+ * Copying:: Your rights and freedoms.
+ * First Chapter:: Getting started ...
+ * Second Chapter:: ...
+ ...
+ ...
+ @end menu
+
+ @node First Chapter, Second Chapter, top, top
+ @comment node-name, next, previous, up
+ @chapter First Chapter
+ @cindex Index entry for First Chapter
+
+\1f
+File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
+
+The Texinfo File Header
+=======================
+
+ Texinfo files start with at least three lines that provide Info and
+TeX with necessary information. These are the `\input texinfo' line,
+the `@settitle' line, and the `@setfilename' line. If you want to run
+TeX on just a part of the Texinfo File, you must write the `@settitle'
+and `@setfilename' lines between start-of-header and end-of-header
+lines.
+
+ Thus, the beginning of a Texinfo file looks like this:
+
+ \input texinfo @c -*-texinfo-*-
+ @setfilename sample.info
+ @settitle Sample Document
+
+or else like this:
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename sample.info
+ @settitle Sample Document
+ @c %**end of header
+
+* Menu:
+
+* First Line:: The first line of a Texinfo file.
+* Start of Header:: Formatting a region requires this.
+* setfilename:: Tell Info the name of the Info file.
+* settitle:: Create a title for the printed work.
+* setchapternewpage:: Start chapters on right-hand pages.
+* paragraphindent:: An option to specify paragraph indentation.
+* End of Header:: Formatting a region requires this.
+
+\1f
+File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header
+
+The First Line of a Texinfo File
+--------------------------------
+
+ Every Texinfo file that is to be the top-level input to TeX must begin
+with a line that looks like this:
+
+ \input texinfo @c -*-texinfo-*-
+
+This line serves two functions:
+
+ 1. When the file is processed by TeX, the `\input texinfo' command
+ tells TeX to load the macros needed for processing a Texinfo file.
+ These are in a file called `texinfo.tex', which is usually located
+ in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
+ `\', to mark the beginning of a command, just as Texinfo uses `@'.
+ The `texinfo.tex' file causes the switch from `\' to `@'; before
+ the switch occurs, TeX requires `\', which is why it appears at
+ the beginning of the file.
+
+ 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
+ specification tells Emacs to use Texinfo mode.
+
+\1f
+File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
+
+Start of Header
+---------------
+
+ Write a start-of-header line on the second line of a Texinfo file.
+Follow the start-of-header line with `@setfilename' and `@settitle'
+lines and, optionally, with other command lines, such as `@smallbook'
+or `@footnotestyle'; and then by an end-of-header line (*note End of
+Header::.).
+
+ With these lines, you can format part of a Texinfo file for Info or
+typeset part for printing.
+
+ A start-of-header line looks like this:
+
+ @c %**start of header
+
+ The odd string of characters, `%**', is to ensure that no other
+comment is accidentally taken for a start-of-header line.
+
+\1f
+File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
+
+`@setfilename'
+--------------
+
+ In order to serve as the primary input file for either `makeinfo' or
+TeX, a Texinfo file must contain a line that looks like this:
+
+ @setfilename INFO-FILE-NAME
+
+ Write the `@setfilename' command at the beginning of a line and
+follow it on the same line by the Info file name. Do not write anything
+else on the line; anything on the line after the command is considered
+part of the file name, including what would otherwise be a comment.
+
+ The `@setfilename' line specifies the name of the Info file to be
+generated. This name should be different from the name of the Texinfo
+file. There are two conventions for choosing the name: you can either
+remove the `.texi' extension from the input file name, or replace it
+with the `.info' extension.
+
+ Some operating systems cannot handle long file names. You can run
+into a problem even when the file name you specify is itself short
+enough. This occurs because the Info formatters split a long Info file
+into short indirect subfiles, and name them by appending `-1', `-2',
+..., `-10', `-11', and so on, to the original file name. (*Note Tag
+Files and Split Files: Tag and Split Files.) The subfile name
+`texinfo.info-10', for example, is too long for some systems; so the
+Info file name for this document is `texinfo' rather than
+`texinfo.info'.
+
+ The Info formatting commands ignore everything written before the
+`@setfilename' line, which is why the very first line of the file (the
+`\input' line) does not show up in the output.
+
+ The `@setfilename' line produces no output when you typeset a manual
+with TeX, but it nevertheless is essential: it opens the index,
+cross-reference, and other auxiliary files used by Texinfo, and also
+reads `texinfo.cnf' if that file is present on your system (*note
+Preparing to Use TeX: Preparing for TeX.).
+
+\1f
+File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
+
+`@settitle'
+-----------
+
+ In order to be made into a printed manual, a Texinfo file must contain
+a line that looks like this:
+
+ @settitle TITLE
+
+ Write the `@settitle' command at the beginning of a line and follow
+it on the same line by the title. This tells TeX the title to use in a
+header or footer. Do not write anything else on the line; anything on
+the line after the command is considered part of the title, including a
+comment.
+
+ Conventionally, when TeX formats a Texinfo file for double-sided
+output, the title is printed in the left-hand (even-numbered) page
+headings and the current chapter title is printed in the right-hand
+(odd-numbered) page headings. (TeX learns the title of each chapter
+from each `@chapter' command.) Page footers are not printed.
+
+ Even if you are printing in a single-sided style, TeX looks for an
+`@settitle' command line, in case you include the manual title in the
+heading.
+
+ The `@settitle' command should precede everything that generates
+actual output in TeX.
+
+ Although the title in the `@settitle' command is usually the same as
+the title on the title page, it does not affect the title as it appears
+on the title page. Thus, the two do not need not match exactly; and
+the title in the `@settitle' command can be a shortened or expanded
+version of the title as it appears on the title page. (*Note
+`@titlepage': titlepage.)
+
+ TeX prints page headings only for that text that comes after the
+`@end titlepage' command in the Texinfo file, or that comes after an
+`@headings' command that turns on headings. (*Note The `@headings'
+Command: headings on off, for more information.)
+
+ You may, if you wish, create your own, customized headings and
+footings. *Note Page Headings: Headings, for a detailed discussion of
+this process.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header
+
+`@setchapternewpage'
+--------------------
+
+ In a book or a manual, text is usually printed on both sides of the
+paper, chapters start on right-hand pages, and right-hand pages have
+odd numbers. But in short reports, text often is printed only on one
+side of the paper. Also in short reports, chapters sometimes do not
+start on new pages, but are printed on the same page as the end of the
+preceding chapter, after a small amount of vertical whitespace.
+
+ You can use the `@setchapternewpage' command with various arguments
+to specify how TeX should start chapters and whether it should typeset
+pages for printing on one or both sides of the paper (single-sided or
+double-sided printing).
+
+ Write the `@setchapternewpage' command at the beginning of a line
+followed by its argument.
+
+ For example, you would write the following to cause each chapter to
+start on a fresh odd-numbered page:
+
+ @setchapternewpage odd
+
+ You can specify one of three alternatives with the
+`@setchapternewpage' command:
+
+`@setchapternewpage off'
+ Cause TeX to typeset a new chapter on the same page as the last
+ chapter, after skipping some vertical whitespace. Also, cause TeX
+ to format page headers for single-sided printing. (You can
+ override the headers format with the `@headings double' command;
+ see *Note The `@headings' Command: headings on off.)
+
+`@setchapternewpage on'
+ Cause TeX to start new chapters on new pages and to typeset page
+ headers for single-sided printing. This is the form most often
+ used for short reports.
+
+ This alternative is the default.
+
+`@setchapternewpage odd'
+ Cause TeX to start new chapters on new, odd-numbered pages
+ (right-handed pages) and to typeset for double-sided printing.
+ This is the form most often used for books and manuals.
+
+Texinfo does not have an `@setchapternewpage even' command.
+
+(You can countermand or modify an `@setchapternewpage' command with an
+`@headings' command. *Note The `@headings' Command: headings on off.)
+
+ At the beginning of a manual or book, pages are not numbered--for
+example, the title and copyright pages of a book are not numbered. By
+convention, table of contents pages are numbered with roman numerals
+and not in sequence with the rest of the document.
+
+ Since an Info file does not have pages, the `@setchapternewpage'
+command has no effect on it.
+
+ Usually, you do not write an `@setchapternewpage' command for
+single-sided printing, but accept the default which is to typeset for
+single-sided printing and to start new chapters on new pages. Usually,
+you write an `@setchapternewpage odd' command for double-sided printing.
+
+\1f
+File: texinfo.info, Node: paragraphindent, Next: End of Header, Prev: setchapternewpage, Up: Header
+
+Paragraph Indenting
+-------------------
+
+ The Info formatting commands may insert spaces at the beginning of the
+first line of each paragraph, thereby indenting that paragraph. You
+can use the `@paragraphindent' command to specify the indentation.
+Write an `@paragraphindent' command at the beginning of a line followed
+by either `asis' or a number. The template is:
+
+ @paragraphindent INDENT
+
+ The Info formatting commands indent according to the value of INDENT:
+
+ * If the value of INDENT is `asis', the Info formatting commands do
+ not change the existing indentation.
+
+ * If the value of INDENT is zero, the Info formatting commands delete
+ existing indentation.
+
+ * If the value of INDENT is greater than zero, the Info formatting
+ commands indent the paragraph by that number of spaces.
+
+ The default value of INDENT is `asis'.
+
+ Write the `@paragraphindent' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you write
+the command between the start-of-header and end-of-header lines, the
+region formatting commands indent paragraphs as specified.)
+
+ A peculiarity of the `texinfo-format-buffer' and
+`texinfo-format-region' commands is that they do not indent (nor fill)
+paragraphs that contain `@w' or `@*' commands. *Note Refilling
+Paragraphs::, for a detailed description of what goes on.
+
+\1f
+File: texinfo.info, Node: End of Header, Prev: paragraphindent, Up: Header
+
+End of Header
+-------------
+
+ Follow the header lines with an end-of-header line. An end-of-header
+line looks like this:
+
+ @c %**end of header
+
+ If you include the `@setchapternewpage' command between the
+start-of-header and end-of-header lines, TeX will typeset a region as
+that command specifies. Similarly, if you include an `@smallbook'
+command between the start-of-header and end-of-header lines, TeX will
+typeset a region in the "small" book format.
+
+ The reason for the odd string of characters (`%**') is so that the
+`texinfo-tex-region' command does not accidentally find something that
+it should not when it is looking for the header.
+
+ The start-of-header line and the end-of-header line are Texinfo mode
+variables that you can change.
+
+\1f
+File: texinfo.info, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File
+
+Summary and Copying Permissions for Info
+========================================
+
+ The title page and the copyright page appear only in the printed copy
+of the manual; therefore, the same information must be inserted in a
+section that appears only in the Info file. This section usually
+contains a brief description of the contents of the Info file, a
+copyright notice, and copying permissions.
+
+ The copyright notice should read:
+
+ Copyright YEAR COPYRIGHT-OWNER
+
+and be put on a line by itself.
+
+ Standard text for the copyright permissions is contained in an
+appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo
+Permissions, for the complete text.
+
+ The permissions text appears in an Info file *before* the first node.
+This mean that a reader does *not* see this text when reading the file
+using Info, except when using the advanced Info command `g *'.
+
+\1f
+File: texinfo.info, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File
+
+The Title and Copyright Pages
+=============================
+
+ A manual's name and author are usually printed on a title page.
+Sometimes copyright information is printed on the title page as well;
+more often, copyright information is printed on the back of the title
+page.
+
+ The title and copyright pages appear in the printed manual, but not
+in the Info file. Because of this, it is possible to use several
+slightly obscure TeX typesetting commands that cannot be used in an
+Info file. In addition, this part of the beginning of a Texinfo file
+contains the text of the copying permissions that will appear in the
+printed manual.
+
+ *Note Titlepage Copying Permissions: Titlepage Permissions, for the
+standard text for the copyright permissions.
+
+* Menu:
+
+* titlepage:: Create a title for the printed document.
+* titlefont center sp:: The `@titlefont', `@center',
+ and `@sp' commands.
+* title subtitle author:: The `@title', `@subtitle',
+ and `@author' commands.
+* Copyright & Permissions:: How to write the copyright notice and
+ include copying permissions.
+* end titlepage:: Turn on page headings after the title and
+ copyright pages.
+* headings on off:: An option for turning headings on and off
+ and double or single sided printing.
+
+\1f
+File: texinfo.info, Node: titlepage, Next: titlefont center sp, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page
+
+`@titlepage'
+------------
+
+ Start the material for the title page and following copyright page
+with `@titlepage' on a line by itself and end it with `@end titlepage'
+on a line by itself.
+
+ The `@end titlepage' command starts a new page and turns on page
+numbering. (*Note Page Headings: Headings, for details about how to
+generate page headings.) All the material that you want to appear on
+unnumbered pages should be put between the `@titlepage' and `@end
+titlepage' commands. By using the `@page' command you can force a page
+break within the region delineated by the `@titlepage' and `@end
+titlepage' commands and thereby create more than one unnumbered page.
+This is how the copyright page is produced. (The `@titlepage' command
+might perhaps have been better named the `@titleandadditionalpages'
+command, but that would have been rather long!)
+
+ When you write a manual about a computer program, you should write the
+version of the program to which the manual applies on the title page.
+If the manual changes more frequently than the program or is
+independent of it, you should also include an edition number(1) (*note
+titlepage-Footnotes::) for the manual. This helps readers keep track
+of which manual is for which version of the program. (The `Top' node
+should also contain this information; see *Note `@top': makeinfo top.)
+
+ Texinfo provides two main methods for creating a title page. One
+method uses the `@titlefont', `@sp', and `@center' commands to generate
+a title page in which the words on the page are centered.
+
+ The second method uses the `@title', `@subtitle', and `@author'
+commands to create a title page with black rules under the title and
+author lines and the subtitle text set flush to the right hand side of
+the page. With this method, you do not specify any of the actual
+formatting of the title page. You specify the text you want, and
+Texinfo does the formatting. You may use either method.
+
+ For extremely simple applications, Texinfo also provides a command
+`@shorttitlepage' which takes a single argument as the title. The
+argument is typeset on a page by itself and followed by a blank page.
+
+\1f
+File: texinfo.info, Node: titlepage-Footnotes, Up: titlepage
+
+ (1) We have found that it is helpful to refer to versions of manuals
+as `editions' and versions of programs as `versions'; otherwise, we
+find we are liable to confuse each other in conversation by referring
+to both the documentation and the software with the same words.
+
+\1f
+File: texinfo.info, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page
+
+`@titlefont', `@center', and `@sp'
+----------------------------------
+
+ You can use the `@titlefont', `@sp', and `@center' commands to create
+a title page for a printed document. (This is the first of the two
+methods for creating a title page in Texinfo.)
+
+ Use the `@titlefont' command to select a large font suitable for the
+title itself.
+
+ For example:
+
+ @titlefont{Texinfo}
+
+ Use the `@center' command at the beginning of a line to center the
+remaining text on that line. Thus,
+
+ @center @titlefont{Texinfo}
+
+centers the title, which in this example is "Texinfo" printed in the
+title font.
+
+ Use the `@sp' command to insert vertical space. For example:
+
+ @sp 2
+
+This inserts two blank lines on the printed page. (*Note `@sp': sp,
+for more information about the `@sp' command.)
+
+ A template for this method looks like this:
+
+ @titlepage
+ @sp 10
+ @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED}
+ @sp 2
+ @center SUBTITLE-IF-ANY
+ @sp 2
+ @center AUTHOR
+ ...
+ @end titlepage
+
+ The spacing of the example fits an 8 1/2 by 11 inch manual.
+
+\1f
+File: texinfo.info, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page
+
+`@title', `@subtitle', and `@author'
+------------------------------------
+
+ You can use the `@title', `@subtitle', and `@author' commands to
+create a title page in which the vertical and horizontal spacing is
+done for you automatically. This contrasts with the method described in
+the previous section, in which the `@sp' command is needed to adjust
+vertical spacing.
+
+ Write the `@title', `@subtitle', or `@author' commands at the
+beginning of a line followed by the title, subtitle, or author.
+
+ The `@title' command produces a line in which the title is set flush
+to the left-hand side of the page in a larger than normal font. The
+title is underlined with a black rule.
+
+ The `@subtitle' command sets subtitles in a normal-sized font flush
+to the right-hand side of the page.
+
+ The `@author' command sets the names of the author or authors in a
+middle-sized font flush to the left-hand side of the page on a line
+near the bottom of the title page. The names are underlined with a
+black rule that is thinner than the rule that underlines the title.
+(The black rule only occurs if the `@author' command line is followed
+by an `@page' command line.)
+
+ There are two ways to use the `@author' command: you can write the
+name or names on the remaining part of the line that starts with an
+`@author' command:
+
+ @author by Jane Smith and John Doe
+
+or you can write the names one above each other by using two (or more)
+`@author' commands:
+
+ @author Jane Smith
+ @author John Doe
+
+(Only the bottom name is underlined with a black rule.)
+
+ A template for this method looks like this:
+
+ @titlepage
+ @title NAME-OF-MANUAL-WHEN-PRINTED
+ @subtitle SUBTITLE-IF-ANY
+ @subtitle SECOND-SUBTITLE
+ @author AUTHOR
+ @page
+ ...
+ @end titlepage
+
+Contrast this form with the form of a title page written using the
+`@sp', `@center', and `@titlefont' commands:
+
+ @titlepage
+ @sp 10
+ @center @titlefont{Name of Manual When Printed}
+ @sp 2
+ @center Subtitle, If Any
+ @sp 1
+ @center Second subtitle
+ @sp 2
+ @center Author
+ @page
+ ...
+ @end titlepage
+
+\1f
+File: texinfo.info, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page
+
+Copyright Page and Permissions
+------------------------------
+
+ By international treaty, the copyright notice for a book should be
+either on the title page or on the back of the title page. The
+copyright notice should include the year followed by the name of the
+organization or person who owns the copyright.
+
+ When the copyright notice is on the back of the title page, that page
+is customarily not numbered. Therefore, in Texinfo, the information on
+the copyright page should be within `@titlepage' and `@end titlepage'
+commands.
+
+ Use the `@page' command to cause a page break. To push the copyright
+notice and the other text on the copyright page towards the bottom of
+the page, you can write a somewhat mysterious line after the `@page'
+command that reads like this:
+
+ @vskip 0pt plus 1filll
+
+This is a TeX command that is not supported by the Info formatting
+commands. The `@vskip' command inserts whitespace. The `0pt plus
+1filll' means to put in zero points of mandatory whitespace, and as
+much optional whitespace as needed to push the following text to the
+bottom of the page. Note the use of three `l's in the word `filll';
+this is the correct usage in TeX.
+
+ In a printed manual, the `@copyright{}' command generates a `c'
+inside a circle. (In Info, it generates `(C)'.) The copyright notice
+itself has the following legally defined sequence:
+
+ Copyright (C) YEAR COPYRIGHT-OWNER
+
+ It is customary to put information on how to get a manual after the
+copyright notice, followed by the copying permissions for the manual.
+
+ Note that permissions must be given here as well as in the summary
+segment within `@ifinfo' and `@end ifinfo' that immediately follows the
+header since this text appears only in the printed manual and the
+`ifinfo' text appears only in the Info file.
+
+ *Note Sample Permissions::, for the standard text.
+
+\1f
+File: texinfo.info, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page
+
+Heading Generation
+------------------
+
+ An `@end titlepage' command on a line by itself not only marks the
+end of the title and copyright pages, but also causes TeX to start
+generating page headings and page numbers.
+
+ To repeat what is said elsewhere, Texinfo has two standard page
+heading formats, one for documents which are printed on one side of
+each sheet of paper (single-sided printing), and the other for
+documents which are printed on both sides of each sheet (double-sided
+printing). (*Note `@setchapternewpage': setchapternewpage.) You can
+specify these formats in different ways:
+
+ * The conventional way is to write an `@setchapternewpage' command
+ before the title page commands, and then have the `@end titlepage'
+ command start generating page headings in the manner desired.
+ (*Note `@setchapternewpage': setchapternewpage.)
+
+ * Alternatively, you can use the `@headings' command to prevent page
+ headings from being generated or to start them for either single or
+ double-sided printing. (Write an `@headings' command immediately
+ after the `@end titlepage' command. *Note The `@headings'
+ Command: headings on off, for more information.)
+
+ * Or, you may specify your own page heading and footing format.
+ *Note Page Headings: Headings, for detailed information about page
+ headings and footings.
+
+ Most documents are formatted with the standard single-sided or
+double-sided format, using `@setchapternewpage odd' for double-sided
+printing and no `@setchapternewpage' command for single-sided printing.
+
+\1f
+File: texinfo.info, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page
+
+The `@headings' Command
+-----------------------
+
+ The `@headings' command is rarely used. It specifies what kind of
+page headings and footings to print on each page. Usually, this is
+controlled by the `@setchapternewpage' command. You need the
+`@headings' command only if the `@setchapternewpage' command does not
+do what you want, or if you want to turn off pre-defined page headings
+prior to defining your own. Write an `@headings' command immediately
+after the `@end titlepage' command.
+
+ You can use `@headings' as follows:
+
+`@headings off'
+ Turn off printing of page headings.
+
+`@headings single'
+ Turn on page headings appropriate for single-sided printing.
+
+`@headings double'
+ Turn on page headings appropriate for double-sided printing. The
+ two commands, `@headings on' and `@headings double', are
+ synonymous.
+
+`@headings singleafter'
+`@headings doubleafter'
+ Turn on `single' or `double' headings, respectively, after the
+ current page is output.
+
+`@headings on'
+ Turn on page headings: `single' if `@setchapternewpage on',
+ `double' otherwise.
+
+ For example, suppose you write `@setchapternewpage off' before the
+`@titlepage' command to tell TeX to start a new chapter on the same
+page as the end of the last chapter. This command also causes TeX to
+typeset page headers for single-sided printing. To cause TeX to
+typeset for double sided printing, write `@headings double' after the
+`@end titlepage' command.
+
+ You can stop TeX from generating any page headings at all by writing
+`@headings off' on a line of its own immediately after the line
+containing the `@end titlepage' command, like this:
+
+ @end titlepage
+ @headings off
+
+The `@headings off' command overrides the `@end titlepage' command,
+which would otherwise cause TeX to print page headings.
+
+ You can also specify your own style of page heading and footing.
+*Note Page Headings: Headings, for more information.
+
+\1f
+File: texinfo.info, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File
+
+The `Top' Node and Master Menu
+==============================
+
+ The `Top' node is the node from which you enter an Info file.
+
+ A `Top' node should contain a brief description of the Info file and
+an extensive, master menu for the whole Info file. This helps the
+reader understand what the Info file is about. Also, you should write
+the version number of the program to which the Info file applies; or,
+at least, the edition number.
+
+ The contents of the `Top' node should appear only in the Info file;
+none of it should appear in printed output, so enclose it between
+`@ifinfo' and `@end ifinfo' commands. (TeX does not print either an
+`@node' line or a menu; they appear only in Info; strictly speaking,
+you are not required to enclose these parts between `@ifinfo' and `@end
+ifinfo', but it is simplest to do so. *Note Conditionally Visible
+Text: Conditionals.)
+
+* Menu:
+
+* Title of Top Node:: Sketch what the file is about.
+* Master Menu Parts:: A master menu has three or more parts.
+
+\1f
+File: texinfo.info, Node: Title of Top Node, Next: Master Menu Parts, Prev: The Top Node, Up: The Top Node
+
+`Top' Node Title
+----------------
+
+ Sometimes, you will want to place an `@top' sectioning command line
+containing the title of the document immediately after the `@node Top'
+line (*note The `@top' Sectioning Command: makeinfo top command., for
+more information).
+
+ For example, the beginning of the Top node of this manual contains an
+`@top' sectioning command, a short description, and edition and version
+information. It looks like this:
+
+ ...
+ @end titlepage
+
+ @ifinfo
+ @node Top, Copying, , (dir)
+ @top Texinfo
+
+ Texinfo is a documentation system...
+
+ This is edition...
+ ...
+ @end ifinfo
+
+ @menu
+ * Copying:: Texinfo is freely
+ redistributable.
+ * Overview:: What is Texinfo?
+ ...
+ @end menu
+
+ In a `Top' node, the `Previous', and `Up' nodes usually refer to the
+top level directory of the whole Info system, which is called `(dir)'.
+The `Next' node refers to the first node that follows the main or master
+menu, which is usually the copying permissions, introduction, or first
+chapter.
+
+\1f
+File: texinfo.info, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node
+
+Parts of a Master Menu
+----------------------
+
+ A "master menu" is a detailed main menu listing all the nodes in a
+file.
+
+ A master menu is enclosed in `@menu' and `@end menu' commands and
+does not appear in the printed document.
+
+ Generally, a master menu is divided into parts.
+
+ * The first part contains the major nodes in the Texinfo file: the
+ nodes for the chapters, chapter-like sections, and the appendices.
+
+ * The second part contains nodes for the indices.
+
+ * The third and subsequent parts contain a listing of the other,
+ lower level nodes, often ordered by chapter. This way, rather
+ than go through an intermediary menu, an inquirer can go directly
+ to a particular node when searching for specific information.
+ These menu items are not required; add them if you think they are a
+ convenience. If you do use them, put `@detailmenu' before the
+ first one, and `@end detailmenu' after the last; otherwise,
+ `makeinfo' will get confused.
+
+ Each section in the menu can be introduced by a descriptive line. So
+long as the line does not begin with an asterisk, it will not be
+treated as a menu entry. (*Note Writing a Menu::, for more
+information.)
+
+ For example, the master menu for this manual looks like the following
+(but has many more entries):
+
+ @menu
+ * Copying:: Texinfo is freely
+ redistributable.
+ * Overview:: What is Texinfo?
+ * Texinfo Mode:: Special features in GNU Emacs.
+ ...
+ ...
+ * Command and Variable Index::
+ An entry for each @-command.
+ * Concept Index:: An entry for each concept.
+
+ @detailmenu
+ --- The Detailed Node Listing ---
+
+ Overview of Texinfo
+
+ * Info Files:: What is an Info file?
+ * Printed Manuals:: Characteristics of
+ a printed manual.
+ ...
+ ...
+
+ Using Texinfo Mode
+
+ * Info on a Region:: Formatting part of a file
+ for Info.
+ ...
+ ...
+ @end detailmenu
+ @end menu
+
+\1f
+File: texinfo.info, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File
+
+Software Copying Permissions
+============================
+
+ If the Texinfo file has a section containing the "General Public
+License" and the distribution information and a warranty disclaimer for
+the software that is documented, this section usually follows the `Top'
+node. The General Public License is very important to Project GNU
+software. It ensures that you and others will continue to have a right
+to use and share the software.
+
+ The copying and distribution information and the disclaimer are
+followed by an introduction or else by the first chapter of the manual.
+
+ Although an introduction is not a required part of a Texinfo file, it
+is very helpful. Ideally, it should state clearly and concisely what
+the file is about and who would be interested in reading it. In
+general, an introduction would follow the licensing and distribution
+information, although sometimes people put it earlier in the document.
+Usually, an introduction is put in an `@unnumbered' section. (*Note
+The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.)
+
+\1f
+File: texinfo.info, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top
+
+Ending a Texinfo File
+*********************
+
+ The end of a Texinfo file should include the commands that create
+indices and generate detailed and summary tables of contents. And it
+must include the `@bye' command that marks the last line processed by
+TeX.
+
+ For example:
+
+ @node Concept Index, , Variables Index, Top
+ @c node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @contents
+ @bye
+
+* Menu:
+
+* Printing Indices & Menus:: How to print an index in hardcopy and
+ generate index menus in Info.
+* Contents:: How to create a table of contents.
+* File End:: How to mark the end of a file.
+
+\1f
+File: texinfo.info, Node: Printing Indices & Menus, Next: Contents, Prev: Ending a File, Up: Ending a File
+
+Index Menus and Printing an Index
+=================================
+
+ To print an index means to include it as part of a manual or Info
+file. This does not happen automatically just because you use
+`@cindex' or other index-entry generating commands in the Texinfo file;
+those just cause the raw data for the index to be accumulated. To
+generate an index, you must include the `@printindex' command at the
+place in the document where you want the index to appear. Also, as
+part of the process of creating a printed manual, you must run a
+program called `texindex' (*note Format/Print Hardcopy::.) to sort the
+raw data to produce a sorted index file. The sorted index file is what
+is actually used to print the index.
+
+ Texinfo offers six different types of predefined index: the concept
+index, the function index, the variables index, the keystroke index, the
+program index, and the data type index (*note Predefined Indices::.).
+Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg',
+and `tp'. You may merge indices, or put them into separate sections
+(*note Combining Indices::.); or you may define your own indices (*note
+Defining New Indices: New Indices.).
+
+ The `@printindex' command takes a two-letter index name, reads the
+corresponding sorted index file and formats it appropriately into an
+index.
+
+ The `@printindex' command does not generate a chapter heading for the
+index. Consequently, you should precede the `@printindex' command with
+a suitable section or chapter command (usually `@unnumbered') to supply
+the chapter heading and put the index into the table of contents.
+Precede the `@unnumbered' command with an `@node' line.
+
+ For example:
+
+ @node Variable Index, Concept Index, Function Index, Top
+ @comment node-name, next, previous, up
+ @unnumbered Variable Index
+
+ @printindex vr
+
+ @node Concept Index, , Variable Index, Top
+ @comment node-name, next, previous, up
+ @unnumbered Concept Index
+
+ @printindex cp
+
+ @summarycontents
+ @contents
+ @bye
+
+(Readers often prefer that the concept index come last in a book, since
+that makes it easiest to find.)
+
+\1f
+File: texinfo.info, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File
+
+Generating a Table of Contents
+==============================
+
+ The `@chapter', `@section', and other structuring commands supply the
+information to make up a table of contents, but they do not cause an
+actual table to appear in the manual. To do this, you must use the
+`@contents' and `@summarycontents' commands:
+
+`@contents'
+ Generate a table of contents in a printed manual, including all
+ chapters, sections, subsections, etc., as well as appendices and
+ unnumbered chapters. (Headings generated by the `@heading' series
+ of commands do not appear in the table of contents.) The
+ `@contents' command should be written on a line by itself.
+
+`@shortcontents'
+`@summarycontents'
+ (`@summarycontents' is a synonym for `@shortcontents'; the two
+ commands are exactly the same.)
+
+ Generate a short or summary table of contents that lists only the
+ chapters (and appendices and unnumbered chapters). Omit sections,
+ subsections and subsubsections. Only a long manual needs a short
+ table of contents in addition to the full table of contents.
+
+ Write the `@shortcontents' command on a line by itself right
+ *before* the `@contents' command.
+
+ The table of contents commands automatically generate a chapter-like
+heading at the top of the first table of contents page. Write the table
+of contents commands at the very end of a Texinfo file, just before the
+`@bye' command, following any index sections--anything in the Texinfo
+file after the table of contents commands will be omitted from the
+table of contents.
+
+ When you print a manual with a table of contents, the table of
+contents are printed last and numbered with roman numerals. You need
+to place those pages in their proper place, after the title page,
+yourself. (This is the only collating you need to do for a printed
+manual. The table of contents is printed last because it is generated
+after the rest of the manual is typeset.)
+
+ Here is an example of where to write table of contents commands:
+
+ INDICES...
+ @shortcontents
+ @contents
+ @bye
+
+ Since an Info file uses menus instead of tables of contents, the Info
+formatting commands ignore the `@contents' and `@shortcontents'
+commands.
+
+\1f
+File: texinfo.info, Node: File End, Prev: Contents, Up: Ending a File
+
+`@bye' File Ending
+==================
+
+ An `@bye' command terminates TeX or Info formatting. None of the
+formatting commands see any of the file following `@bye'. The `@bye'
+command should be on a line by itself.
+
+ If you wish, you may follow the `@bye' line with notes. These notes
+will not be formatted and will not appear in either Info or a printed
+manual; it is as if text after `@bye' were within `@ignore' ... `@end
+ignore'. Also, you may follow the `@bye' line with a local variables
+list. *Note Using Local Variables and the Compile Command:
+Compile-Command, for more information.
+
+\1f
+File: texinfo.info, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top
+
+Chapter Structuring
+*******************
+
+ The "chapter structuring" commands divide a document into a hierarchy
+of chapters, sections, subsections, and subsubsections. These commands
+generate large headings; they also provide information for the table of
+contents of a printed manual (*note Generating a Table of Contents:
+Contents.).
+
+ The chapter structuring commands do not create an Info node structure,
+so normally you should put an `@node' command immediately before each
+chapter structuring command (*note Nodes::.). The only time you are
+likely to use the chapter structuring commands without using the node
+structuring commands is if you are writing a document that contains no
+cross references and will never be transformed into Info format.
+
+ It is unlikely that you will ever write a Texinfo file that is
+intended only as an Info file and not as a printable document. If you
+do, you might still use chapter structuring commands to create a
+heading at the top of each node--but you don't need to.
+
+* Menu:
+
+* Tree Structuring:: A manual is like an upside down tree ...
+* Structuring Command Types:: How to divide a manual into parts.
+* makeinfo top:: The `@top' command, part of the `Top' node.
+* chapter::
+* unnumbered & appendix::
+* majorheading & chapheading::
+* section::
+* unnumberedsec appendixsec heading::
+* subsection::
+* unnumberedsubsec appendixsubsec subheading::
+* subsubsection:: Commands for the lowest level sections.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
+\1f
+File: texinfo.info, Node: Tree Structuring, Next: Structuring Command Types, Prev: Structuring, Up: Structuring
+
+Tree Structure of Sections
+==========================
+
+ A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
+subsubsections.
+
+ Here is a diagram that shows a Texinfo file with three chapters, each
+of which has two sections.
+
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
+ In a Texinfo file that has this structure, the beginning of Chapter 2
+looks like this:
+
+ @node Chapter 2, Chapter 3, Chapter 1, top
+ @chapter Chapter 2
+
+ The chapter structuring commands are described in the sections that
+follow; the `@node' and `@menu' commands are described in following
+chapters. (*Note Nodes::, and see *Note Menus::.)
+
+\1f
+File: texinfo.info, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring
+
+Types of Structuring Commands
+=============================
+
+ The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
+subsubsections.
+
+ The four groups are the `@chapter' series, the `@unnumbered' series,
+the `@appendix' series, and the `@heading' series.
+
+ Each command produces titles that have a different appearance on the
+printed page or Info file; only some of the commands produce titles
+that are listed in the table of contents of a printed book or manual.
+
+ * The `@chapter' and `@appendix' series of commands produce numbered
+ or lettered entries both in the body of a printed work and in its
+ table of contents.
+
+ * The `@unnumbered' series of commands produce unnumbered entries
+ both in the body of a printed work and in its table of contents.
+ The `@top' command, which has a special use, is a member of this
+ series (*note `@top': makeinfo top.).
+
+ * The `@heading' series of commands produce unnumbered headings that
+ do not appear in a table of contents. The heading commands never
+ start a new page.
+
+ * The `@majorheading' command produces results similar to using the
+ `@chapheading' command but generates a larger vertical whitespace
+ before the heading.
+
+ * When an `@setchapternewpage' command says to do so, the
+ `@chapter', `@unnumbered', and `@appendix' commands start new
+ pages in the printed manual; the `@heading' commands do not.
+
+ Here are the four groups of chapter structuring commands:
+
+ No new pages
+ Numbered Unnumbered Lettered and numbered Unnumbered
+ In contents In contents In contents Not in contents
+
+ @top @majorheading
+ @chapter @unnumbered @appendix @chapheading
+ @section @unnumberedsec @appendixsec @heading
+ @subsection @unnumberedsubsec @appendixsubsec @subheading
+ @subsubsection @unnumberedsubsubsec @appendixsubsubsec @subsubheading
+
+\1f
+File: texinfo.info, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring
+
+`@top'
+======
+
+ The `@top' command is a special sectioning command that you use only
+after an `@node Top' line at the beginning of a Texinfo file. The
+`@top' command tells the `makeinfo' formatter which node is the `Top'
+node. It has the same typesetting effect as `@unnumbered' (*note
+`@unnumbered': (`@appendix')unnumbered & appendix.). For detailed
+information, see *Note The `@top' Command: makeinfo top command.
+
+\1f
+File: texinfo.info, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring
+
+`@chapter'
+==========
+
+ `@chapter' identifies a chapter in the document. Write the command
+at the beginning of a line and follow it on the same line by the title
+of the chapter.
+
+ For example, this chapter in this manual is entitled "Chapter
+Structuring"; the `@chapter' line looks like this:
+
+ @chapter Chapter Structuring
+
+ In TeX, the `@chapter' command creates a chapter in the document,
+specifying the chapter title. The chapter is numbered automatically.
+
+ In Info, the `@chapter' command causes the title to appear on a line
+by itself, with a line of asterisks inserted underneath. Thus, in
+Info, the above example produces the following output:
+
+ Chapter Structuring
+ *******************
+
+ Texinfo also provides a command `@centerchap', which is analogous to
+`@unnumbered', but centers its argument in the printed output. This
+kind of stylistic choice is not usually offered by Texinfo.
+
+\1f
+File: texinfo.info, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring
+
+`@unnumbered', `@appendix'
+==========================
+
+ Use the `@unnumbered' command to create a chapter that appears in a
+printed manual without chapter numbers of any kind. Use the
+`@appendix' command to create an appendix in a printed manual that is
+labelled by letter instead of by number.
+
+ For Info file output, the `@unnumbered' and `@appendix' commands are
+equivalent to `@chapter': the title is printed on a line by itself with
+a line of asterisks underneath. (*Note `@chapter': chapter.)
+
+ To create an appendix or an unnumbered chapter, write an `@appendix'
+or `@unnumbered' command at the beginning of a line and follow it on
+the same line by the title, as you would if you were creating a chapter.
+
+\1f
+File: texinfo.info, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring
+
+`@majorheading', `@chapheading'
+===============================
+
+ The `@majorheading' and `@chapheading' commands put chapter-like
+headings in the body of a document.
+
+ However, neither command causes TeX to produce a numbered heading or
+an entry in the table of contents; and neither command causes TeX to
+start a new page in a printed manual.
+
+ In TeX, an `@majorheading' command generates a larger vertical
+whitespace before the heading than an `@chapheading' command but is
+otherwise the same.
+
+ In Info, the `@majorheading' and `@chapheading' commands are
+equivalent to `@chapter': the title is printed on a line by itself with
+a line of asterisks underneath. (*Note `@chapter': chapter.)
+
+\1f
+File: texinfo.info, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring
+
+`@section'
+==========
+
+ In a printed manual, an `@section' command identifies a numbered
+section within a chapter. The section title appears in the table of
+contents. In Info, an `@section' command provides a title for a
+segment of text, underlined with `='.
+
+ This section is headed with an `@section' command and looks like this
+in the Texinfo file:
+
+ @section @code{@@section}
+
+ To create a section, write the `@section' command at the beginning of
+a line and follow it on the same line by the section title.
+
+ Thus,
+
+ @section This is a section
+
+produces
+
+ This is a section
+ =================
+
+in Info.
+
+\1f
+File: texinfo.info, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring
+
+`@unnumberedsec', `@appendixsec', `@heading'
+============================================
+
+ The `@unnumberedsec', `@appendixsec', and `@heading' commands are,
+respectively, the unnumbered, appendix-like, and heading-like
+equivalents of the `@section' command. (*Note `@section': section.)
+
+`@unnumberedsec'
+ The `@unnumberedsec' command may be used within an unnumbered
+ chapter or within a regular chapter or appendix to provide an
+ unnumbered section.
+
+`@appendixsec'
+`@appendixsection'
+ `@appendixsection' is a longer spelling of the `@appendixsec'
+ command; the two are synonymous.
+
+ Conventionally, the `@appendixsec' or `@appendixsection' command
+ is used only within appendices.
+
+`@heading'
+ You may use the `@heading' command anywhere you wish for a
+ section-style heading that will not appear in the table of
+ contents.
+
+\1f
+File: texinfo.info, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring
+
+The `@subsection' Command
+=========================
+
+ Subsections are to sections as sections are to chapters. (*Note
+`@section': section.) In Info, subsection titles are underlined with
+`-'. For example,
+
+ @subsection This is a subsection
+
+produces
+
+ This is a subsection
+ --------------------
+
+ In a printed manual, subsections are listed in the table of contents
+and are numbered three levels deep.
+
+\1f
+File: texinfo.info, Node: unnumberedsubsec appendixsubsec subheading, Next: subsubsection, Prev: subsection, Up: Structuring
+
+The `@subsection'-like Commands
+===============================
+
+ The `@unnumberedsubsec', `@appendixsubsec', and `@subheading'
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the `@subsection' command. (*Note
+`@subsection': subsection.)
+
+ In Info, the `@subsection'-like commands generate a title underlined
+with hyphens. In a printed manual, an `@subheading' command produces a
+heading like that of a subsection except that it is not numbered and
+does not appear in the table of contents. Similarly, an
+`@unnumberedsubsec' command produces an unnumbered heading like that of
+a subsection and an `@appendixsubsec' command produces a
+subsection-like heading labelled with a letter and numbers; both of
+these commands produce headings that appear in the table of contents.
+
+\1f
+File: texinfo.info, Node: subsubsection, Next: Raise/lower sections, Prev: unnumberedsubsec appendixsubsec subheading, Up: Structuring
+
+The `subsub' Commands
+=====================
+
+ The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:
+
+`@subsubsection'
+ Subsubsections are to subsections as subsections are to sections.
+ (*Note `@subsection': subsection.) In a printed manual,
+ subsubsection titles appear in the table of contents and are
+ numbered four levels deep.
+
+`@unnumberedsubsubsec'
+ Unnumbered subsubsection titles appear in the table of contents of
+ a printed manual, but lack numbers. Otherwise, unnumbered
+ subsubsections are the same as subsubsections. In Info, unnumbered
+ subsubsections look exactly like ordinary subsubsections.
+
+`@appendixsubsubsec'
+ Conventionally, appendix commands are used only for appendices and
+ are lettered and numbered appropriately in a printed manual. They
+ also appear in the table of contents. In Info, appendix
+ subsubsections look exactly like ordinary subsubsections.
+
+`@subsubheading'
+ The `@subsubheading' command may be used anywhere that you need a
+ small heading that will not appear in the table of contents. In
+ Info, subsubheadings look exactly like ordinary subsubsection
+ headings.
+
+ In Info, `subsub' titles are underlined with periods. For example,
+
+ @subsubsection This is a subsubsection
+
+produces
+
+ This is a subsubsection
+ .......................
+
+\1f
+File: texinfo.info, Node: Raise/lower sections, Prev: subsubsection, Up: Structuring
+
+`@raisesections' and `@lowersections'
+=====================================
+
+ The `@raisesections' and `@lowersections' commands raise and lower
+the hierarchical level of chapters, sections, subsections and the like.
+The `@raisesections' command changes sections to chapters, subsections
+to sections, and so on. The `@lowersections' command changes chapters
+to sections, sections to subsections, and so on.
+
+ An `@lowersections' command is useful if you wish to include text
+that is written as an outer or standalone Texinfo file in another
+Texinfo file as an inner, included file. If you write the command at
+the beginning of the file, all your `@chapter' commands are formatted
+as if they were `@section' commands, all your `@section' command are
+formatted as if they were `@subsection' commands, and so on.
+
+ `@raisesections' raises a command one level in the chapter
+structuring hierarchy:
+
+ Change To
+
+ @subsection @section,
+ @section @chapter,
+ @heading @chapheading,
+ etc.
+
+ `@lowersections' lowers a command one level in the chapter
+structuring hierarchy:
+
+ Change To
+
+ @chapter @section,
+ @subsection @subsubsection,
+ @heading @subheading,
+ etc.
+
+ An `@raisesections' or `@lowersections' command changes only those
+structuring commands that follow the command in the Texinfo file.
+Write an `@raisesections' or `@lowersections' command on a line of its
+own.
+
+ An `@lowersections' command cancels an `@raisesections' command, and
+vice versa. Typically, the commands are used like this:
+
+ @lowersections
+ @include somefile.texi
+ @raisesections
+
+ Without the `@raisesections', all the subsequent sections in your
+document will be lowered.
+
+ Repeated use of the commands continue to raise or lower the
+hierarchical level a step at a time.
+
+ An attempt to raise above `chapters' reproduces chapter commands; an
+attempt to lower below `subsubsections' reproduces subsubsection
+commands.
+
+\1f
+File: texinfo.info, Node: Nodes, Next: Menus, Prev: Structuring, Up: Top
+
+Nodes
+*****
+
+ "Nodes" are the primary segments of a Texinfo file. They do not
+themselves impose a hierarchic or any other kind of structure on a file.
+Nodes contain "node pointers" that name other nodes, and can contain
+"menus" which are lists of nodes. In Info, the movement commands can
+carry you to a pointed-to node or to a node listed in a menu. Node
+pointers and menus provide structure for Info files just as chapters,
+sections, subsections, and the like, provide structure for printed
+books.
+
+* Menu:
+
+* Two Paths:: Different commands to structure
+ Info output and printed output.
+* Node Menu Illustration:: A diagram, and sample nodes and menus.
+* node:: How to write a node, in detail.
+* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
+
+\1f
+File: texinfo.info, Node: Two Paths, Next: Node Menu Illustration, Prev: Nodes, Up: Nodes
+
+Two Paths
+=========
+
+ The node and menu commands and the chapter structuring commands are
+independent of each other:
+
+ * In Info, node and menu commands provide structure. The chapter
+ structuring commands generate headings with different kinds of
+ underlining--asterisks for chapters, hyphens for sections, and so
+ on; they do nothing else.
+
+ * In TeX, the chapter structuring commands generate chapter and
+ section numbers and tables of contents. The node and menu
+ commands provide information for cross references; they do nothing
+ else.
+
+ You can use node pointers and menus to structure an Info file any way
+you want; and you can write a Texinfo file so that its Info output has a
+different structure than its printed output. However, most Texinfo
+files are written such that the structure for the Info output
+corresponds to the structure for the printed output. It is not
+convenient to do otherwise.
+
+ Generally, printed output is structured in a tree-like hierarchy in
+which the chapters are the major limbs from which the sections branch
+out. Similarly, node pointers and menus are organized to create a
+matching structure in the Info output.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Node Menu Illustration, Next: node, Prev: Two Paths, Up: Nodes
+
+Node and Menu Illustration
+==========================
+
+ Here is a copy of the diagram shown earlier that illustrates a Texinfo
+file with three chapters, each of which contains two sections.
+
+ Note that the "root" is at the top of the diagram and the "leaves"
+are at the bottom. This is how such a diagram is drawn conventionally;
+it illustrates an upside-down tree. For this reason, the root node is
+called the `Top' node, and `Up' node pointers carry you closer to the
+root.
+
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+ Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
+ Write the beginning of the node for Chapter 2 like this:
+
+ @node Chapter 2, Chapter 3, Chapter 1, top
+ @comment node-name, next, previous, up
+
+This `@node' line says that the name of this node is "Chapter 2", the
+name of the `Next' node is "Chapter 3", the name of the `Previous' node
+is "Chapter 1", and the name of the `Up' node is "Top".
+
+ *Please Note:* `Next' refers to the next node at the same
+ hierarchical level in the manual, not necessarily to the next node
+ within the Texinfo file. In the Texinfo file, the subsequent node
+ may be at a lower level--a section-level node may follow a
+ chapter-level node, and a subsection-level node may follow a
+ section-level node. `Next' and `Previous' refer to nodes at the
+ *same* hierarchical level. (The `Top' node contains the exception
+ to this rule. Since the `Top' node is the only node at that
+ level, `Next' refers to the first following node, which is almost
+ always a chapter or chapter-level node.)
+
+ To go to Sections 2.1 and 2.2 using Info, you need a menu inside
+Chapter 2. (*Note Menus::.) You would write the menu just before the
+beginning of Section 2.1, like this:
+
+ @menu
+ * Sect. 2.1:: Description of this section.
+ * Sect. 2.2::
+ @end menu
+
+ Write the node for Sect. 2.1 like this:
+
+ @node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
+ @comment node-name, next, previous, up
+
+ In Info format, the `Next' and `Previous' pointers of a node usually
+lead to other nodes at the same level--from chapter to chapter or from
+section to section (sometimes, as shown, the `Previous' pointer points
+up); an `Up' pointer usually leads to a node at the level above (closer
+to the `Top' node); and a `Menu' leads to nodes at a level below (closer
+to `leaves'). (A cross reference can point to a node at any level; see
+*Note Cross References::.)
+
+ Usually, an `@node' command and a chapter structuring command are
+used in sequence, along with indexing commands. (You may follow the
+`@node' line with a comment line that reminds you which pointer is
+which.)
+
+ Here is the beginning of the chapter in this manual called "Ending a
+Texinfo File". This shows an `@node' line followed by a comment line,
+an `@chapter' line, and then by indexing lines.
+
+ @node Ending a File, Structuring, Beginning a File, Top
+ @comment node-name, next, previous, up
+ @chapter Ending a Texinfo File
+ @cindex Ending a Texinfo file
+ @cindex Texinfo file ending
+ @cindex File ending
+
+\1f
+File: texinfo.info, Node: node, Next: makeinfo Pointer Creation, Prev: Node Menu Illustration, Up: Nodes
+
+The `@node' Command
+===================
+
+ A "node" is a segment of text that begins at an `@node' command and
+continues until the next `@node' command. The definition of node is
+different from that for chapter or section. A chapter may contain
+sections and a section may contain subsections; but a node cannot
+contain subnodes; the text of a node continues only until the next
+`@node' command in the file. A node usually contains only one chapter
+structuring command, the one that follows the `@node' line. On the
+other hand, in printed output nodes are used only for cross references,
+so a chapter or section may contain any number of nodes. Indeed, a
+chapter usually contains several nodes, one for each section,
+subsection, and subsubsection.
+
+ To create a node, write an `@node' command at the beginning of a
+line, and follow it with four arguments, separated by commas, on the
+rest of the same line. These arguments are the name of the node, and
+the names of the `Next', `Previous', and `Up' pointers, in that order.
+You may insert spaces before each pointer if you wish; the spaces are
+ignored. You must write the name of the node, and the names of the
+`Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
+the formatters fail. (*note info: (info)Top, for more information
+about nodes in Info.)
+
+ Usually, you write one of the chapter-structuring command lines
+immediately after an `@node' line--for example, an `@section' or
+`@subsection' line. (*Note Types of Structuring Commands: Structuring
+Command Types.)
+
+ *Please note:* The GNU Emacs Texinfo mode updating commands work
+ only with Texinfo files in which `@node' lines are followed by
+ chapter structuring lines. *Note Updating Requirements::.
+
+ TeX uses `@node' lines to identify the names to use for cross
+references. For this reason, you must write `@node' lines in a Texinfo
+file that you intend to format for printing, even if you do not intend
+to format it for Info. (Cross references, such as the one at the end
+of this sentence, are made with `@xref' and its related commands; see
+*Note Cross References::.)
+
+* Menu:
+
+* Node Names:: How to choose node and pointer names.
+* Writing a Node:: How to write an `@node' line.
+* Node Line Tips:: Keep names short.
+* Node Line Requirements:: Keep names unique, without @-commands.
+* First Node:: How to write a `Top' node.
+* makeinfo top command:: How to use the `@top' command.
+* Top Node Summary:: Write a brief description for readers.
+
+\1f
+File: texinfo.info, Node: Node Names, Next: Writing a Node, Prev: node, Up: node
+
+Choosing Node and Pointer Names
+-------------------------------
+
+ The name of a node identifies the node. The pointers enable you to
+reach other nodes and consist of the names of those nodes.
+
+ Normally, a node's `Up' pointer contains the name of the node whose
+menu mentions that node. The node's `Next' pointer contains the name
+of the node that follows that node in that menu and its `Previous'
+pointer contains the name of the node that precedes it in that menu.
+When a node's `Previous' node is the same as its `Up' node, both node
+pointers name the same node.
+
+ Usually, the first node of a Texinfo file is the `Top' node, and its
+`Up' and `Previous' pointers point to the `dir' file, which contains
+the main menu for all of Info.
+
+ The `Top' node itself contains the main or master menu for the manual.
+Also, it is helpful to include a brief description of the manual in the
+`Top' node. *Note First Node::, for information on how to write the
+first node of a Texinfo file.
+
+\1f
+File: texinfo.info, Node: Writing a Node, Next: Node Line Tips, Prev: Node Names, Up: node
+
+How to Write an `@node' Line
+----------------------------
+
+ The easiest way to write an `@node' line is to write `@node' at the
+beginning of a line and then the name of the node, like this:
+
+ @node NODE-NAME
+
+ If you are using GNU Emacs, you can use the update node commands
+provided by Texinfo mode to insert the names of the pointers; or you
+can leave the pointers out of the Texinfo file and let `makeinfo'
+insert node pointers into the Info file it creates. (*Note Texinfo
+Mode::, and *Note makeinfo Pointer Creation::.)
+
+ Alternatively, you can insert the `Next', `Previous', and `Up'
+pointers yourself. If you do this, you may find it helpful to use the
+Texinfo mode keyboard command `C-c C-c n'. This command inserts
+`@node' and a comment line listing the names of the pointers in their
+proper order. The comment line helps you keep track of which arguments
+are for which pointers. This comment line is especially useful if you
+are not familiar with Texinfo.
+
+ The template for a node line with `Next', `Previous', and `Up'
+pointers looks like this:
+
+ @node NODE-NAME, NEXT, PREVIOUS, UP
+
+ If you wish, you can ignore `@node' lines altogether in your first
+draft and then use the `texinfo-insert-node-lines' command to create
+`@node' lines for you. However, we do not recommend this practice. It
+is better to name the node itself at the same time that you write a
+segment so you can easily make cross references. A large number of
+cross references are an especially important feature of a good Info
+file.
+
+ After you have inserted an `@node' line, you should immediately write
+an @-command for the chapter or section and insert its name. Next (and
+this is important!), put in several index entries. Usually, you will
+find at least two and often as many as four or five ways of referring
+to the node in the index. Use them all. This will make it much easier
+for people to find the node.
+
+\1f
+File: texinfo.info, Node: Node Line Tips, Next: Node Line Requirements, Prev: Writing a Node, Up: node
+
+`@node' Line Tips
+-----------------
+
+ Here are three suggestions:
+
+ * Try to pick node names that are informative but short.
+
+ In the Info file, the file name, node name, and pointer names are
+ all inserted on one line, which may run into the right edge of the
+ window. (This does not cause a problem with Info, but is ugly.)
+
+ * Try to pick node names that differ from each other near the
+ beginnings of their names. This way, it is easy to use automatic
+ name completion in Info.
+
+ * By convention, node names are capitalized just as they would be for
+ section or chapter titles--initial and significant words are
+ capitalized; others are not.
+
+\1f
+File: texinfo.info, Node: Node Line Requirements, Next: First Node, Prev: Node Line Tips, Up: node
+
+`@node' Line Requirements
+-------------------------
+
+ Here are several requirements for `@node' lines:
+
+ * All the node names for a single Info file must be unique.
+
+ Duplicates confuse the Info movement commands. This means, for
+ example, that if you end every chapter with a summary, you must
+ name each summary node differently. You cannot just call each one
+ "Summary". You may, however, duplicate the titles of chapters,
+ sections, and the like. Thus you can end each chapter in a book
+ with a section called "Summary", so long as the node names for
+ those sections are all different.
+
+ * A pointer name must be the name of a node.
+
+ The node to which a pointer points may come before or after the
+ node containing the pointer.
+
+ * You cannot use any of the Texinfo @-commands in a node name;
+ @-commands confuse Info.
+
+ Thus, the beginning of the section called `@chapter' looks like
+ this:
+
+ @node chapter, unnumbered & appendix, makeinfo top, Structuring
+ @comment node-name, next, previous, up
+ @section @code{@@chapter}
+ @findex chapter
+
+ * You cannot use commas or apostrophes within a node name; these
+ confuse TeX or the Info formatters.
+
+ For example, the following is a section title:
+
+ @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
+
+ The corresponding node name is:
+
+ unnumberedsec appendixsec heading
+
+ * Case is significant.
+
+\1f
+File: texinfo.info, Node: First Node, Next: makeinfo top command, Prev: Node Line Requirements, Up: node
+
+The First Node
+--------------
+
+ The first node of a Texinfo file is the "Top" node, except in an
+included file (*note Include Files::.). The Top node contains the main
+or master menu for the document, and a short summary of the document
+(*note Top Node Summary::.).
+
+ The Top node (which must be named `top' or `Top') should have as its
+`Up' node the name of a node in another file, where there is a menu
+that leads to this file. Specify the file name in parentheses. If the
+file is to be installed directly in the Info directory file, use
+`(dir)' as the parent of the Top node; this is short for `(dir)top',
+and specifies the Top node in the `dir' file, which contains the main
+menu for the Info system as a whole. For example, the `@node Top' line
+of this manual looks like this:
+
+ @node Top, Copying, , (dir)
+
+(You can use the Texinfo updating commands or the `makeinfo' utility to
+insert these pointers automatically.)
+
+ Do not define the `Previous' node of the Top node to be `(dir)', as
+it causes confusing behavior for users: if you are in the Top node and
+hits <DEL> to go backwards, you wind up in the middle of the some other
+entry in the `dir' file, which has nothing to do with what you were
+reading.
+
+ *Note Install an Info File::, for more information about installing
+an Info file in the `info' directory.
+
+\1f
+File: texinfo.info, Node: makeinfo top command, Next: Top Node Summary, Prev: First Node, Up: node
+
+The `@top' Sectioning Command
+-----------------------------
+
+ A special sectioning command, `@top', has been created for use with
+the `@node Top' line. The `@top' sectioning command tells `makeinfo'
+that it marks the `Top' node in the file. It provides the information
+that `makeinfo' needs to insert node pointers automatically. Write the
+`@top' command at the beginning of the line immediately following the
+`@node Top' line. Write the title on the remaining part of the same
+line as the `@top' command.
+
+ In Info, the `@top' sectioning command causes the title to appear on a
+line by itself, with a line of asterisks inserted underneath.
+
+ In TeX and `texinfo-format-buffer', the `@top' sectioning command is
+merely a synonym for `@unnumbered'. Neither of these formatters
+require an `@top' command, and do nothing special with it. You can use
+`@chapter' or `@unnumbered' after the `@node Top' line when you use
+these formatters. Also, you can use `@chapter' or `@unnumbered' when
+you use the Texinfo updating commands to create or update pointers and
+menus.
+
+\1f
+File: texinfo.info, Node: Top Node Summary, Prev: makeinfo top command, Up: node
+
+The `Top' Node Summary
+----------------------
+
+ You can help readers by writing a summary in the `Top' node, after the
+`@top' line, before the main or master menu. The summary should
+briefly describe the document. In Info, this summary will appear just
+before the master menu. In a printed manual, this summary will appear
+on a page of its own.
+
+ If you do not want the summary to appear on a page of its own in a
+printed manual, you can enclose the whole of the `Top' node, including
+the `@node Top' line and the `@top' sectioning command line or other
+sectioning command line between `@ifinfo' and `@end ifinfo'. This
+prevents any of the text from appearing in the printed output. (*note
+Conditionally Visible Text: Conditionals.). You can repeat the brief
+description from the `Top' node within `@iftex' ... `@end iftex' at the
+beginning of the first chapter, for those who read the printed manual.
+This saves paper and may look neater.
+
+ You should write the version number of the program to which the manual
+applies in the summary. This helps the reader keep track of which
+manual is for which version of the program. If the manual changes more
+frequently than the program or is independent of it, you should also
+include an edition number for the manual. (The title page should also
+contain this information: see *Note `@titlepage': titlepage.)
+
+\1f
+File: texinfo.info, Node: makeinfo Pointer Creation, Prev: node, Up: Nodes
+
+Creating Pointers with `makeinfo'
+=================================
+
+ The `makeinfo' program has a feature for automatically creating node
+pointers for a hierarchically organized file that lacks them.
+
+ When you take advantage of this feature, you do not need to write the
+`Next', `Previous', and `Up' pointers after the name of a node.
+However, you must write a sectioning command, such as `@chapter' or
+`@section', on the line immediately following each truncated `@node'
+line. You cannot write a comment line after a node line; the section
+line must follow it immediately.
+
+ In addition, you must follow the `Top' `@node' line with a line
+beginning with `@top' to mark the `Top' node in the file. *Note `@top':
+makeinfo top.
+
+ Finally, you must write the name of each node (except for the `Top'
+node) in a menu that is one or more hierarchical levels above the
+node's hierarchical level.
+
+ This node pointer insertion feature in `makeinfo' is an alternative
+to the menu and pointer creation and update commands in Texinfo mode.
+(*Note Updating Nodes and Menus::.) It is especially helpful to people
+who do not use GNU Emacs for writing Texinfo documents.
+
+\1f
+File: texinfo.info, Node: Menus, Next: Cross References, Prev: Nodes, Up: Top
+
+Menus
+*****
+
+ "Menus" contain pointers to subordinate nodes.(1) (*note
+Menus-Footnotes::) In Info, you use menus to go to such nodes. Menus
+have no effect in printed manuals and do not appear in them.
+
+ By convention, a menu is put at the end of a node since a reader who
+uses the menu may not see text that follows it.
+
+ A node that has a menu should *not* contain much text. If you have a
+lot of text and a menu, move most of the text into a new subnode--all
+but a few lines.
+
+* Menu:
+
+* Menu Location:: Put a menu in a short node.
+* Writing a Menu:: What is a menu?
+* Menu Parts:: A menu entry has three parts.
+* Less Cluttered Menu Entry:: Two part menu entry.
+* Menu Example:: Two and three part menu entries.
+* Other Info Files:: How to refer to a different Info file.
+
+\1f
+File: texinfo.info, Node: Menus-Footnotes, Up: Menus
+
+ (1) Menus can carry you to any node, regardless of the hierarchical
+structure; even to nodes in a different Info file. However, the GNU
+Emacs Texinfo mode updating commands work only to create menus of
+subordinate nodes. Conventionally, cross references are used to refer
+to other nodes.
+
+\1f
+File: texinfo.info, Node: Menu Location, Next: Writing a Menu, Prev: Menus, Up: Menus
+
+Menus Need Short Nodes
+======================
+
+ A reader can easily see a menu that is close to the beginning of the
+node. The node should be short. As a practical matter, you should
+locate a menu within 20 lines of the beginning of the node. Otherwise,
+a reader with a terminal that displays only a few lines may miss the
+menu and its associated text.
+
+ The short text before a menu may look awkward in a printed manual. To
+avoid this, you can write a menu near the beginning of its node and
+follow the menu by an `@node' line, and then an `@heading' line located
+within `@ifinfo' and `@end ifinfo'. This way, the menu, `@node' line,
+and title appear only in the Info file, not the printed document.
+
+ For example, the preceding two paragraphs follow an Info-only menu,
+`@node' line, and heading, and look like this:
+
+ @menu
+ * Menu Location:: Put a menu in a short node.
+ * Writing a Menu:: What is a menu?
+ * Menu Parts:: A menu entry has three parts.
+ * Less Cluttered Menu Entry:: Two part menu entry.
+ * Menu Example:: Two and three part entries.
+ * Other Info Files:: How to refer to a different
+ Info file.
+ @end menu
+
+ @node Menu Location, Writing a Menu, , Menus
+ @ifinfo
+ @heading Menus Need Short Nodes
+ @end ifinfo
+
+ The Texinfo file for this document contains more than a dozen
+examples of this procedure. One is at the beginning of this chapter;
+another is at the beginning of the "Cross References" chapter.
+
+\1f
+File: texinfo.info, Node: Writing a Menu, Next: Menu Parts, Prev: Menu Location, Up: Menus
+
+Writing a Menu
+==============
+
+ A menu consists of an `@menu' command on a line by itself followed by
+menu entry lines or menu comment lines and then by an `@end menu'
+command on a line by itself.
+
+ A menu looks like this:
+
+ @menu
+ Larger Units of Text
+
+ * Files:: All about handling files.
+ * Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+ @end menu
+
+ In a menu, every line that begins with an `* ' is a "menu entry".
+(Note the space after the asterisk.) A line that does not start with
+an `* ' may also appear in a menu. Such a line is not a menu entry but
+is a menu comment line that appears in the Info file. In the example
+above, the line `Larger Units of Text' is a menu comment line; the two
+lines starting with `* ' are menu entries.
+
+\1f
+File: texinfo.info, Node: Menu Parts, Next: Less Cluttered Menu Entry, Prev: Writing a Menu, Up: Menus
+
+The Parts of a Menu
+===================
+
+ A menu entry has three parts, only the second of which is required:
+
+ 1. The menu entry name (optional).
+
+ 2. The name of the node (required).
+
+ 3. A description of the item (optional).
+
+ The template for a menu entry looks like this:
+
+ * MENU-ENTRY-NAME: NODE-NAME. DESCRIPTION
+
+ Follow the menu entry name with a single colon and follow the node
+name with tab, comma, period, or newline.
+
+ In Info, a user selects a node with the `m' (`Info-menu') command.
+The menu entry name is what the user types after the `m' command.
+
+ The third part of a menu entry is a descriptive phrase or sentence.
+Menu entry names and node names are often short; the description
+explains to the reader what the node is about. A useful description
+complements the node name rather than repeats it. The description,
+which is optional, can spread over two or more lines; if it does, some
+authors prefer to indent the second line while others prefer to align it
+with the first (and all others). It's up to you.
+
+\1f
+File: texinfo.info, Node: Less Cluttered Menu Entry, Next: Menu Example, Prev: Menu Parts, Up: Menus
+
+Less Cluttered Menu Entry
+=========================
+
+ When the menu entry name and node name are the same, you can write
+the name immediately after the asterisk and space at the beginning of
+the line and follow the name with two colons.
+
+ For example, write
+
+ * Name:: DESCRIPTION
+
+instead of
+
+ * Name: Name. DESCRIPTION
+
+ You should use the node name for the menu entry name whenever
+possible, since it reduces visual clutter in the menu.
+
+\1f
+File: texinfo.info, Node: Menu Example, Next: Other Info Files, Prev: Less Cluttered Menu Entry, Up: Menus
+
+A Menu Example
+==============
+
+ A menu looks like this in Texinfo:
+
+ @menu
+ * menu entry name: Node name. A short description.
+ * Node name:: This form is preferred.
+ @end menu
+
+This produces:
+
+ * menu:
+
+ * menu entry name: Node name. A short description.
+ * Node name:: This form is preferred.
+
+ Here is an example as you might see it in a Texinfo file:
+
+ @menu
+ Larger Units of Text
+
+ * Files:: All about handling files.
+ * Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+ @end menu
+
+This produces:
+
+ * menu:
+ Larger Units of Text
+
+ * Files:: All about handling files.
+ * Multiples: Buffers. Multiple buffers; editing
+ several files at once.
+
+ In this example, the menu has two entries. `Files' is both a menu
+entry name and the name of the node referred to by that name.
+`Multiples' is the menu entry name; it refers to the node named
+`Buffers'. The line `Larger Units of Text' is a comment; it appears in
+the menu, but is not an entry.
+
+ Since no file name is specified with either `Files' or `Buffers',
+they must be the names of nodes in the same Info file (*note Referring
+to Other Info Files: Other Info Files.).
+
+\1f
+File: texinfo.info, Node: Other Info Files, Prev: Menu Example, Up: Menus
+
+Referring to Other Info Files
+=============================
+
+ You can create a menu entry that enables a reader in Info to go to a
+node in another Info file by writing the file name in parentheses just
+before the node name. In this case, you should use the three-part menu
+entry format, which saves the reader from having to type the file name.
+
+ The format looks like this:
+
+ @menu
+ * FIRST-ENTRY-NAME:(FILENAME)NODENAME. DESCRIPTION
+ * SECOND-ENTRY-NAME:(FILENAME)SECOND-NODE. DESCRIPTION
+ @end menu
+
+ For example, to refer directly to the `Outlining' and `Rebinding'
+nodes in the `Emacs Manual', you would write a menu like this:
+
+ @menu
+ * Outlining: (emacs)Outline Mode. The major mode for
+ editing outlines.
+ * Rebinding: (emacs)Rebinding. How to redefine the
+ meaning of a key.
+ @end menu
+
+ If you do not list the node name, but only name the file, then Info
+presumes that you are referring to the `Top' node.
+
+ The `dir' file that contains the main menu for Info has menu entries
+that list only file names. These take you directly to the `Top' nodes
+of each Info document. (*Note Install an Info File::.)
+
+ For example:
+
+ * Info: (info). Documentation browsing system.
+ * Emacs: (emacs). The extensible, self-documenting
+ text editor.
+
+(The `dir' top level directory for the Info system is an Info file, not
+a Texinfo file, but a menu entry looks the same in both types of file.)
+
+ Note that the GNU Emacs Texinfo mode menu updating commands only work
+with nodes within the current buffer, so you cannot use them to create
+menus that refer to other files. You must write such menus by hand.
+
+\1f
+File: texinfo.info, Node: Cross References, Next: Marking Text, Prev: Menus, Up: Top
+
+Cross References
+****************
+
+ "Cross references" are used to refer the reader to other parts of the
+same or different Texinfo files. In Texinfo, nodes are the places to
+which cross references can refer.
+
+* Menu:
+
+* References:: What cross references are for.
+* Cross Reference Commands:: A summary of the different commands.
+* Cross Reference Parts:: A cross reference has several parts.
+* xref:: Begin a reference with `See' ...
+* Top Node Naming:: How to refer to the beginning of another file.
+* ref:: A reference for the last part of a sentence.
+* pxref:: How to write a parenthetical cross reference.
+* inforef:: How to refer to an Info-only file.
+* uref:: How to refer to a uniform resource locator.
+
+\1f
+File: texinfo.info, Node: References, Next: Cross Reference Commands, Prev: Cross References, Up: Cross References
+
+What References Are For
+=======================
+
+ Often, but not always, a printed document should be designed so that
+it can be read sequentially. People tire of flipping back and forth to
+find information that should be presented to them as they need it.
+
+ However, in any document, some information will be too detailed for
+the current context, or incidental to it; use cross references to
+provide access to such information. Also, an on-line help system or a
+reference manual is not like a novel; few read such documents in
+sequence from beginning to end. Instead, people look up what they
+need. For this reason, such creations should contain many cross
+references to help readers find other information that they may not
+have read.
+
+ In a printed manual, a cross reference results in a page reference,
+unless it is to another manual altogether, in which case the cross
+reference names that manual.
+
+ In Info, a cross reference results in an entry that you can follow
+using the Info `f' command. (*note Some advanced Info commands:
+(info)Help-Adv.)
+
+ The various cross reference commands use nodes to define cross
+reference locations. This is evident in Info, in which a cross
+reference takes you to the specified node. TeX also uses nodes to
+define cross reference locations, but the action is less obvious. When
+TeX generates a DVI file, it records nodes' page numbers and uses the
+page numbers in making references. Thus, if you are writing a manual
+that will only be printed, and will not be used on-line, you must
+nonetheless write `@node' lines to name the places to which you make
+cross references.
+
+\1f
+File: texinfo.info, Node: Cross Reference Commands, Next: Cross Reference Parts, Prev: References, Up: Cross References
+
+Different Cross Reference Commands
+==================================
+
+ There are four different cross reference commands:
+
+`@xref'
+ Used to start a sentence in the printed manual saying `See ...'
+ or an Info cross-reference saying `*Note NAME: NODE.'.
+
+`@ref'
+ Used within or, more often, at the end of a sentence; same as
+ `@xref' for Info; produces just the reference in the printed
+ manual without a preceding `See'.
+
+`@pxref'
+ Used within parentheses to make a reference that suits both an Info
+ file and a printed book. Starts with a lower case `see' within the
+ printed manual. (`p' is for `parenthesis'.)
+
+`@inforef'
+ Used to make a reference to an Info file for which there is no
+ printed manual.
+
+(The `@cite' command is used to make references to books and manuals
+for which there is no corresponding Info file and, therefore, no node
+to which to point. *Note `@cite': cite.)
+
+\1f
+File: texinfo.info, Node: Cross Reference Parts, Next: xref, Prev: Cross Reference Commands, Up: Cross References
+
+Parts of a Cross Reference
+==========================
+
+ A cross reference command requires only one argument, which is the
+name of the node to which it refers. But a cross reference command may
+contain up to four additional arguments. By using these arguments, you
+can provide a cross reference name for Info, a topic description or
+section title for the printed output, the name of a different Info
+file, and the name of a different printed manual.
+
+ Here is a simple cross reference example:
+
+ @xref{Node name}.
+
+which produces
+
+ *Note Node name::.
+
+and
+
+ See Section NNN [Node name], page PPP.
+
+ Here is an example of a full five-part cross reference:
+
+ @xref{Node name, Cross Reference Name, Particular Topic,
+ info-file-name, A Printed Manual}, for details.
+
+which produces
+
+ *Note Cross Reference Name: (info-file-name)Node name,
+ for details.
+
+in Info and
+
+ See section "Particular Topic" in A Printed Manual, for details.
+
+in a printed book.
+
+ The five possible arguments for a cross reference are:
+
+ 1. The node name (required). This is the node to which the cross
+ reference takes you. In a printed document, the location of the
+ node provides the page reference only for references within the
+ same document.
+
+ 2. The cross reference name for the Info reference, if it is to be
+ different from the node name. If you include this argument, it
+ becomes the first part of the cross reference. It is usually
+ omitted.
+
+ 3. A topic description or section name. Often, this is the title of
+ the section. This is used as the name of the reference in the
+ printed manual. If omitted, the node name is used.
+
+ 4. The name of the Info file in which the reference is located, if it
+ is different from the current file. You need not include any
+ `.info' suffix on the file name, since Info readers try appending
+ it automatically.
+
+ 5. The name of a printed manual from a different Texinfo file.
+
+ The template for a full five argument cross reference looks like this:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+ INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+ Cross references with one, two, three, four, and five arguments are
+described separately following the description of `@xref'.
+
+ Write a node name in a cross reference in exactly the same way as in
+the `@node' line, including the same capitalization; otherwise, the
+formatters may not find the reference.
+
+ You can write cross reference commands within a paragraph, but note
+how Info and TeX format the output of each of the various commands:
+write `@xref' at the beginning of a sentence; write `@pxref' only
+within parentheses, and so on.
+
+\1f
+File: texinfo.info, Node: xref, Next: Top Node Naming, Prev: Cross Reference Parts, Up: Cross References
+
+`@xref'
+=======
+
+ The `@xref' command generates a cross reference for the beginning of
+a sentence. The Info formatting commands convert it into an Info cross
+reference, which the Info `f' command can use to bring you directly to
+another node. The TeX typesetting commands convert it into a page
+reference, or a reference to another book or manual.
+
+* Menu:
+
+* Reference Syntax:: What a reference looks like and requires.
+* One Argument:: `@xref' with one argument.
+* Two Arguments:: `@xref' with two arguments.
+* Three Arguments:: `@xref' with three arguments.
+* Four and Five Arguments:: `@xref' with four and five arguments.
+
+\1f
+File: texinfo.info, Node: Reference Syntax, Next: One Argument, Prev: xref, Up: xref
+
+What a Reference Looks Like and Requires
+----------------------------------------
+
+ Most often, an Info cross reference looks like this:
+
+ *Note NODE-NAME::.
+
+or like this
+
+ *Note CROSS-REFERENCE-NAME: NODE-NAME.
+
+In TeX, a cross reference looks like this:
+
+ See Section SECTION-NUMBER [NODE-NAME], page PAGE.
+
+or like this
+
+ See Section SECTION-NUMBER [TITLE-OR-TOPIC], page PAGE.
+
+ The `@xref' command does not generate a period or comma to end the
+cross reference in either the Info file or the printed output. You
+must write that period or comma yourself; otherwise, Info will not
+recognize the end of the reference. (The `@pxref' command works
+differently. *Note `@pxref': pxref.)
+
+ *Please note:* A period or comma *must* follow the closing brace
+ of an `@xref'. It is required to terminate the cross reference.
+ This period or comma will appear in the output, both in the Info
+ file and in the printed manual.
+
+ `@xref' must refer to an Info node by name. Use `@node' to define
+the node (*note Writing a Node::.).
+
+ `@xref' is followed by several arguments inside braces, separated by
+commas. Whitespace before and after these commas is ignored.
+
+ A cross reference requires only the name of a node; but it may contain
+up to four additional arguments. Each of these variations produces a
+cross reference that looks somewhat different.
+
+ *Please note:* Commas separate arguments in a cross reference;
+ avoid including them in the title or other part lest the formatters
+ mistake them for separators.
+
+\1f
+File: texinfo.info, Node: One Argument, Next: Two Arguments, Prev: Reference Syntax, Up: xref
+
+`@xref' with One Argument
+-------------------------
+
+ The simplest form of `@xref' takes one argument, the name of another
+node in the same Info file. The Info formatters produce output that
+the Info readers can use to jump to the reference; TeX produces output
+that specifies the page and section number for you.
+
+For example,
+
+ @xref{Tropical Storms}.
+
+produces
+
+ *Note Tropical Storms::.
+
+and
+
+ See Section 3.1 [Tropical Storms], page 24.
+
+(Note that in the preceding example the closing brace is followed by a
+period.)
+
+ You can write a clause after the cross reference, like this:
+
+ @xref{Tropical Storms}, for more info.
+
+which produces
+
+ *Note Tropical Storms::, for more info.
+
+ See Section 3.1 [Tropical Storms], page 24, for more info.
+
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+\1f
+File: texinfo.info, Node: Two Arguments, Next: Three Arguments, Prev: One Argument, Up: xref
+
+`@xref' with Two Arguments
+--------------------------
+
+ With two arguments, the second is used as the name of the Info cross
+reference, while the first is still the name of the node to which the
+cross reference points.
+
+The template is like this:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning}.
+
+produces:
+
+ *Note Lightning: Electrical Effects.
+
+and
+
+ See Section 5.2 [Electrical Effects], page 57.
+
+(Note that in the preceding example the closing brace is followed by a
+period; and that the node name is printed, not the cross reference
+name.)
+
+ You can write a clause after the cross reference, like this:
+
+ @xref{Electrical Effects, Lightning}, for more info.
+
+which produces
+ *Note Lightning: Electrical Effects, for more info.
+
+and
+
+ See Section 5.2 [Electrical Effects], page 57, for more info.
+
+(Note that in the preceding example the closing brace is followed by a
+comma, and then by the clause, which is followed by a period.)
+
+\1f
+File: texinfo.info, Node: Three Arguments, Next: Four and Five Arguments, Prev: Two Arguments, Up: xref
+
+`@xref' with Three Arguments
+----------------------------
+
+ A third argument replaces the node name in the TeX output. The third
+argument should be the name of the section in the printed output, or
+else state the topic discussed by that section. Often, you will want to
+use initial upper case letters so it will be easier to read when the
+reference is printed. Use a third argument when the node name is
+unsuitable because of syntax or meaning.
+
+ Remember to avoid placing a comma within the title or topic section of
+a cross reference, or within any other section. The formatters divide
+cross references into arguments according to the commas; a comma within
+a title or other section will divide it into two arguments. In a
+reference, you need to write a title such as "Clouds, Mist, and Fog"
+without the commas.
+
+ Also, remember to write a comma or period after the closing brace of a
+`@xref' to terminate the cross reference. In the following examples, a
+clause follows a terminating comma.
+
+The template is like this:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning, Thunder and Lightning},
+ for details.
+
+produces
+
+ *Note Lightning: Electrical Effects, for details.
+
+and
+
+ See Section 5.2 [Thunder and Lightning], page 57, for details.
+
+ If a third argument is given and the second one is empty, then the
+third argument serves both. (Note how two commas, side by side, mark
+the empty second argument.)
+
+ @xref{Electrical Effects, , Thunder and Lightning},
+ for details.
+
+produces
+
+ *Note Thunder and Lightning: Electrical Effects, for details.
+
+and
+
+ See Section 5.2 [Thunder and Lightning], page 57, for details.
+
+ As a practical matter, it is often best to write cross references with
+just the first argument if the node name and the section title are the
+same, and with the first and third arguments if the node name and title
+are different.
+
+ Here are several examples from `The GNU Awk User's Guide':
+
+ @xref{Sample Program}.
+ @xref{Glossary}.
+ @xref{Case-sensitivity, ,Case-sensitivity in Matching}.
+ @xref{Close Output, , Closing Output Files and Pipes},
+ for more information.
+ @xref{Regexp, , Regular Expressions as Patterns}.
+
+\1f
+File: texinfo.info, Node: Four and Five Arguments, Prev: Three Arguments, Up: xref
+
+`@xref' with Four and Five Arguments
+------------------------------------
+
+ In a cross reference, a fourth argument specifies the name of another
+Info file, different from the file in which the reference appears, and
+a fifth argument specifies its title as a printed manual.
+
+ Remember that a comma or period must follow the closing brace of an
+`@xref' command to terminate the cross reference. In the following
+examples, a clause follows a terminating comma.
+
+The template is:
+
+ @xref{NODE-NAME, CROSS-REFERENCE-NAME, TITLE-OR-TOPIC,
+ INFO-FILE-NAME, PRINTED-MANUAL-TITLE}.
+
+For example,
+
+ @xref{Electrical Effects, Lightning, Thunder and Lightning,
+ weather, An Introduction to Meteorology}, for details.
+
+produces
+
+ *Note Lightning: (weather)Electrical Effects, for details.
+
+The name of the Info file is enclosed in parentheses and precedes the
+name of the node.
+
+In a printed manual, the reference looks like this:
+
+ See section "Thunder and Lightning" in An Introduction to
+ Meteorology, for details.
+
+The title of the printed manual is typeset in italics; and the
+reference lacks a page number since TeX cannot know to which page a
+reference refers when that reference is to another manual.
+
+ Often, you will leave out the second argument when you use the long
+version of `@xref'. In this case, the third argument, the topic
+description, will be used as the cross reference name in Info.
+
+The template looks like this:
+
+ @xref{NODE-NAME, , TITLE-OR-TOPIC, INFO-FILE-NAME,
+ PRINTED-MANUAL-TITLE}, for details.
+
+which produces
+
+ *Note TITLE-OR-TOPIC: (INFO-FILE-NAME)NODE-NAME, for details.
+
+and
+
+ See section TITLE-OR-TOPIC in PRINTED-MANUAL-TITLE, for details.
+
+For example,
+
+ @xref{Electrical Effects, , Thunder and Lightning,
+ weather, An Introduction to Meteorology}, for details.
+
+produces
+
+ *Note Thunder and Lightning: (weather)Electrical Effects,
+ for details.
+
+and
+
+ See section "Thunder and Lightning" in An Introduction to
+ Meteorology, for details.
+
+ On rare occasions, you may want to refer to another Info file that is
+within a single printed manual--when multiple Texinfo files are
+incorporated into the same TeX run but make separate Info files. In
+this case, you need to specify only the fourth argument, and not the
+fifth.
+
+\1f
+File: texinfo.info, Node: Top Node Naming, Next: ref, Prev: xref, Up: Cross References
+
+Naming a `Top' Node
+===================
+
+ In a cross reference, you must always name a node. This means that in
+order to refer to a whole manual, you must identify the `Top' node by
+writing it as the first argument to the `@xref' command. (This is
+different from the way you write a menu entry; see *Note Referring to
+Other Info Files: Other Info Files.) At the same time, to provide a
+meaningful section topic or title in the printed cross reference
+(instead of the word `Top'), you must write an appropriate entry for
+the third argument to the `@xref' command.
+
+Thus, to make a cross reference to `The GNU Make Manual', write:
+
+ @xref{Top, , Overview, make, The GNU Make Manual}.
+
+which produces
+
+ *Note Overview: (make)Top.
+
+and
+
+ See section "Overview" in The GNU Make Manual.
+
+In this example, `Top' is the name of the first node, and `Overview' is
+the name of the first section of the manual.
+
+\1f
+File: texinfo.info, Node: ref, Next: pxref, Prev: Top Node Naming, Up: Cross References
+
+`@ref'
+======
+
+ `@ref' is nearly the same as `@xref' except that it does not generate
+a `See' in the printed output, just the reference itself. This makes
+it useful as the last part of a sentence.
+
+For example,
+
+ For more information, see @ref{Hurricanes}.
+
+produces
+
+ For more information, see *Note Hurricanes.
+
+and
+
+ For more information, see Section 8.2 [Hurricanes], page 123.
+
+ The `@ref' command sometimes leads writers to express themselves in a
+manner that is suitable for a printed manual but looks awkward in the
+Info format. Bear in mind that your audience will be using both the
+printed and the Info format.
+
+For example,
+
+ Sea surges are described in @ref{Hurricanes}.
+
+produces
+
+ Sea surges are described in Section 6.7 [Hurricanes], page 72.
+
+in a printed document, and the following in Info:
+
+ Sea surges are described in *Note Hurricanes::.
+
+ *Caution:* You *must* write a period or comma immediately after an
+ `@ref' command with two or more arguments. Otherwise, Info will
+ not find the end of the cross reference entry and its attempt to
+ follow the cross reference will fail. As a general rule, you
+ should write a period or comma after every `@ref' command. This
+ looks best in both the printed and the Info output.
+
+\1f
+File: texinfo.info, Node: pxref, Next: inforef, Prev: ref, Up: Cross References
+
+`@pxref'
+========
+
+ The parenthetical reference command, `@pxref', is nearly the same as
+`@xref', but you use it *only* inside parentheses and you do *not* type
+a comma or period after the command's closing brace. The command
+differs from `@xref' in two ways:
+
+ 1. TeX typesets the reference for the printed manual with a lower case
+ `see' rather than an upper case `See'.
+
+ 2. The Info formatting commands automatically end the reference with a
+ closing colon or period.
+
+ Because one type of formatting automatically inserts closing
+punctuation and the other does not, you should use `@pxref' *only*
+inside parentheses as part of another sentence. Also, you yourself
+should not insert punctuation after the reference, as you do with
+`@xref'.
+
+ `@pxref' is designed so that the output looks right and works right
+between parentheses both in printed output and in an Info file. In a
+printed manual, a closing comma or period should not follow a cross
+reference within parentheses; such punctuation is wrong. But in an
+Info file, suitable closing punctuation must follow the cross reference
+so Info can recognize its end. `@pxref' spares you the need to use
+complicated methods to put a terminator into one form of the output and
+not the other.
+
+With one argument, a parenthetical cross reference looks like this:
+
+ ... storms cause flooding (@pxref{Hurricanes}) ...
+
+which produces
+
+ ... storms cause flooding (*Note Hurricanes::) ...
+
+and
+
+ ... storms cause flooding (see Section 6.7 [Hurricanes], page 72)
+ ...
+
+ With two arguments, a parenthetical cross reference has this template:
+
+ ... (@pxref{NODE-NAME, CROSS-REFERENCE-NAME}) ...
+
+which produces
+
+ ... (*Note CROSS-REFERENCE-NAME: NODE-NAME.) ...
+
+and
+
+ ... (see Section NNN [NODE-NAME], page PPP) ...
+
+ `@pxref' can be used with up to five arguments just like `@xref'
+(*note `@xref': xref.).
+
+ *Please note:* Use `@pxref' only as a parenthetical reference. Do
+ not try to use `@pxref' as a clause in a sentence. It will look
+ bad in either the Info file, the printed output, or both.
+
+ Also, parenthetical cross references look best at the ends of
+ sentences. Although you may write them in the middle of a
+ sentence, that location breaks up the flow of text.
+
+\1f
+File: texinfo.info, Node: inforef, Next: uref, Prev: pxref, Up: Cross References
+
+`@inforef'
+==========
+
+ `@inforef' is used for cross references to Info files for which there
+are no printed manuals. Even in a printed manual, `@inforef' generates
+a reference directing the user to look in an Info file.
+
+ The command takes either two or three arguments, in the following
+order:
+
+ 1. The node name.
+
+ 2. The cross reference name (optional).
+
+ 3. The Info file name.
+
+Separate the arguments with commas, as with `@xref'. Also, you must
+terminate the reference with a comma or period after the `}', as you do
+with `@xref'.
+
+The template is:
+
+ @inforef{NODE-NAME, CROSS-REFERENCE-NAME, INFO-FILE-NAME},
+
+Thus,
+
+ @inforef{Expert, Advanced Info commands, info},
+ for more information.
+
+produces
+
+ *Note Advanced Info commands: (info)Expert,
+ for more information.
+
+and
+
+ See Info file `info', node `Expert', for more information.
+
+Similarly,
+
+ @inforef{Expert, , info}, for more information.
+
+produces
+
+ *Note (info)Expert::, for more information.
+
+and
+
+ See Info file `info', node `Expert', for more information.
+
+ The converse of `@inforef' is `@cite', which is used to refer to
+printed works for which no Info form exists. *Note `@cite': cite.
+
+\1f
+File: texinfo.info, Node: uref, Prev: inforef, Up: Cross References
+
+`@uref{URL[, DISPLAYED-TEXT]}'
+==============================
+
+ `@uref' produces a reference to a uniform resource locator (URL). It
+takes one mandatory argument, the URL, and one optional argument, the
+text to display (the default is the URL itself). In HTML output,
+`@uref' produces a link you can follow. For example:
+
+ The official GNU ftp site is
+ @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
+
+produces (in text):
+ The official GNU ftp site is
+ `ftp://ftp.gnu.ai.mit.edu/pub/gnu'
+
+whereas
+ The official
+ @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
+ GNU ftp site} holds programs and texts.
+
+produces (in text):
+ The official GNU ftp site (ftp://ftp.gnu.ai.mit.edu/pub/gnu) holds
+ programs and texts.
+
+and (in HTML):
+ The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
+ site</A> holds programs and texts.
+
+ To merely indicate a URL, use `@url' (*note `@url': url.).
+
+\1f
+File: texinfo.info, Node: Marking Text, Next: Quotations and Examples, Prev: Cross References, Up: Top
+
+Marking Words and Phrases
+*************************
+
+ In Texinfo, you can mark words and phrases in a variety of ways. The
+Texinfo formatters use this information to determine how to highlight
+the text. You can specify, for example, whether a word or phrase is a
+defining occurrence, a metasyntactic variable, or a symbol used in a
+program. Also, you can emphasize text.
+
+* Menu:
+
+* Indicating:: How to indicate definitions, files, etc.
+* Emphasis:: How to emphasize text.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Indicating, Next: Emphasis, Prev: Marking Text, Up: Marking Text
+
+Indicating Definitions, Commands, etc.
+======================================
+
+ Texinfo has commands for indicating just what kind of object a piece
+of text refers to. For example, metasyntactic variables are marked by
+`@var', and code by `@code'. Since the pieces of text are labelled by
+commands that tell what kind of object they are, it is easy to change
+the way the Texinfo formatters prepare such text. (Texinfo is an
+*intentional* formatting language rather than a *typesetting*
+formatting language.)
+
+ For example, in a printed manual, code is usually illustrated in a
+typewriter font; `@code' tells TeX to typeset this text in this font.
+But it would be easy to change the way TeX highlights code to use
+another font, and this change would not effect how keystroke examples
+are highlighted. If straight typesetting commands were used in the body
+of the file and you wanted to make a change, you would need to check
+every single occurrence to make sure that you were changing code and
+not something else that should not be changed.
+
+* Menu:
+
+* Useful Highlighting:: Highlighting provides useful information.
+* code:: How to indicate code.
+* kbd:: How to show keyboard input.
+* key:: How to specify keys.
+* samp:: How to show a literal sequence of characters.
+* var:: How to indicate a metasyntactic variable.
+* file:: How to indicate the name of a file.
+* dfn:: How to specify a definition.
+* cite:: How to refer to a book that is not in Info.
+* url:: How to indicate a world wide web reference.
+* email:: How to indicate an electronic mail address.
+
+\1f
+File: texinfo.info, Node: Useful Highlighting, Next: code, Prev: Indicating, Up: Indicating
+
+Highlighting Commands are Useful
+--------------------------------
+
+ The highlighting commands can be used to generate useful information
+from the file, such as lists of functions or file names. It is
+possible, for example, to write a program in Emacs Lisp (or a keyboard
+macro) to insert an index entry after every paragraph that contains
+words or phrases marked by a specified command. You could do this to
+construct an index of functions if you had not already made the entries.
+
+ The commands serve a variety of purposes:
+
+`@code{SAMPLE-CODE}'
+ Indicate text that is a literal example of a piece of a program.
+
+`@kbd{KEYBOARD-CHARACTERS}'
+ Indicate keyboard input.
+
+`@key{KEY-NAME}'
+ Indicate the conventional name for a key on a keyboard.
+
+`@samp{TEXT}'
+ Indicate text that is a literal example of a sequence of
+ characters.
+
+`@var{METASYNTACTIC-VARIABLE}'
+ Indicate a metasyntactic variable.
+
+`@url{UNIFORM-RESOURCE-LOCATOR}'
+ Indicate a uniform resource locator for the World Wide Web.
+
+`@file{FILE-NAME}'
+ Indicate the name of a file.
+
+`@email{EMAIL-ADDRESS[, DISPLAYED-TEXT]}'
+ Indicate an electronic mail address.
+
+`@dfn{TERM}'
+ Indicate the introductory or defining use of a term.
+
+`@cite{REFERENCE}'
+ Indicate the name of a book.
+
+\1f
+File: texinfo.info, Node: code, Next: kbd, Prev: Useful Highlighting, Up: Indicating
+
+`@code'{SAMPLE-CODE}
+--------------------
+
+ Use the `@code' command to indicate text that is a piece of a program
+and which consists of entire syntactic tokens. Enclose the text in
+braces.
+
+ Thus, you should use `@code' for an expression in a program, for the
+name of a variable or function used in a program, or for a keyword.
+Also, you should use `@code' for the name of a program, such as `diff',
+that is a name used in the machine. (You should write the name of a
+program in the ordinary text font if you regard it as a new English
+word, such as `Emacs' or `Bison'.)
+
+ Use `@code' for environment variables such as `TEXINPUTS', and other
+variables.
+
+ Use `@code' for command names in command languages that resemble
+programming languages, such as Texinfo or the shell. For example,
+`@code' and `@samp' are produced by writing `@code{@@code}' and
+`@code{@@samp}' in the Texinfo source, respectively.
+
+ Note, however, that you should not use `@code' for shell options such
+as `-c' when such options stand alone. (Use `@samp'.) Also, an entire
+shell command often looks better if written using `@samp' rather than
+`@code'. In this case, the rule is to choose the more pleasing format.
+
+ It is incorrect to alter the case of a word inside an `@code' command
+when it appears at the beginning of a sentence. Most computer
+languages are case sensitive. In C, for example, `Printf' is different
+from the identifier `printf', and most likely is a misspelling of it.
+Even in languages which are not case sensitive, it is confusing to a
+human reader to see identifiers spelled in different ways. Pick one
+spelling and always use that. If you do not want to start a sentence
+with a command written all in lower case, you should rearrange the
+sentence.
+
+ Do not use the `@code' command for a string of characters shorter
+than a syntactic token. If you are writing about `TEXINPU', which is
+just a part of the name for the `TEXINPUTS' environment variable, you
+should use `@samp'.
+
+ In particular, you should not use the `@code' command when writing
+about the characters used in a token; do not, for example, use `@code'
+when you are explaining what letters or printable symbols can be used
+in the names of functions. (Use `@samp'.) Also, you should not use
+`@code' to mark text that is considered input to programs unless the
+input is written in a language that is like a programming language.
+For example, you should not use `@code' for the keystroke commands of
+GNU Emacs (use `@kbd' instead) although you may use `@code' for the
+names of the Emacs Lisp functions that the keystroke commands invoke.
+
+ In the printed manual, `@code' causes TeX to typeset the argument in
+a typewriter face. In the Info file, it causes the Info formatting
+commands to use single quotation marks around the text.
+
+ For example,
+
+ Use @code{diff} to compare two files.
+
+produces this in the printed manual:
+
+ Use `diff' to compare two files.
+
+\1f
+File: texinfo.info, Node: kbd, Next: key, Prev: code, Up: Indicating
+
+`@kbd'{KEYBOARD-CHARACTERS}
+---------------------------
+
+ Use the `@kbd' command for characters of input to be typed by users.
+For example, to refer to the characters `M-a', write
+
+ @kbd{M-a}
+
+and to refer to the characters `M-x shell', write
+
+ @kbd{M-x shell}
+
+ The `@kbd' command has the same effect as `@code' in Info, but by
+default produces a different font (slanted typewriter instead of normal
+typewriter) in the printed manual, so users can distinguish the
+characters they are supposed to type from those the computer outputs.
+
+ Since the usage of `@kbd' varies from manual to manual, you can
+control the font switching with the `@kbdinputstyle' command. This
+command has no effect on Info output. Write this command at the
+beginning of a line with a single word as an argument, one of the
+following:
+`code'
+ Always use the same font for `@kbd' as `@code'.
+
+`example'
+ Use the distinguishing font for `@kbd' only in `@example' and
+ similar environments.
+
+`example'
+ (the default) Always use the distinguishing font for `@kbd'.
+
+ You can embed another @-command inside the braces of an `@kbd'
+command. Here, for example, is the way to describe a command that
+would be described more verbosely as "press an `r' and then press the
+<RET> key":
+
+ @kbd{r @key{RET}}
+
+This produces: `r <RET>'
+
+ You also use the `@kbd' command if you are spelling out the letters
+you type; for example:
+
+ To give the @code{logout} command,
+ type the characters @kbd{l o g o u t @key{RET}}.
+
+This produces:
+
+ To give the `logout' command, type the characters `l o g o u t
+ <RET>'.
+
+ (Also, this example shows that you can add spaces for clarity. If you
+really want to mention a space character as one of the characters of
+input, write `@key{SPC}' for it.)
+
+\1f
+File: texinfo.info, Node: key, Next: samp, Prev: kbd, Up: Indicating
+
+`@key'{KEY-NAME}
+----------------
+
+ Use the `@key' command for the conventional name for a key on a
+keyboard, as in:
+
+ @key{RET}
+
+ You can use the `@key' command within the argument of an `@kbd'
+command when the sequence of characters to be typed includes one or
+more keys that are described by name.
+
+ For example, to produce `C-x <ESC>' you would type:
+
+ @kbd{C-x @key{ESC}}
+
+ Here is a list of the recommended names for keys:
+
+ SPC
+ Space
+
+ RET
+ Return
+
+ LFD
+ Linefeed (however, since most keyboards nowadays do not have
+ a Linefeed key, it might be better to call this character
+ `C-j'.
+
+ TAB
+ Tab
+
+ BS
+ Backspace
+
+ ESC
+ Escape
+
+ DEL
+ Delete
+
+ SHIFT
+ Shift
+
+ CTRL
+ Control
+
+ META
+ Meta
+
+ There are subtleties to handling words like `meta' or `ctrl' that are
+names of modifier keys. When mentioning a character in which the
+modifier key is used, such as `Meta-a', use the `@kbd' command alone;
+do not use the `@key' command; but when you are referring to the
+modifier key in isolation, use the `@key' command. For example, write
+`@kbd{Meta-a}' to produce `Meta-a' and `@key{META}' to produce <META>.
+
+\1f
+File: texinfo.info, Node: samp, Next: var, Prev: key, Up: Indicating
+
+`@samp'{TEXT}
+-------------
+
+ Use the `@samp' command to indicate text that is a literal example or
+`sample' of a sequence of characters in a file, string, pattern, etc.
+Enclose the text in braces. The argument appears within single
+quotation marks in both the Info file and the printed manual; in
+addition, it is printed in a fixed-width font.
+
+ To match @samp{foo} at the end of the line,
+ use the regexp @samp{foo$}.
+
+produces
+
+ To match `foo' at the end of the line, use the regexp `foo$'.
+
+ Any time you are referring to single characters, you should use
+`@samp' unless `@kbd' or `@key' is more appropriate. Use `@samp' for
+the names of command-line options (except in an `@table', where `@code'
+seems to read more easily). Also, you may use `@samp' for entire
+statements in C and for entire shell commands--in this case, `@samp'
+often looks better than `@code'. Basically, `@samp' is a catchall for
+whatever is not covered by `@code', `@kbd', or `@key'.
+
+ Only include punctuation marks within braces if they are part of the
+string you are specifying. Write punctuation marks outside the braces
+if those punctuation marks are part of the English text that surrounds
+the string. In the following sentence, for example, the commas and
+period are outside of the braces:
+
+ In English, the vowels are @samp{a}, @samp{e},
+ @samp{i}, @samp{o}, @samp{u}, and sometimes
+ @samp{y}.
+
+This produces:
+
+ In English, the vowels are `a', `e', `i', `o', `u', and sometimes
+ `y'.
+
+\1f
+File: texinfo.info, Node: var, Next: file, Prev: samp, Up: Indicating
+
+`@var'{METASYNTACTIC-VARIABLE}
+------------------------------
+
+ Use the `@var' command to indicate metasyntactic variables. A
+"metasyntactic variable" is something that stands for another piece of
+text. For example, you should use a metasyntactic variable in the
+documentation of a function to describe the arguments that are passed
+to that function.
+
+ Do not use `@var' for the names of particular variables in
+programming languages. These are specific names from a program, so
+`@code' is correct for them. For example, the Emacs Lisp variable
+`texinfo-tex-command' is not a metasyntactic variable; it is properly
+formatted using `@code'.
+
+ The effect of `@var' in the Info file is to change the case of the
+argument to all upper case; in the printed manual, to italicize it.
+
+ For example,
+
+ To delete file @var{filename},
+ type @code{rm @var{filename}}.
+
+produces
+
+ To delete file FILENAME, type `rm FILENAME'.
+
+(Note that `@var' may appear inside `@code', `@samp', `@file', etc.)
+
+ Write a metasyntactic variable all in lower case without spaces, and
+use hyphens to make it more readable. Thus, the Texinfo source for the
+illustration of how to begin a Texinfo manual looks like this:
+
+ \input texinfo
+ @@setfilename @var{info-file-name}
+ @@settitle @var{name-of-manual}
+
+This produces:
+
+ \input texinfo
+ @setfilename INFO-FILE-NAME
+ @settitle NAME-OF-MANUAL
+
+ In some documentation styles, metasyntactic variables are shown with
+angle brackets, for example:
+
+ ..., type rm <filename>
+
+However, that is not the style that Texinfo uses. (You can, of course,
+modify the sources to TeX and the Info formatting commands to output
+the `<...>' format if you wish.)
+
+\1f
+File: texinfo.info, Node: file, Next: dfn, Prev: var, Up: Indicating
+
+`@file'{FILE-NAME}
+------------------
+
+ Use the `@file' command to indicate text that is the name of a file,
+buffer, or directory, or is the name of a node in Info. You can also
+use the command for file name suffixes. Do not use `@file' for symbols
+in a programming language; use `@code'.
+
+ Currently, `@file' is equivalent to `@samp' in its effects. For
+example,
+
+ The @file{.el} files are in
+ the @file{/usr/local/emacs/lisp} directory.
+
+produces
+
+ The `.el' files are in the `/usr/local/emacs/lisp' directory.
+
+\1f
+File: texinfo.info, Node: dfn, Next: cite, Prev: file, Up: Indicating
+
+`@dfn'{TERM}
+------------
+
+ Use the `@dfn' command to identify the introductory or defining use
+of a technical term. Use the command only in passages whose purpose is
+to introduce a term which will be used again or which the reader ought
+to know. Mere passing mention of a term for the first time does not
+deserve `@dfn'. The command generates italics in the printed manual,
+and double quotation marks in the Info file. For example:
+
+ Getting rid of a file is called @dfn{deleting} it.
+
+produces
+
+ Getting rid of a file is called "deleting" it.
+
+ As a general rule, a sentence containing the defining occurrence of a
+term should be a definition of the term. The sentence does not need to
+say explicitly that it is a definition, but it should contain the
+information of a definition--it should make the meaning clear.
+
+\1f
+File: texinfo.info, Node: cite, Next: url, Prev: dfn, Up: Indicating
+
+`@cite'{REFERENCE}
+------------------
+
+ Use the `@cite' command for the name of a book that lacks a companion
+Info file. The command produces italics in the printed manual, and
+quotation marks in the Info file.
+
+ (If a book is written in Texinfo, it is better to use a cross
+reference command since a reader can easily follow such a reference in
+Info. *Note `@xref': xref.)
+
+\1f
+File: texinfo.info, Node: url, Next: email, Prev: cite, Up: Indicating
+
+`@url'{UNIFORM-RESOURCE-LOCATOR}
+--------------------------------
+
+ Use the `@url' to indicate a uniform resource locator on the World
+Wide Web. This is analogous to `@file', `@var', etc., and is purely
+for markup purposes. It does not produce a link you can follow in HTML
+output (the `@uref' command does, *note `@uref': uref.). It is useful
+for example URL's which do not actually exist. For example:
+
+ For example, the url might be
+ @url{http://host.domain.org/path}.
+
+\1f
+File: texinfo.info, Node: email, Prev: url, Up: Indicating
+
+`@email'{EMAIL-ADDRESS[, DISPLAYED-TEXT]}
+-----------------------------------------
+
+ Use the `@email' command to indicate an electronic mail address. It
+takes one mandatory argument, the address, and one optional argument,
+the text to display (the default is the address itself).
+
+ In Info and TeX, the address is shown in angle brackets, preceded by
+the text to display if any. In HTML output, `@email' produces a
+`mailto' link that usually brings up a mail composition window. For
+example:
+
+ Send bug reports to @email{bug-texinfo@@gnu.org}.
+ Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
+
+produces
+ Send bug reports to <bug-texinfo@gnu.org>.
+ Send suggestions to the same place <bug-texinfo@gnu.org>.
+
+\1f
+File: texinfo.info, Node: Emphasis, Prev: Indicating, Up: Marking Text
+
+Emphasizing Text
+================
+
+ Usually, Texinfo changes the font to mark words in the text according
+to what category the words belong to; an example is the `@code' command.
+Most often, this is the best way to mark words. However, sometimes you
+will want to emphasize text without indicating a category. Texinfo has
+two commands to do this. Also, Texinfo has several commands that
+specify the font in which TeX will typeset text. These commands have
+no affect on Info and only one of them, the `@r' command, has any
+regular use.
+
+* Menu:
+
+* emph & strong:: How to emphasize text in Texinfo.
+* Smallcaps:: How to use the small caps font.
+* Fonts:: Various font commands for printed output.
+* Customized Highlighting:: How to define highlighting commands.
+
+\1f
+File: texinfo.info, Node: emph & strong, Next: Smallcaps, Prev: Emphasis, Up: Emphasis
+
+`@emph'{TEXT} and `@strong'{TEXT}
+---------------------------------
+
+ The `@emph' and `@strong' commands are for emphasis; `@strong' is
+stronger. In printed output, `@emph' produces *italics* and `@strong'
+produces *bold*.
+
+ For example,
+
+ @quotation
+ @strong{Caution:} @samp{rm * .[^.]*} removes @emph{all}
+ files in the directory.
+ @end quotation
+
+produces:
+
+ *Caution*: `rm * .[^.]*' removes *all*
+ files in the directory.
+
+ The `@strong' command is seldom used except to mark what is, in
+effect, a typographical element, such as the word `Caution' in the
+preceding example.
+
+ In the Info file, both `@emph' and `@strong' put asterisks around the
+text.
+
+ *Caution:* Do not use `@emph' or `@strong' with the word `Note';
+ Info will mistake the combination for a cross reference. Use a
+ phrase such as *Please note* or *Caution* instead.
+
+\1f
+File: texinfo.info, Node: Smallcaps, Next: Fonts, Prev: emph & strong, Up: Emphasis
+
+`@sc'{TEXT}: The Small Caps Font
+--------------------------------
+
+ Use the `@sc' command to set text in the printed output in a small
+caps font and set text in the Info file in upper case letters.
+
+ Write the text between braces in lower case, like this:
+
+ The @sc{acm} and @sc{ieee} are technical societies.
+
+This produces:
+
+ The ACM and IEEE are technical societies.
+
+ TeX typesets the small caps font in a manner that prevents the
+letters from `jumping out at you on the page'. This makes small caps
+text easier to read than text in all upper case. The Info formatting
+commands set all small caps text in upper case.
+
+ If the text between the braces of an `@sc' command is upper case, TeX
+typesets in full-size capitals. Use full-size capitals sparingly.
+
+ You may also use the small caps font for a jargon word such as ATO (a
+NASA word meaning `abort to orbit').
+
+ There are subtleties to using the small caps font with a jargon word
+such as CDR, a word used in Lisp programming. In this case, you should
+use the small caps font when the word refers to the second and
+subsequent elements of a list (the CDR of the list), but you should use
+`@code' when the word refers to the Lisp function of the same spelling.
+
+\1f
+File: texinfo.info, Node: Fonts, Next: Customized Highlighting, Prev: Smallcaps, Up: Emphasis
+
+Fonts for Printing, Not Info
+----------------------------
+
+ Texinfo provides four font commands that specify font changes in the
+printed manual but have no effect in the Info file. `@i' requests
+italic font (in some versions of TeX, a slanted font is used), `@b'
+requests bold face, `@t' requests the fixed-width, typewriter-style
+font used by `@code', and `@r' requests a roman font, which is the
+usual font in which text is printed. All four commands apply to an
+argument that follows, surrounded by braces.
+
+ Only the `@r' command has much use: in example programs, you can use
+the `@r' command to convert code comments from the fixed-width font to
+a roman font. This looks better in printed output.
+
+ For example,
+
+ @lisp
+ (+ 2 2) ; @r{Add two plus two.}
+ @end lisp
+
+produces
+
+ (+ 2 2) ; Add two plus two.
+
+ If possible, you should avoid using the other three font commands. If
+you need to use one, it probably indicates a gap in the Texinfo
+language.
+
+\1f
+File: texinfo.info, Node: Customized Highlighting, Prev: Fonts, Up: Emphasis
+
+Customized Highlighting
+-----------------------
+
+ You can use regular TeX commands inside of `@iftex' ... `@end iftex'
+to create your own customized highlighting commands for Texinfo. The
+easiest way to do this is to equate your customized commands with
+pre-existing commands, such as those for italics. Such new commands
+work only with TeX.
+
+ You can use the `@definfoenclose' command inside of `@ifinfo' ...
+`@end ifinfo' to define commands for Info with the same names as new
+commands for TeX. `@definfoenclose' creates new commands for Info that
+mark text by enclosing it in strings that precede and follow the text.
+(1) (*note Customized Highlighting-Footnotes::)
+
+ Here is how to create a new @-command called `@phoo' that causes TeX
+to typeset its argument in italics and causes Info to display the
+argument between `//' and `\\'.
+
+ For TeX, write the following to equate the `@phoo' command with the
+existing `@i' italics command:
+
+ @iftex
+ @global@let@phoo=@i
+ @end iftex
+
+This defines `@phoo' as a command that causes TeX to typeset the
+argument to `@phoo' in italics. `@global@let' tells TeX to equate the
+next argument with the argument that follows the equals sign.
+
+ For Info, write the following to tell the Info formatters to enclose
+the argument between `//' and `\\':
+
+ @ifinfo
+ @definfoenclose phoo, //, \\
+ @end ifinfo
+
+Write the `@definfoenclose' command on a line and follow it with three
+arguments separated by commas (commas are used as separators in an
+`@node' line in the same way).
+
+ * The first argument to `@definfoenclose' is the @-command name
+ *without* the `@';
+
+ * the second argument is the Info start delimiter string; and,
+
+ * the third argument is the Info end delimiter string.
+
+The latter two arguments enclose the highlighted text in the Info file.
+A delimiter string may contain spaces. Neither the start nor end
+delimiter is required. However, if you do not provide a start
+delimiter, you must follow the command name with two commas in a row;
+otherwise, the Info formatting commands will misinterpret the end
+delimiter string as a start delimiter string.
+
+ After you have defined `@phoo' both for TeX and for Info, you can
+then write `@phoo{bar}' to see `//bar\\' in Info and see `bar' in
+italics in printed output.
+
+ Note that each definition applies to its own formatter: one for TeX,
+the other for Info.
+
+ Here is another example:
+
+ @ifinfo
+ @definfoenclose headword, , :
+ @end ifinfo
+ @iftex
+ @global@let@headword=@b
+ @end iftex
+
+This defines `@headword' as an Info formatting command that inserts
+nothing before and a colon after the argument and as a TeX formatting
+command to typeset its argument in bold.
+
+\1f
+File: texinfo.info, Node: Customized Highlighting-Footnotes, Up: Customized Highlighting
+
+ (1) Currently, `@definfoenclose' works only with
+`texinfo-format-buffer' and `texinfo-format-region', not with
+`makeinfo'.
+
+\1f
+File: texinfo.info, Node: Quotations and Examples, Next: Lists and Tables, Prev: Marking Text, Up: Top
+
+Quotations and Examples
+***********************
+
+ Quotations and examples are blocks of text consisting of one or more
+whole paragraphs that are set off from the bulk of the text and treated
+differently. They are usually indented.
+
+ In Texinfo, you always begin a quotation or example by writing an
+@-command at the beginning of a line by itself, and end it by writing
+an `@end' command that is also at the beginning of a line by itself.
+For instance, you begin an example by writing `@example' by itself at
+the beginning of a line and end the example by writing `@end example'
+on a line by itself, at the beginning of that line.
+
+* Menu:
+
+* Block Enclosing Commands:: Use different constructs for
+ different purposes.
+* quotation:: How to write a quotation.
+* example:: How to write an example in a fixed-width font.
+* noindent:: How to prevent paragraph indentation.
+* Lisp Example:: How to illustrate Lisp code.
+* smallexample & smalllisp:: Forms for the `@smallbook' option.
+* display:: How to write an example in the current font.
+* format:: How to write an example that does not narrow
+ the margins.
+* exdent:: How to undo the indentation of a line.
+* flushleft & flushright:: How to push text flushleft or flushright.
+* cartouche:: How to draw cartouches around examples.
+
+\1f
+File: texinfo.info, Node: Block Enclosing Commands, Next: quotation, Prev: Quotations and Examples, Up: Quotations and Examples
+
+The Block Enclosing Commands
+============================
+
+ Here are commands for quotations and examples:
+
+`@quotation'
+ Indicate text that is quoted. The text is filled, indented, and
+ printed in a roman font by default.
+
+`@example'
+ Illustrate code, commands, and the like. The text is printed in a
+ fixed-width font, and indented but not filled.
+
+`@lisp'
+ Illustrate Lisp code. The text is printed in a fixed-width font,
+ and indented but not filled.
+
+`@smallexample'
+ Illustrate code, commands, and the like. Similar to `@example',
+ except that in TeX this command typesets text in a smaller font
+ for the smaller `@smallbook' format than for the 8.5 by 11 inch
+ format.
+
+`@smalllisp'
+ Illustrate Lisp code. Similar to `@lisp', except that in TeX this
+ command typesets text in a smaller font for the smaller
+ `@smallbook' format than for the 8.5 by 11 inch format.
+
+`@display'
+ Display illustrative text. The text is indented but not filled,
+ and no font is specified (so, by default, the font is roman).
+
+`@format'
+ Print illustrative text. The text is not indented and not filled
+ and no font is specified (so, by default, the font is roman).
+
+ The `@exdent' command is used within the above constructs to undo the
+indentation of a line.
+
+ The `@flushleft' and `@flushright' commands are used to line up the
+left or right margins of unfilled text.
+
+ The `@noindent' command may be used after one of the above constructs
+to prevent the following text from being indented as a new paragraph.
+
+ You can use the `@cartouche' command within one of the above
+constructs to highlight the example or quotation by drawing a box with
+rounded corners around it. (The `@cartouche' command affects only the
+printed manual; it has no effect in the Info file; see *Note Drawing
+Cartouches Around Examples: cartouche.)
+
+\1f
+File: texinfo.info, Node: quotation, Next: example, Prev: Block Enclosing Commands, Up: Quotations and Examples
+
+`@quotation'
+============
+
+ The text of a quotation is processed normally except that:
+
+ * the margins are closer to the center of the page, so the whole of
+ the quotation is indented;
+
+ * the first lines of paragraphs are indented no more than other
+ lines;
+
+ * in the printed output, interparagraph spacing is reduced.
+
+ This is an example of text written between an `@quotation' command
+ and an `@end quotation' command. An `@quotation' command is most
+ often used to indicate text that is excerpted from another (real
+ or hypothetical) printed work.
+
+ Write an `@quotation' command as text on a line by itself. This line
+will disappear from the output. Mark the end of the quotation with a
+line beginning with and containing only `@end quotation'. The `@end
+quotation' line will likewise disappear from the output. Thus, the
+following,
+
+ @quotation
+ This is
+ a foo.
+ @end quotation
+
+produces
+
+ This is a foo.
+
+\1f
+File: texinfo.info, Node: example, Next: noindent, Prev: quotation, Up: Quotations and Examples
+
+`@example'
+==========
+
+ The `@example' command is used to indicate an example that is not
+part of the running text, such as computer input or output.
+
+ This is an example of text written between an
+ `@example' command
+ and an `@end example' command.
+ The text is indented but not filled.
+
+ In the printed manual, the text is typeset in a
+ fixed-width font, and extra spaces and blank lines are
+ significant. In the Info file, an analogous result is
+ obtained by indenting each line with five spaces.
+
+ Write an `@example' command at the beginning of a line by itself.
+This line will disappear from the output. Mark the end of the example
+with an `@end example' command, also written at the beginning of a line
+by itself. The `@end example' will disappear from the output.
+
+ For example,
+
+ @example
+ mv foo bar
+ @end example
+
+produces
+
+ mv foo bar
+
+ Since the lines containing `@example' and `@end example' will
+disappear, you should put a blank line before the `@example' and
+another blank line after the `@end example'. (Remember that blank
+lines between the beginning `@example' and the ending `@end example'
+will appear in the output.)
+
+ *Caution:* Do not use tabs in the lines of an example (or anywhere
+ else in Texinfo, for that matter)! TeX treats tabs as single
+ spaces, and that is not what they look like. This is a problem
+ with TeX. (If necessary, in Emacs, you can use `M-x untabify' to
+ convert tabs in a region to multiple spaces.)
+
+ Examples are often, logically speaking, "in the middle" of a
+paragraph, and the text continues after an example should not be
+indented. The `@noindent' command prevents a piece of text from being
+indented as if it were a new paragraph. (*Note noindent::.)
+
+ (The `@code' command is used for examples of code that are embedded
+within sentences, not set off from preceding and following text. *Note
+`@code': code.)
+
+\1f
+File: texinfo.info, Node: noindent, Next: Lisp Example, Prev: example, Up: Quotations and Examples
+
+`@noindent'
+===========
+
+ An example or other inclusion can break a paragraph into segments.
+Ordinarily, the formatters indent text that follows an example as a new
+paragraph. However, you can prevent this by writing `@noindent' at the
+beginning of a line by itself preceding the continuation text.
+
+ For example:
+
+ @example
+ This is an example
+ @end example
+
+ @noindent
+ This line is not indented. As you can see, the
+ beginning of the line is fully flush left with the line
+ that follows after it. (This whole example is between
+ @code{@@display} and @code{@@end display}.)
+
+produces
+
+ This is an example
+
+
+ This line is not indented. As you can see, the
+ beginning of the line is fully flush left with the line
+ that follows after it. (This whole example is between
+ `@display' and `@end display'.)
+
+ To adjust the number of blank lines properly in the Info file output,
+remember that the line containing `@noindent' does not generate a blank
+line, and neither does the `@end example' line.
+
+ In the Texinfo source file for this manual, each line that says
+`produces' is preceded by a line containing `@noindent'.
+
+ Do not put braces after an `@noindent' command; they are not
+necessary, since `@noindent' is a command used outside of paragraphs
+(*note Command Syntax::.).
+
+\1f
+File: texinfo.info, Node: Lisp Example, Next: smallexample & smalllisp, Prev: noindent, Up: Quotations and Examples
+
+`@lisp'
+=======
+
+ The `@lisp' command is used for Lisp code. It is synonymous with the
+`@example' command.
+
+ This is an example of text written between an
+ `@lisp' command and an `@end lisp' command.
+
+ Use `@lisp' instead of `@example' to preserve information regarding
+the nature of the example. This is useful, for example, if you write a
+function that evaluates only and all the Lisp code in a Texinfo file.
+Then you can use the Texinfo file as a Lisp library.(1) (*note Lisp
+Example-Footnotes::)
+
+ Mark the end of `@lisp' with `@end lisp' on a line by itself.
+
+\1f
+File: texinfo.info, Node: Lisp Example-Footnotes, Up: Lisp Example
+
+ (1) It would be straightforward to extend Texinfo to work in a
+similar fashion for C, Fortran, or other languages.
+
+\1f
+File: texinfo.info, Node: smallexample & smalllisp, Next: display, Prev: Lisp Example, Up: Quotations and Examples
+
+`@smallexample' and `@smalllisp'
+================================
+
+ In addition to the regular `@example' and `@lisp' commands, Texinfo
+has two other "example-style" commands. These are the `@smallexample'
+and `@smalllisp' commands. Both these commands are designed for use
+with the `@smallbook' command that causes TeX to produce a printed
+manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11
+inch format.
+
+ In TeX, the `@smallexample' and `@smalllisp' commands typeset text in
+a smaller font for the smaller `@smallbook' format than for the 8.5 by
+11 inch format. Consequently, many examples containing long lines fit
+in a narrower, `@smallbook' page without needing to be shortened. Both
+commands typeset in the normal font size when you format for the 8.5 by
+11 inch size; indeed, in this situation, the `@smallexample' and
+`@smalllisp' commands are defined to be the `@example' and `@lisp'
+commands.
+
+ In Info, the `@smallexample' and `@smalllisp' commands are equivalent
+to the `@example' and `@lisp' commands, and work exactly the same.
+
+ Mark the end of `@smallexample' or `@smalllisp' with `@end
+smallexample' or `@end smalllisp', respectively.
+
+ This is an example of text written between `@smallexample' and
+ `@end smallexample'. In Info and in an 8.5 by 11 inch manual,
+ this text appears in its normal size; but in a 7 by 9.25 inch manual,
+ this text appears in a smaller font.
+
+ The `@smallexample' and `@smalllisp' commands make it easier to
+prepare smaller format manuals without forcing you to edit examples by
+hand to fit them onto narrower pages.
+
+ As a general rule, a printed document looks better if you write all
+the examples in a chapter consistently in `@example' or in
+`@smallexample'. Only occasionally should you mix the two formats.
+
+ *Note Printing "Small" Books: smallbook, for more information about
+the `@smallbook' command.
+
+\1f
+File: texinfo.info, Node: display, Next: format, Prev: smallexample & smalllisp, Up: Quotations and Examples
+
+`@display'
+==========
+
+ The `@display' command begins a kind of example. It is like the
+`@example' command except that, in a printed manual, `@display' does
+not select the fixed-width font. In fact, it does not specify the font
+at all, so that the text appears in the same font it would have
+appeared in without the `@display' command.
+
+ This is an example of text written between an `@display' command
+ and an `@end display' command. The `@display' command
+ indents the text, but does not fill it.
+
+\1f
+File: texinfo.info, Node: format, Next: exdent, Prev: display, Up: Quotations and Examples
+
+`@format'
+=========
+
+ The `@format' command is similar to `@example' except that, in the
+printed manual, `@format' does not select the fixed-width font and does
+not narrow the margins.
+
+This is an example of text written between an `@format' command
+and an `@end format' command. As you can see
+from this example,
+the `@format' command does not fill the text.
+
+\1f
+File: texinfo.info, Node: exdent, Next: flushleft & flushright, Prev: format, Up: Quotations and Examples
+
+`@exdent': Undoing a Line's Indentation
+=======================================
+
+ The `@exdent' command removes any indentation a line might have. The
+command is written at the beginning of a line and applies only to the
+text that follows the command that is on the same line. Do not use
+braces around the text. In a printed manual, the text on an `@exdent'
+line is printed in the roman font.
+
+ `@exdent' is usually used within examples. Thus,
+
+ @example
+ This line follows an @@example command.
+ @exdent This line is exdented.
+ This line follows the exdented line.
+ The @@end example comes on the next line.
+ @end group
+
+produces
+
+ This line follows an @example command.
+This line is exdented.
+ This line follows the exdented line.
+ The @end example comes on the next line.
+
+ In practice, the `@exdent' command is rarely used. Usually, you
+un-indent text by ending the example and returning the page to its
+normal width.
+
+\1f
+File: texinfo.info, Node: flushleft & flushright, Next: cartouche, Prev: exdent, Up: Quotations and Examples
+
+`@flushleft' and `@flushright'
+==============================
+
+ The `@flushleft' and `@flushright' commands line up the ends of lines
+on the left and right margins of a page, but do not fill the text. The
+commands are written on lines of their own, without braces. The
+`@flushleft' and `@flushright' commands are ended by `@end flushleft'
+and `@end flushright' commands on lines of their own.
+
+ For example,
+
+ @flushleft
+ This text is
+ written flushleft.
+ @end flushleft
+
+produces
+
+ This text is
+ written flushleft.
+
+ `@flushright' produces the type of indentation often used in the
+return address of letters. For example,
+
+ @flushright
+ Here is an example of text written
+ flushright. The @code{@flushright} command
+ right justifies every line but leaves the
+ left end ragged.
+ @end flushright
+
+produces
+
+ Here is an example of text written
+ flushright. The `@flushright' command
+ right justifies every line but leaves the
+ left end ragged.
+
+\1f
+File: texinfo.info, Node: cartouche, Prev: flushleft & flushright, Up: Quotations and Examples
+
+Drawing Cartouches Around Examples
+==================================
+
+ In a printed manual, the `@cartouche' command draws a box with
+rounded corners around its contents. You can use this command to
+further highlight an example or quotation. For instance, you could
+write a manual in which one type of example is surrounded by a cartouche
+for emphasis.
+
+ The `@cartouche' command affects only the printed manual; it has no
+effect in the Info file.
+
+ For example,
+
+ @example
+ @cartouche
+ % pwd
+ /usr/local/share/emacs
+ @end cartouche
+ @end example
+
+surrounds the two-line example with a box with rounded corners, in the
+printed manual.
+
+\1f
+File: texinfo.info, Node: Lists and Tables, Next: Indices, Prev: Quotations and Examples, Up: Top
+
+Lists and Tables
+****************
+
+ Texinfo has several ways of making lists and tables. Lists can be
+bulleted or numbered; two-column tables can highlight the items in the
+first column; multi-column tables are also supported.
+
+* Menu:
+
+* Introducing Lists:: Texinfo formats lists for you.
+* itemize:: How to construct a simple list.
+* enumerate:: How to construct a numbered list.
+* Two-column Tables:: How to construct a two-column table.
+* Multi-column Tables:: How to construct generalized tables.
+
+\1f
+File: texinfo.info, Node: Introducing Lists, Next: itemize, Prev: Lists and Tables, Up: Lists and Tables
+
+Introducing Lists
+=================
+
+ Texinfo automatically indents the text in lists or tables, and numbers
+an enumerated list. This last feature is useful if you modify the
+list, since you do not need to renumber it yourself.
+
+ Numbered lists and tables begin with the appropriate @-command at the
+beginning of a line, and end with the corresponding `@end' command on a
+line by itself. The table and itemized-list commands also require that
+you write formatting information on the same line as the beginning
+@-command.
+
+ Begin an enumerated list, for example, with an `@enumerate' command
+and end the list with an `@end enumerate' command. Begin an itemized
+list with an `@itemize' command, followed on the same line by a
+formatting command such as `@bullet', and end the list with an `@end
+itemize' command.
+
+ Precede each element of a list with an `@item' or `@itemx' command.
+
+Here is an itemized list of the different kinds of table and lists:
+
+ * Itemized lists with and without bullets.
+
+ * Enumerated lists, using numbers or letters.
+
+ * Two-column tables with highlighting.
+
+Here is an enumerated list with the same items:
+
+ 1. Itemized lists with and without bullets.
+
+ 2. Enumerated lists, using numbers or letters.
+
+ 3. Two-column tables with highlighting.
+
+And here is a two-column table with the same items and their @-commands:
+
+`@itemize'
+ Itemized lists with and without bullets.
+
+`@enumerate'
+ Enumerated lists, using numbers or letters.
+
+`@table'
+`@ftable'
+`@vtable'
+ Two-column tables with indexing.
+
+\1f
+File: texinfo.info, Node: itemize, Next: enumerate, Prev: Introducing Lists, Up: Lists and Tables
+
+Making an Itemized List
+=======================
+
+ The `@itemize' command produces sequences of indented paragraphs,
+with a bullet or other mark inside the left margin at the beginning of
+each paragraph for which such a mark is desired.
+
+ Begin an itemized list by writing `@itemize' at the beginning of a
+line. Follow the command, on the same line, with a character or a
+Texinfo command that generates a mark. Usually, you will write
+`@bullet' after `@itemize', but you can use `@minus', or any character
+or any special symbol that results in a single character in the Info
+file. (When you write `@bullet' or `@minus' after an `@itemize'
+command, you may omit the `{}'.)
+
+ Write the text of the indented paragraphs themselves after the
+`@itemize', up to another line that says `@end itemize'.
+
+ Before each paragraph for which a mark in the margin is desired, write
+a line that says just `@item'. Do not write any other text on this
+line.
+
+ Usually, you should put a blank line before an `@item'. This puts a
+blank line in the Info file. (TeX inserts the proper interline
+whitespace in either case.) Except when the entries are very brief,
+these blank lines make the list look better.
+
+ Here is an example of the use of `@itemize', followed by the output
+it produces. Note that `@bullet' produces an `*' in Info and a round
+dot in TeX.
+
+ @itemize @bullet
+ @item
+ Some text for foo.
+
+ @item
+ Some text
+ for bar.
+ @end itemize
+
+This produces:
+
+ * Some text for foo.
+
+ * Some text for bar.
+
+ Itemized lists may be embedded within other itemized lists. Here is a
+list marked with dashes embedded in a list marked with bullets:
+
+ @itemize @bullet
+ @item
+ First item.
+
+ @itemize @minus
+ @item
+ Inner item.
+
+ @item
+ Second inner item.
+ @end itemize
+
+ @item
+ Second outer item.
+ @end itemize
+
+This produces:
+
+ * First item.
+
+ - Inner item.
+
+ - Second inner item.
+
+ * Second outer item.
+
+\1f
+File: texinfo.info, Node: enumerate, Next: Two-column Tables, Prev: itemize, Up: Lists and Tables
+
+Making a Numbered or Lettered List
+==================================
+
+ `@enumerate' is like `@itemize' (*note `@itemize': itemize.), except
+that the labels on the items are successive integers or letters instead
+of bullets.
+
+ Write the `@enumerate' command at the beginning of a line. The
+command does not require an argument, but accepts either a number or a
+letter as an option. Without an argument, `@enumerate' starts the list
+with the number `1'. With a numeric argument, such as `3', the command
+starts the list with that number. With an upper or lower case letter,
+such as `a' or `A', the command starts the list with that letter.
+
+ Write the text of the enumerated list in the same way you write an
+itemized list: put `@item' on a line of its own before the start of
+each paragraph that you want enumerated. Do not write any other text
+on the line beginning with `@item'.
+
+ You should put a blank line between entries in the list. This
+generally makes it easier to read the Info file.
+
+ Here is an example of `@enumerate' without an argument:
+
+ @enumerate
+ @item
+ Underlying causes.
+
+ @item
+ Proximate causes.
+ @end enumerate
+
+This produces:
+
+ 1. Underlying causes.
+
+ 2. Proximate causes.
+
+ Here is an example with an argument of `3':
+
+ @enumerate 3
+ @item
+ Predisposing causes.
+
+ @item
+ Precipitating causes.
+
+ @item
+ Perpetuating causes.
+ @end enumerate
+
+This produces:
+
+ 3. Predisposing causes.
+
+ 4. Precipitating causes.
+
+ 5. Perpetuating causes.
+
+ Here is a brief summary of the alternatives. The summary is
+constructed using `@enumerate' with an argument of `a'.
+
+ a. `@enumerate'
+
+ Without an argument, produce a numbered list, starting with the
+ number 1.
+
+ b. `@enumerate POSITIVE-INTEGER'
+
+ With a (positive) numeric argument, start a numbered list with that
+ number. You can use this to continue a list that you interrupted
+ with other text.
+
+ c. `@enumerate UPPER-CASE-LETTER'
+
+ With an upper case letter as argument, start a list in which each
+ item is marked by a letter, beginning with that upper case letter.
+
+ d. `@enumerate LOWER-CASE-LETTER'
+
+ With a lower case letter as argument, start a list in which each
+ item is marked by a letter, beginning with that lower case letter.
+
+ You can also nest enumerated lists, as in an outline.
+
+\1f
+File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: enumerate, Up: Lists and Tables
+
+Making a Two-column Table
+=========================
+
+ `@table' is similar to `@itemize' (*note `@itemize': itemize.), but
+allows you to specify a name or heading line for each item. The
+`@table' command is used to produce two-column tables, and is
+especially useful for glossaries, explanatory exhibits, and
+command-line option summaries.
+
+* Menu:
+
+* table:: How to construct a two-column table.
+* ftable vtable:: Automatic indexing for two-column tables.
+* itemx:: How to put more entries in the first column.
+
+\1f
+File: texinfo.info, Node: table, Next: ftable vtable, Prev: Two-column Tables, Up: Two-column Tables
+
+Using the `@table' Command
+--------------------------
+
+ Use the `@table' command to produce two-column tables.
+
+ Write the `@table' command at the beginning of a line and follow it
+on the same line with an argument that is a Texinfo "indicating"
+command such as `@code', `@samp', `@var', or `@kbd' (*note
+Indicating::.). Although these commands are usually followed by
+arguments in braces, in this case you use the command name without an
+argument because `@item' will supply the argument. This command will
+be applied to the text that goes into the first column of each item and
+determines how it will be highlighted. For example, `@code' will cause
+the text in the first column to be highlighted with an `@code' command.
+(We recommend `@code' for `@table''s of command-line options.)
+
+ You may also choose to use the `@asis' command as an argument to
+`@table'. `@asis' is a command that does nothing; if you use this
+command after `@table', TeX and the Info formatting commands output the
+first column entries without added highlighting ("as is").
+
+ (The `@table' command may work with other commands besides those
+listed here. However, you can only use commands that normally take
+arguments in braces.)
+
+ Begin each table entry with an `@item' command at the beginning of a
+line. Write the first column text on the same line as the `@item'
+command. Write the second column text on the line following the
+`@item' line and on subsequent lines. (You do not need to type
+anything for an empty second column entry.) You may write as many
+lines of supporting text as you wish, even several paragraphs. But
+only text on the same line as the `@item' will be placed in the first
+column.
+
+ Normally, you should put a blank line before an `@item' line. This
+puts a blank like in the Info file. Except when the entries are very
+brief, a blank line looks better.
+
+ The following table, for example, highlights the text in the first
+column with an `@samp' command:
+
+ @table @samp
+ @item foo
+ This is the text for
+ @samp{foo}.
+
+ @item bar
+ Text for @samp{bar}.
+ @end table
+
+This produces:
+
+`foo'
+ This is the text for `foo'.
+
+`bar'
+ Text for `bar'.
+
+ If you want to list two or more named items with a single block of
+text, use the `@itemx' command. (*Note `@itemx': itemx.)
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables
+
+`@ftable' and `@vtable'
+-----------------------
+
+ The `@ftable' and `@vtable' commands are the same as the `@table'
+command except that `@ftable' automatically enters each of the items in
+the first column of the table into the index of functions and `@vtable'
+automatically enters each of the items in the first column of the table
+into the index of variables. This simplifies the task of creating
+indices. Only the items on the same line as the `@item' commands are
+indexed, and they are indexed in exactly the form that they appear on
+that line. *Note Creating Indices: Indices, for more information about
+indices.
+
+ Begin a two-column table using `@ftable' or `@vtable' by writing the
+@-command at the beginning of a line, followed on the same line by an
+argument that is a Texinfo command such as `@code', exactly as you
+would for an `@table' command; and end the table with an `@end ftable'
+or `@end vtable' command on a line by itself.
+
+ See the example for `@table' in the previous section.
+
+\1f
+File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables
+
+`@itemx'
+--------
+
+ Use the `@itemx' command inside a table when you have two or more
+first column entries for the same item, each of which should appear on a
+line of its own. Use `@itemx' for all but the first entry; `@itemx'
+should always follow an `@item' command. The `@itemx' command works
+exactly like `@item' except that it does not generate extra vertical
+space above the first column text.
+
+ For example,
+
+ @table @code
+ @item upcase
+ @itemx downcase
+ These two functions accept a character or a string as
+ argument, and return the corresponding upper case (lower
+ case) character or string.
+ @end table
+
+This produces:
+
+`upcase'
+`downcase'
+ These two functions accept a character or a string as argument,
+ and return the corresponding upper case (lower case) character or
+ string.
+
+(Note also that this example illustrates multi-line supporting text in
+a two-column table.)
+
+\1f
+File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables
+
+Multi-column Tables
+===================
+
+ `@multitable' allows you to construct tables with any number of
+columns, with each column having any width you like.
+
+ You define the column widths on the `@multitable' line itself, and
+write each row of the actual table following an `@item' command, with
+columns separated by an `@tab' command. Finally, `@end multitable'
+completes the table. Details in the sections below.
+
+* Menu:
+
+* Multitable Column Widths:: Defining multitable column widths.
+* Multitable Rows:: Defining multitable rows, with examples.
+
+\1f
+File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Prev: Multi-column Tables, Up: Multi-column Tables
+
+Multitable Column Widths
+------------------------
+
+ You can define the column widths for a multitable in two ways: as
+fractions of the line length; or with a prototype row. Mixing the two
+methods is not supported. In either case, the widths are defined
+entirely on the same line as the `@multitable' command.
+
+ 1. To specify column widths as fractions of the line length, write
+ `@columnfractions' and the decimal numbers (presumably less than
+ 1) after the `@multitable' command, as in:
+
+ @multitable @columnfractions .33 .33 .33
+
+ The fractions need not add up exactly to 1.0, as these do not.
+ This allows you to produce tables that do not need the full line
+ length.
+
+ 2. To specify a prototype row, write the longest entry for each column
+ enclosed in braces after the `@multitable' command. For example:
+
+ @multitable {some text for column one} {for column two}
+
+ The first column will then have the width of the typeset `some
+ text for column one', and the second column the width of `for
+ column two'.
+
+ The prototype entries need not appear in the table itself.
+
+ Although we used simple text in this example, the prototype
+ entries can contain Texinfo commands; markup commands such as
+ `@code' are particularly likely to be useful.
+
+
+\1f
+File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables
+
+Multitable Rows
+---------------
+
+ After the `@multitable' command defining the column widths (see the
+previous section), you begin each row in the body of a multitable with
+`@item', and separate the column entries with `@tab'. Line breaks are
+not special within the table body, and you may break input lines in
+your source file as necessary.
+
+ Here is a complete example of a multi-column table (the text is from
+`The GNU Emacs Manual', *note Splitting Windows: (xemacs)Split Window.):
+
+ @multitable @columnfractions .15 .45 .4
+ @item Key @tab Command @tab Description
+ @item C-x 2
+ @tab @code{split-window-vertically}
+ @tab Split the selected window into two windows,
+ with one above the other.
+ @item C-x 3
+ @tab @code{split-window-horizontally}
+ @tab Split the selected window into two windows
+ positioned side by side.
+ @item C-Mouse-2
+ @tab
+ @tab In the mode line or scroll bar of a window,
+ split that window.
+ @end multitable
+
+produces:
+
+Key Command Description
+C-x 2 `split-window-vertically' Split the selected window
+ into two windows, with one
+ above the other.
+C-x 3 `split-window-horizontally' Split the selected window
+ into two windows positioned
+ side by side.
+C-Mouse-2 In the mode line or scroll
+ bar of a window, split that
+ window.
+
+\1f
+File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top
+
+Creating Indices
+****************
+
+ Using Texinfo, you can generate indices without having to sort and
+collate entries manually. In an index, the entries are listed in
+alphabetical order, together with information on how to find the
+discussion of each entry. In a printed manual, this information
+consists of page numbers. In an Info file, this information is a menu
+entry leading to the first node referenced.
+
+ Texinfo provides several predefined kinds of index: an index for
+functions, an index for variables, an index for concepts, and so on.
+You can combine indices or use them for other than their canonical
+purpose. If you wish, you can define your own indices.
+
+* Menu:
+
+* Index Entries:: Choose different words for index entries.
+* Predefined Indices:: Use different indices for different kinds
+ of entry.
+* Indexing Commands:: How to make an index entry.
+* Combining Indices:: How to combine indices.
+* New Indices:: How to define your own indices.
+
+\1f
+File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices
+
+Making Index Entries
+====================
+
+ When you are making index entries, it is good practice to think of the
+different ways people may look for something. Different people *do
+not* think of the same words when they look something up. A helpful
+index will have items indexed under all the different words that people
+may use. For example, one reader may think it obvious that the
+two-letter names for indices should be listed under "Indices,
+two-letter names", since the word "Index" is the general concept. But
+another reader may remember the specific concept of two-letter names
+and search for the entry listed as "Two letter names for indices". A
+good index will have both entries and will help both readers.
+
+ Like typesetting, the construction of an index is a highly skilled,
+professional art, the subtleties of which are not appreciated until you
+need to do it yourself.
+
+ *Note Printing Indices & Menus::, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+\1f
+File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices
+
+Predefined Indices
+==================
+
+ Texinfo provides six predefined indices:
+
+ * A "concept index" listing concepts that are discussed.
+
+ * A "function index" listing functions (such as entry points of
+ libraries).
+
+ * A "variables index" listing variables (such as global variables of
+ libraries).
+
+ * A "keystroke index" listing keyboard commands.
+
+ * A "program index" listing names of programs.
+
+ * A "data type index" listing data types (such as structures defined
+ in header files).
+
+Not every manual needs all of these, and most manuals use two or three
+of them. This manual has two indices: a concept index and an @-command
+index (that is actually the function index but is called a command
+index in the chapter heading). Two or more indices can be combined
+into one using the `@synindex' or `@syncodeindex' commands. *Note
+Combining Indices::.
+
+\1f
+File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices
+
+Defining the Entries of an Index
+================================
+
+ The data to make an index come from many individual indexing commands
+scattered throughout the Texinfo source file. Each command says to add
+one entry to a particular index; after formatting, the index will give
+the current page number or node name as the reference.
+
+ An index entry consists of an indexing command at the beginning of a
+line followed, on the rest of the line, by the entry.
+
+ For example, this section begins with the following five entries for
+the concept index:
+
+ @cindex Defining indexing entries
+ @cindex Index entries
+ @cindex Entries for an index
+ @cindex Specifying index entries
+ @cindex Creating index entries
+
+ Each predefined index has its own indexing command--`@cindex' for the
+concept index, `@findex' for the function index, and so on.
+
+ Concept index entries consist of text. The best way to write an index
+is to choose entries that are terse yet clear. If you can do this, the
+index often looks better if the entries are not capitalized, but
+written just as they would appear in the middle of a sentence.
+(Capitalize proper names and acronyms that always call for upper case
+letters.) This is the case convention we use in most GNU manuals'
+indices.
+
+ If you don't see how to make an entry terse yet clear, make it longer
+and clear--not terse and confusing. If many of the entries are several
+words long, the index may look better if you use a different convention:
+to capitalize the first word of each entry. But do not capitalize a
+case-sensitive name such as a C or Lisp function name or a shell
+command; that would be a spelling error.
+
+ Whichever case convention you use, please use it consistently!
+
+ Entries in indices other than the concept index are symbol names in
+programming languages, or program names; these names are usually
+case-sensitive, so use upper and lower case as required for them.
+
+ By default, entries for a concept index are printed in a small roman
+font and entries for the other indices are printed in a small `@code'
+font. You may change the way part of an entry is printed with the
+usual Texinfo commands, such as `@file' for file names and `@emph' for
+emphasis (*note Marking Text::.).
+
+ The six indexing commands for predefined indices are:
+
+`@cindex CONCEPT'
+ Make an entry in the concept index for CONCEPT.
+
+`@findex FUNCTION'
+ Make an entry in the function index for FUNCTION.
+
+`@vindex VARIABLE'
+ Make an entry in the variable index for VARIABLE.
+
+`@kindex KEYSTROKE'
+ Make an entry in the key index for KEYSTROKE.
+
+`@pindex PROGRAM'
+ Make an entry in the program index for PROGRAM.
+
+`@tindex DATA TYPE'
+ Make an entry in the data type index for DATA TYPE.
+
+ *Caution:* Do not use a colon in an index entry. In Info, a colon
+ separates the menu entry name from the node name. An extra colon
+ confuses Info. *Note The Parts of a Menu: Menu Parts, for more
+ information about the structure of a menu entry.
+
+ If you write several identical index entries in different places in a
+Texinfo file, the index in the printed manual will list all the pages to
+which those entries refer. However, the index in the Info file will
+list *only* the node that references the *first* of those index
+entries. Therefore, it is best to write indices in which each entry
+refers to only one place in the Texinfo file. Fortunately, this
+constraint is a feature rather than a loss since it means that the index
+will be easy to use. Otherwise, you could create an index that lists
+several pages for one entry and your reader would not know to which page
+to turn. If you have two identical entries for one topic, change the
+topics slightly, or qualify them to indicate the difference.
+
+ You are not actually required to use the predefined indices for their
+canonical purposes. For example, suppose you wish to index some C
+preprocessor macros. You could put them in the function index along
+with actual functions, just by writing `@findex' commands for them;
+then, when you print the "Function Index" as an unnumbered chapter, you
+could give it the title `Function and Macro Index' and all will be
+consistent for the reader. Or you could put the macros in with the
+data types by writing `@tindex' commands for them, and give that index
+a suitable title so the reader will understand. (*Note Printing
+Indices & Menus::.)
+
+\1f
+File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices
+
+Combining Indices
+=================
+
+ Sometimes you will want to combine two disparate indices such as
+functions and concepts, perhaps because you have few enough of one of
+them that a separate index for them would look silly.
+
+ You could put functions into the concept index by writing `@cindex'
+commands for them instead of `@findex' commands, and produce a
+consistent manual by printing the concept index with the title
+`Function and Concept Index' and not printing the `Function Index' at
+all; but this is not a robust procedure. It works only if your
+document is never included as part of another document that is designed
+to have a separate function index; if your document were to be included
+with such a document, the functions from your document and those from
+the other would not end up together. Also, to make your function names
+appear in the right font in the concept index, you would need to
+enclose every one of them between the braces of `@code'.
+
+* Menu:
+
+* syncodeindex:: How to merge two indices, using `@code'
+ font for the merged-from index.
+* synindex:: How to merge two indices, using the
+ default font of the merged-to index.
+
+\1f
+File: texinfo.info, Node: syncodeindex, Next: synindex, Prev: Combining Indices, Up: Combining Indices
+
+`@syncodeindex'
+---------------
+
+ When you want to combine functions and concepts into one index, you
+should index the functions with `@findex' and index the concepts with
+`@cindex', and use the `@syncodeindex' command to redirect the function
+index entries into the concept index.
+
+ The `@syncodeindex' command takes two arguments; they are the name of
+the index to redirect, and the name of the index to redirect it to.
+The template looks like this:
+
+ @syncodeindex FROM TO
+
+ For this purpose, the indices are given two-letter names:
+
+`cp'
+ concept index
+
+`fn'
+ function index
+
+`vr'
+ variable index
+
+`ky'
+ key index
+
+`pg'
+ program index
+
+`tp'
+ data type index
+
+ Write an `@syncodeindex' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. For example, to
+merge a function index with a concept index, write the following:
+
+ @syncodeindex fn cp
+
+This will cause all entries designated for the function index to merge
+in with the concept index instead.
+
+ To merge both a variables index and a function index into a concept
+index, write the following:
+
+ @syncodeindex vr cp
+ @syncodeindex fn cp
+
+ The `@syncodeindex' command puts all the entries from the `from'
+index (the redirected index) into the `@code' font, overriding whatever
+default font is used by the index to which the entries are now
+directed. This way, if you direct function names from a function index
+into a concept index, all the function names are printed in the `@code'
+font as you would expect.
+
+\1f
+File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices
+
+`@synindex'
+-----------
+
+ The `@synindex' command is nearly the same as the `@syncodeindex'
+command, except that it does not put the `from' index entries into the
+`@code' font; rather it puts them in the roman font. Thus, you use
+`@synindex' when you merge a concept index into a function index.
+
+ *Note Printing Indices & Menus::, for information about printing an
+index at the end of a book or creating an index menu in an Info file.
+
+\1f
+File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices
+
+Defining New Indices
+====================
+
+ In addition to the predefined indices, you may use the `@defindex'
+and `@defcodeindex' commands to define new indices. These commands
+create new indexing @-commands with which you mark index entries. The
+`@defindex 'command is used like this:
+
+ @defindex NAME
+
+ The name of an index should be a two letter word, such as `au'. For
+example:
+
+ @defindex au
+
+ This defines a new index, called the `au' index. At the same time,
+it creates a new indexing command, `@auindex', that you can use to make
+index entries. Use the new indexing command just as you would use a
+predefined indexing command.
+
+ For example, here is a section heading followed by a concept index
+entry and two `au' index entries.
+
+ @section Cognitive Semantics
+ @cindex kinesthetic image schemas
+ @auindex Johnson, Mark
+ @auindex Lakoff, George
+
+(Evidently, `au' serves here as an abbreviation for "author".) Texinfo
+constructs the new indexing command by concatenating the name of the
+index with `index'; thus, defining an `au' index leads to the automatic
+creation of an `@auindex' command.
+
+ Use the `@printindex' command to print the index, as you do with the
+predefined indices. For example:
+
+ @node Author Index, Subject Index, , Top
+ @unnumbered Author Index
+
+ @printindex au
+
+ The `@defcodeindex' is like the `@defindex' command, except that, in
+the printed output, it prints entries in an `@code' font instead of a
+roman font. Thus, it parallels the `@findex' command rather than the
+`@cindex' command.
+
+ You should define new indices within or right after the end-of-header
+line of a Texinfo file, before any `@synindex' or `@syncodeindex'
+commands (*note Header::.).
+
+\1f
+File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
+
+Special Insertions
+******************
+
+ Texinfo provides several commands for inserting characters that have
+special meaning in Texinfo, such as braces, and for other graphic
+elements that do not correspond to simple characters you can type.
+
+* Menu:
+
+* Braces Atsigns:: How to insert braces, `@'.
+* Inserting Space:: How to insert the right amount of space
+ within a sentence.
+* Inserting Accents:: How to insert accents and special characters.
+* Dots Bullets:: How to insert dots and bullets.
+* TeX and copyright:: How to insert the TeX logo
+ and the copyright symbol.
+* pounds:: How to insert the pounds currency symbol.
+* minus:: How to insert a minus sign.
+* math:: How to format a mathematical expression.
+* Glyphs:: How to indicate results of evaluation,
+ expansion of macros, errors, etc.
+* Images:: How to include graphics.
+
+\1f
+File: texinfo.info, Node: Braces Atsigns, Next: Inserting Space, Prev: Insertions, Up: Insertions
+
+Inserting @ and Braces
+======================
+
+ `@' and curly braces are special characters in Texinfo. To insert
+these characters so they appear in text, you must put an `@' in front
+of these characters to prevent Texinfo from misinterpreting them.
+
+ Do not put braces after any of these commands; they are not necessary.
+
+* Menu:
+
+* Inserting An Atsign:: How to insert `@'.
+* Inserting Braces:: How to insert `{' and `}'.
+
+\1f
+File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns, Up: Braces Atsigns
+
+Inserting `@' with @@
+---------------------
+
+ `@@' stands for a single `@' in either printed or Info output.
+
+ Do not put braces after an `@@' command.
+
+\1f
+File: texinfo.info, Node: Inserting Braces, Prev: Inserting An Atsign, Up: Braces Atsigns
+
+Inserting `{' and `}'with @{ and @}
+-----------------------------------
+
+ `@{' stands for a single `{' in either printed or Info output.
+
+ `@}' stands for a single `}' in either printed or Info output.
+
+ Do not put braces after either an `@{' or an `@}' command.
+
+\1f
+File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Braces Atsigns, Up: Insertions
+
+Inserting Space
+===============
+
+ The following sections describe commands that control spacing of
+various kinds within and after sentences.
+
+* Menu:
+
+* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
+* Ending a Sentence:: Sometimes it does.
+* Multiple Spaces:: Inserting multiple spaces.
+* dmn:: How to format a dimension.
+
+\1f
+File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space
+
+Not Ending a Sentence
+---------------------
+
+ Depending on whether a period or exclamation point or question mark is
+inside or at the end of a sentence, less or more space is inserted after
+a period in a typeset manual. Since it is not always possible for
+Texinfo to determine when a period ends a sentence and when it is used
+in an abbreviation, special commands are needed in some circumstances.
+(Usually, Texinfo can guess how to handle periods, so you do not need to
+use the special commands; you just enter a period as you would if you
+were using a typewriter, which means you put two spaces after the
+period, question mark, or exclamation mark that ends a sentence.)
+
+ Use the `@:' command after a period, question mark, exclamation mark,
+or colon that should not be followed by extra space. For example, use
+`@:' after periods that end abbreviations which are not at the ends of
+sentences.
+
+ For example,
+
+ The s.o.p.@: has three parts ...
+ The s.o.p. has three parts ...
+
+produces
+
+ The s.o.p. has three parts ...
+ The s.o.p. has three parts ...
+
+(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
+Procedure".)
+
+ `@:' has no effect on the Info output. Do not put braces after `@:'.
+
+\1f
+File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space
+
+Ending a Sentence
+-----------------
+
+ Use `@.' instead of a period, `@!' instead of an exclamation point,
+and `@?' instead of a question mark at the end of a sentence that ends
+with a single capital letter. Otherwise, TeX will think the letter is
+an abbreviation and will not insert the correct end-of-sentence
+spacing. Here is an example:
+
+ Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.
+ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
+
+produces
+
+ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
+ Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
+
+ In the Info file output, `@.' is equivalent to a simple `.'; likewise
+for `@!' and `@?'.
+
+ The meanings of `@:' and `@.' in Texinfo are designed to work well
+with the Emacs sentence motion commands (*note Sentences:
+(xemacs)Sentences.). This made it necessary for them to be
+incompatible with some other formatting systems that use @-commands.
+
+ Do not put braces after any of these commands.
+
+\1f
+File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space
+
+Multiple Spaces
+---------------
+
+ Ordinarily, TeX collapses multiple whitespace characters (space, tab,
+and newline) into a single space. Info output, on the other hand,
+preserves whitespace as you type it, except for changing a newline into
+a space; this is why it is important to put two spaces at the end of
+sentences in Texinfo documents.
+
+ Occasionally, you may want to actually insert several consecutive
+spaces, either for purposes of example (what your program does with
+multiple spaces as input), or merely for purposes of appearance in
+headings or lists. Texinfo supports three commands: `@SPACE', `@TAB',
+and `@NL', all of which insert a single space into the output. (Here,
+`@SPACE' represents an `@' character followed by a space, i.e., `@ ',
+and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
+when `@' is the last character on a line.)
+
+ For example,
+ Spacey@ @ @ @
+ example.
+
+produces
+
+ Spacey example.
+
+ Other possible uses of `@SPACE' have been subsumed by `@multitable'
+(*note Multi-column Tables::.).
+
+ Do not follow any of these commands with braces.
+
+\1f
+File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space
+
+`@dmn'{DIMENSION}: Format a Dimension
+-------------------------------------
+
+ At times, you may want to write `12pt' or `8.5in' with little or no
+space between the number and the abbreviation for the dimension. You
+can use the `@dmn' command to do this. On seeing the command, TeX
+inserts just enough space for proper typesetting; the Info formatting
+commands insert no space at all, since the Info file does not require
+it.
+
+ To use the `@dmn' command, write the number and then follow it
+immediately, with no intervening space, by `@dmn', and then by the
+dimension within braces. For example,
+
+ A4 paper is 8.27@dmn{in} wide.
+
+produces
+
+ A4 paper is 8.27in wide.
+
+ Not everyone uses this style. Some people prefer `8.27 in.@:' or
+`8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
+however, the formatters may insert a line break between the number and
+the dimension, so use `@w' (*note w::.). Also, if you write a period
+after an abbreviation within a sentence, you should write `@:' after
+the period to prevent TeX from inserting extra whitespace, as shown
+here. *Note Inserting Space::.
+
+\1f
+File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
+
+Inserting Accents
+=================
+
+ Here is a table with the commands Texinfo provides for inserting
+floating accents. The commands with non-alphabetic names do not take
+braces around their argument (which is taken to be the next character).
+(Exception: `@,' *does* take braces around its argument.) This is so
+as to make the source as convenient to type and read as possible, since
+accented characters are very common in some languages.
+
+Command Output What
+@"o "o umlaut accent
+@'o 'o acute accent
+@,{c} c, cedilla accent
+@=o =o macron/overbar accent
+@^o ^o circumflex accent
+@`o `o grave accent
+@~o ~o tilde accent
+@dotaccent{o} .o overdot accent
+@H{o} ''o long Hungarian umlaut
+@ringaccent{o} *o ring accent
+@tieaccent{oo} [oo tie-after accent
+@u{o} (o breve accent
+@ubaraccent{o} o_ underbar accent
+@udotaccent{o} o-. underdot accent
+@v{o} <o hacek or check accent
+
+ This table lists the Texinfo commands for inserting other characters
+commonly used in languages other than English.
+
+@exclamdown{} ! upside-down !
+@questiondown{} ? upside-down ?
+@aa{},@AA{} aa,AA A,a with circle
+@ae{},@AE{} ae,AE ae,AE ligatures
+@dotless{i} i dotless i
+@dotless{j} j dotless j
+@l{},@L{} l/,L/ suppressed-L,l
+@o{},@O{} o/,O/ O,o with slash
+@oe{},@OE{} oe,OE OE,oe ligatures
+@ss{} ss es-zet or sharp S
+
+\1f
+File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
+
+Inserting Ellipsis, Dots, and Bullets
+=====================================
+
+ An "ellipsis" (a line of dots) is not typeset as a string of periods,
+so a special command is used for ellipsis in Texinfo. The `@bullet'
+command is special, too. Each of these commands is followed by a pair
+of braces, `{}', without any whitespace between the name of the command
+and the braces. (You need to use braces with these commands because
+you can use them next to other text; without the braces, the formatters
+would be confused. *Note @-Command Syntax: Command Syntax, for further
+information.)
+
+* Menu:
+
+* dots:: How to insert dots ...
+* bullet:: How to insert a bullet.
+
+\1f
+File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets
+
+`@dots'{} (...)
+---------------
+
+ Use the `@dots{}' command to generate an ellipsis, which is three
+dots in a row, appropriately spaced, like this: `...'. Do not simply
+write three periods in the input file; that would work for the Info
+file output, but would produce the wrong amount of space between the
+periods in the printed manual.
+
+ Similarly, the `@enddots{}' command generates an end-of-sentence
+ellipsis (four dots) ....
+
+\1f
+File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets
+
+`@bullet'{} (*)
+---------------
+
+ Use the `@bullet{}' command to generate a large round dot, or the
+closest possible thing to one. In Info, an asterisk is used.
+
+ Here is a bullet: *
+
+ When you use `@bullet' in `@itemize', you do not need to type the
+braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)
+
+\1f
+File: texinfo.info, Node: TeX and copyright, Next: pounds, Prev: Dots Bullets, Up: Insertions
+
+Inserting TeX and the Copyright Symbol
+======================================
+
+ The logo `TeX' is typeset in a special fashion and it needs an
+@-command. The copyright symbol, `(C)', is also special. Each of
+these commands is followed by a pair of braces, `{}', without any
+whitespace between the name of the command and the braces.
+
+* Menu:
+
+* tex:: How to insert the TeX logo.
+* copyright symbol:: How to use `@copyright'{}.
+
+\1f
+File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright
+
+`@TeX'{} (TeX)
+--------------
+
+ Use the `@TeX{}' command to generate `TeX'. In a printed manual,
+this is a special logo that is different from three ordinary letters.
+In Info, it just looks like `TeX'. The `@TeX{}' command is unique
+among Texinfo commands in that the `T' and the `X' are in upper case.
+
+\1f
+File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright
+
+`@copyright'{} ((C))
+--------------------
+
+ Use the `@copyright{}' command to generate `(C)'. In a printed
+manual, this is a `c' inside a circle, and in Info, this is `(C)'.
+
+\1f
+File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions
+
+`@pounds{}' (#): Pounds Sterling
+================================
+
+ Use the `@pounds{}' command to generate `#'. In a printed manual,
+this is the symbol for the currency pounds sterling. In Info, it is a
+`#'. Other currency symbols are unfortunately not available.
+
+\1f
+File: texinfo.info, Node: minus, Next: math, Prev: pounds, Up: Insertions
+
+`@minus'{} (-): Inserting a Minus Sign
+======================================
+
+ Use the `@minus{}' command to generate a minus sign. In a
+fixed-width font, this is a single hyphen, but in a proportional font,
+the symbol is the customary length for a minus sign--a little longer
+than a hyphen, shorter than an em-dash:
+
+ `-' is a minus sign generated with `@minus{}',
+
+ `-' is a hyphen generated with the character `-',
+
+ `---' is an em-dash for text.
+
+In the fixed-width font used by Info, `@minus{}' is the same as a
+hyphen.
+
+ You should not use `@minus{}' inside `@code' or `@example' because
+the width distinction is not made in the fixed-width font they use.
+
+ When you use `@minus' to specify the mark beginning each entry in an
+itemized list, you do not need to type the braces (*note `@itemize':
+itemize..)
+
+\1f
+File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
+
+`@math' - Inserting Mathematical Expressions
+============================================
+
+ You can write a short mathematical expression with the `@math'
+command. Write the mathematical expression between braces, like this:
+
+ @math{(a + b)(a + b) = a^2 + 2ab + b^2}
+
+This produces the following in Info:
+
+ (a + b)(a + b) = a^2 + 2ab + b^2
+
+ Thus, the `@math' command has no effect on the Info output.
+
+ For complex mathematical expressions, you can also use TeX directly
+(*note Raw Formatter Commands::.). When you use TeX directly, remember
+to write the mathematical expression between one or two `$'
+(dollar-signs) as appropriate.
+
+\1f
+File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions
+
+Glyphs for Examples
+===================
+
+ In Texinfo, code is often illustrated in examples that are delimited
+by `@example' and `@end example', or by `@lisp' and `@end lisp'. In
+such examples, you can indicate the results of evaluation or an
+expansion using `=>' or `==>'. Likewise, there are commands to insert
+glyphs to indicate printed output, error messages, equivalence of
+expressions, and the location of point.
+
+ The glyph-insertion commands do not need to be used within an
+example, but most often they are. Every glyph-insertion command is
+followed by a pair of left- and right-hand braces.
+
+* Menu:
+
+* Glyphs Summary::
+* result:: How to show the result of expression.
+* expansion:: How to indicate an expansion.
+* Print Glyph:: How to indicate printed output.
+* Error Glyph:: How to indicate an error message.
+* Equivalence:: How to indicate equivalence.
+* Point Glyph:: How to indicate the location of point.
+
+\1f
+File: texinfo.info, Node: Glyphs Summary, Next: result, Prev: Glyphs, Up: Glyphs
+
+Glyphs Summary
+--------------
+
+ Here are the different glyph commands:
+
+=>
+ `@result{}' points to the result of an expression.
+
+==>
+ `@expansion{}' shows the results of a macro expansion.
+
+-|
+ `@print{}' indicates printed output.
+
+error-->
+ `@error{}' indicates that the following text is an error message.
+
+==
+ `@equiv{}' indicates the exact equivalence of two forms.
+
+-!-
+ `@point{}' shows the location of point.
+
+* Menu:
+
+* result::
+* expansion::
+* Print Glyph::
+* Error Glyph::
+* Equivalence::
+* Point Glyph::
+
+\1f
+File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs
+
+`@result{}' (=>): Indicating Evaluation
+---------------------------------------
+
+ Use the `@result{}' command to indicate the result of evaluating an
+expression.
+
+ The `@result{}' command is displayed as `=>' in Info and as a double
+stemmed arrow in the printed output.
+
+ Thus, the following,
+
+ (cdr '(1 2 3))
+ => (2 3)
+
+may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
+
+\1f
+File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs
+
+`@expansion{}' (==>): Indicating an Expansion
+---------------------------------------------
+
+ When an expression is a macro call, it expands into a new expression.
+You can indicate the result of the expansion with the `@expansion{}'
+command.
+
+ The `@expansion{}' command is displayed as `==>' in Info and as a
+long arrow with a flat base in the printed output.
+
+ For example, the following
+
+ @lisp
+ (third '(a b c))
+ @expansion{} (car (cdr (cdr '(a b c))))
+ @result{} c
+ @end lisp
+
+produces
+
+ (third '(a b c))
+ ==> (car (cdr (cdr '(a b c))))
+ => c
+
+which may be read as:
+
+ `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
+ result of evaluating the expression is `c'.
+
+Often, as in this case, an example looks better if the `@expansion{}'
+and `@result{}' commands are indented five spaces.
+
+\1f
+File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs
+
+`@print{}' (-|): Indicating Printed Output
+------------------------------------------
+
+ Sometimes an expression will print output during its execution. You
+can indicate the printed output with the `@print{}' command.
+
+ The `@print{}' command is displayed as `-|' in Info and similarly, as
+a horizontal dash butting against a vertical bar, in the printed output.
+
+ In the following example, the printed text is indicated with `-|',
+and the value of the expression follows on the last line.
+
+ (progn (print 'foo) (print 'bar))
+ -| foo
+ -| bar
+ => bar
+
+In a Texinfo source file, this example is written as follows:
+
+ @lisp
+ (progn (print 'foo) (print 'bar))
+ @print{} foo
+ @print{} bar
+ @result{} bar
+ @end lisp
+
+\1f
+File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs
+
+`@error{}' (error-->): Indicating an Error Message
+--------------------------------------------------
+
+ A piece of code may cause an error when you evaluate it. You can
+designate the error message with the `@error{}' command.
+
+ The `@error{}' command is displayed as `error-->' in Info and as the
+word `error' in a box in the printed output.
+
+ Thus,
+
+ @lisp
+ (+ 23 'x)
+ @error{} Wrong type argument: integer-or-marker-p, x
+ @end lisp
+
+produces
+
+ (+ 23 'x)
+ error--> Wrong type argument: integer-or-marker-p, x
+
+This indicates that the following error message is printed when you
+evaluate the expression:
+
+ Wrong type argument: integer-or-marker-p, x
+
+ `error-->' itself is not part of the error message.
+
+\1f
+File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs
+
+`@equiv{}' (==): Indicating Equivalence
+---------------------------------------
+
+ Sometimes two expressions produce identical results. You can
+indicate the exact equivalence of two forms with the `@equiv{}' command.
+
+ The `@equiv{}' command is displayed as `==' in Info and as a three
+parallel horizontal lines in the printed output.
+
+ Thus,
+
+ @lisp
+ (make-sparse-keymap) @equiv{} (list 'keymap)
+ @end lisp
+
+produces
+
+ (make-sparse-keymap) == (list 'keymap)
+
+This indicates that evaluating `(make-sparse-keymap)' produces
+identical results to evaluating `(list 'keymap)'.
+
+\1f
+File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
+
+`@point{}' (-!-): Indicating Point in a Buffer
+----------------------------------------------
+
+ Sometimes you need to show an example of text in an Emacs buffer. In
+such examples, the convention is to include the entire contents of the
+buffer in question between two lines of dashes containing the buffer
+name.
+
+ You can use the `@point{}' command to show the location of point in
+the text in the buffer. (The symbol for point, of course, is not part
+of the text in the buffer; it indicates the place *between* two
+characters where point is located.)
+
+ The `@point{}' command is displayed as `-!-' in Info and as a small
+five pointed star in the printed output.
+
+ The following example shows the contents of buffer `foo' before and
+after evaluating a Lisp command to insert the word `changed'.
+
+ ---------- Buffer: foo ----------
+ This is the -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ => nil
+ ---------- Buffer: foo ----------
+ This is the changed -!-contents of foo.
+ ---------- Buffer: foo ----------
+
+ In a Texinfo source file, the example is written like this:
+
+ @example
+ ---------- Buffer: foo ----------
+ This is the @point{}contents of foo.
+ ---------- Buffer: foo ----------
+
+ (insert "changed ")
+ @result{} nil
+ ---------- Buffer: foo ----------
+ This is the changed @point{}contents of foo.
+ ---------- Buffer: foo ----------
+ @end example
+
+\1f
+File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions
+
+Inserting Images
+================
+
+ You can insert an image in an external file with the `@image' command:
+
+ @image{FILENAME, [WIDTH], [HEIGHT]}
+
+ The FILENAME argument is mandatory, and must not have an extension,
+because the different processors support different formats: TeX reads
+the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
+uses `FILENAME.txt' verbatim for Info output (more or less as if it was
+an `@example'). HTML output requires `FILENAME.jpg'.
+
+ The optional WIDTH and HEIGHT arguments specify the size to scale the
+image to (they are ignored for Info output). If they are both
+specified, the image is presented in its natural size (given in the
+file); if only one is specified, the other is scaled proportionately;
+and if both are specified, both are respected, thus possibly distorting
+the original image by changing its aspect ratio.
+
+ The WIDTH and HEIGHT may be specified using any valid TeX dimension,
+namely:
+
+pt
+ point (72.27pt = 1in)
+
+pc
+ pica (1pc = 12pt)
+
+bp
+ big point (72bp = 1in)
+
+in
+ inch
+
+cm
+ centimeter (2.54cm = 1in)
+
+mm
+ millimeter (10mm = 1cm)
+
+dd
+ did^ot point (1157dd = 1238pt)
+
+cc
+ cicero (1cc = 12dd)
+
+sp
+ scaled point (65536sp = 1pt)
+
+ For example, the following will scale a file `ridt.eps' to one inch
+vertically, with the width scaled proportionately:
+
+ @image{ridt,,1in}
+
+ For `@image' to work with TeX, the file `epsf.tex' must be installed
+somewhere that TeX can find it. This file is included in the Texinfo
+distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
+
+\1f
+File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
+
+Making and Preventing Breaks
+****************************
+
+ Usually, a Texinfo file is processed both by TeX and by one of the
+Info formatting commands. Line, paragraph, or page breaks sometimes
+occur in the `wrong' place in one or other form of output. You must
+ensure that text looks right both in the printed manual and in the Info
+file.
+
+ For example, in a printed manual, page breaks may occur awkwardly in
+the middle of an example; to prevent this, you can hold text together
+using a grouping command that keeps the text from being split across
+two pages. Conversely, you may want to force a page break where none
+would occur normally. Fortunately, problems like these do not often
+arise. When they do, use the break, break prevention, or pagination
+commands.
+
+* Menu:
+
+* Break Commands:: Cause and prevent splits.
+* Line Breaks:: How to force a single line to use two lines.
+* - and hyphenation:: How to tell TeX about hyphenation points.
+* w:: How to prevent unwanted line breaks.
+* sp:: How to insert blank lines.
+* page:: How to force the start of a new page.
+* group:: How to prevent unwanted page breaks.
+* need:: Another way to prevent unwanted page breaks.
+
+\1f
+File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
+
+The Break Commands
+==================
+
+ The break commands create or allow line and paragraph breaks:
+
+`@*'
+ Force a line break.
+
+`@sp N'
+ Skip N blank lines.
+
+`@-'
+ Insert a discretionary hyphen.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Define hyphen points in HY-PHEN-A-TED WORDS.
+
+ The line-break-prevention command holds text together all on one line:
+
+`@w{TEXT}'
+ Prevent TEXT from being split and hyphenated across two lines.
+
+ The pagination commands apply only to printed output, since Info
+files do not have pages.
+
+`@page'
+ Start a new page in the printed manual.
+
+`@group'
+ Hold text together that must appear on one printed page.
+
+`@need MILS'
+ Start a new printed page if not enough space on this one.
+
+\1f
+File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
+
+`@*': Generate Line Breaks
+==========================
+
+ The `@*' command forces a line break in both the printed manual and
+in Info.
+
+ For example,
+
+ This line @* is broken @*in two places.
+
+produces
+
+ This line
+ is broken
+ in two places.
+
+(Note that the space after the first `@*' command is faithfully carried
+down to the next line.)
+
+ The `@*' command is often used in a file's copyright page:
+
+ This is edition 2.0 of the Texinfo documentation,@*
+ and is for ...
+
+In this case, the `@*' command keeps TeX from stretching the line
+across the whole page in an ugly manner.
+
+ *Please note:* Do not write braces after an `@*' command; they are
+ not needed.
+
+ Do not write an `@refill' command at the end of a paragraph
+ containing an `@*' command; it will cause the paragraph to be
+ refilled after the line break occurs, negating the effect of the
+ line break.
+
+\1f
+File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
+
+`@-' and `@hyphenation': Helping TeX hyphenate
+==============================================
+
+ Although TeX's hyphenation algorithm is generally pretty good, it
+does miss useful hyphenation points from time to time. (Or, far more
+rarely, insert an incorrect hyphenation.) So, for documents with an
+unusual vocabulary or when fine-tuning for a printed edition, you may
+wish to help TeX out. Texinfo supports two commands for this:
+
+`@-'
+ Insert a discretionary hyphen, i.e., a place where TeX can (but
+ does not have to) hyphenate. This is especially useful when you
+ notice an overfull hbox is due to TeX missing a hyphenation (*note
+ Overfull hboxes::.). TeX will not insert any hyphenation points
+ in a word containing `@-'.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
+ a `-' at each hyphenation point. For example:
+ @hyphenation{man-u-script man-u-scripts}
+
+ TeX only uses the specified hyphenation points when the words
+ match exactly, so give all necessary variants.
+
+ Info output is not hyphenated, so these commands have no effect there.
+
+\1f
+File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
+
+`@w'{TEXT}: Prevent Line Breaks
+===============================
+
+ `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
+
+ You can use the `@w' command to prevent TeX from automatically
+hyphenating a long name or phrase that happens to fall near the end of a
+line.
+
+ You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
+
+produces
+
+ You can copy GNU software from `ftp.gnu.ai.mit.edu'.
+
+ *Caution:* Do not write an `@refill' command at the end of a
+ paragraph containing an `@w' command; it will cause the paragraph
+ to be refilled and may thereby negate the effect of the `@w'
+ command.
+
+\1f
+File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
+
+`@sp' N: Insert Blank Lines
+===========================
+
+ A line beginning with and containing only `@sp N' generates N blank
+lines of space in both the printed manual and the Info file. `@sp'
+also forces a paragraph break. For example,
+
+ @sp 2
+
+generates two blank lines.
+
+ The `@sp' command is most often used in the title page.
+
+\1f
+File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
+
+`@page': Start a New Page
+=========================
+
+ A line containing only `@page' starts a new page in a printed manual.
+The command has no effect on Info files since they are not paginated.
+An `@page' command is often used in the `@titlepage' section of a
+Texinfo file to start the copyright page.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks
+
+`@group': Prevent Page Breaks
+=============================
+
+ The `@group' command (on a line by itself) is used inside an
+`@example' or similar construct to begin an unsplittable vertical
+group, which will appear entirely on one page in the printed output.
+The group is terminated by a line containing only `@end group'. These
+two lines produce no output of their own, and in the Info file output
+they have no effect at all.
+
+ Although `@group' would make sense conceptually in a wide variety of
+contexts, its current implementation works reliably only within
+`@example' and variants, and within `@display', `@format', `@flushleft'
+and `@flushright'. *Note Quotations and Examples::. (What all these
+commands have in common is that each line of input produces a line of
+output.) In other contexts, `@group' can cause anomalous vertical
+spacing.
+
+ This formatting requirement means that you should write:
+
+ @example
+ @group
+ ...
+ @end group
+ @end example
+
+with the `@group' and `@end group' commands inside the `@example' and
+`@end example' commands.
+
+ The `@group' command is most often used to hold an example together
+on one page. In this Texinfo manual, more than 100 examples contain
+text that is enclosed between `@group' and `@end group'.
+
+ If you forget to end a group, you may get strange and unfathomable
+error messages when you run TeX. This is because TeX keeps trying to
+put the rest of the Texinfo file onto the one page and does not start
+to generate error messages until it has processed considerable text.
+It is a good rule of thumb to look for a missing `@end group' if you
+get incomprehensible error messages in TeX.
+
+\1f
+File: texinfo.info, Node: need, Prev: group, Up: Breaks
+
+`@need MILS': Prevent Page Breaks
+=================================
+
+ A line containing only `@need N' starts a new page in a printed
+manual if fewer than N mils (thousandths of an inch) remain on the
+current page. Do not use braces around the argument N. The `@need'
+command has no effect on Info files since they are not paginated.
+
+ This paragraph is preceded by an `@need' command that tells TeX to
+start a new page if fewer than 800 mils (eight-tenths inch) remain on
+the page. It looks like this:
+
+ @need 800
+ This paragraph is preceded by ...
+
+ The `@need' command is useful for preventing orphans (single lines at
+the bottoms of printed pages).
+
+\1f
+File: texinfo.info, Node: Definition Commands, Next: Footnotes, Prev: Breaks, Up: Top
+
+Definition Commands
+*******************
+
+ The `@deffn' command and the other "definition commands" enable you
+to describe functions, variables, macros, commands, user options,
+special forms and other such artifacts in a uniform format.
+
+ In the Info file, a definition causes the entity
+category--`Function', `Variable', or whatever--to appear at the
+beginning of the first line of the definition, followed by the entity's
+name and arguments. In the printed manual, the command causes TeX to
+print the entity's name and its arguments on the left margin and print
+the category next to the right margin. In both output formats, the
+body of the definition is indented. Also, the name of the entity is
+entered into the appropriate index: `@deffn' enters the name into the
+index of functions, `@defvr' enters it into the index of variables, and
+so on.
+
+ A manual need not and should not contain more than one definition for
+a given name. An appendix containing a summary should use `@table'
+rather than the definition commands.
+
+* Menu:
+
+* Def Cmd Template:: How to structure a description using a
+ definition command.
+* Optional Arguments:: How to handle optional and repeated arguments.
+* deffnx:: How to group two or more `first' lines.
+* Def Cmds in Detail:: All the definition commands.
+* Def Cmd Conventions:: Conventions for writing definitions.
+* Sample Function Definition::
+
+\1f
+File: texinfo.info, Node: Def Cmd Template, Next: Optional Arguments, Prev: Definition Commands, Up: Definition Commands
+
+The Template for a Definition
+=============================
+
+ The `@deffn' command is used for definitions of entities that
+resemble functions. To write a definition using the `@deffn' command,
+write the `@deffn' command at the beginning of a line and follow it on
+the same line by the category of the entity, the name of the entity
+itself, and its arguments (if any). Then write the body of the
+definition on succeeding lines. (You may embed examples in the body.)
+Finally, end the definition with an `@end deffn' command written on a
+line of its own. (The other definition commands follow the same
+format.)
+
+ The template for a definition looks like this:
+
+ @deffn CATEGORY NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end deffn
+
+For example,
+
+ @deffn Command forward-word count
+ This command moves point forward @var{count} words
+ (or backward if @var{count} is negative). ...
+ @end deffn
+
+produces
+
+ - Command: forward-word COUNT
+ This function moves point forward COUNT words (or backward if
+ COUNT is negative). ...
+
+ Capitalize the category name like a title. If the name of the
+category contains spaces, as in the phrase `Interactive Command', write
+braces around it. For example:
+
+ @deffn {Interactive Command} isearch-forward
+ ...
+ @end deffn
+
+Otherwise, the second word will be mistaken for the name of the entity.
+
+ Some of the definition commands are more general than others. The
+`@deffn' command, for example, is the general definition command for
+functions and the like--for entities that may take arguments. When you
+use this command, you specify the category to which the entity belongs.
+The `@deffn' command possesses three predefined, specialized
+variations, `@defun', `@defmac', and `@defspec', that specify the
+category for you: "Function", "Macro", and "Special Form" respectively.
+(In Lisp, a special form is an entity much like a function.) The
+`@defvr' command also is accompanied by several predefined, specialized
+variations for describing particular kinds of variables.
+
+ The template for a specialized definition, such as `@defun', is
+similar to the template for a generalized definition, except that you
+do not need to specify the category:
+
+ @defun NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end defun
+
+Thus,
+
+ @defun buffer-end flag
+ This function returns @code{(point-min)} if @var{flag}
+ is less than 1, @code{(point-max)} otherwise.
+ ...
+ @end defun
+
+produces
+
+ - Function: buffer-end FLAG
+ This function returns `(point-min)' if FLAG is less than 1,
+ `(point-max)' otherwise. ...
+
+*Note Sample Function Definition: Sample Function Definition, for a
+more detailed example of a function definition, including the use of
+`@example' inside the definition.
+
+ The other specialized commands work like `@defun'.
+
+\1f
+File: texinfo.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Template, Up: Definition Commands
+
+Optional and Repeated Arguments
+===============================
+
+ Some entities take optional or repeated arguments, which may be
+specified by a distinctive glyph that uses square brackets and
+ellipses. For example, a special form often breaks its argument list
+into separate arguments in more complicated ways than a straightforward
+function.
+
+ An argument enclosed within square brackets is optional. Thus,
+[OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument
+followed by an ellipsis is optional and may be repeated more than once.
+Thus, REPEATED-ARGS... stands for zero or more arguments. Parentheses
+are used when several arguments are grouped into additional levels of
+list structure in Lisp.
+
+ Here is the `@defspec' line of an example of an imaginary special
+form:
+
+ - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
+
+In this example, the arguments FROM and TO are optional, but must both
+be present or both absent. If they are present, INC may optionally be
+specified as well. These arguments are grouped with the argument VAR
+into a list, to distinguish them from BODY, which includes all
+remaining elements of the form.
+
+ In a Texinfo source file, this `@defspec' line is written like this
+(except it would not be split over two lines, as it is in this example).
+
+ @defspec foobar (@var{var} [@var{from} @var{to}
+ [@var{inc}]]) @var{body}@dots{}
+
+The function is listed in the Command and Variable Index under `foobar'.
+
+\1f
+File: texinfo.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands
+
+Two or More `First' Lines
+=========================
+
+ To create two or more `first' or header lines for a definition, follow
+the first `@deffn' line by a line beginning with `@deffnx'. The
+`@deffnx' command works exactly like `@deffn' except that it does not
+generate extra vertical white space between it and the preceding line.
+
+ For example,
+
+ @deffn {Interactive Command} isearch-forward
+ @deffnx {Interactive Command} isearch-backward
+ These two search commands are similar except ...
+ @end deffn
+
+produces
+
+ - Interactive Command: isearch-forward
+ - Interactive Command: isearch-backward
+ These two search commands are similar except ...
+
+ Each of the other definition commands has an `x' form: `@defunx',
+`@defvrx', `@deftypefunx', etc.
+
+ The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
+
+\1f
+File: texinfo.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands
+
+The Definition Commands
+=======================
+
+ Texinfo provides more than a dozen definition commands, all of which
+are described in this section.
+
+ The definition commands automatically enter the name of the entity in
+the appropriate index: for example, `@deffn', `@defun', and `@defmac'
+enter function names in the index of functions; `@defvr' and `@defvar'
+enter variable names in the index of variables.
+
+ Although the examples that follow mostly illustrate Lisp, the commands
+can be used for other programming languages.
+
+* Menu:
+
+* Functions Commands:: Commands for functions and similar entities.
+* Variables Commands:: Commands for variables and similar entities.
+* Typed Functions:: Commands for functions in typed languages.
+* Typed Variables:: Commands for variables in typed languages.
+* Abstract Objects:: Commands for object-oriented programming.
+* Data Types:: The definition command for data types.
+
+\1f
+File: texinfo.info, Node: Functions Commands, Next: Variables Commands, Prev: Def Cmds in Detail, Up: Def Cmds in Detail
+
+Functions and Similar Entities
+------------------------------
+
+ This section describes the commands for describing functions and
+similar entities:
+
+`@deffn CATEGORY NAME ARGUMENTS...'
+ The `@deffn' command is the general definition command for
+ functions, interactive commands, and similar entities that may take
+ arguments. You must choose a term to describe the category of
+ entity being defined; for example, "Function" could be used if the
+ entity is a function. The `@deffn' command is written at the
+ beginning of a line and is followed on the same line by the
+ category of entity being described, the name of this particular
+ entity, and its arguments, if any. Terminate the definition with
+ `@end deffn' on a line of its own.
+
+ For example, here is a definition:
+
+ @deffn Command forward-char nchars
+ Move point forward @var{nchars} characters.
+ @end deffn
+
+ This shows a rather terse definition for a "command" named
+ `forward-char' with one argument, NCHARS.
+
+ `@deffn' prints argument names such as NCHARS in italics or upper
+ case, as if `@var' had been used, because we think of these names
+ as metasyntactic variables--they stand for the actual argument
+ values. Within the text of the description, write an argument name
+ explicitly with `@var' to refer to the value of the argument. In
+ the example above, we used `@var{nchars}' in this way.
+
+ The template for `@deffn' is:
+
+ @deffn CATEGORY NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end deffn
+
+`@defun NAME ARGUMENTS...'
+ The `@defun' command is the definition command for functions.
+ `@defun' is equivalent to `@deffn Function ...'.
+
+ For example,
+
+ @defun set symbol new-value
+ Change the value of the symbol @var{symbol}
+ to @var{new-value}.
+ @end defun
+
+ shows a rather terse definition for a function `set' whose
+ arguments are SYMBOL and NEW-VALUE. The argument names on the
+ `@defun' line automatically appear in italics or upper case as if
+ they were enclosed in `@var'. Terminate the definition with `@end
+ defun' on a line of its own.
+
+ The template is:
+
+ @defun FUNCTION-NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end defun
+
+ `@defun' creates an entry in the index of functions.
+
+`@defmac NAME ARGUMENTS...'
+ The `@defmac' command is the definition command for macros.
+ `@defmac' is equivalent to `@deffn Macro ...' and works like
+ `@defun'.
+
+`@defspec NAME ARGUMENTS...'
+ The `@defspec' command is the definition command for special
+ forms. (In Lisp, a special form is an entity much like a function,
+ *note Special Forms: (lispref)Special Forms..) `@defspec' is
+ equivalent to `@deffn {Special Form} ...' and works like `@defun'.
+
+\1f
+File: texinfo.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail
+
+Variables and Similar Entities
+------------------------------
+
+ Here are the commands for defining variables and similar entities:
+
+`@defvr CATEGORY NAME'
+ The `@defvr' command is a general definition command for something
+ like a variable--an entity that records a value. You must choose
+ a term to describe the category of entity being defined; for
+ example, "Variable" could be used if the entity is a variable.
+ Write the `@defvr' command at the beginning of a line and followed
+ it on the same line by the category of the entity and the name of
+ the entity.
+
+ Capitalize the category name like a title. If the name of the
+ category contains spaces, as in the name "User Option", enclose it
+ in braces. Otherwise, the second word will be mistaken for the
+ name of the entity. For example,
+
+ @defvr {User Option} fill-column
+ This buffer-local variable specifies
+ the maximum width of filled lines.
+ ...
+ @end defvr
+
+ Terminate the definition with `@end defvr' on a line of its own.
+
+ The template is:
+
+ @defvr CATEGORY NAME
+ BODY-OF-DEFINITION
+ @end defvr
+
+ `@defvr' creates an entry in the index of variables for NAME.
+
+`@defvar NAME'
+ The `@defvar' command is the definition command for variables.
+ `@defvar' is equivalent to `@defvr Variable ...'.
+
+ For example:
+
+ @defvar kill-ring
+ ...
+ @end defvar
+
+ The template is:
+
+ @defvar NAME
+ BODY-OF-DEFINITION
+ @end defvar
+
+ `@defvar' creates an entry in the index of variables for NAME.
+
+`@defopt NAME'
+ The `@defopt' command is the definition command for "user
+ options", i.e., variables intended for users to change according to
+ taste; Emacs has many such (*note Variables: (xemacs)Variables.).
+ `@defopt' is equivalent to `@defvr {User Option} ...' and works
+ like `@defvar'.
+
+\1f
+File: texinfo.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail
+
+Functions in Typed Languages
+----------------------------
+
+ The `@deftypefn' command and its variations are for describing
+functions in languages in which you must declare types of variables and
+functions, such as C and C++.
+
+`@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
+ The `@deftypefn' command is the general definition command for
+ functions and similar entities that may take arguments and that are
+ typed. The `@deftypefn' command is written at the beginning of a
+ line and is followed on the same line by the category of entity
+ being described, the type of the returned value, the name of this
+ particular entity, and its arguments, if any.
+
+ For example,
+
+ @deftypefn {Library Function} int foobar
+ (int @var{foo}, float @var{bar})
+ ...
+ @end deftypefn
+
+ (where the text before the "...", shown above as two lines, would
+ actually be a single line in a real Texinfo file) produces the
+ following in Info:
+
+ -- Library Function: int foobar (int FOO, float BAR)
+ ...
+
+ This means that `foobar' is a "library function" that returns an
+ `int', and its arguments are FOO (an `int') and BAR (a `float').
+
+ The argument names that you write in `@deftypefn' are not subject
+ to an implicit `@var'--since the actual names of the arguments in
+ `@deftypefn' are typically scattered among data type names and
+ keywords, Texinfo cannot find them without help. Instead, you
+ must write `@var' explicitly around the argument names. In the
+ example above, the argument names are `foo' and `bar'.
+
+ The template for `@deftypefn' is:
+
+ @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
+ BODY-OF-DESCRIPTION
+ @end deftypefn
+
+ Note that if the CATEGORY or DATA TYPE is more than one word then
+ it must be enclosed in braces to make it a single argument.
+
+ If you are describing a procedure in a language that has packages,
+ such as Ada, you might consider using `@deftypefn' in a manner
+ somewhat contrary to the convention described in the preceding
+ paragraphs.
+
+ For example:
+
+ @deftypefn stacks private push
+ (@var{s}:in out stack;
+ @var{n}:in integer)
+ ...
+ @end deftypefn
+
+ (The `@deftypefn' arguments are shown split into three lines, but
+ would be a single line in a real Texinfo file.)
+
+ In this instance, the procedure is classified as belonging to the
+ package `stacks' rather than classified as a `procedure' and its
+ data type is described as `private'. (The name of the procedure
+ is `push', and its arguments are S and N.)
+
+ `@deftypefn' creates an entry in the index of functions for NAME.
+
+`@deftypefun DATA-TYPE NAME ARGUMENTS...'
+ The `@deftypefun' command is the specialized definition command
+ for functions in typed languages. The command is equivalent to
+ `@deftypefn Function ...'.
+
+ Thus,
+
+ @deftypefun int foobar (int @var{foo}, float @var{bar})
+ ...
+ @end deftypefun
+
+ produces the following in Info:
+
+ -- Function: int foobar (int FOO, float BAR)
+ ...
+
+ The template is:
+
+ @deftypefun TYPE NAME ARGUMENTS...
+ BODY-OF-DESCRIPTION
+ @end deftypefun
+
+ `@deftypefun' creates an entry in the index of functions for NAME.
+
+\1f
+File: texinfo.info, Node: Typed Variables, Next: Abstract Objects, Prev: Typed Functions, Up: Def Cmds in Detail
+
+Variables in Typed Languages
+----------------------------
+
+ Variables in typed languages are handled in a manner similar to
+functions in typed languages. *Note Typed Functions::. The general
+definition command `@deftypevr' corresponds to `@deftypefn' and the
+specialized definition command `@deftypevar' corresponds to
+`@deftypefun'.
+
+`@deftypevr CATEGORY DATA-TYPE NAME'
+ The `@deftypevr' command is the general definition command for
+ something like a variable in a typed language--an entity that
+ records a value. You must choose a term to describe the category
+ of the entity being defined; for example, "Variable" could be used
+ if the entity is a variable.
+
+ The `@deftypevr' command is written at the beginning of a line and
+ is followed on the same line by the category of the entity being
+ described, the data type, and the name of this particular entity.
+
+ For example:
+
+ @deftypevr {Global Flag} int enable
+ ...
+ @end deftypevr
+
+ produces the following in Info:
+
+ -- Global Flag: int enable
+ ...
+
+ The template is:
+
+ @deftypevr CATEGORY DATA-TYPE NAME
+ BODY-OF-DESCRIPTION
+ @end deftypevr
+
+ `@deftypevr' creates an entry in the index of variables for NAME.
+
+`@deftypevar DATA-TYPE NAME'
+ The `@deftypevar' command is the specialized definition command
+ for variables in typed languages. `@deftypevar' is equivalent to
+ `@deftypevr Variable ...'.
+
+ For example:
+
+ @deftypevar int fubar
+ ...
+ @end deftypevar
+
+ produces the following in Info:
+
+ -- Variable: int fubar
+ ...
+
+ The template is:
+
+ @deftypevar DATA-TYPE NAME
+ BODY-OF-DESCRIPTION
+ @end deftypevar
+
+ `@deftypevar' creates an entry in the index of variables for NAME.
+
+\1f
+File: texinfo.info, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail
+
+Object-Oriented Programming
+---------------------------
+
+ Here are the commands for formatting descriptions about abstract
+objects, such as are used in object-oriented programming. A class is a
+defined type of abstract object. An instance of a class is a
+particular object that has the type of the class. An instance variable
+is a variable that belongs to the class but for which each instance has
+its own value.
+
+ In a definition, if the name of a class is truly a name defined in the
+programming system for a class, then you should write an `@code' around
+it. Otherwise, it is printed in the usual text font.
+
+`@defcv CATEGORY CLASS NAME'
+ The `@defcv' command is the general definition command for
+ variables associated with classes in object-oriented programming.
+ The `@defcv' command is followed by three arguments: the category
+ of thing being defined, the class to which it belongs, and its
+ name. Thus,
+
+ @defcv {Class Option} Window border-pattern
+ ...
+ @end defcv
+
+ illustrates how you would write the first line of a definition of
+ the `border-pattern' class option of the class `Window'.
+
+ The template is
+
+ @defcv CATEGORY CLASS NAME
+ ...
+ @end defcv
+
+ `@defcv' creates an entry in the index of variables.
+
+`@defivar CLASS NAME'
+ The `@defivar' command is the definition command for instance
+ variables in object-oriented programming. `@defivar' is
+ equivalent to `@defcv {Instance Variable} ...'
+
+ The template is:
+
+ @defivar CLASS INSTANCE-VARIABLE-NAME
+ BODY-OF-DEFINITION
+ @end defivar
+
+ `@defivar' creates an entry in the index of variables.
+
+`@defop CATEGORY CLASS NAME ARGUMENTS...'
+ The `@defop' command is the general definition command for
+ entities that may resemble methods in object-oriented programming.
+ These entities take arguments, as functions do, but are associated
+ with particular classes of objects.
+
+ For example, some systems have constructs called "wrappers" that
+ are associated with classes as methods are, but that act more like
+ macros than like functions. You could use `@defop Wrapper' to
+ describe one of these.
+
+ Sometimes it is useful to distinguish methods and "operations".
+ You can think of an operation as the specification for a method.
+ Thus, a window system might specify that all window classes have a
+ method named `expose'; we would say that this window system
+ defines an `expose' operation on windows in general. Typically,
+ the operation has a name and also specifies the pattern of
+ arguments; all methods that implement the operation must accept
+ the same arguments, since applications that use the operation do
+ so without knowing which method will implement it.
+
+ Often it makes more sense to document operations than methods. For
+ example, window application developers need to know about the
+ `expose' operation, but need not be concerned with whether a given
+ class of windows has its own method to implement this operation.
+ To describe this operation, you would write:
+
+ @defop Operation windows expose
+
+ The `@defop' command is written at the beginning of a line and is
+ followed on the same line by the overall name of the category of
+ operation, the name of the class of the operation, the name of the
+ operation, and its arguments, if any.
+
+ The template is:
+
+ @defop CATEGORY CLASS NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end defop
+
+ `@defop' creates an entry, such as ``expose' on `windows'', in the
+ index of functions.
+
+`@defmethod CLASS NAME ARGUMENTS...'
+ The `@defmethod' command is the definition command for methods in
+ object-oriented programming. A method is a kind of function that
+ implements an operation for a particular class of objects and its
+ subclasses. In the Lisp Machine, methods actually were functions,
+ but they were usually defined with `defmethod'.
+
+ `@defmethod' is equivalent to `@defop Method ...'. The command is
+ written at the beginning of a line and is followed by the name of
+ the class of the method, the name of the method, and its
+ arguments, if any.
+
+ For example,
+
+ @defmethod `bar-class' bar-method argument
+ ...
+ @end defmethod
+
+ illustrates the definition for a method called `bar-method' of the
+ class `bar-class'. The method takes an argument.
+
+ The template is:
+
+ @defmethod CLASS METHOD-NAME ARGUMENTS...
+ BODY-OF-DEFINITION
+ @end defmethod
+
+ `@defmethod' creates an entry, such as ``bar-method' on
+ `bar-class'', in the index of functions.
+
+`@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
+ The `@deftypemethod' command is the definition command for methods
+ in object-oriented typed languages, such as C++ and Java. It is
+ similar to the `@defmethod' command with the addition of the
+ DATA-TYPE parameter to specify the return type of the method.
+
+\1f
+File: texinfo.info, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail
+
+Data Types
+----------
+
+ Here is the command for data types:
+
+`@deftp CATEGORY NAME ATTRIBUTES...'
+ The `@deftp' command is the generic definition command for data
+ types. The command is written at the beginning of a line and is
+ followed on the same line by the category, by the name of the type
+ (which is a word like `int' or `float'), and then by names of
+ attributes of objects of that type. Thus, you could use this
+ command for describing `int' or `float', in which case you could
+ use `data type' as the category. (A data type is a category of
+ certain objects for purposes of deciding which operations can be
+ performed on them.)
+
+ In Lisp, for example, "pair" names a particular data type, and an
+ object of that type has two slots called the CAR and the CDR.
+ Here is how you would write the first line of a definition of
+ `pair'.
+
+ @deftp {Data type} pair car cdr
+ ...
+ @end deftp
+
+ The template is:
+
+ @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
+ BODY-OF-DEFINITION
+ @end deftp
+
+ `@deftp' creates an entry in the index of data types.
+
+\1f
+File: texinfo.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands
+
+Conventions for Writing Definitions
+===================================
+
+ When you write a definition using `@deffn', `@defun', or one of the
+other definition commands, please take care to use arguments that
+indicate the meaning, as with the COUNT argument to the `forward-word'
+function. Also, if the name of an argument contains the name of a
+type, such as INTEGER, take care that the argument actually is of that
+type.
+
+\1f
+File: texinfo.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands
+
+A Sample Function Definition
+============================
+
+ A function definition uses the `@defun' and `@end defun' commands.
+The name of the function follows immediately after the `@defun' command
+and it is followed, on the same line, by the parameter list.
+
+ Here is a definition from *Note Calling Functions: (lispref)Calling
+Functions.
+
+ - Function: apply FUNCTION &rest ARGUMENTS
+ `apply' calls FUNCTION with ARGUMENTS, just like `funcall'
+ but with one difference: the last of ARGUMENTS is a list of
+ arguments to give to FUNCTION, rather than a single argument.
+ We also say that this list is "appended" to the other
+ arguments.
+
+ `apply' returns the result of calling FUNCTION. As with
+ `funcall', FUNCTION must either be a Lisp function or a
+ primitive function; special forms and macros do not make
+ sense in `apply'.
+
+ (setq f 'list)
+ => list
+ (apply f 'x 'y 'z)
+ error--> Wrong type argument: listp, z
+ (apply '+ 1 2 '(3 4))
+ => 10
+ (apply '+ '(1 2 3 4))
+ => 10
+
+ (apply 'append '((a b c) nil (x y z) nil))
+ => (a b c x y z)
+
+ An interesting example of using `apply' is found in the
+ description of `mapcar'.
+
+ In the Texinfo source file, this example looks like this:
+
+ @defun apply function &rest arguments
+
+ @code{apply} calls @var{function} with
+ @var{arguments}, just like @code{funcall} but with one
+ difference: the last of @var{arguments} is a list of
+ arguments to give to @var{function}, rather than a single
+ argument. We also say that this list is @dfn{appended}
+ to the other arguments.
+
+ @code{apply} returns the result of calling
+ @var{function}. As with @code{funcall},
+ @var{function} must either be a Lisp function or a
+ primitive function; special forms and macros do not make
+ sense in @code{apply}.
+
+ @example
+ (setq f 'list)
+ @result{} list
+ (apply f 'x 'y 'z)
+ @error{} Wrong type argument: listp, z
+ (apply '+ 1 2 '(3 4))
+ @result{} 10
+ (apply '+ '(1 2 3 4))
+ @result{} 10
+
+ (apply 'append '((a b c) nil (x y z) nil))
+ @result{} (a b c x y z)
+ @end example
+
+ An interesting example of using @code{apply} is found
+ in the description of @code{mapcar}.@refill
+ @end defun
+
+In this manual, this function is listed in the Command and Variable
+Index under `apply'.
+
+ Ordinary variables and user options are described using a format like
+that for functions except that variables do not take arguments.
+
+\1f
+File: texinfo.info, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top
+
+Footnotes
+*********
+
+ A "footnote" is for a reference that documents or elucidates the
+primary text.(1) (*note Footnotes-Footnotes::)
+
+* Menu:
+
+* Footnote Commands:: How to write a footnote in Texinfo.
+* Footnote Styles:: Controlling how footnotes appear in Info.
+
+\1f
+File: texinfo.info, Node: Footnotes-Footnotes, Up: Footnotes
+
+ (1) A footnote should complement or expand upon the primary text, but
+a reader should not need to read a footnote to understand the primary
+text. For a thorough discussion of footnotes, see `The Chicago Manual
+of Style', which is published by the University of Chicago Press.
+
+\1f
+File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Prev: Footnotes, Up: Footnotes
+
+Footnote Commands
+=================
+
+ In Texinfo, footnotes are created with the `@footnote' command. This
+command is followed immediately by a left brace, then by the text of
+the footnote, and then by a terminating right brace. Footnotes may be
+of any length (they will be broken across pages if necessary), but are
+usually short. The template is:
+
+ ordinary text@footnote{TEXT OF FOOTNOTE}
+
+ As shown here, the `@footnote' command should come right after the
+text being footnoted, with no intervening space; otherwise, the
+formatters the footnote mark might end up starting up a line.
+
+ For example, this clause is followed by a sample footnote(1) (*note
+Footnote Commands-Footnotes::); in the Texinfo source, it looks like
+this:
+
+ ...a sample footnote@footnote{Here is the sample
+ footnote.}; in the Texinfo source...
+
+ *Warning:* Don't use footnotes in the argument of the `@item' command
+for a `@table' table. This doesn't work, and because of limitations of
+TeX, there is no way to fix it. You must put the footnote into the
+body text of the table.
+
+ In a printed manual or book, the reference mark for a footnote is a
+small, superscripted number; the text of the footnote appears at the
+bottom of the page, below a horizontal line.
+
+ In Info, the reference mark for a footnote is a pair of parentheses
+with the footnote number between them, like this: `(1)'.
+
+\1f
+File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands
+
+ (1) Here is the sample footnote.
+
+\1f
+File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes
+
+Footnote Styles
+===============
+
+ Info has two footnote styles, which determine where the text of the
+footnote is located:
+
+ * In the `End' node style, all the footnotes for a single node are
+ placed at the end of that node. The footnotes are separated from
+ the rest of the node by a line of dashes with the word `Footnotes'
+ within it. Each footnote begins with an `(N)' reference mark.
+
+ Here is an example of a single footnote in the end of node style:
+
+ --------- Footnotes ---------
+
+ (1) Here is a sample footnote.
+
+ * In the `Separate' node style, all the footnotes for a single node
+ are placed in an automatically constructed node of their own. In
+ this style, a "footnote reference" follows each `(N)' reference
+ mark in the body of the node. The footnote reference is actually
+ a cross reference which you use to reach the footnote node.
+
+ The name of the node containing the footnotes is constructed by
+ appending `-Footnotes' to the name of the node that contains the
+ footnotes. (Consequently, the footnotes' node for the `Footnotes'
+ node is `Footnotes-Footnotes'!) The footnotes' node has an `Up'
+ node pointer that leads back to its parent node.
+
+ Here is how the first footnote in this manual looks after being
+ formatted for Info in the separate node style:
+
+ File: texinfo.info Node: Overview-Footnotes, Up: Overview
+
+ (1) Note that the first syllable of "Texinfo" is
+ pronounced like "speck", not "hex". ...
+
+ A Texinfo file may be formatted into an Info file with either footnote
+style.
+
+ Use the `@footnotestyle' command to specify an Info file's footnote
+style. Write this command at the beginning of a line followed by an
+argument, either `end' for the end node style or `separate' for the
+separate node style.
+
+ For example,
+
+ @footnotestyle end
+
+or
+ @footnotestyle separate
+
+ Write an `@footnotestyle' command before or shortly after the
+end-of-header line at the beginning of a Texinfo file. (If you include
+the `@footnotestyle' command between the start-of-header and
+end-of-header lines, the region formatting commands will format
+footnotes as specified.)
+
+ If you do not specify a footnote style, the formatting commands use
+their default style. Currently, `texinfo-format-buffer' and
+`texinfo-format-region' use the `separate' style and `makeinfo' uses
+the `end' style.
+
+ This chapter contains two footnotes.
+
+\1f
+File: texinfo.info, Node: Conditionals, Next: Macros, Prev: Footnotes, Up: Top
+
+Conditionally Visible Text
+**************************
+
+ Sometimes it is good to use different text for a printed manual and
+its corresponding Info file. In this case, you can use the
+"conditional commands" to specify which text is for the printed manual
+and which is for the Info file.
+
+* Menu:
+
+* Conditional Commands:: Specifying text for HTML, Info, or TeX.
+* Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
+* Raw Formatter Commands:: Using raw TeX or HTML commands.
+* set clear value:: Designating which text to format (for
+ all output formats); and how to set a
+ flag to a string that you can insert.
+
+\1f
+File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Prev: Conditionals, Up: Conditionals
+
+Conditional Commands
+====================
+
+ `@ifinfo' begins segments of text that should be ignored by TeX when
+it typesets the printed manual. The segment of text appears only in
+the Info file. The `@ifinfo' command should appear on a line by
+itself; end the Info-only text with a line containing `@end ifinfo' by
+itself. At the beginning of a Texinfo file, the Info permissions are
+contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
+Info Summary and Permissions::.)
+
+ The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
+and `@end ifinfo' commands, except that they specify text that will
+appear in the printed manual but not in the Info file. Likewise for
+`@ifhtml' and `@end ifhtml', which specify text to appear only in HTML
+output.
+
+ For example,
+
+ @iftex
+ This text will appear only in the printed manual.
+ @end iftex
+ @ifinfo
+ However, this text will appear only in Info.
+ @end ifinfo
+
+The preceding example produces the following line: However, this text
+will appear only in Info.
+
+Note how you only see one of the two lines, depending on whether you
+are reading the Info version or the printed version of this manual.
+
+ The `@titlepage' command is a special variant of `@iftex' that is
+used for making the title and copyright pages of the printed manual.
+(*Note `@titlepage': titlepage.)
+
+\1f
+File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals
+
+Conditional Not Commands
+========================
+
+ You can specify text to be included in any output format *other* than
+some given one with the `@ifnot...' commands:
+ @ifnothtml ... @end ifnothtml
+ @ifnotinfo ... @end ifnotinfo
+ @ifnottex ... @end ifnottex
+
+(The `@ifnot...' command and the `@end' command must actually appear on
+lines by themselves.)
+
+ If the output file is not being made for the given format, the region
+is included. Otherwise, it is ignored.
+
+ The regions delimited by these commands are ordinary Texinfo source as
+with `@iftex', not raw formatter source as with `@tex'.
+
+\1f
+File: texinfo.info, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals
+
+Raw Formatter Commands
+======================
+
+ Inside a region delineated by `@iftex' and `@end iftex', you can
+embed some raw TeX commands. Info will ignore these commands since
+they are only in that part of the file which is seen by TeX. You can
+write the TeX commands as you would write them in a normal TeX file,
+except that you must replace the `\' used by TeX with an `@'. For
+example, in the `@titlepage' section of a Texinfo file, you can use the
+TeX command `@vskip' to format the copyright page. (The `@titlepage'
+command causes Info to ignore the region automatically, as it does with
+the `@iftex' command.)
+
+ However, many features of plain TeX will not work, as they are
+overridden by Texinfo features.
+
+ You can enter plain TeX completely, and use `\' in the TeX commands,
+by delineating a region with the `@tex' and `@end tex' commands. (The
+`@tex' command also causes Info to ignore the region, like the `@iftex'
+command.) The sole exception is that `@' chracter still introduces a
+command, so that `@end tex' can be recognized properly.
+
+ For example, here is a mathematical expression written in plain TeX:
+
+ @tex
+ $$ \chi^2 = \sum_{i=1}^N
+ \left (y_i - (a + b x_i)
+ \over \sigma_i\right)^2 $$
+ @end tex
+
+The output of this example will appear only in a printed manual. If
+you are reading this in Info, you will not see the equation that appears
+in the printed manual.
+
+ Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
+region to be included in HTML output only, and `@html ... @end ifhtml'
+for a region of raw HTML (again, except that `@' is still the escape
+character, so the `@end' command can be recognized.)
+
+\1f
+File: texinfo.info, Node: set clear value, Prev: Raw Formatter Commands, Up: Conditionals
+
+`@set', `@clear', and `@value'
+==============================
+
+ You can direct the Texinfo formatting commands to format or ignore
+parts of a Texinfo file with the `@set', `@clear', `@ifset', and
+`@ifclear' commands.
+
+ In addition, you can use the `@set FLAG' command to set the value of
+FLAG to a string of characters; and use `@value{FLAG}' to insert that
+string. You can use `@set', for example, to set a date and use
+`@value' to insert the date in several places in the Texinfo file.
+
+* Menu:
+
+* ifset ifclear:: Format a region if a flag is set.
+* value:: Replace a flag with a string.
+* value Example:: An easy way to update edition information.
+
+\1f
+File: texinfo.info, Node: ifset ifclear, Next: value, Prev: set clear value, Up: set clear value
+
+`@ifset' and `@ifclear'
+-----------------------
+
+ When a FLAG is set, the Texinfo formatting commands format text
+between subsequent pairs of `@ifset FLAG' and `@end ifset' commands.
+When the FLAG is cleared, the Texinfo formatting commands do *not*
+format the text.
+
+ Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
+can be any single word. The format for the command looks like this:
+
+ @set FLAG
+
+ Write the conditionally formatted text between `@ifset FLAG' and
+`@end ifset' commands, like this:
+
+ @ifset FLAG
+ CONDITIONAL-TEXT
+ @end ifset
+
+ For example, you can create one document that has two variants, such
+as a manual for a `large' and `small' model:
+
+ You can use this machine to dig up shrubs
+ without hurting them.
+
+ @set large
+
+ @ifset large
+ It can also dig up fully grown trees.
+ @end ifset
+
+ Remember to replant promptly ...
+
+In the example, the formatting commands will format the text between
+`@ifset large' and `@end ifset' because the `large' flag is set.
+
+ Use the `@clear FLAG' command to turn off, or "clear", a flag.
+Clearing a flag is the opposite of setting a flag. The command looks
+like this:
+
+ @clear FLAG
+
+Write the command on a line of its own.
+
+ When FLAG is cleared, the Texinfo formatting commands do *not* format
+the text between `@ifset FLAG' and `@end ifset'; that text is ignored
+and does not appear in either printed or Info output.
+
+ For example, if you clear the flag of the preceding example by writing
+an `@clear large' command after the `@set large' command (but before
+the conditional text), then the Texinfo formatting commands ignore the
+text between the `@ifset large' and `@end ifset' commands. In the
+formatted output, that text does not appear; in both printed and Info
+output, you see only the lines that say, "You can use this machine to
+dig up shrubs without hurting them. Remember to replant promptly ...".
+
+ If a flag is cleared with an `@clear FLAG' command, then the
+formatting commands format text between subsequent pairs of `@ifclear'
+and `@end ifclear' commands. But if the flag is set with `@set FLAG',
+then the formatting commands do *not* format text between an `@ifclear'
+and an `@end ifclear' command; rather, they ignore that text. An
+`@ifclear' command looks like this:
+
+ @ifclear FLAG
+
+ In brief, the commands are:
+
+`@set FLAG'
+ Tell the Texinfo formatting commands that FLAG is set.
+
+`@clear FLAG'
+ Tell the Texinfo formatting commands that FLAG is cleared.
+
+`@ifset FLAG'
+ If FLAG is set, tell the Texinfo formatting commands to format the
+ text up to the following `@end ifset' command.
+
+ If FLAG is cleared, tell the Texinfo formatting commands to ignore
+ text up to the following `@end ifset' command.
+
+`@ifclear FLAG'
+ If FLAG is set, tell the Texinfo formatting commands to ignore the
+ text up to the following `@end ifclear' command.
+
+ If FLAG is cleared, tell the Texinfo formatting commands to format
+ the text up to the following `@end ifclear' command.
+
+\1f
+File: texinfo.info, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value
+
+`@value'
+--------
+
+ You can use the `@set' command to specify a value for a flag, which
+is expanded by the `@value' command. The value is a string a
+characters.
+
+ Write the `@set' command like this:
+
+ @set foo This is a string.
+
+This sets the value of `foo' to "This is a string."
+
+ The Texinfo formatters replace an `@value{FLAG}' command with the
+string to which FLAG is set.
+
+ Thus, when `foo' is set as shown above, the Texinfo formatters convert
+
+ @value{foo}
+to
+ This is a string.
+
+ You can write an `@value' command within a paragraph; but you must
+write an `@set' command on a line of its own.
+
+ If you write the `@set' command like this:
+
+ @set foo
+
+without specifying a string, the value of `foo' is an empty string.
+
+ If you clear a previously set flag with an `@clear FLAG' command, a
+subsequent `@value{flag}' command is invalid and the string is replaced
+with an error message that says `{No value for "FLAG"}'.
+
+ For example, if you set `foo' as follows:
+
+ @set how-much very, very, very
+
+then the formatters transform
+
+ It is a @value{how-much} wet day.
+into
+ It is a very, very, very wet day.
+
+ If you write
+
+ @clear how-much
+
+then the formatters transform
+
+ It is a @value{how-much} wet day.
+into
+ It is a {No value for "how-much"} wet day.
+
+\1f
+File: texinfo.info, Node: value Example, Prev: value, Up: set clear value
+
+`@value' Example
+----------------
+
+ You can use the `@value' command to limit the number of places you
+need to change when you record an update to a manual. Here is how it
+is done in `The GNU Make Manual':
+
+Set the flags:
+
+ @set EDITION 0.35 Beta
+ @set VERSION 3.63 Beta
+ @set UPDATED 14 August 1992
+ @set UPDATE-MONTH August 1992
+
+Write text for the first `@ifinfo' section, for people reading the
+Texinfo file:
+
+ This is Edition @value{EDITION},
+ last updated @value{UPDATED},
+ of @cite{The GNU Make Manual},
+ for @code{make}, Version @value{VERSION}.
+
+Write text for the title page, for people reading the printed manual:
+
+ @title GNU Make
+ @subtitle A Program for Directing Recompilation
+ @subtitle Edition @value{EDITION}, ...
+ @subtitle @value{UPDATE-MONTH}
+
+(On a printed cover, a date listing the month and the year looks less
+fussy than a date listing the day as well as the month and year.)
+
+Write text for the Top node, for people reading the Info file:
+
+ This is Edition @value{EDITION}
+ of the @cite{GNU Make Manual},
+ last updated @value{UPDATED}
+ for @code{make} Version @value{VERSION}.
+
+ After you format the manual, the text in the first `@ifinfo' section
+looks like this:
+
+ This is Edition 0.35 Beta, last updated 14 August 1992,
+ of `The GNU Make Manual', for `make', Version 3.63 Beta.
+
+ When you update the manual, change only the values of the flags; you
+do not need to rewrite the three sections.
+
+\1f
+File: texinfo.info, Node: Macros, Next: Format/Print Hardcopy, Prev: Conditionals, Up: Top
+
+Macros: Defining New Texinfo Commands
+*************************************
+
+ A Texinfo "macro" allows you to define a new Texinfo command as any
+sequence of text and/or existing commands (including other macros). The
+macro can have any number of "parameters"--text you supply each time
+you use the macro. (This has nothing to do with the `@defmac' command,
+which is for documenting macros in the subject of the manual; *note Def
+Cmd Template::..)
+
+* Menu:
+
+* Defining Macros:: Both defining and undefining new commands.
+* Invoking Macros:: Using a macro, once you've defined it.
+
+\1f
+File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Prev: Macros, Up: Macros
+
+Defining Macros
+===============
+
+ You use the Texinfo `@macro' command to define a macro. For example:
+
+ @macro MACRO-NAME{PARAM1, PARAM2, ...}
+ TEXT ... \PARAM1\ ...
+ @end macro
+
+ The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
+when the macro is subsequently used in the document (see the next
+section).
+
+ If a macro needs no parameters, you can define it either with an empty
+list (`@macro foo {}') or with no braces at all (`@macro foo').
+
+ The definition or "body" of the macro can contain any Texinfo
+commands, including previously-defined macros. (It is not possible to
+have mutually recursive Texinfo macros.) In the body, instances of a
+parameter name surrounded by backslashes, as in `\PARAM1\' in the
+example above, are replaced by the corresponding argument from the
+macro invocation.
+
+ You can undefine a macro FOO with `@unmacro FOO'. It is not an error
+to undefine a macro that is already undefined. For example:
+
+ @unmacro foo
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Invoking Macros, Prev: Defining Macros, Up: Macros
+
+Invoking Macros
+===============
+
+ After a macro is defined (see the previous section), you can use
+("invoke") it in your document like this:
+
+ @MACRO-NAME {ARG1, ARG2, ...}
+
+and the result will be just as if you typed the body of MACRO-NAME at
+that spot. For example:
+
+ @macro foo {p, q}
+ Together: \p\ & \q\.
+ @end macro
+ @foo{a, b}
+
+produces:
+
+ Together: a & b.
+
+ Thus, the arguments and parameters are separated by commas and
+delimited by braces; any whitespace after (but not before) a comma is
+ignored. To insert a comma, brace, or backslash in an argument,
+prepend a backslash, as in
+
+ @MACRO-NAME {\\\{\}\,}
+
+which will pass the (almost certainly error-producing) argument `\{},'
+to MACRO-NAME.
+
+ If the macro is defined to take a single argument, and is invoked
+without any braces, the entire rest of the line after the macro name is
+supplied as the argument. For example:
+
+ @macro bar {p}
+ Twice: \p\, \p\.
+ @end macro
+ @bar aah
+
+produces:
+
+ Twice: aah, aah.
+
+\1f
+File: texinfo.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Macros, Up: Top
+
+Format and Print Hardcopy
+*************************
+
+ There are three major shell commands for making a printed manual from
+a Texinfo file: one for converting the Texinfo file into a file that
+will be printed, a second for sorting indices, and a third for printing
+the formatted document. When you use the shell commands, you can either
+work directly in the operating system shell or work within a shell
+inside GNU Emacs.
+
+ If you are using GNU Emacs, you can use commands provided by Texinfo
+mode instead of shell commands. In addition to the three commands to
+format a file, sort the indices, and print the result, Texinfo mode
+offers key bindings for commands to recenter the output buffer, show the
+print queue, and delete a job from the print queue.
+
+* Menu:
+
+* Use TeX:: Use TeX to format for hardcopy.
+* Format with tex/texindex:: How to format in a shell.
+* Format with texi2dvi:: A simpler way to use the shell.
+* Print with lpr:: How to print.
+* Within Emacs:: How to format and print from an Emacs shell.
+* Texinfo Mode Printing:: How to format and print in Texinfo mode.
+* Compile-Command:: How to print using Emacs's compile command.
+* Requirements Summary:: TeX formatting requirements summary.
+* Preparing for TeX:: What you need to do to use TeX.
+* Overfull hboxes:: What are and what to do with overfull hboxes.
+* smallbook:: How to print small format books and manuals.
+* A4 Paper:: How to print on European A4 paper.
+* Cropmarks and Magnification:: How to print marks to indicate the size
+ of pages and how to print scaled up output.
+
+\1f
+File: texinfo.info, Node: Use TeX, Next: Format with tex/texindex, Prev: Format/Print Hardcopy, Up: Format/Print Hardcopy
+
+Use TeX
+=======
+
+ The typesetting program called TeX is used for formatting a Texinfo
+file. TeX is a very powerful typesetting program and, if used right,
+does an exceptionally good job. (*Note How to Obtain TeX: Obtaining
+TeX, for information on how to obtain TeX.)
+
+ The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer'
+commands read the very same @-commands in the Texinfo file as does TeX,
+but process them differently to make an Info file; see *Note Create an
+Info File::.
+
+\1f
+File: texinfo.info, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Format/Print Hardcopy
+
+Format using `tex' and `texindex'
+=================================
+
+ Format the Texinfo file with the shell command `tex' followed by the
+name of the Texinfo file. For example:
+
+ tex foo.texi
+
+TeX will produce a "DVI file" as well as several auxiliary files
+containing information for indices, cross references, etc. The DVI
+file (for "DeVice Independent" file) can be printed on virtually any
+printe (see the following sections).
+
+ The `tex' formatting command itself does not sort the indices; it
+writes an output file of unsorted index data. (The `texi2dvi' command
+automatically generates indices; see *Note Format using `texi2dvi':
+Format with texi2dvi.) To generate a printed index after running the
+`tex' command, you first need a sorted index to work from. The
+`texindex' command sorts indices. (The source file `texindex.c' comes
+as part of the standard Texinfo distribution, among other places.)
+
+ The `tex' formatting command outputs unsorted index files under names
+that obey a standard convention: the name of your main input file with
+any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.)
+extension removed, followed by the two letter names of indices. For
+example, the raw index output files for the input file `foo.texinfo'
+would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.
+Those are exactly the arguments to give to `texindex'.
+
+ Instead of specifying all the unsorted index file names explicitly,
+you can use `??' as shell wildcards and give the command in this form:
+
+ texindex foo.??
+
+This command will run `texindex' on all the unsorted index files,
+including any that you have defined yourself using `@defindex' or
+`@defcodeindex'. (You may execute `texindex foo.??' even if there are
+similarly named files with two letter extensions that are not index
+files, such as `foo.el'. The `texindex' command reports but otherwise
+ignores such files.)
+
+ For each file specified, `texindex' generates a sorted index file
+whose name is made by appending `s' to the input file name. The
+`@printindex' command knows to look for a file of that name (*note
+Printing Indices & Menus::.). `texindex' does not alter the raw index
+output file.
+
+ After you have sorted the indices, you need to rerun the `tex'
+formatting command on the Texinfo file. This regenerates the DVI file,
+this time with up-to-date index entries.
+
+ Finally, you may need to run `tex' one more time, to get the page
+numbers in the cross-references correct.
+
+ To summarize, this is a four step process:
+
+ 1. Run `tex' on your Texinfo file. This generates a DVI file (with
+ undefined cross-references and no indices), and the raw index files
+ (with two letter extensions).
+
+ 2. Run `texindex' on the raw index files. This creates the
+ corresponding sorted index files (with three letter extensions).
+
+ 3. Run `tex' again on your Texinfo file. This regenerates the DVI
+ file, this time with indices and defined cross-references, but
+ with page numbers for the cross-references from last time,
+ generally incorrect.
+
+ 4. Run `tex' one last time. This time the correct page numbers are
+ written for the cross-references.
+
+ Alternatively, it's a one-step process: run `texi2dvi'.
+
+ You need not run `texindex' each time after you run `tex'. If you do
+not, on the next run, the `tex' formatting command will use whatever
+sorted index files happen to exist from the previous use of `texindex'.
+This is usually ok while you are debugging.
+
+\1f
+File: texinfo.info, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Format/Print Hardcopy
+
+Format using `texi2dvi'
+=======================
+
+ The `texi2dvi' command automatically runs both `tex' and `texindex'
+as many times as necessary to produce a DVI file with up-to-date,
+sorted indices. It simplifies the `tex'--`texindex'--`tex' sequence
+described in the previous section.
+
+ The syntax for `texi2dvi' is like this (where `prompt$' is your shell
+prompt):
+
+ prompt$ texi2dvi FILENAME...
+
+ For a list of options, run `texi2dvi --help'.
+
+\1f
+File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Format/Print Hardcopy
+
+Shell Print Using `lpr -d'
+==========================
+
+ The precise command to print a DVI file depends on your system
+installation, but `lpr -d' is common. The command may require the DVI
+file name without any extension or with a `.dvi' extension. (If it is
+`lpr', you must include the `.dvi'.)
+
+ The following commands, for example, will (probably) suffice to sort
+the indices, format, and print the `Bison Manual':
+
+ tex bison.texinfo
+ texindex bison.??
+ tex bison.texinfo
+ lpr -d bison.dvi
+
+(Remember that the shell commands may be different at your site; but
+these are commonly used versions.)
+
+ Using the `texi2dvi' shell script, you simply need type:
+
+ texi2dvi bison.texinfo
+ lpr -d bison.dvi
+
+\1f
+File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Format/Print Hardcopy
+
+From an Emacs Shell
+===================
+
+ You can give formatting and printing commands from a shell within GNU
+Emacs. To create a shell within Emacs, type `M-x shell'. In this
+shell, you can format and print the document. *Note Format and Print
+Hardcopy: Format/Print Hardcopy, for details.
+
+ You can switch to and from the shell buffer while `tex' is running
+and do other editing. If you are formatting a long document on a slow
+machine, this can be very convenient.
+
+ You can also use `texi2dvi' from an Emacs shell. For example, here
+is how to use `texi2dvi' to format and print `Using and Porting GNU CC'
+from a shell within Emacs:
+
+ texi2dvi gcc.texinfo
+ lpr -d gcc.dvi
+
+ *Note Texinfo Mode Printing::, for more information about formatting
+and printing in Texinfo mode.
+
+\1f
+File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy
+
+Formatting and Printing in Texinfo Mode
+=======================================
+
+ Texinfo mode provides several predefined key commands for TeX
+formatting and printing. These include commands for sorting indices,
+looking at the printer queue, killing the formatting job, and
+recentering the display of the buffer in which the operations occur.
+
+`C-c C-t C-b'
+`M-x texinfo-tex-buffer'
+ Run `texi2dvi' on the current buffer.
+
+`C-c C-t C-r'
+`M-x texinfo-tex-region'
+ Run TeX on the current region.
+
+`C-c C-t C-i'
+`M-x texinfo-texindex'
+ Sort the indices of a Texinfo file formatted with
+ `texinfo-tex-region'.
+
+`C-c C-t C-p'
+`M-x texinfo-tex-print'
+ Print a DVI file that was made with `texinfo-tex-region' or
+ `texinfo-tex-buffer'.
+
+`C-c C-t C-q'
+`M-x tex-show-print-queue'
+ Show the print queue.
+
+`C-c C-t C-d'
+`M-x texinfo-delete-from-print-queue'
+ Delete a job from the print queue; you will be prompted for the job
+ number shown by a preceding `C-c C-t C-q' command
+ (`texinfo-show-tex-print-queue').
+
+`C-c C-t C-k'
+`M-x tex-kill-job'
+ Kill the currently running TeX job started by `texinfo-tex-region'
+ or `texinfo-tex-buffer', or any other process running in the
+ Texinfo shell buffer.
+
+`C-c C-t C-x'
+`M-x texinfo-quit-job'
+ Quit a TeX formatting job that has stopped because of an error by
+ sending an <x> to it. When you do this, TeX preserves a record of
+ what it did in a `.log' file.
+
+`C-c C-t C-l'
+`M-x tex-recenter-output-buffer'
+ Redisplay the shell buffer in which the TeX printing and formatting
+ commands are run to show its most recent output.
+
+ Thus, the usual sequence of commands for formatting a buffer is as
+follows (with comments to the right):
+
+ C-c C-t C-b Run `texi2dvi' on the buffer.
+ C-c C-t C-p Print the DVI file.
+ C-c C-t C-q Display the printer queue.
+
+ The Texinfo mode TeX formatting commands start a subshell in Emacs
+called the `*tex-shell*'. The `texinfo-tex-command',
+`texinfo-texindex-command', and `tex-dvi-print-command' commands are
+all run in this shell.
+
+ You can watch the commands operate in the `*tex-shell*' buffer, and
+you can switch to and from and use the `*tex-shell*' buffer as you
+would any other shell buffer.
+
+ The formatting and print commands depend on the values of several
+variables. The default values are:
+
+ Variable Default value
+
+ texinfo-texi2dvi-command "texi2dvi"
+ texinfo-tex-command "tex"
+ texinfo-texindex-command "texindex"
+ texinfo-delete-from-print-queue-command "lprm"
+ texinfo-tex-trailer "@bye"
+ tex-start-of-header "%**start"
+ tex-end-of-header "%**end"
+ tex-dvi-print-command "lpr -d"
+ tex-show-queue-command "lpq"
+
+ You can change the values of these variables with the `M-x
+edit-options' command (*note Editing Variable Values: (xemacs)Edit
+Options.), with the `M-x set-variable' command (*note Examining and
+Setting Variables: (xemacs)Examining.), or with your `.emacs'
+initialization file (*note Init File: (xemacs)Init File.).
+
+\1f
+File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy
+
+Using the Local Variables List
+==============================
+
+ Yet another way to apply the TeX formatting command to a Texinfo file
+is to put that command in a "local variables list" at the end of the
+Texinfo file. You can then specify the `tex' or `texi2dvi' commands as
+a `compile-command' and have Emacs run it by typing `M-x compile'.
+This creates a special shell called the `*compilation*' buffer in which
+Emacs runs the compile command. For example, at the end of the
+`gdb.texinfo' file, after the `@bye', you could put the following:
+
+ Local Variables:
+ compile-command: "texi2dvi gdb.texinfo"
+ End:
+
+This technique is most often used by programmers who also compile
+programs this way; see *Note Compilation: (xemacs)Compilation.
+
+\1f
+File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy
+
+TeX Formatting Requirements Summary
+===================================
+
+ Every Texinfo file that is to be input to TeX must begin with a
+`\input' command and must contain an `@setfilename' command:
+
+ \input texinfo
+ @setfilename ARG-NOT-USED-BY-@TEX{}
+
+The first command instructs TeX to load the macros it needs to process
+a Texinfo file and the second command opens auxiliary files.
+
+ Every Texinfo file must end with a line that terminates TeX's
+processing and forces out unfinished pages:
+
+ @bye
+
+ Strictly speaking, these lines are all a Texinfo file needs to be
+processed successfully by TeX.
+
+ Usually, however, the beginning includes an `@settitle' command to
+define the title of the printed manual, an `@setchapternewpage'
+command, a title page, a copyright page, and permissions. Besides an
+`@bye', the end of a file usually includes indices and a table of
+contents. (And of course most manuals contain a body of text as well.)
+
+For more information, see
+*Note `@settitle': settitle,
+*Note `@setchapternewpage': setchapternewpage,
+*Note Page Headings: Headings,
+*Note Titlepage & Copyright Page::,
+*Note Printing Indices & Menus::, and
+*Note Contents::.
+
+\1f
+File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy
+
+Preparing to Use TeX
+====================
+
+TeX needs to know where to find the `texinfo.tex' file that you have
+told it to input with the `\input texinfo' command at the beginning of
+the first line. The `texinfo.tex' file tells TeX how to handle
+@-commands; it is included in all standard GNU distributions.
+
+ Usually, the `texinfo.tex' file is put under the default directory
+that contains TeX macros
+(`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when GNU
+Emacs or other GNU software is installed. In this case, TeX will find
+the file and you do not need to do anything special. Alternatively,
+you can put `texinfo.tex' in the current directory when you run TeX,
+and TeX will find it there.
+
+ Also, you should install `epsf.tex' in the same place as
+`texinfo.tex', if it is not already installed from another
+distribution. This file is needed to support the `@image' command
+(*note Images::.).
+
+ Optionally, you may create an additional `texinfo.cnf', and install
+it as well. This file is read by TeX at the `@setfilename' command
+(*note `@setfilename': setfilename.). You can put any commands you
+like there according to local site-wide conventions, and they will be
+read by TeX when processing any Texinfo document. For example, if
+`texinfo.cnf' contains the a single line `@afourpaper' (*note A4
+Paper::.), then all Texinfo documents will be processed with that page
+size in effect. If you have nothing to put in `texinfo.cnf', you do
+not need to create it.
+
+ If neither of the above locations for these system files suffice for
+you, you can specify the directories explicitly. For `texinfo.tex',
+you can do this by writing the complete path for the file after the
+`\input' command. Another way, that works for both `texinfo.tex' and
+`texinfo.cnf' (and any other file TeX might read), is to set the
+`TEXINPUTS' environment variable in your `.cshrc' or `.profile' file.
+
+ Which you use of `.cshrc' or `.profile' depends on whether you use a
+Bourne shell-compatible (`sh', `bash', `ksh', ...) or C
+shell-compatible (`csh', `tcsh') command interpreter. The latter read
+the `.cshrc' file for initialization information, and the former read
+`.profile'.
+
+ In a `.cshrc' file, you could use the following `csh' command
+sequence:
+
+ setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
+
+ In a `.profile' file, you could use the following `sh' command
+sequence:
+
+ TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
+ export TEXINPUTS
+
+This would cause TeX to look for `\input' file first in the current
+directory, indicated by the `.', then in a hypothetical user's
+`me/mylib' directory, and finally in a system directory.
+
+\1f
+File: texinfo.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy
+
+Overfull "hboxes"
+=================
+
+ TeX is sometimes unable to typeset a line without extending it into
+the right margin. This can occur when TeX comes upon what it
+interprets as a long word that it cannot hyphenate, such as an
+electronic mail network address or a very long title. When this
+happens, TeX prints an error message like this:
+
+ Overfull \hbox (20.76302pt too wide)
+
+(In TeX, lines are in "horizontal boxes", hence the term, "hbox". The
+backslash, `\', is the TeX equivalent of `@'.)
+
+ TeX also provides the line number in the Texinfo source file and the
+text of the offending line, which is marked at all the places that TeX
+knows how to hyphenate words. *Note Catching Errors with TeX
+Formatting: Debugging with TeX, for more information about typesetting
+errors.
+
+ If the Texinfo file has an overfull hbox, you can rewrite the sentence
+so the overfull hbox does not occur, or you can decide to leave it. A
+small excursion into the right margin often does not matter and may not
+even be noticeable.
+
+ However, unless told otherwise, TeX will print a large, ugly, black
+rectangle beside the line that contains the overfull hbox. This is so
+you will notice the location of the problem if you are correcting a
+draft.
+
+ To prevent such a monstrosity from marring your final printout, write
+the following in the beginning of the Texinfo file on a line of its own,
+before the `@titlepage' command:
+
+ @finalout
+
+\1f
+File: texinfo.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy
+
+Printing "Small" Books
+======================
+
+ By default, TeX typesets pages for printing in an 8.5 by 11 inch
+format. However, you can direct TeX to typeset a document in a 7 by
+9.25 inch format that is suitable for bound books by inserting the
+following command on a line by itself at the beginning of the Texinfo
+file, before the title page:
+
+ @smallbook
+
+(Since regular sized books are often about 7 by 9.25 inches, this
+command might better have been called the `@regularbooksize' command,
+but it came to be called the `@smallbook' command by comparison to the
+8.5 by 11 inch format.)
+
+ If you write the `@smallbook' command between the start-of-header and
+end-of-header lines, the Texinfo mode TeX region formatting command,
+`texinfo-tex-region', will format the region in "small" book size
+(*note Start of Header::.).
+
+ The Free Software Foundation distributes printed copies of `The GNU
+Emacs Manual' and other manuals in the "small" book size. *Note
+`@smallexample' and `@smalllisp': smallexample & smalllisp, for
+information about commands that make it easier to produce examples for
+a smaller manual.
+
+ Alternatively, to avoid embedding this physical paper size in your
+document, use `texi2dvi' to format your document (*note Format with
+texi2dvi::.), and supply `-t @smallbook' as an argument. Then other
+people do not have to change the document source file to format it
+differently.
+
+\1f
+File: texinfo.info, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy
+
+Printing on A4 Paper
+====================
+
+ You can tell TeX to typeset a document for printing on European size
+A4 paper with the `@afourpaper' command. Write the command on a line
+by itself between `@iftex' and `@end iftex' lines near the beginning of
+the Texinfo file, before the title page:
+
+ For example, this is how you would write the header for this manual:
+
+ \input texinfo @c -*-texinfo-*-
+ @c %**start of header
+ @setfilename texinfo
+ @settitle Texinfo
+ @syncodeindex vr fn
+ @iftex
+ @afourpaper
+ @end iftex
+ @c %**end of header
+
+ Alternatively, to avoid embedding this physical paper size in your
+document, use `texi2dvi' to format your document (*note Format with
+texi2dvi::.), and supply `-t @afourpaper' as an argument. Then other
+people do not have to change the document source file to format it
+differently.
+
+ Another alternative: put the `@afourpaper' command in the file
+`texinfo.cnf' that TeX will read. (No need for `@iftex' there.) This
+will automatically typeset all the Texinfo documents at your site with
+that paper size in effect.
+
+\1f
+File: texinfo.info, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy
+
+Cropmarks and Magnification
+===========================
+
+ You can attempt to direct TeX to print cropmarks at the corners of
+pages with the `@cropmarks' command. Write the `@cropmarks' command on
+a line by itself between `@iftex' and `@end iftex' lines near the
+beginning of the Texinfo file, before the title page, like this:
+
+ @iftex
+ @cropmarks
+ @end iftex
+
+ This command is mainly for printers that typeset several pages on one
+sheet of film; but you can attempt to use it to mark the corners of a
+book set to 7 by 9.25 inches with the `@smallbook' command. (Printers
+will not produce cropmarks for regular sized output that is printed on
+regular sized paper.) Since different printing machines work in
+different ways, you should explore the use of this command with a
+spirit of adventure. You may have to redefine the command in the
+`texinfo.tex' definitions file.
+
+ You can attempt to direct TeX to typeset pages larger or smaller than
+usual with the `\mag' TeX command. Everything that is typeset is
+scaled proportionally larger or smaller. (`\mag' stands for
+"magnification".) This is *not* a Texinfo @-command, but is a plain
+TeX command that is prefixed with a backslash. You have to write this
+command between `@tex' and `@end tex' (*note Raw Formatter Commands::.).
+
+ Follow the `\mag' command with an `=' and then a number that is 1000
+times the magnification you desire. For example, to print pages at 1.2
+normal size, write the following near the beginning of the Texinfo
+file, before the title page:
+
+ @tex
+ \mag=1200
+ @end tex
+
+ With some printing technologies, you can print normal-sized copies
+that look better than usual by using a larger-than-normal master.
+
+ Depending on your system, `\mag' may not work or may work only at
+certain magnifications. Be prepared to experiment.
+
+\1f
+File: texinfo.info, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top
+
+Creating an Info File
+*********************
+
+ `makeinfo' is a utility that converts a Texinfo file into an Info
+file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
+functions that do the same.
+
+ A Texinfo file must contain an `@setfilename' line near its
+beginning, otherwise the Info formatting commands will fail.
+
+ For information on installing the Info file in the Info system, see
+*Note Install an Info File::.
+
+* Menu:
+
+* makeinfo advantages:: `makeinfo' provides better error checking.
+* Invoking makeinfo:: How to run `makeinfo' from a shell.
+* makeinfo options:: Specify fill-column and other options.
+* Pointer Validation:: How to check that pointers point somewhere.
+* makeinfo in Emacs:: How to run `makeinfo' from Emacs.
+* texinfo-format commands:: Two Info formatting commands written
+ in Emacs Lisp are an alternative
+ to `makeinfo'.
+* Batch Formatting:: How to format for Info in Emacs Batch mode.
+* Tag and Split Files:: How tagged and split files help Info
+ to run better.
+
+\1f
+File: texinfo.info, Node: makeinfo advantages, Next: Invoking makeinfo, Prev: Create an Info File, Up: Create an Info File
+
+`makeinfo' Preferred
+====================
+
+ The `makeinfo' utility creates an Info file from a Texinfo source
+file more quickly than either of the Emacs formatting commands and
+provides better error messages. We recommend it. `makeinfo' is a C
+program that is independent of Emacs. You do not need to run Emacs to
+use `makeinfo', which means you can use `makeinfo' on machines that are
+too small to run Emacs. You can run `makeinfo' in any one of three
+ways: from an operating system shell, from a shell inside Emacs, or by
+typing a key command in Texinfo mode in Emacs.
+
+ The `texinfo-format-region' and the `texinfo-format-buffer' commands
+are useful if you cannot run `makeinfo'. Also, in some circumstances,
+they format short regions or buffers more quickly than `makeinfo'.
+
+\1f
+File: texinfo.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File
+
+Running `makeinfo' from a Shell
+===============================
+
+ To create an Info file from a Texinfo file, type `makeinfo' followed
+by the name of the Texinfo file. Thus, to create the Info file for
+Bison, type the following to the shell: is the prompt):
+
+ makeinfo bison.texinfo
+
+ (You can run a shell inside Emacs by typing `M-x shell'.)
+
+ Sometimes you will want to specify options. For example, if you wish
+to discover which version of `makeinfo' you are using, type:
+
+ makeinfo --version
+
+ *Note makeinfo options::, for more information.
+
+\1f
+File: texinfo.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File
+
+Options for `makeinfo'
+======================
+
+ The `makeinfo' command takes a number of options. Most often,
+options are used to set the value of the fill column and specify the
+footnote style. Each command line option is a word preceded by `--' or
+a letter preceded by `-'. You can use abbreviations for the long
+option names as long as they are unique.
+
+ For example, you could use the following shell command to create an
+Info file for `bison.texinfo' in which each line is filled to only 68
+columns:
+
+ makeinfo --fill-column=68 bison.texinfo
+
+ You can write two or more options in sequence, like this:
+
+ makeinfo --no-split --fill-column=70 ...
+
+This would keep the Info file together as one possibly very long file
+and would also set the fill column to 70.
+
+ The options are:
+
+`-D VAR'
+ Cause the variable VAR to be defined. This is equivalent to `@set
+ VAR' in the Texinfo file (*note set clear value::.).
+
+`--error-limit=LIMIT'
+ Set the maximum number of errors that `makeinfo' will report
+ before exiting (on the assumption that continuing would be
+ useless); default 100.
+
+`--fill-column=WIDTH'
+ Specify the maximum number of columns in a line; this is the
+ right-hand edge of a line. Paragraphs that are filled will be
+ filled to this width. (Filling is the process of breaking up and
+ connecting lines so that lines are the same length as or shorter
+ than the number specified as the fill column. Lines are broken
+ between words.) The default value is 72.
+
+`--footnote-style=STYLE'
+ Set the footnote style to STYLE, either `end' for the end node
+ style (the default) or `separate' for the separate node style.
+ The value set by this option overrides the value set in a Texinfo
+ file by an `@footnotestyle' command (*note Footnotes::.). When the
+ footnote style is `separate', `makeinfo' makes a new node
+ containing the footnotes found in the current node. When the
+ footnote style is `end', `makeinfo' places the footnote references
+ at the end of the current node.
+
+`--force'
+ Ordinarily, if the input file has errors, the output files are not
+ created. With this option, they are preserved.
+
+`--help'
+ Print a usage message listing all available options, then exit
+ successfully.
+
+`-I DIR'
+ Add `dir' to the directory search list for finding files that are
+ included using the `@include' command. By default, `makeinfo'
+ searches only the current directory.
+
+`--no-headers'
+ Do not include menus or node lines in the output. This results in
+ an ASCII file that you cannot read in Info since it does not
+ contain the requisite nodes or menus. It is primarily useful to
+ extract certain pieces of a manual into separate files to be
+ included in a distribution, such as `INSTALL' files.
+
+`--no-split'
+ Suppress the splitting stage of `makeinfo'. By default, large
+ output files (where the size is greater than 70k bytes) are split
+ into smaller subfiles, each one approximately 50k bytes.
+
+`--no-pointer-validate'
+`--no-validate'
+ Suppress the pointer-validation phase of `makeinfo'. Normally,
+ after a Texinfo file is processed, some consistency checks are
+ made to ensure that cross references can be resolved, etc. *Note
+ Pointer Validation::.
+
+`--no-warn'
+ Suppress warning messages (but *not* error messages). You might
+ want this if the file you are creating has examples of Texinfo
+ cross references within it, and the nodes that are referenced do
+ not actually exist.
+
+`--no-number-footnotes'
+ Suppress automatic footnote numbering. By default, `makeinfo'
+ numbers each footnote sequentially in a single node, resetting the
+ current footnote number to 1 at the start of each node.
+
+`--output=FILE'
+`-o FILE'
+ Specify that the output should be directed to FILE and not to the
+ file name specified in the `@setfilename' command found in the
+ Texinfo source (*note setfilename::.). If FILE is `-', output
+ goes to standard output and `--no-split' is implied.
+
+`-P DIR'
+ Prepend `dir' to the directory search list for `@include'. See
+ `-I' for more details.
+
+`--paragraph-indent=INDENT'
+ Set the paragraph indentation style to INDENT. The value set by
+ this option overrides the value set in a Texinfo file by an
+ `@paragraphindent' command (*note paragraphindent::.). The value
+ of INDENT is interpreted as follows:
+
+ `asis'
+ Preserve any existing indentation at the starts of paragraphs.
+
+ `0' or `none'
+ Delete any existing indentation.
+
+ NUM
+ Indent each paragraph by that number of spaces.
+
+`--reference-limit=LIMIT'
+ Set the value of the number of references to a node that
+ `makeinfo' will make without reporting a warning. If a node has
+ more than this number of references in it, `makeinfo' will make the
+ references but also report a warning. The default is 1000.
+
+`-U VAR'
+ Cause VAR to be undefined. This is equivalent to `@clear VAR' in
+ the Texinfo file (*note set clear value::.).
+
+`--verbose'
+ Cause `makeinfo' to display messages saying what it is doing.
+ Normally, `makeinfo' only outputs messages if there are errors or
+ warnings.
+
+`--version'
+ Print the version number, then exit successfully.
+
+\1f
+File: texinfo.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File
+
+Pointer Validation
+==================
+
+ If you do not suppress pointer-validation, `makeinfo' will check the
+validity of the final Info file. Mostly, this means ensuring that
+nodes you have referenced really exist. Here is a complete list of what
+is checked:
+
+ 1. If a `Next', `Previous', or `Up' node reference is a reference to a
+ node in the current file and is not an external reference such as
+ to `(dir)', then the referenced node must exist.
+
+ 2. In every node, if the `Previous' node is different from the `Up'
+ node, then the `Previous' node must also be pointed to by a `Next'
+ node.
+
+ 3. Every node except the `Top' node must have an `Up' pointer.
+
+ 4. The node referenced by an `Up' pointer must contain a reference to
+ the current node in some manner other than through a `Next'
+ reference. This includes menu entries and cross references.
+
+ 5. If the `Next' reference of a node is not the same as the `Next'
+ reference of the `Up' reference, then the node referenced by the
+ `Next' pointer must have a `Previous' pointer that points back to
+ the current node. This rule allows the last node in a section to
+ point to the first node of the next chapter.
+
+\1f
+File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File
+
+Running `makeinfo' inside Emacs
+===============================
+
+ You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
+`makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode,
+the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
+
+`C-c C-m C-r'
+`M-x makeinfo-region'
+ Format the current region for Info.
+
+`C-c C-m C-b'
+`M-x makeinfo-buffer'
+ Format the current buffer for Info.
+
+ When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
+prompts for a file name, offering the name of the visited file as the
+default. You can edit the default file name in the minibuffer if you
+wish, before pressing <RET> to start the `makeinfo' process.
+
+ The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
+`makeinfo' program in a temporary shell buffer. If `makeinfo' finds
+any errors, Emacs displays the error messages in the temporary buffer.
+
+ You can parse the error messages by typing `C-x `' (`next-error').
+This causes Emacs to go to and position the cursor on the line in the
+Texinfo source that `makeinfo' thinks caused the error. *Note Running
+`make' or Compilers Generally: (xemacs)Compilation, for more
+information about using the `next-error' command.
+
+ In addition, you can kill the shell in which the `makeinfo' command
+is running or make the shell buffer display its most recent output.
+
+`C-c C-m C-k'
+`M-x makeinfo-kill-job'
+ Kill the current running `makeinfo' job created by
+ `makeinfo-region' or `makeinfo-buffer'.
+
+`C-c C-m C-l'
+`M-x makeinfo-recenter-output-buffer'
+ Redisplay the `makeinfo' shell buffer to display its most recent
+ output.
+
+(Note that the parallel commands for killing and recentering a TeX job
+are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.)
+
+ You can specify options for `makeinfo' by setting the
+`makeinfo-options' variable with either the `M-x edit-options' or the
+`M-x set-variable' command, or by setting the variable in your `.emacs'
+initialization file.
+
+ For example, you could write the following in your `.emacs' file:
+
+ (setq makeinfo-options
+ "--paragraph-indent=0 --no-split
+ --fill-column=70 --verbose")
+
+For more information, see
+*Note Editing Variable Values: (xemacs)Edit Options,
+*Note Examining and Setting Variables: (xemacs)Examining,
+*Note Init File: (xemacs)Init File, and
+*Note Options for `makeinfo': makeinfo options.
+
+\1f
+File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File
+
+The `texinfo-format...' Commands
+================================
+
+In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
+file with the `texinfo-format-region' command. This formats the
+current region and displays the formatted text in a temporary buffer
+called `*Info Region*'.
+
+ Similarly, you can format a buffer with the `texinfo-format-buffer'
+command. This command creates a new buffer and generates the Info file
+in it. Typing `C-x C-s' will save the Info file under the name
+specified by the `@setfilename' line which must be near the beginning
+of the Texinfo file.
+
+`C-c C-e C-r'
+``texinfo-format-region''
+ Format the current region for Info.
+
+`C-c C-e C-b'
+``texinfo-format-buffer''
+ Format the current buffer for Info.
+
+ The `texinfo-format-region' and `texinfo-format-buffer' commands
+provide you with some error checking, and other functions can provide
+you with further help in finding formatting errors. These procedures
+are described in an appendix; see *Note Catching Mistakes::. However,
+the `makeinfo' program is often faster and provides better error
+checking (*note makeinfo in Emacs::.).
+
+\1f
+File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Create an Info File
+
+Batch Formatting
+================
+
+ You can format Texinfo files for Info using `batch-texinfo-format'
+and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
+including a shell inside of Emacs. (*Note Command Line Switches and
+Arguments: (xemacs)Command Switches.)
+
+ Here is a shell command to format all the files that end in
+`.texinfo' in the current directory:
+
+ emacs -batch -funcall batch-texinfo-format *.texinfo
+
+Emacs processes all the files listed on the command line, even if an
+error occurs while attempting to format some of them.
+
+ Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
+is not interactive. It kills the Batch mode Emacs on completion.
+
+ `batch-texinfo-format' is convenient if you lack `makeinfo' and want
+to format several Texinfo files at once. When you use Batch mode, you
+create a new Emacs process. This frees your current Emacs, so you can
+continue working in it. (When you run `texinfo-format-region' or
+`texinfo-format-buffer', you cannot use that Emacs for anything else
+until the command finishes.)
+
+\1f
+File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Create an Info File
+
+Tag Files and Split Files
+=========================
+
+ If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
+automatically creates a tag table for its Info file; `makeinfo' always
+creates a tag table. With a "tag table", Info can jump to new nodes
+more quickly than it can otherwise.
+
+ In addition, if the Texinfo file contains more than about 70,000
+bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
+into shorter "indirect" subfiles of about 50,000 bytes each. Big files
+are split into smaller files so that Emacs does not need to make a
+large buffer to hold the whole of a large Info file; instead, Emacs
+allocates just enough memory for the small, split off file that is
+needed at the time. This way, Emacs avoids wasting memory when you run
+Info. (Before splitting was implemented, Info files were always kept
+short and "include files" were designed as a way to create a single,
+large printed manual out of the smaller Info files. *Note Include
+Files::, for more information. Include files are still used for very
+large documents, such as `The XEmacs Lisp Reference Manual', in which
+each chapter is a separate file.)
+
+ When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off. The split off files are called
+"indirect" files.
+
+ The split off files have names that are created by appending `-1',
+`-2', `-3' and so on to the file name specified by the `@setfilename'
+command. The shortened version of the original file continues to have
+the name specified by `@setfilename'.
+
+ At one stage in writing this document, for example, the Info file was
+saved as `test-texinfo' and that file looked like this:
+
+ Info file: test-texinfo, -*-Text-*-
+ produced by texinfo-format-buffer
+ from file: new-texinfo-manual.texinfo
+
+ ^_
+ Indirect:
+ test-texinfo-1: 102
+ test-texinfo-2: 50422
+ test-texinfo-3: 101300
+ ^_^L
+ Tag table:
+ (Indirect)
+ Node: overview^?104
+ Node: info file^?1271
+ Node: printed manual^?4853
+ Node: conventions^?6855
+ ...
+
+(But `test-texinfo' had far more nodes than are shown here.) Each of
+the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
+`test-texinfo-3', is listed in this file after the line that says
+`Indirect:'. The tag table is listed after the line that says `Tag
+table:'.
+
+ In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect files,
+not counting the file list itself, the tag table, or the permissions
+text in each file. In the tag table, the number following the node name
+records the location of the beginning of the node, in bytes from the
+beginning.
+
+ If you are using `texinfo-format-buffer' to create Info files, you
+may want to run the `Info-validate' command. (The `makeinfo' command
+does such a good job on its own, you do not need `Info-validate'.)
+However, you cannot run the `M-x Info-validate' node-checking command
+on indirect files. For information on how to prevent files from being
+split and how to validate the structure of the nodes, see *Note Using
+Info-validate::.
+
+\1f
+File: texinfo.info, Node: Install an Info File, Next: Command List, Prev: Create an Info File, Up: Top
+
+Installing an Info File
+***********************
+
+ Info files are usually kept in the `info' directory. You can read
+Info files using the standalone Info program or the Info reader built
+into Emacs. (*note info: (info)Top, for an introduction to Info.)
+
+* Menu:
+
+* Directory file:: The top level menu for all Info files.
+* New Info File:: Listing a new info file.
+* Other Info Directories:: How to specify Info files that are
+ located in other directories.
+* Installing Dir Entries:: How to specify what menu entry to add
+ to the Info directory.
+* Invoking install-info:: `install-info' options.
+
+\1f
+File: texinfo.info, Node: Directory file, Next: New Info File, Prev: Install an Info File, Up: Install an Info File
+
+The `dir' File
+==============
+
+ For Info to work, the `info' directory must contain a file that
+serves as a top level directory for the Info system. By convention,
+this file is called `dir'. (You can find the location of this file
+within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
+to see the pathname to the `info' directory.)
+
+ The `dir' file is itself an Info file. It contains the top level
+menu for all the Info files in the system. The menu looks like this:
+
+ * Menu:
+
+ * Info: (info). Documentation browsing system.
+ * Emacs: (emacs). The extensible, self-documenting
+ text editor.
+ * Texinfo: (texinfo). With one source file, make
+ either a printed manual using
+ TeX or an Info file.
+ ...
+
+ Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses. (The menu entry does not need to specify
+the `Top' node, since Info goes to the `Top' node if no node name is
+mentioned. *Note Nodes in Other Info Files: Other Info Files.)
+
+ Thus, the `Info' entry points to the `Top' node of the `info' file
+and the `Emacs' entry points to the `Top' node of the `emacs' file.
+
+ In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the `dir' file. For example, the line for the `Top' node of
+the Emacs manual looks like this in Info:
+
+ File: emacs Node: Top, Up: (DIR), Next: Distrib
+
+(Note that in this case, the `dir' file name is written in upper case
+letters--it can be written in either upper or lower case. Info has a
+feature that it will change the case of the file name to lower case if
+it cannot find the name as written.)
+
+\1f
+File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory file, Up: Install an Info File
+
+Listing a New Info File
+=======================
+
+ To add a new Info file to your system, you must write a menu entry to
+add to the menu in the `dir' file in the `info' directory. For
+example, if you were adding documentation for GDB, you would write the
+following new entry:
+
+ * GDB: (gdb). The source-level C debugger.
+
+The first part of the menu entry is the menu entry name, followed by a
+colon. The second part is the name of the Info file, in parentheses,
+followed by a period. The third part is the description.
+
+ The name of an Info file often has a `.info' extension. Thus, the
+Info file for GDB might be called either `gdb' or `gdb.info'. The Info
+reader programs automatically try the file name both with and without
+`.info'; so it is better to avoid clutter and not to write `.info'
+explicitly in the menu entry. For example, the GDB menu entry should
+use just `gdb' for the file name, not `gdb.info'.
+
+\1f
+File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Install an Info File
+
+Info Files in Other Directories
+===============================
+
+ If an Info file is not in the `info' directory, there are three ways
+to specify its location:
+
+ * Write the pathname in the `dir' file as the second part of the
+ menu.
+
+ * If you are using Emacs, list the name of the file in a second `dir'
+ file, in its directory; and then add the name of that directory to
+ the `Info-directory-list' variable in your personal or site
+ initialization file.
+
+ This tells Emacs where to look for `dir' files. Emacs merges the
+ files named `dir' from each of the listed directories. (In Emacs
+ version 18, you can set the `Info-directory' variable to the name
+ of only one directory.)
+
+ * Specify the Info directory name in the `INFOPATH' environment
+ variable in your `.profile' or `.cshrc' initialization file.
+ (Only you and others who set this environment variable will be
+ able to find Info files whose location is specified this way.)
+
+ For example, to reach a test file in the `/home/bob/manuals'
+directory, you could add an entry like this to the menu in the `dir'
+file:
+
+ * Test: (/home/bob/manuals/info-test). Bob's own test file.
+
+In this case, the absolute file name of the `info-test' file is written
+as the second part of the menu entry.
+
+ Alternatively, you could write the following in your `.emacs' file:
+
+ (setq Info-directory-list
+ '("/home/bob/manuals"
+ "/usr/local/info"))
+
+ This tells Emacs to merge the `dir' file from the `/home/bob/manuals'
+directory with the `dir' file from the `/usr/local/info' directory.
+Info will list the `/home/bob/manuals/info-test' file as a menu entry
+in the `/home/bob/manuals/dir' file.
+
+ Finally, you can tell Info where to look by setting the `INFOPATH'
+environment variable in your `.cshrc' or `.profile' file. If you use a
+Bourne-compatible shell such as `sh' or `bash' for your shell command
+interpreter, you set the `INFOPATH' environment variable in the
+`.profile' initialization file; but if you use `csh' or `tcsh', you
+must set the variable in the `.cshrc' initialization file. The two
+types of shells use different syntax.
+
+ * In a `.cshrc' file, you could set the `INFOPATH' variable as
+ follows:
+
+ setenv INFOPATH .:~/manuals:/usr/local/emacs/info
+
+ * In a `.profile' file, you would achieve the same effect by writing:
+
+ INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
+ export INFOPATH
+
+The `.' indicates the current directory as usual. Emacs uses the
+`INFOPATH' environment variable to initialize the value of Emacs's own
+`Info-directory-list' variable.
+
+ However you set `INFOPATH', if its last character is a colon, this is
+replaced by the default (compiled-in) path. This gives you a way to
+augment the default path with new directories without having to list all
+the standard places. For example (using `sh' syntax:
+
+ INFOPATH=/local/info:
+ export INFOPATH
+
+will search `/local/info' first, then the standard directories.
+Leading or doubled colons are not treated specially.
+
--- /dev/null
+This is Info file ../info/texinfo.info, produced by Makeinfo version
+1.68 from the input file texinfo.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo). The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
+* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
+* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
+* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
+END-INFO-DIR-ENTRY
+
+ This file documents Texinfo, a documentation system that can produce
+both on-line information and a printed manual from a single source file.
+
+ Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
+Foundation, Inc.
+
+ This edition is for Texinfo version 3.12.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+\1f
+File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Install an Info File
+
+Installing Info Directory Files
+===============================
+
+ When you install an Info file onto your system, you can use the
+program `install-info' to update the Info directory file `dir'.
+Normally the makefile for the package runs `install-info', just after
+copying the Info file into its proper installed location.
+
+ In order for the Info file to work with `install-info', you should
+use the commands `@dircategory' and `@direntry' in the Texinfo source
+file. Use `@direntry' to specify the menu entry to add to the Info
+directory file, and use `@dircategory' to specify which part of the
+Info directory to put it in. Here is how these commands are used in
+this manual:
+
+ @dircategory Texinfo documentation system
+ @direntry
+ * Texinfo: (texinfo). The GNU documentation format.
+ * install-info: (texinfo)Invoking install-info. ...
+ ...
+ @end direntry
+
+ Here's what this produces in the Info file:
+
+ INFO-DIR-SECTION Texinfo documentation system
+ START-INFO-DIR-ENTRY
+ * Texinfo: (texinfo). The GNU documentation format.
+ * install-info: (texinfo)Invoking install-info. ...
+ ...
+ END-INFO-DIR-ENTRY
+
+The `install-info' program sees these lines in the Info file, and that
+is how it knows what to do.
+
+ Always use the `@direntry' and `@dircategory' commands near the
+beginning of the Texinfo input, before the first `@node' command. If
+you use them later on in the input, `install-info' will not notice them.
+
+ If you use `@dircategory' more than once in the Texinfo source, each
+usage specifies one category; the new menu entry is added to the Info
+directory file in each of the categories you specify. If you use
+`@direntry' more than once, each usage specifies one menu entry; each
+of these menu entries is added to the directory in each of the
+specified categories.
+
+\1f
+File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Install an Info File
+
+Invoking install-info
+=====================
+
+ `install-info' inserts menu entries from an Info file into the
+top-level `dir' file in the Info system (see the previous sections for
+an explanation of how the `dir' file works). It's most often run as
+part of software installation, or when constructing a dir file for all
+manuals on a system. Synopsis:
+
+ install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+
+ If INFO-FILE or DIR-FILE are not specified, the various options
+(described below) that define them must be. There are no compile-time
+defaults, and standard input is never used. `install-info' can read
+only one info file and write only one dir file per invocation.
+
+ If DIR-FILE (however specified) does not exist, `install-info'
+creates it if possible (with no entries).
+
+ Options:
+
+`--delete'
+ Delete the entries in INFO-FILE from DIR-FILE. The file name in
+ the entry in DIR-FILE must be INFO-FILE (except for an optional
+ `.info' in either one). Don't insert any new entries.
+
+`--dir-file=NAME'
+ Specify file name of the Info directory file. This is equivalent
+ to using the DIR-FILE argument.
+
+`--entry=TEXT'
+ Insert TEXT as an Info directory entry; TEXT should have the form
+ of an Info menu item line plus zero or more extra lines starting
+ with whitespace. If you specify more than one entry, they are all
+ added. If you don't specify any entries, they are determined from
+ information in the Info file itself.
+
+`--help'
+ Display a usage message listing basic usage and all available
+ options, then exit successfully.
+
+`--info-file=FILE'
+ Specify Info file to install in the directory. This is equivalent
+ to using the INFO-FILE argument.
+
+`--info-dir=DIR'
+ Equivalent to `--dir-file=DIR/dir'.
+
+`--item=TEXT'
+ Same as `--entry=TEXT'. An Info directory entry is actually a
+ menu item.
+
+`--quiet'
+ Suppress warnings.
+
+`--remove'
+ Same as `--delete'.
+
+`--section=SEC'
+ Put this file's entries in section SEC of the directory. If you
+ specify more than one section, all the entries are added in each
+ of the sections. If you don't specify any sections, they are
+ determined from information in the Info file itself.
+
+`--version'
+ Display version information and exit successfully.
+
+\1f
+File: texinfo.info, Node: Command List, Next: Tips, Prev: Install an Info File, Up: Top
+
+@-Command List
+**************
+
+ Here is an alphabetical list of the @-commands in Texinfo. Square
+brackets, [ ], indicate optional arguments; an ellipsis, `...',
+indicates repeated text.
+
+`@WHITESPACE'
+ An `@' followed by a space, tab, or newline produces a normal,
+ stretchable, interword space. *Note Multiple Spaces::.
+
+`@!'
+ Generate an exclamation point that really does end a sentence
+ (usually after an end-of-sentence capital letter). *Note Ending a
+ Sentence::.
+
+`@"'
+`@''
+ Generate an umlaut or acute accent, respectively, over the next
+ character, as in "o and 'o. *Note Inserting Accents::.
+
+`@*'
+ Force a line break. Do not end a paragraph that uses `@*' with an
+ `@refill' command. *Note Line Breaks::.
+
+`@,{C}'
+ Generate a cedilla accent under C, as in c,. *Note Inserting
+ Accents::.
+
+`@-'
+ Insert a discretionary hyphenation point. *Note - and
+ hyphenation::.
+
+`@.'
+ Produce a period that really does end a sentence (usually after an
+ end-of-sentence capital letter). *Note Ending a Sentence::.
+
+`@:'
+ Indicate to TeX that an immediately preceding period, question
+ mark, exclamation mark, or colon does not end a sentence. Prevent
+ TeX from inserting extra whitespace as it does at the end of a
+ sentence. The command has no effect on the Info file output.
+ *Note Not Ending a Sentence::.
+
+`@='
+ Generate a macro (bar) accent over the next character, as in =o.
+ *Note Inserting Accents::.
+
+`@?'
+ Generate a question mark that really does end a sentence (usually
+ after an end-of-sentence capital letter). *Note Ending a
+ Sentence::.
+
+`@@'
+ Stands for an at sign, `@'. *Note Inserting @ and braces: Braces
+ Atsigns.
+
+`@^'
+`@`'
+ Generate a circumflex (hat) or grave accent, respectively, over
+ the next character, as in ^o. *Note Inserting Accents::.
+
+`@{'
+ Stands for a left brace, `{'. *Note Inserting @ and braces:
+ Braces Atsigns.
+
+`@}'
+ Stands for a right-hand brace, `}'.
+ *Note Inserting @ and braces: Braces Atsigns.
+
+`@='
+ Generate a tilde accent over the next character, as in ~N. *Note
+ Inserting Accents::.
+
+`@AA{}'
+`@aa{}'
+ Generate the uppercase and lowercase Scandinavian A-ring letters,
+ respectively: AA, aa. *Note Inserting Accents::.
+
+`@AE{}'
+`@ae{}'
+ Generate the uppercase and lowercase AE ligatures, respectively:
+ AE, ae. *Note Inserting Accents::.
+
+`@afourpaper'
+ Change page dimensions for the A4 paper size. Only allowed inside
+ `@iftex' ... `@end iftex'. *Note A4 Paper::.
+
+`@appendix TITLE'
+ Begin an appendix. The title appears in the table of contents of
+ a printed manual. In Info, the title is underlined with
+ asterisks. *Note The `@unnumbered' and `@appendix' Commands:
+ unnumbered & appendix.
+
+`@appendixsec TITLE'
+`@appendixsection TITLE'
+ Begin an appendix section within an appendix. The section title
+ appears in the table of contents of a printed manual. In Info,
+ the title is underlined with equal signs. `@appendixsection' is a
+ longer spelling of the `@appendixsec' command. *Note Section
+ Commands: unnumberedsec appendixsec heading.
+
+`@appendixsubsec TITLE'
+ Begin an appendix subsection within an appendix. The title appears
+ in the table of contents of a printed manual. In Info, the title
+ is underlined with hyphens. *Note Subsection Commands:
+ unnumberedsubsec appendixsubsec subheading.
+
+`@appendixsubsubsec TITLE'
+ Begin an appendix subsubsection within an appendix subsection. The
+ title appears in the table of contents of a printed manual. In
+ Info, the title is underlined with periods. *Note The `subsub'
+ Commands: subsubsection.
+
+`@asis'
+ Used following `@table', `@ftable', and `@vtable' to print the
+ table's first column without highlighting ("as is"). *Note Making
+ a Two-column Table: Two-column Tables.
+
+`@author AUTHOR'
+ Typeset AUTHOR flushleft and underline it. *Note The `@title' and
+ `@author' Commands: title subtitle author.
+
+`@b{TEXT}'
+ Print TEXT in bold font. No effect in Info. *Note Fonts::.
+
+`@bullet{}'
+ Generate a large round dot, or the closest possible thing to one.
+ *Note `@bullet': bullet.
+
+`@bye'
+ Stop formatting a file. The formatters do not see the contents of
+ a file following an `@bye' command. *Note Ending a File::.
+
+`@c COMMENT'
+ Begin a comment in Texinfo. The rest of the line does not appear
+ in either the Info file or the printed manual. A synonym for
+ `@comment'. *Note Comments: Comments.
+
+`@cartouche'
+ Highlight an example or quotation by drawing a box with rounded
+ corners around it. Pair with `@end cartouche'. No effect in
+ Info. *Note Drawing Cartouches Around Examples: cartouche.)
+
+`@center LINE-OF-TEXT'
+ Center the line of text following the command. *Note `@center':
+ titlefont center sp.
+
+`@centerchap LINE-OF-TEXT'
+ Like `@chapter', but centers the chapter title. *Note `@chapter':
+ chapter.
+
+`@chapheading TITLE'
+ Print a chapter-like heading in the text, but not in the table of
+ contents of a printed manual. In Info, the title is underlined
+ with asterisks. *Note `@majorheading' and `@chapheading':
+ majorheading & chapheading.
+
+`@chapter TITLE'
+ Begin a chapter. The chapter title appears in the table of
+ contents of a printed manual. In Info, the title is underlined
+ with asterisks. *Note `@chapter': chapter.
+
+`@cindex ENTRY'
+ Add ENTRY to the index of concepts. *Note Defining the Entries of
+ an Index: Index Entries.
+
+`@cite{REFERENCE}'
+ Highlight the name of a book or other reference that lacks a
+ companion Info file. *Note `@cite': cite.
+
+`@clear FLAG'
+ Unset FLAG, preventing the Texinfo formatting commands from
+ formatting text between subsequent pairs of `@ifset FLAG' and
+ `@end ifset' commands, and preventing `@value{FLAG}' from
+ expanding to the value to which FLAG is set. *Note `@set'
+ `@clear' `@value': set clear value.
+
+`@code{SAMPLE-CODE}'
+ Highlight text that is an expression, a syntactically complete
+ token of a program, or a program name. *Note `@code': code.
+
+`@comment COMMENT'
+ Begin a comment in Texinfo. The rest of the line does not appear
+ in either the Info file or the printed manual. A synonym for `@c'.
+ *Note Comments: Comments.
+
+`@contents'
+ Print a complete table of contents. Has no effect in Info, which
+ uses menus instead. *Note Generating a Table of Contents:
+ Contents.
+
+`@copyright{}'
+ Generate a copyright symbol. *Note `@copyright': copyright symbol.
+
+`@defcodeindex INDEX-NAME'
+ Define a new index and its indexing command. Print entries in an
+ `@code' font. *Note Defining New Indices: New Indices.
+
+`@defcv CATEGORY CLASS NAME'
+`@defcvx CATEGORY CLASS NAME'
+ Format a description for a variable associated with a class in
+ object-oriented programming. Takes three arguments: the category
+ of thing being defined, the class to which it belongs, and its
+ name. *Note Definition Commands::, and *Note Def Cmds in Detail:
+ deffnx.
+
+`@deffn CATEGORY NAME ARGUMENTS...'
+`@deffnx CATEGORY NAME ARGUMENTS...'
+ Format a description for a function, interactive command, or
+ similar entity that may take arguments. `@deffn' takes as
+ arguments the category of entity being described, the name of this
+ particular entity, and its arguments, if any. *Note Definition
+ Commands::.
+
+`@defindex INDEX-NAME'
+ Define a new index and its indexing command. Print entries in a
+ roman font. *Note Defining New Indices: New Indices.
+
+`@definfoenclose NEW-COMMAND, BEFORE, AFTER,'
+ Create new @-command for Info that marks text by enclosing it in
+ strings that precede and follow the text. Write definition inside
+ of `@ifinfo' ... `@end ifinfo'. *Note Customized Highlighting::.
+
+`@defivar CLASS INSTANCE-VARIABLE-NAME'
+`@defivarx CLASS INSTANCE-VARIABLE-NAME'
+ This command formats a description for an instance variable in
+ object-oriented programming. The command is equivalent to `@defcv
+ {Instance Variable} ...'. *Note Definition Commands::, and *Note
+ Def Cmds in Detail: deffnx.
+
+`@defmac MACRO-NAME ARGUMENTS...'
+`@defmacx MACRO-NAME ARGUMENTS...'
+ Format a description for a macro. The command is equivalent to
+ `@deffn Macro ...'. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@defmethod CLASS METHOD-NAME ARGUMENTS...'
+`@defmethodx CLASS METHOD-NAME ARGUMENTS...'
+ Format a description for a method in object-oriented programming.
+ The command is equivalent to `@defop Method ...'. Takes as
+ arguments the name of the class of the method, the name of the
+ method, and its arguments, if any. *Note Definition Commands::,
+ and *Note Def Cmds in Detail: deffnx.
+
+`@defop CATEGORY CLASS NAME ARGUMENTS...'
+`@defopx CATEGORY CLASS NAME ARGUMENTS...'
+ Format a description for an operation in object-oriented
+ programming. `@defop' takes as arguments the overall name of the
+ category of operation, the name of the class of the operation, the
+ name of the operation, and its arguments, if any. *Note
+ Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@defopt OPTION-NAME'
+`@defoptx OPTION-NAME'
+ Format a description for a user option. The command is equivalent
+ to `@defvr {User Option} ...'. *Note Definition Commands::, and
+ *Note Def Cmds in Detail: deffnx.
+
+`@defspec SPECIAL-FORM-NAME ARGUMENTS...'
+`@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
+ Format a description for a special form. The command is
+ equivalent to `@deffn {Special Form} ...'. *Note Definition
+ Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
+`@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
+ Format a description for a data type. `@deftp' takes as arguments
+ the category, the name of the type (which is a word like `int' or
+ `float'), and then the names of attributes of objects of that type.
+ *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
+`@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
+ Format a description for a function or similar entity that may take
+ arguments and that is typed. `@deftypefn' takes as arguments the
+ classification of entity being described, the type, the name of the
+ entity, and its arguments, if any. *Note Definition Commands::,
+ and *Note Def Cmds in Detail: deffnx.
+
+`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
+`@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
+ Format a description for a function in a typed language. The
+ command is equivalent to `@deftypefn Function ...'. *Note
+ Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
+`@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
+ Format a description for a typed method in object-oriented
+ programming. Takes as arguments the name of the class of the
+ method, the return type of the method, the name of the method, and
+ its arguments, if any. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@deftypevr CLASSIFICATION DATA-TYPE NAME'
+`@deftypevrx CLASSIFICATION DATA-TYPE NAME'
+ Format a description for something like a variable in a typed
+ language--an entity that records a value. Takes as arguments the
+ classification of entity being described, the type, and the name
+ of the entity. *Note Definition Commands::, and *Note Def Cmds in
+ Detail: deffnx.
+
+`@deftypevar DATA-TYPE VARIABLE-NAME'
+`@deftypevarx DATA-TYPE VARIABLE-NAME'
+ Format a description for a variable in a typed language. The
+ command is equivalent to `@deftypevr Variable ...'. *Note
+ Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@defun FUNCTION-NAME ARGUMENTS...'
+`@defunx FUNCTION-NAME ARGUMENTS...'
+ Format a description for functions. The command is equivalent to
+ `@deffn Function ...'. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@defvar VARIABLE-NAME'
+`@defvarx VARIABLE-NAME'
+ Format a description for variables. The command is equivalent to
+ `@defvr Variable ...'. *Note Definition Commands::, and *Note Def
+ Cmds in Detail: deffnx.
+
+`@defvr CATEGORY NAME'
+`@defvrx CATEGORY NAME'
+ Format a description for any kind of variable. `@defvr' takes as
+ arguments the category of the entity and the name of the entity.
+ *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
+
+`@detailmenu{}'
+ Avoid `makeinfo' confusion stemming from the detailed node listing
+ in a master menu. *Note Master Menu Parts::.
+
+`@dfn{TERM}'
+ Highlight the introductory or defining use of a term. *Note
+ `@dfn': dfn.
+
+`@dircategory DIRPART'
+ Specify a part of the Info directory menu where this file's entry
+ should go. *Note Installing Dir Entries::.
+
+`@direntry'
+ Begin the Info directory menu entry for this file. *Note
+ Installing Dir Entries::.
+
+`@display'
+ Begin a kind of example. Indent text, do not fill, do not select a
+ new font. Pair with `@end display'. *Note `@display': display.
+
+`@dmn{DIMENSION}'
+ Format a unit of measure, as in 12pt. Causes TeX to insert a thin
+ space before DIMENSION. No effect in Info. *Note `@dmn': dmn.
+
+`@dotaccent{C}'
+ Generate a dot accent over the character C, as in .oo. *Note
+ Inserting Accents::.
+
+`@dots{}'
+ Insert an ellipsis: `...'. *Note `@dots{}': dots.
+
+`@email{ADDRESS[, DISPLAYED-TEXT]}'
+ Indicate an electronic mail address. *Note `@email': email.
+
+`@emph{TEXT}'
+ Highlight TEXT; text is displayed in *italics* in printed output,
+ and surrounded by asterisks in Info. *Note Emphasizing Text:
+ Emphasis.
+
+`@end ENVIRONMENT'
+ Ends ENVIRONMENT, as in `@end example'. *Note @-commands:
+ Formatting Commands.
+
+`@enddots{}'
+ Generate an end-of-sentence of ellipsis, like this .... *Note
+ `@dots{}': dots.
+
+`@enumerate [NUMBER-OR-LETTER]'
+ Begin a numbered list, using `@item' for each entry. Optionally,
+ start list with NUMBER-OR-LETTER. Pair with `@end enumerate'.
+ *Note `@enumerate': enumerate.
+
+`@equiv{}'
+ Indicate to the reader the exact equivalence of two forms with a
+ glyph: `=='. *Note Equivalence::.
+
+`@error{}'
+ Indicate to the reader with a glyph that the following text is an
+ error message: `error-->'. *Note Error Glyph::.
+
+`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
+ Specify page footings resp. headings for even-numbered (left-hand)
+ pages. Only allowed inside `@iftex'. *Note How to Make Your Own
+ Headings: Custom Headings.
+
+`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
+ Specify page footings resp. headings for every page. Not relevant
+ to Info. *Note How to Make Your Own Headings: Custom Headings.
+
+`@example'
+ Begin an example. Indent text, do not fill, and select
+ fixed-width font. Pair with `@end example'. *Note `@example':
+ example.
+
+`@exclamdown{}'
+ Produce an upside-down exclamation point. *Note Inserting
+ Accents::.
+
+`@exdent LINE-OF-TEXT'
+ Remove any indentation a line might have. *Note Undoing the
+ Indentation of a Line: exdent.
+
+`@expansion{}'
+ Indicate the result of a macro expansion to the reader with a
+ special glyph: `==>'. *Note ==> Indicating an Expansion:
+ expansion.
+
+`@file{FILENAME}'
+ Highlight the name of a file, buffer, node, or directory. *Note
+ `@file': file.
+
+`@finalout'
+ Prevent TeX from printing large black warning rectangles beside
+ over-wide lines. *Note Overfull hboxes::.
+
+`@findex ENTRY'
+ Add ENTRY to the index of functions. *Note Defining the Entries
+ of an Index: Index Entries.
+
+`@flushleft'
+`@flushright'
+ Left justify every line but leave the right end ragged. Leave
+ font as is. Pair with `@end flushleft'. `@flushright' analogous.
+ *Note `@flushleft' and `@flushright': flushleft & flushright.
+
+`@footnote{TEXT-OF-FOOTNOTE}'
+ Enter a footnote. Footnote text is printed at the bottom of the
+ page by TeX; Info may format in either `End' node or `Separate'
+ node style. *Note Footnotes::.
+
+`@footnotestyle STYLE'
+ Specify an Info file's footnote style, either `end' for the end
+ node style or `separate' for the separate node style. *Note
+ Footnotes::.
+
+`@format'
+ Begin a kind of example. Like `@example' or `@display', but do
+ not narrow the margins and do not select the fixed-width font.
+ Pair with `@end format'. *Note `@example': example.
+
+`@ftable FORMATTING-COMMAND'
+ Begin a two-column table, using `@item' for each entry.
+ Automatically enter each of the items in the first column into the
+ index of functions. Pair with `@end ftable'. The same as
+ `@table', except for indexing. *Note `@ftable' and `@vtable':
+ ftable vtable.
+
+`@group'
+ Hold text together that must appear on one printed page. Pair with
+ `@end group'. Not relevant to Info. *Note `@group': group.
+
+`@H{C}'
+ Generate the long Hungarian umlaut accent over C, as in ''o.
+
+`@heading TITLE'
+ Print an unnumbered section-like heading in the text, but not in
+ the table of contents of a printed manual. In Info, the title is
+ underlined with equal signs. *Note Section Commands:
+ unnumberedsec appendixsec heading.
+
+`@headings ON-OFF-SINGLE-DOUBLE'
+ Turn page headings on or off, and/or specify single-sided or
+ double-sided page headings for printing. *Note The `@headings'
+ Command: headings on off.
+
+`@html'
+ Enter HTML completely. Pair with `@end html'. *Note Raw
+ Formatter Commands::.
+
+`@hyphenation{HY-PHEN-A-TED WORDS}'
+ Explicitly define hyphenation points. *Note `@-' and
+ `@hyphenation': - and hyphenation.
+
+`@i{TEXT}'
+ Print TEXT in italic font. No effect in Info. *Note Fonts::.
+
+`@ifclear FLAG'
+ If FLAG is cleared, the Texinfo formatting commands format text
+ between `@ifclear FLAG' and the following `@end ifclear' command.
+ *Note `@set' `@clear' `@value': set clear value.
+
+`@ifhtml'
+`@ifinfo'
+ Begin a stretch of text that will be ignored by TeX when it
+ typesets the printed manual. The text appears only in the HTML
+ resp. Info file. Pair with `@end ifhtml' resp. `@end ifinfo'.
+ *Note Conditionals::.
+
+`@ifnothtml'
+`@ifnotinfo'
+`@ifnottex'
+ Begin a stretch of text that will be ignored in one output format
+ but not the others. The text appears only in the format not
+ specified. Pair with `@end ifnothtml' resp. `@end ifnotinfo' resp.
+ `@end ifnotinfo'. *Note Conditionals::.
+
+`@ifset FLAG'
+ If FLAG is set, the Texinfo formatting commands format text
+ between `@ifset FLAG' and the following `@end ifset' command.
+ *Note `@set' `@clear' `@value': set clear value.
+
+`@iftex'
+ Begin a stretch of text that will not appear in the Info file, but
+ will be processed only by TeX. Pair with `@end iftex'. *Note
+ Conditionally Visible Text: Conditionals.
+
+`@ignore'
+ Begin a stretch of text that will not appear in either the Info
+ file or the printed output. Pair with `@end ignore'. *Note
+ Comments and Ignored Text: Comments.
+
+`@image{FILENAME, [WIDTH], [HEIGHT]}'
+ Include graphics image in external FILENAME scaled to the given
+ WIDTH and/or HEIGHT. *Note Images::.
+
+`@include FILENAME'
+ Incorporate the contents of the file FILENAME into the Info file
+ or printed document. *Note Include Files::.
+
+`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
+ Make a cross reference to an Info file for which there is no
+ printed manual. *Note Cross references using `@inforef': inforef.
+
+`\input MACRO-DEFINITIONS-FILE'
+ Use the specified macro definitions file. This command is used
+ only in the first line of a Texinfo file to cause TeX to make use
+ of the `texinfo' macro definitions file. The backslash in `\input'
+ is used instead of an `@' because TeX does not recognize `@' until
+ after it has read the definitions file. *Note The Texinfo File
+ Header: Header.
+
+`@item'
+ Indicate the beginning of a marked paragraph for `@itemize' and
+ `@enumerate'; indicate the beginning of the text of a first column
+ entry for `@table', `@ftable', and `@vtable'. *Note Lists and
+ Tables::.
+
+`@itemize MARK-GENERATING-CHARACTER-OR-COMMAND'
+ Produce a sequence of indented paragraphs, with a mark inside the
+ left margin at the beginning of each paragraph. Pair with `@end
+ itemize'. *Note `@itemize': itemize.
+
+`@itemx'
+ Like `@item' but do not generate extra vertical space above the
+ item text. *Note `@itemx': itemx.
+
+`@kbd{KEYBOARD-CHARACTERS}'
+ Indicate text that is characters of input to be typed by users.
+ *Note `@kbd': kbd.
+
+`@kbdinputstyle STYLE'
+ Specify when `@kbd' should use a font distinct from `@code'.
+ *Note `@kbd': kbd.
+
+`@key{KEY-NAME}'
+ Indicate a name for a key on a keyboard. *Note `@key': key.
+
+`@kindex ENTRY'
+ Add ENTRY to the index of keys. *Note Defining the Entries of an
+ Index: Index Entries.
+
+`@L{}'
+`@l{}'
+ Generate the uppercase and lowercase Polish suppressed-L letters,
+ respectively: L/, l/.
+
+`@lisp'
+ Begin an example of Lisp code. Indent text, do not fill, and
+ select fixed-width font. Pair with `@end lisp'. *Note `@lisp':
+ Lisp Example.
+
+`@lowersections'
+ Change subsequent chapters to sections, sections to subsections,
+ and so on. *Note `@raisesections' and `@lowersections':
+ Raise/lower sections.
+
+`@macro MACRO-NAME {PARAMS}'
+ Define a new Texinfo command `@MACRO-NAME{PARAMS}'. Only
+ supported by `makeinfo' and `texi2dvi'. *Note Defining Macros::.
+
+`@majorheading TITLE'
+ Print a chapter-like heading in the text, but not in the table of
+ contents of a printed manual. Generate more vertical whitespace
+ before the heading than the `@chapheading' command. In Info, the
+ chapter heading line is underlined with asterisks. *Note
+ `@majorheading' and `@chapheading': majorheading & chapheading.
+
+`@math{MATHEMATICAL-EXPRESSION}'
+ Format a mathematical expression. *Note `@math' - Inserting
+ Mathematical Expressions: math.
+
+`@menu'
+ Mark the beginning of a menu of nodes in Info. No effect in a
+ printed manual. Pair with `@end menu'. *Note Menus::.
+
+`@minus{}'
+ Generate a minus sign, `-'. *Note `@minus': minus.
+
+`@multitable COLUMN-WIDTH-SPEC'
+ Begin a multi-column table. Pair with `@end multitable'. *Note
+ Multitable Column Widths::.
+
+`@need N'
+ Start a new page in a printed manual if fewer than N mils
+ (thousandths of an inch) remain on the current page. *Note
+ `@need': need.
+
+`@node NAME, NEXT, PREVIOUS, UP'
+ Define the beginning of a new node in Info, and serve as a locator
+ for references for TeX. *Note `@node': node.
+
+`@noindent'
+ Prevent text from being indented as if it were a new paragraph.
+ *Note `@noindent': noindent.
+
+`@O{}'
+`@o{}'
+ Generate the uppercase and lowercase O-with-slash letters,
+ respectively: O/, o/.
+
+`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
+`@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
+ Specify page footings resp. headings for odd-numbered (right-hand)
+ pages. Only allowed inside `@iftex'. *Note How to Make Your Own
+ Headings: Custom Headings.
+
+`@OE{}'
+`@oe{}'
+ Generate the uppercase and lowercase OE ligatures, respectively:
+ OE, oe. *Note Inserting Accents::.
+
+`@page'
+ Start a new page in a printed manual. No effect in Info. *Note
+ `@page': page.
+
+`@paragraphindent INDENT'
+ Indent paragraphs by INDENT number of spaces; delete indentation
+ if the value of INDENT is 0; and do not change indentation if
+ INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.
+
+`@pindex ENTRY'
+ Add ENTRY to the index of programs. *Note Defining the Entries of
+ an Index: Index Entries.
+
+`@point{}'
+ Indicate the position of point in a buffer to the reader with a
+ glyph: `-!-'. *Note Indicating Point in a Buffer: Point Glyph.
+
+`@pounds{}'
+ Generate the pounds sterling currency sign. *Note `@pounds{}':
+ pounds.
+
+`@print{}'
+ Indicate printed output to the reader with a glyph: `-|'. *Note
+ Print Glyph::.
+
+`@printindex INDEX-NAME'
+ Print an alphabetized two-column index in a printed manual or
+ generate an alphabetized menu of index entries for Info. *Note
+ Printing Indices & Menus::.
+
+`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+ Make a reference that starts with a lower case `see' in a printed
+ manual. Use within parentheses only. Do not follow command with a
+ punctuation mark--the Info formatting commands automatically insert
+ terminating punctuation as needed. Only the first argument is
+ mandatory. *Note `@pxref': pxref.
+
+`@questiondown{}'
+ Generate an upside-down question mark. *Note Inserting Accents::.
+
+`@quotation'
+ Narrow the margins to indicate text that is quoted from another
+ real or imaginary work. Write command on a line of its own. Pair
+ with `@end quotation'. *Note `@quotation': quotation.
+
+`@r{TEXT}'
+ Print TEXT in roman font. No effect in Info. *Note Fonts::.
+
+`@raisesections'
+ Change subsequent sections to chapters, subsections to sections,
+ and so on. *Note `@raisesections' and `@lowersections':
+ Raise/lower sections.
+
+`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+ Make a reference. In a printed manual, the reference does not
+ start with a `See'. Follow command with a punctuation mark. Only
+ the first argument is mandatory. *Note `@ref': ref.
+
+`@refill'
+ In Info, refill and indent the paragraph after all the other
+ processing has been done. No effect on TeX, which always refills.
+ This command is no longer needed, since all formatters now
+ automatically refill. *Note Refilling Paragraphs::.
+
+`@result{}'
+ Indicate the result of an expression to the reader with a special
+ glyph: `=>'. *Note `@result': result.
+
+`@ringaccent{C}'
+ Generate a ring accent over the next character, as in *o. *Note
+ Inserting Accents::.
+
+`@samp{TEXT}'
+ Highlight TEXT that is a literal example of a sequence of
+ characters. Used for single characters, for statements, and often
+ for entire shell commands. *Note `@samp': samp.
+
+`@sc{TEXT}'
+ Set TEXT in a printed output in THE SMALL CAPS FONT and set text
+ in the Info file in uppercase letters. *Note Smallcaps::.
+
+`@section TITLE'
+ Begin a section within a chapter. In a printed manual, the section
+ title is numbered and appears in the table of contents. In Info,
+ the title is underlined with equal signs. *Note `@section':
+ section.
+
+`@set FLAG [STRING]'
+ Make FLAG active, causing the Texinfo formatting commands to
+ format text between subsequent pairs of `@ifset FLAG' and `@end
+ ifset' commands. Optionally, set value of FLAG to STRING. *Note
+ `@set' `@clear' `@value': set clear value.
+
+`@setchapternewpage ON-OFF-ODD'
+ Specify whether chapters start on new pages, and if so, whether on
+ odd-numbered (right-hand) new pages. *Note `@setchapternewpage':
+ setchapternewpage.
+
+`@setfilename INFO-FILE-NAME'
+ Provide a name to be used by the Info file. This command is
+ essential for TeX formatting as well, even though it produces no
+ output. *Note `@setfilename': setfilename.
+
+`@settitle TITLE'
+ Provide a title for page headers in a printed manual. *Note
+ `@settitle': settitle.
+
+`@shortcontents'
+ Print a short table of contents. Not relevant to Info, which uses
+ menus rather than tables of contents. A synonym for
+ `@summarycontents'. *Note Generating a Table of Contents:
+ Contents.
+
+`@shorttitlepage{TITLE}'
+ Generate a minimal title page. *Note `@titlepage': titlepage.
+
+`@smallbook'
+ Cause TeX to produce a printed manual in a 7 by 9.25 inch format
+ rather than the regular 8.5 by 11 inch format. *Note Printing
+ Small Books: smallbook. Also, see *Note `@smallexample' and
+ `@smalllisp': smallexample & smalllisp.
+
+`@smallexample'
+ Indent text to indicate an example. Do not fill, select
+ fixed-width font. In `@smallbook' format, print text in a smaller
+ font than with `@example'. Pair with `@end smallexample'. *Note
+ `@smallexample' and `@smalllisp': smallexample & smalllisp.
+
+`@smalllisp'
+ Begin an example of Lisp code. Indent text, do not fill, select
+ fixed-width font. In `@smallbook' format, print text in a smaller
+ font. Pair with `@end smalllisp'. *Note `@smallexample' and
+ `@smalllisp': smallexample & smalllisp.
+
+`@sp N'
+ Skip N blank lines. *Note `@sp': sp.
+
+`@ss{}'
+ Generate the German sharp-S es-zet letter, ss. *Note Inserting
+ Accents::.
+
+`@strong TEXT'
+ Emphasize TEXT by typesetting it in a *bold* font for the printed
+ manual and by surrounding it with asterisks for Info. *Note
+ Emphasizing Text: emph & strong.
+
+`@subheading TITLE'
+ Print an unnumbered subsection-like heading in the text, but not in
+ the table of contents of a printed manual. In Info, the title is
+ underlined with hyphens. *Note `@unnumberedsubsec'
+ `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
+ subheading.
+
+`@subsection TITLE'
+ Begin a subsection within a section. In a printed manual, the
+ subsection title is numbered and appears in the table of contents.
+ In Info, the title is underlined with hyphens. *Note
+ `@subsection': subsection.
+
+`@subsubheading TITLE'
+ Print an unnumbered subsubsection-like heading in the text, but
+ not in the table of contents of a printed manual. In Info, the
+ title is underlined with periods. *Note The `subsub' Commands:
+ subsubsection.
+
+`@subsubsection TITLE'
+ Begin a subsubsection within a subsection. In a printed manual,
+ the subsubsection title is numbered and appears in the table of
+ contents. In Info, the title is underlined with periods. *Note
+ The `subsub' Commands: subsubsection.
+
+`@subtitle TITLE'
+ In a printed manual, set a subtitle in a normal sized font flush to
+ the right-hand side of the page. Not relevant to Info, which does
+ not have title pages. *Note `@title' `@subtitle' and `@author'
+ Commands: title subtitle author.
+
+`@summarycontents'
+ Print a short table of contents. Not relevant to Info, which uses
+ menus rather than tables of contents. A synonym for
+ `@shortcontents'. *Note Generating a Table of Contents: Contents.
+
+`@syncodeindex FROM-INDEX INTO-INDEX'
+ Merge the index named in the first argument into the index named in
+ the second argument, printing the entries from the first index in
+ `@code' font. *Note Combining Indices::.
+
+`@synindex FROM-INDEX INTO-INDEX'
+ Merge the index named in the first argument into the index named in
+ the second argument. Do not change the font of FROM-INDEX
+ entries. *Note Combining Indices::.
+
+`@t{TEXT}'
+ Print TEXT in a fixed-width, typewriter-like font. No effect in
+ Info. *Note Fonts::.
+
+`@tab'
+ Separate columns in a multitable. *Note Multitable Rows::.
+
+`@table FORMATTING-COMMAND'
+ Begin a two-column table, using `@item' for each entry. Write
+ each first column entry on the same line as `@item'. First column
+ entries are printed in the font resulting from FORMATTING-COMMAND.
+ Pair with `@end table'. *Note Making a Two-column Table:
+ Two-column Tables. Also see *Note `@ftable' and `@vtable': ftable
+ vtable, and *Note `@itemx': itemx.
+
+`@TeX{}'
+ Insert the logo TeX. *Note Inserting TeX and (C): TeX and
+ copyright.
+
+`@tex'
+ Enter TeX completely. Pair with `@end tex'. *Note Raw Formatter
+ Commands::.
+
+`@thischapter'
+`@thischaptername'
+`@thisfile'
+`@thispage'
+`@thistitle'
+ Only allowed in a heading or footing. Stands for the number and
+ name of the current chapter (in the format `Chapter 1: Title'),
+ the chapter name only, the filename, the current page number, and
+ the title of the document, respectively. *Note How to Make Your
+ Own Headings: Custom Headings.
+
+`@tieaccent{CC}'
+ Generate a tie-after accent over the next two characters CC, as in
+ `[oo'. *Note Inserting Accents::.
+
+`@tindex ENTRY'
+ Add ENTRY to the index of data types. *Note Defining the Entries
+ of an Index: Index Entries.
+
+`@title TITLE'
+ In a printed manual, set a title flush to the left-hand side of the
+ page in a larger than normal font and underline it with a black
+ rule. Not relevant to Info, which does not have title pages.
+ *Note The `@title' `@subtitle' and `@author' Commands: title
+ subtitle author.
+
+`@titlefont{TEXT}'
+ In a printed manual, print TEXT in a larger than normal font. Not
+ relevant to Info, which does not have title pages. *Note The
+ `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
+
+`@titlepage'
+ Indicate to Texinfo the beginning of the title page. Write
+ command on a line of its own. Pair with `@end titlepage'.
+ Nothing between `@titlepage' and `@end titlepage' appears in Info.
+ *Note `@titlepage': titlepage.
+
+`@today{}'
+ Insert the current date, in `1 Jan 1900' style. *Note How to Make
+ Your Own Headings: Custom Headings.
+
+`@top TITLE'
+ In a Texinfo file to be formatted with `makeinfo', identify the
+ topmost `@node' line in the file, which must be written on the line
+ immediately preceding the `@top' command. Used for `makeinfo''s
+ node pointer insertion feature. The title is underlined with
+ asterisks. Both the `@node' line and the `@top' line normally
+ should be enclosed by `@ifinfo' and `@end ifinfo'. In TeX and
+ `texinfo-format-buffer', the `@top' command is merely a synonym
+ for `@unnumbered'. *Note Creating Pointers with `makeinfo':
+ makeinfo Pointer Creation.
+
+`@u{C}'
+`@ubaraccent{C}'
+`@udotaccent{C}'
+ Generate a breve, underbar, or underdot accent, respectively, over
+ or under the character C, as in (o, o_, o-.. *Note Inserting
+ Accents::.
+
+`@unnumbered TITLE'
+ In a printed manual, begin a chapter that appears without chapter
+ numbers of any kind. The title appears in the table of contents
+ of a printed manual. In Info, the title is underlined with
+ asterisks. *Note `@unnumbered' and `@appendix': unnumbered &
+ appendix.
+
+`@unnumberedsec TITLE'
+ In a printed manual, begin a section that appears without section
+ numbers of any kind. The title appears in the table of contents
+ of a printed manual. In Info, the title is underlined with equal
+ signs. *Note Section Commands: unnumberedsec appendixsec heading.
+
+`@unnumberedsubsec TITLE'
+ In a printed manual, begin an unnumbered subsection within a
+ chapter. The title appears in the table of contents of a printed
+ manual. In Info, the title is underlined with hyphens. *Note
+ `@unnumberedsubsec' `@appendixsubsec' `@subheading':
+ unnumberedsubsec appendixsubsec subheading.
+
+`@unnumberedsubsubsec TITLE'
+ In a printed manual, begin an unnumbered subsubsection within a
+ chapter. The title appears in the table of contents of a printed
+ manual. In Info, the title is underlined with periods. *Note The
+ `subsub' Commands: subsubsection.
+
+`@uref{URL[, DISPLAYED-TEXT}'
+ Define a cross reference to an external uniform resource locator
+ for the World Wide Web. *Note `@url': url.
+
+`@url{URL}'
+ Indicate text that is a uniform resource locator for the World Wide
+ Web. *Note `@url': url.
+
+`@v{C}'
+ Generate check accent over the character C, as in <o. *Note
+ Inserting Accents::.
+
+`@value{FLAG}'
+ Replace FLAG with the value to which it is set by `@set FLAG'.
+ *Note `@set' `@clear' `@value': set clear value.
+
+`@var{METASYNTACTIC-VARIABLE}'
+ Highlight a metasyntactic variable, which is something that stands
+ for another piece of text. *Note Indicating Metasyntactic
+ Variables: var.
+
+`@vindex ENTRY'
+ Add ENTRY to the index of variables. *Note Defining the Entries
+ of an Index: Index Entries.
+
+`@vskip AMOUNT'
+ In a printed manual, insert whitespace so as to push text on the
+ remainder of the page towards the bottom of the page. Used in
+ formatting the copyright page with the argument `0pt plus 1filll'.
+ (Note spelling of `filll'.) `@vskip' may be used only in
+ contexts ignored for Info. *Note The Copyright Page and Printed
+ Permissions: Copyright & Permissions.
+
+`@vtable FORMATTING-COMMAND'
+ Begin a two-column table, using `@item' for each entry.
+ Automatically enter each of the items in the first column into the
+ index of variables. Pair with `@end vtable'. The same as
+ `@table', except for indexing. *Note `@ftable' and `@vtable':
+ ftable vtable.
+
+`@w{TEXT}'
+ Prevent TEXT from being split across two lines. Do not end a
+ paragraph that uses `@w' with an `@refill' command. *Note `@w': w.
+
+`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
+ Make a reference that starts with `See' in a printed manual.
+ Follow command with a punctuation mark. Only the first argument is
+ mandatory. *Note `@xref': xref.
+
--- /dev/null
+This is Info file ../info/widget.info, produced by Makeinfo version
+1.68 from the input file widget.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Widgets: (widget). The Emacs Widget Library.
+END-INFO-DIR-ENTRY
+
+\1f
+File: widget.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
+
+The Emacs Widget Library
+************************
+
+* Menu:
+
+* Introduction::
+* User Interface::
+* Programming Example::
+* Setting Up the Buffer::
+* Basic Types::
+* Sexp Types::
+* Widget Properties::
+* Defining New Widgets::
+* Widget Browser::
+* Widget Minor Mode::
+* Utilities::
+* Widget Wishlist::
+
+\1f
+File: widget.info, Node: Introduction, Next: User Interface, Prev: Top, Up: Top
+
+Introduction
+============
+
+ Most graphical user interface toolkits, such as Motif and XView,
+provide a number of standard user interface controls (sometimes known as
+`widgets' or `gadgets'). Emacs doesn't really support anything like
+this, except for an incredible powerful text "widget". On the other
+hand, Emacs does provide the necessary primitives to implement many
+other widgets within a text buffer. The `widget' package simplifies
+this task.
+
+ The basic widgets are:
+
+`link'
+ Areas of text with an associated action. Intended for hypertext
+ links embedded in text.
+
+`push-button'
+ Like link, but intended for stand-alone buttons.
+
+`editable-field'
+ An editable text field. It can be either variable or fixed length.
+
+`menu-choice'
+ Allows the user to choose one of multiple options from a menu, each
+ option is itself a widget. Only the selected option will be
+ visible in the buffer.
+
+`radio-button-choice'
+ Allows the user to choose one of multiple options by activating
+ radio buttons. The options are implemented as widgets. All
+ options will be visible in the buffer.
+
+`item'
+ A simple constant widget intended to be used in the `menu-choice'
+ and `radio-button-choice' widgets.
+
+`choice-item'
+ An button item only intended for use in choices. When invoked,
+ the user will be asked to select another option from the choice
+ widget.
+
+`toggle'
+ A simple `on'/`off' switch.
+
+`checkbox'
+ A checkbox (`[ ]'/`[X]').
+
+`editable-list'
+ Create an editable list. The user can insert or delete items in
+ the list. Each list item is itself a widget.
+
+ Now of what possible use can support for widgets be in a text editor?
+I'm glad you asked. The answer is that widgets are useful for
+implementing forms. A "form" in emacs is a buffer where the user is
+supposed to fill out a number of fields, each of which has a specific
+meaning. The user is not supposed to change or delete any of the text
+between the fields. Examples of forms in Emacs are the `forms' package
+(of course), the customize buffers, the mail and news compose modes,
+and the HTML form support in the `w3' browser.
+
+ The advantages for a programmer of using the `widget' package to
+implement forms are:
+
+ 1. More complex field than just editable text are supported.
+
+ 2. You can give the user immediate feedback if he enters invalid data
+ in a text field, and sometimes prevent entering invalid data.
+
+ 3. You can have fixed sized fields, thus allowing multiple field to be
+ lined up in columns.
+
+ 4. It is simple to query or set the value of a field.
+
+ 5. Editing happens in buffer, not in the mini-buffer.
+
+ 6. Packages using the library get a uniform look, making them easier
+ for the user to learn.
+
+ 7. As support for embedded graphics improve, the widget library will
+ extended to support it. This means that your code using the widget
+ library will also use the new graphic features by automatic.
+
+ In order to minimize the code that is loaded by users who does not
+create any widgets, the code has been split in two files:
+
+`widget.el'
+ This will declare the user variables, define the function
+ `widget-define', and autoload the function `widget-create'.
+
+`wid-edit.el'
+ Everything else is here, there is no reason to load it explicitly,
+ as it will be autoloaded when needed.
+
+\1f
+File: widget.info, Node: User Interface, Next: Programming Example, Prev: Introduction, Up: Top
+
+User Interface
+==============
+
+ A form consist of read only text for documentation and some fields,
+where each the fields contain two parts, as tag and a value. The tags
+are used to identify the fields, so the documentation can refer to the
+foo field, meaning the field tagged with `Foo'. Here is an example form:
+
+ Here is some documentation.
+
+ Name: My Name *Choose*: This option
+ Address: Some Place
+ In some City
+ Some country.
+
+ See also _other work_ for more information.
+
+ Numbers: count to three below
+ [INS] [DEL] One
+ [INS] [DEL] Eh, two?
+ [INS] [DEL] Five!
+ [INS]
+
+ Select multiple:
+
+ [X] This
+ [ ] That
+ [X] Thus
+
+ Select one:
+
+ (*) One
+ ( ) Another One.
+ ( ) A Final One.
+
+ [Apply Form] [Reset Form]
+
+ The top level widgets in is example are tagged `Name', `Choose',
+`Address', `_other work_', `Numbers', `Select multiple', `Select one',
+`[Apply Form]', and `[Reset Form]'. There are basically two thing the
+user can do within a form, namely editing the editable text fields and
+activating the buttons.
+
+Editable Text Fields
+--------------------
+
+ In the example, the value for the `Name' is most likely displayed in
+an editable text field, and so are values for each of the members of
+the `Numbers' list. All the normal Emacs editing operations are
+available for editing these fields. The only restriction is that each
+change you make must be contained within a single editable text field.
+For example, capitalizing all text from the middle of one field to the
+middle of another field is prohibited.
+
+ Editing text fields are created by the `editable-field' widget.
+
+ The editing text fields are highlighted with the `widget-field-face'
+face, making them easy to find.
+
+ - Face: widget-field-face
+ Face used for other editing fields.
+
+Buttons
+-------
+
+ Some portions of the buffer have an associated "action", which can
+be "invoked" by a standard key or mouse command. These portions are
+called "buttons". The default commands for activating a button are:
+
+`<RET>'
+ - Command: widget-button-press POS &optional EVENT
+ Invoke the button at POS, defaulting to point. If point is
+ not located on a button, invoke the binding in
+ `widget-global-map' (by default the global map).
+
+`mouse-2'
+ - Command: widget-button-click EVENT
+ Invoke the button at the location of the mouse pointer. If
+ the mouse pointer is located in an editable text field,
+ invoke the binding in `widget-global-map' (by default the
+ global map).
+
+ There are several different kind of buttons, all of which are
+present in the example:
+
+*The Option Field Tags.*
+ When you invoke one of these buttons, you will be asked to choose
+ between a number of different options. This is how you edit an
+ option field. Option fields are created by the `menu-choice'
+ widget. In the example, `Choose' is an option field tag.
+
+*The `[INS]' and `[DEL]' buttons.*
+ Activating these will insert or delete elements from a editable
+ list. The list is created by the `editable-list' widget.
+
+*Embedded Buttons.*
+ The `_other work_' is an example of an embedded button. Embedded
+ buttons are not associated with a fields, but can serve any
+ purpose, such as implementing hypertext references. They are
+ usually created by the `link' widget.
+
+*The `[ ]' and `[X]' buttons.*
+ Activating one of these will convert it to the other. This is
+ useful for implementing multiple-choice fields. You can create it
+ wit
+
+*The `( )' and `(*)' buttons.*
+ Only one radio button in a `radio-button-choice' widget can be
+ selected at any time. When you invoke one of the unselected radio
+ buttons, it will be selected and the previous selected radio
+ button will become unselected.
+
+*The `[Apply Form]' `[Reset Form]' buttons.*
+ These are explicit buttons made with the `push-button' widget.
+ The main difference from the `link' widget is that the buttons are
+ will be displayed as GUI buttons when possible. enough.
+
+ To make them easier to locate, buttons are emphasized in the buffer.
+
+ - Face: widget-button-face
+ Face used for buttons.
+
+ - User Option: widget-mouse-face
+ Face used for buttons when the mouse pointer is above it.
+
+Navigation
+----------
+
+ You can use all the normal Emacs commands to move around in a form
+buffer, plus you will have these additional commands:
+
+`<TAB>'
+ - Command: widget-forward &optional COUNT
+ Move point COUNT buttons or editing fields forward.
+
+`<M-TAB>'
+ - Command: widget-backward &optional COUNT
+ Move point COUNT buttons or editing fields backward.
+
+\1f
+File: widget.info, Node: Programming Example, Next: Setting Up the Buffer, Prev: User Interface, Up: Top
+
+Programming Example
+===================
+
+ Here is the code to implement the user interface example (see *Note
+User Interface::).
+
+ (require 'widget)
+
+ (eval-when-compile
+ (require 'wid-edit))
+
+ (defvar widget-example-repeat)
+
+ (defun widget-example ()
+ "Create the widgets from the Widget manual."
+ (interactive)
+ (kill-buffer (get-buffer-create "*Widget Example*"))
+ (switch-to-buffer (get-buffer-create "*Widget Example*"))
+ (kill-all-local-variables)
+ (make-local-variable 'widget-example-repeat)
+ (widget-insert "Here is some documentation.\n\nName: ")
+ (widget-create 'editable-field
+ :size 13
+ "My Name")
+ (widget-create 'menu-choice
+ :tag "Choose"
+ :value "This"
+ :help-echo "Choose me, please!"
+ :notify (lambda (widget &rest ignore)
+ (message "%s is a good choice!"
+ (widget-value widget)))
+ '(item :tag "This option" :value "This")
+ '(choice-item "That option")
+ '(editable-field :menu-tag "No option" "Thus option"))
+ (widget-insert "Address: ")
+ (widget-create 'editable-field
+ "Some Place\nIn some City\nSome country.")
+ (widget-insert "\nSee also ")
+ (widget-create 'link
+ :notify (lambda (&rest ignore)
+ (widget-value-set widget-example-repeat
+ '("En" "To" "Tre"))
+ (widget-setup))
+ "other work")
+ (widget-insert " for more information.\n\nNumbers: count to three below\n")
+ (setq widget-example-repeat
+ (widget-create 'editable-list
+ :entry-format "%i %d %v"
+ :notify (lambda (widget &rest ignore)
+ (let ((old (widget-get widget
+ ':example-length))
+ (new (length (widget-value widget))))
+ (unless (eq old new)
+ (widget-put widget ':example-length new)
+ (message "You can count to %d." new))))
+ :value '("One" "Eh, two?" "Five!")
+ '(editable-field :value "three")))
+ (widget-insert "\n\nSelect multiple:\n\n")
+ (widget-create 'checkbox t)
+ (widget-insert " This\n")
+ (widget-create 'checkbox nil)
+ (widget-insert " That\n")
+ (widget-create 'checkbox
+ :notify (lambda (&rest ignore) (message "Tickle"))
+ t)
+ (widget-insert " Thus\n\nSelect one:\n\n")
+ (widget-create 'radio-button-choice
+ :value "One"
+ :notify (lambda (widget &rest ignore)
+ (message "You selected %s"
+ (widget-value widget)))
+ '(item "One") '(item "Another One.") '(item "A Final One."))
+ (widget-insert "\n")
+ (widget-create 'push-button
+ :notify (lambda (&rest ignore)
+ (if (= (length (widget-value widget-example-repeat))
+ 3)
+ (message "Congratulation!")
+ (error "Three was the count!")))
+ "Apply Form")
+ (widget-insert " ")
+ (widget-create 'push-button
+ :notify (lambda (&rest ignore)
+ (widget-example))
+ "Reset Form")
+ (widget-insert "\n")
+ (use-local-map widget-keymap)
+ (widget-setup))
+
+\1f
+File: widget.info, Node: Setting Up the Buffer, Next: Basic Types, Prev: Programming Example, Up: Top
+
+Setting Up the Buffer
+=====================
+
+ Widgets are created with `widget-create', which returns a "widget"
+object. This object can be queried and manipulated by other widget
+functions, until it is deleted with `widget-delete'. After the widgets
+have been created, `widget-setup' must be called to enable them.
+
+ - Function: widget-create TYPE [ KEYWORD ARGUMENT ]...
+ Create and return a widget of type TYPE. The syntax for the TYPE
+ argument is described in *Note Basic Types::.
+
+ The keyword arguments can be used to overwrite the keyword
+ arguments that are part of TYPE.
+
+ - Function: widget-delete WIDGET
+ Delete WIDGET and remove it from the buffer.
+
+ - Function: widget-setup
+ Setup a buffer to support widgets.
+
+ This should be called after creating all the widgets and before
+ allowing the user to edit them.
+
+
+ If you want to insert text outside the widgets in the form, the
+recommended way to do that is with `widget-insert'.
+
+ - Function: widget-insert
+ Insert the arguments, either strings or characters, at point. The
+ inserted text will be read only.
+
+ There is a standard widget keymap which you might find useful.
+
+ - Const: widget-keymap
+ A keymap with the global keymap as its parent.
+ <TAB> and `C-<TAB>' are bound to `widget-forward' and
+ `widget-backward', respectively. `<RET>' and `mouse-2' are bound
+ to `widget-button-press' and `widget-button-'.
+
+ - Variable: widget-global-map
+ Keymap used by `widget-button-press' and `widget-button-click'
+ when not on a button. By default this is `global-map'.
+
+\1f
+File: widget.info, Node: Basic Types, Next: Sexp Types, Prev: Setting Up the Buffer, Up: Top
+
+Basic Types
+===========
+
+ The syntax of a type specification is given below:
+
+ NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
+ | NAME
+
+ Where, NAME is a widget name, KEYWORD is the name of a property,
+ARGUMENT is the value of the property, and ARGS are interpreted in a
+widget specific way.
+
+ There following keyword arguments that apply to all widgets:
+
+`:value'
+ The initial value for widgets of this type.
+
+`:format'
+ This string will be inserted in the buffer when you create a
+ widget. The following `%' escapes are available:
+
+ `%['
+ `%]'
+ The text inside will be marked as a button.
+
+ By default, the text will be shown in `widget-button-face',
+ and surrounded by brackets.
+
+ - User Option: widget-button-prefix
+ String to prefix buttons.
+
+ - User Option: widget-button-suffix
+ String to suffix buttons.
+
+ `%{'
+ `%}'
+ The text inside will be displayed with the face specified by
+ `:sample-face'.
+
+ `%v'
+ This will be replaces with the buffer representation of the
+ widgets value. What this is depends on the widget type.
+
+ `%d'
+ Insert the string specified by `:doc' here.
+
+ `%h'
+ Like `%d', with the following modifications: If the
+ documentation string is more than one line, it will add a
+ button which will toggle between showing only the first line,
+ and showing the full text. Furthermore, if there is no
+ `:doc' property in the widget, it will instead examine the
+ `:documentation-property' property. If it is a lambda
+ expression, it will be called with the widget's value as an
+ argument, and the result will be used as the documentation
+ text.
+
+ `%t'
+ Insert the string specified by `:tag' here, or the `princ'
+ representation of the value if there is no tag.
+
+ `%%'
+ Insert a literal `%'.
+
+`:button-face'
+ Face used to highlight text inside %[ %] in the format.
+
+`:button-prefix'
+`:button-suffix'
+ Text around %[ %] in the format.
+
+ These can be
+ *nil*
+ No text is inserted.
+
+ *a string*
+ The string is inserted literally.
+
+ *a symbol*
+ The value of the symbol is expanded according to this table.
+
+`:doc'
+ The string inserted by the `%d' escape in the format string.
+
+`:tag'
+ The string inserted by the `%t' escape in the format string.
+
+`:tag-glyph'
+ Name of image to use instead of the string specified by `:tag' on
+ Emacsen that supports it.
+
+`:help-echo'
+ Message displayed whenever you move to the widget with either
+ `widget-forward' or `widget-backward'.
+
+`:indent'
+ An integer indicating the absolute number of spaces to indent
+ children of this widget.
+
+`:offset'
+ An integer indicating how many extra spaces to add to the widget's
+ grandchildren compared to this widget.
+
+`:extra-offset'
+ An integer indicating how many extra spaces to add to the widget's
+ children compared to this widget.
+
+`:notify'
+ A function called each time the widget or a nested widget is
+ changed. The function is called with two or three arguments. The
+ first argument is the widget itself, the second argument is the
+ widget that was changed, and the third argument is the event
+ leading to the change, if any.
+
+`:menu-tag'
+ Tag used in the menu when the widget is used as an option in a
+ `menu-choice' widget.
+
+`:menu-tag-get'
+ Function used for finding the tag when the widget is used as an
+ option in a `menu-choice' widget. By default, the tag used will
+ be either the `:menu-tag' or `:tag' property if present, or the
+ `princ' representation of the `:value' property if not.
+
+`:match'
+ Should be a function called with two arguments, the widget and a
+ value, and returning non-nil if the widget can represent the
+ specified value.
+
+`:validate'
+ A function which takes a widget as an argument, and return nil if
+ the widgets current value is valid for the widget. Otherwise, it
+ should return the widget containing the invalid data, and set that
+ widgets `:error' property to a string explaining the error.
+
+ The following predefined function can be used:
+
+ - Function: widget-children-validate WIDGET
+ All the `:children' of WIDGET must be valid.
+
+`:tab-order'
+ Specify the order in which widgets are traversed with
+ `widget-forward' or `widget-backward'. This is only partially
+ implemented.
+
+ a. Widgets with tabbing order `-1' are ignored.
+
+ b. (Unimplemented) When on a widget with tabbing order N, go to
+ the next widget in the buffer with tabbing order N+1 or `nil',
+ whichever comes first.
+
+ c. When on a widget with no tabbing order specified, go to the
+ next widget in the buffer with a positive tabbing order, or
+ `nil'
+
+`:parent'
+ The parent of a nested widget (e.g. a `menu-choice' item or an
+ element of a `editable-list' widget).
+
+`:sibling-args'
+ This keyword is only used for members of a `radio-button-choice' or
+ `checklist'. The value should be a list of extra keyword
+ arguments, which will be used when creating the `radio-button' or
+ `checkbox' associated with this item.
+
+ - User Option: widget-glyph-directory
+ Directory where glyphs are found. Widget will look here for a
+ file with the same name as specified for the image, with either a
+ `.xpm' (if supported) or `.xbm' extension.
+
+ - User Option: widget-glyph-enable
+ If non-nil, allow glyphs to appear on displays where they are
+ supported.
+
+* Menu:
+
+* link::
+* url-link::
+* info-link::
+* push-button::
+* editable-field::
+* text::
+* menu-choice::
+* radio-button-choice::
+* item::
+* choice-item::
+* toggle::
+* checkbox::
+* checklist::
+* editable-list::
+* group::
+
+\1f
+File: widget.info, Node: link, Next: url-link, Prev: Basic Types, Up: Basic Types
+
+The `link' Widget
+-----------------
+
+ Syntax:
+
+ TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ])
+
+ The VALUE, if present, is used to initialize the `:value' property.
+The value should be a string, which will be inserted in the buffer.
+
+ By default the link will be shown in brackets.
+
+ - User Option: widget-link-prefix
+ String to prefix links.
+
+ - User Option: widget-link-suffix
+ String to suffix links.
+
+\1f
+File: widget.info, Node: url-link, Next: info-link, Prev: link, Up: Basic Types
+
+The `url-link' Widget
+---------------------
+
+ Syntax:
+
+ TYPE ::= (url-link [KEYWORD ARGUMENT]... URL)
+
+ When this link is invoked, the WWW browser specified by
+`browse-url-browser-function' will be called with URL.
+
+\1f
+File: widget.info, Node: info-link, Next: push-button, Prev: url-link, Up: Basic Types
+
+The `info-link' Widget
+----------------------
+
+ Syntax:
+
+ TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS)
+
+ When this link is invoked, the built-in info browser is started on
+ADDRESS.
+
+\1f
+File: widget.info, Node: push-button, Next: editable-field, Prev: info-link, Up: Basic Types
+
+The `push-button' Widget
+------------------------
+
+ Syntax:
+
+ TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ])
+
+ The VALUE, if present, is used to initialize the `:value' property.
+The value should be a string, which will be inserted in the buffer.
+
+ By default the tag will be shown in brackets.
+
+ - User Option: widget-push-button-prefix
+ String to prefix push buttons.
+
+ - User Option: widget-push-button-suffix
+ String to suffix push buttons.
+
+\1f
+File: widget.info, Node: editable-field, Next: text, Prev: push-button, Up: Basic Types
+
+The `editable-field' Widget
+---------------------------
+
+ Syntax:
+
+ TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ])
+
+ The VALUE, if present, is used to initialize the `:value' property.
+The value should be a string, which will be inserted in field. This
+widget will match all string values.
+
+ The following extra properties are recognized.
+
+`:size'
+ The width of the editable field.
+ By default the field will reach to the end of the line.
+
+`:value-face'
+ Face used for highlighting the editable field. Default is
+ `widget-field-face'.
+
+`:secret'
+ Character used to display the value. You can set this to e.g. `?*'
+ if the field contains a password or other secret information. By
+ default, the value is not secret.
+
+`:valid-regexp'
+ By default the `:validate' function will match the content of the
+ field with the value of this attribute. The default value is `""'
+ which matches everything.
+
+`:keymap'
+ Keymap used in the editable field. The default value is
+ `widget-field-keymap', which allows you to use all the normal
+ editing commands, even if the buffers major mode suppress some of
+ them. Pressing return invokes the function specified by `:action'.
+
+\1f
+File: widget.info, Node: text, Next: menu-choice, Prev: editable-field, Up: Basic Types
+
+The `text' Widget
+-----------------
+
+ This is just like `editable-field', but intended for multiline text
+fields. The default `:keymap' is `widget-text-keymap', which does not
+rebind the return key.
+
+\1f
+File: widget.info, Node: menu-choice, Next: radio-button-choice, Prev: text, Up: Basic Types
+
+The `menu-choice' Widget
+------------------------
+
+ Syntax:
+
+ TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... )
+
+ The TYPE arguments represents each possible choice. The widgets
+value of will be the value of the chosen TYPE argument. This widget
+will match any value that matches at least one of the specified TYPE
+arguments.
+
+`:void'
+ Widget type used as a fallback when the value does not match any
+ of the specified TYPE arguments.
+
+`:case-fold'
+ Set this to nil if you don't want to ignore case when prompting
+ for a choice through the minibuffer.
+
+`:children'
+ A list whose car is the widget representing the currently chosen
+ type in the buffer.
+
+`:choice'
+ The current chosen type
+
+`:args'
+ The list of types.
+
+\1f
+File: widget.info, Node: radio-button-choice, Next: item, Prev: menu-choice, Up: Basic Types
+
+The `radio-button-choice' Widget
+--------------------------------
+
+ Syntax:
+
+ TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... )
+
+ The TYPE arguments represents each possible choice. The widgets
+value of will be the value of the chosen TYPE argument. This widget
+will match any value that matches at least one of the specified TYPE
+arguments.
+
+ The following extra properties are recognized.
+
+`:entry-format'
+ This string will be inserted for each entry in the list. The
+ following `%' escapes are available:
+ `%v'
+ Replaced with the buffer representation of the TYPE widget.
+
+ `%b'
+ Replace with the radio button.
+
+ `%%'
+ Insert a literal `%'.
+
+`button-args'
+ A list of keywords to pass to the radio buttons. Useful for
+ setting e.g. the `:help-echo' for each button.
+
+`:buttons'
+ The widgets representing the radio buttons.
+
+`:children'
+ The widgets representing each type.
+
+`:choice'
+ The current chosen type
+
+`:args'
+ The list of types.
+
+ You can add extra radio button items to a `radio-button-choice'
+widget after it has been created with the function
+`widget-radio-add-item'.
+
+ - Function: widget-radio-add-item WIDGET TYPE
+ Add to `radio-button-choice' widget WIDGET a new radio button item
+ of type TYPE.
+
+ Please note that such items added after the `radio-button-choice'
+widget has been created will *not* be properly destructed when you call
+`widget-delete'.
+
+\1f
+File: widget.info, Node: item, Next: choice-item, Prev: radio-button-choice, Up: Basic Types
+
+The `item' Widget
+-----------------
+
+ Syntax:
+
+ ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)
+
+ The VALUE, if present, is used to initialize the `:value' property.
+The value should be a string, which will be inserted in the buffer.
+This widget will only match the specified value.
+
+\1f
+File: widget.info, Node: choice-item, Next: toggle, Prev: item, Up: Basic Types
+
+The `choice-item' Widget
+------------------------
+
+ Syntax:
+
+ ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE)
+
+ The VALUE, if present, is used to initialize the `:value' property.
+The value should be a string, which will be inserted in the buffer as a
+button. Activating the button of a `choice-item' is equivalent to
+activating the parent widget. This widget will only match the
+specified value.
+
+\1f
+File: widget.info, Node: toggle, Next: checkbox, Prev: choice-item, Up: Basic Types
+
+The `toggle' Widget
+-------------------
+
+ Syntax:
+
+ TYPE ::= (toggle [KEYWORD ARGUMENT]...)
+
+ The widget has two possible states, `on' and `off', which
+corresponds to a `t' or `nil' value.
+
+ The following extra properties are recognized.
+
+`:on'
+ String representing the `on' state. By default the string `on'.
+
+`:off'
+ String representing the `off' state. By default the string `off'.
+
+`:on-glyph'
+ Name of a glyph to be used instead of the `:on' text string, on
+ emacsen that supports it.
+
+`:off-glyph'
+ Name of a glyph to be used instead of the `:off' text string, on
+ emacsen that supports it.
+
+\1f
+File: widget.info, Node: checkbox, Next: checklist, Prev: toggle, Up: Basic Types
+
+The `checkbox' Widget
+---------------------
+
+ The widget has two possible states, `selected' and `unselected',
+which corresponds to a `t' or `nil' value.
+
+ Syntax:
+
+ TYPE ::= (checkbox [KEYWORD ARGUMENT]...)
+
+\1f
+File: widget.info, Node: checklist, Next: editable-list, Prev: checkbox, Up: Basic Types
+
+The `checklist' Widget
+----------------------
+
+ Syntax:
+
+ TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... )
+
+ The TYPE arguments represents each checklist item. The widgets
+value of will be a list containing the value of each ticked TYPE
+argument. The checklist widget will match a list whose elements all
+matches at least one of the specified TYPE arguments.
+
+ The following extra properties are recognized.
+
+`:entry-format'
+ This string will be inserted for each entry in the list. The
+ following `%' escapes are available:
+ `%v'
+ Replaced with the buffer representation of the TYPE widget.
+
+ `%b'
+ Replace with the checkbox.
+
+ `%%'
+ Insert a literal `%'.
+
+`:greedy'
+ Usually, a checklist will only match if the items are in the exact
+ sequence given in the specification. By setting `:greedy' to
+ non-nil, it will allow the items to come in any sequence.
+ However, if you extract the value they will be in the sequence
+ given in the checklist. I.e. the original sequence is forgotten.
+
+`button-args'
+ A list of keywords to pass to the checkboxes. Useful for setting
+ e.g. the `:help-echo' for each checkbox.
+
+`:buttons'
+ The widgets representing the checkboxes.
+
+`:children'
+ The widgets representing each type.
+
+`:args'
+ The list of types.
+
+\1f
+File: widget.info, Node: editable-list, Next: group, Prev: checklist, Up: Basic Types
+
+The `editable-list' Widget
+--------------------------
+
+ Syntax:
+
+ TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE)
+
+ The value is a list, where each member represents one widget of type
+TYPE.
+
+ The following extra properties are recognized.
+
+`:entry-format'
+ This string will be inserted for each entry in the list. The
+ following `%' escapes are available:
+ `%v'
+ This will be replaced with the buffer representation of the
+ TYPE widget.
+
+ `%i'
+ Insert the [INS] button.
+
+ `%d'
+ Insert the [DEL] button.
+
+ `%%'
+ Insert a literal `%'.
+
+`:insert-button-args'
+ A list of keyword arguments to pass to the insert buttons.
+
+`:delete-button-args'
+ A list of keyword arguments to pass to the delete buttons.
+
+`:append-button-args'
+ A list of keyword arguments to pass to the trailing insert button.
+
+`:buttons'
+ The widgets representing the insert and delete buttons.
+
+`:children'
+ The widgets representing the elements of the list.
+
+`:args'
+ List whose car is the type of the list elements.
+
+\1f
+File: widget.info, Node: group, Prev: editable-list, Up: Basic Types
+
+The `group' Widget
+------------------
+
+ This widget simply group other widget together.
+
+ Syntax:
+
+ TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...)
+
+ The value is a list, with one member for each TYPE.
+
+\1f
+File: widget.info, Node: Sexp Types, Next: Widget Properties, Prev: Basic Types, Up: Top
+
+Sexp Types
+==========
+
+ A number of widgets for editing s-expressions (lisp types) are also
+available. These basically fall in the following categories.
+
+* Menu:
+
+* constants::
+* generic::
+* atoms::
+* composite::
+
+\1f
+File: widget.info, Node: constants, Next: generic, Prev: Sexp Types, Up: Sexp Types
+
+The Constant Widgets.
+---------------------
+
+ The `const' widget can contain any lisp expression, but the user is
+prohibited from editing edit it, which is mainly useful as a component
+of one of the composite widgets.
+
+ The syntax for the `const' widget is
+
+ TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ])
+
+ The VALUE, if present, is used to initialize the `:value' property
+and can be any s-expression.
+
+ - Widget: const
+ This will display any valid s-expression in an immutable part of
+ the buffer.
+
+ There are two variations of the `const' widget, namely
+`variable-item' and `function-item'. These should contain a symbol
+with a variable or function binding. The major difference from the
+`const' widget is that they will allow the user to see the variable or
+function documentation for the symbol.
+
+ - Widget: variable-item
+ An immutable symbol that is bound as a variable.
+
+ - Widget: function-item
+ An immutable symbol that is bound as a function.
+
+\1f
+File: widget.info, Node: generic, Next: atoms, Prev: constants, Up: Sexp Types
+
+Generic Sexp Widget.
+--------------------
+
+ The `sexp' widget can contain any lisp expression, and allows the
+user to edit it inline in the buffer.
+
+ The syntax for the `sexp' widget is
+
+ TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ])
+
+ - Widget: sexp
+ This will allow you to edit any valid s-expression in an editable
+ buffer field.
+
+ The `sexp' widget takes the same keyword arguments as the
+ `editable-field' widget.
+
+\1f
+File: widget.info, Node: atoms, Next: composite, Prev: generic, Up: Sexp Types
+
+Atomic Sexp Widgets.
+--------------------
+
+ The atoms are s-expressions that does not consist of other
+s-expressions. A string is an atom, while a list is a composite type.
+You can edit the value of an atom with the following widgets.
+
+ The syntax for all the atoms are
+
+ TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ])
+
+ The VALUE, if present, is used to initialize the `:value' property
+and must be an expression of the same type as the widget. I.e. the
+string widget can only be initialized with a string.
+
+ All the atom widgets take the same keyword arguments as the
+`editable-field' widget.
+
+ - Widget: string
+ Allows you to edit a string in an editable field.
+
+ - Widget: regexp
+ Allows you to edit a regular expression in an editable field.
+
+ - Widget: character
+ Allows you to enter a character in an editable field.
+
+ - Widget: file
+ Allows you to edit a file name in an editable field. If you invoke
+ the tag button, you can edit the file name in the mini-buffer with
+ completion.
+
+ Keywords:
+ `:must-match'
+ If this is set to non-nil, only existing file names will be
+ allowed in the minibuffer.
+
+ - Widget: directory
+ Allows you to edit a directory name in an editable field. Similar
+ to the `file' widget.
+
+ - Widget: symbol
+ Allows you to edit a lisp symbol in an editable field.
+
+ - Widget: function
+ Allows you to edit a lambda expression, or a function name with
+ completion.
+
+ - Widget: variable
+ Allows you to edit a variable name, with completion.
+
+ - Widget: integer
+ Allows you to edit an integer in an editable field.
+
+ - Widget: number
+ Allows you to edit a number in an editable field.
+
+ - Widget: boolean
+ Allows you to edit a boolean. In lisp this means a variable which
+ is either nil meaning false, or non-nil meaning true.
+
+\1f
+File: widget.info, Node: composite, Prev: atoms, Up: Sexp Types
+
+Composite Sexp Widgets.
+-----------------------
+
+ The syntax for the composite are
+
+ TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...)
+
+ Where each COMPONENT must be a widget type. Each component widget
+will be displayed in the buffer, and be editable to the user.
+
+ - Widget: cons
+ The value of a `cons' widget is a cons-cell where the car is the
+ value of the first component and the cdr is the value of the second
+ component. There must be exactly two components.
+
+ - Widget: list
+ The value of a `list' widget is a list containing the value of
+ each of its component.
+
+ - Widget: vector
+ The value of a `vector' widget is a vector containing the value of
+ each of its component.
+
+ The above suffice for specifying fixed size lists and vectors. To
+get variable length lists and vectors, you can use a `choice', `set' or
+`repeat' widgets together with the `:inline' keywords. If any
+component of a composite widget has the `:inline' keyword set, its
+value must be a list which will then be spliced into the composite.
+For example, to specify a list whose first element must be a file name,
+and whose remaining arguments should either by the symbol `t' or two
+files, you can use the following widget specification:
+
+ (list file
+ (choice (const t)
+ (list :inline t
+ :value ("foo" "bar")
+ string string)))
+
+ The value of a widget of this type will either have the form `(file
+t)' or `(file string string)'.
+
+ This concept of inline is probably hard to understand. It was
+certainly hard to implement so instead of confuse you more by trying to
+explain it here, I'll just suggest you meditate over it for a while.
+
+ - Widget: choice
+ Allows you to edit a sexp which may have one of fixed set of
+ types. It is currently implemented with the `choice-menu' basic
+ widget, and has a similar syntax.
+
+ - Widget: set
+ Allows you to specify a type which must be a list whose elements
+ all belong to given set. The elements of the list is not
+ significant. This is implemented on top of the `checklist' basic
+ widget, and has a similar syntax.
+
+ - Widget: repeat
+ Allows you to specify a variable length list whose members are all
+ of the same type. Implemented on top of the `editable-list' basic
+ widget, and has a similar syntax.
+
+\1f
+File: widget.info, Node: Widget Properties, Next: Defining New Widgets, Prev: Sexp Types, Up: Top
+
+Properties
+==========
+
+ You can examine or set the value of a widget by using the widget
+object that was returned by `widget-create'.
+
+ - Function: widget-value WIDGET
+ Return the current value contained in WIDGET. It is an error to
+ call this function on an uninitialized widget.
+
+ - Function: widget-value-set WIDGET VALUE
+ Set the value contained in WIDGET to VALUE. It is an error to
+ call this function with an invalid VALUE.
+
+ *Important:* You *must* call `widget-setup' after modifying the
+value of a widget before the user is allowed to edit the widget again.
+It is enough to call `widget-setup' once if you modify multiple
+widgets. This is currently only necessary if the widget contains an
+editing field, but may be necessary for other widgets in the future.
+
+ If your application needs to associate some information with the
+widget objects, for example a reference to the item being edited, it
+can be done with `widget-put' and `widget-get'. The property names
+must begin with a `:'.
+
+ - Function: widget-put WIDGET PROPERTY VALUE
+ In WIDGET set PROPERTY to VALUE. PROPERTY should be a symbol,
+ while VALUE can be anything.
+
+ - Function: widget-get WIDGET PROPERTY
+ In WIDGET return the value for PROPERTY. PROPERTY should be a
+ symbol, the value is what was last set by `widget-put' for
+ PROPERTY.
+
+ - Function: widget-member WIDGET PROPERTY
+ Non-nil if WIDGET has a value (even nil) for property PROPERTY.
+
+ Occasionally it can be useful to know which kind of widget you have,
+i.e. the name of the widget type you gave when the widget was created.
+
+ - Function: widget-type WIDGET
+ Return the name of WIDGET, a symbol.
+
+ Widgets can be in two states: active, which means they are
+modifiable by the user, or inactive, which means they cannot be
+modified by the user. You can query or set the state with the
+following code:
+
+ ;; Examine if WIDGET is active or not.
+ (if (widget-apply WIDGET :active)
+ (message "Widget is active.")
+ (message "Widget is inactive.")
+
+ ;; Make WIDGET inactive.
+ (widget-apply WIDGET :deactivate)
+
+ ;; Make WIDGET active.
+ (widget-apply WIDGET :activate)
+
+ A widget is inactive if itself, or any of its ancestors (found by
+following the `:parent' link) have been deactivated. To make sure a
+widget is really active, you must therefore activate both itself, and
+all its ancestors.
+
+ (while widget
+ (widget-apply widget :activate)
+ (setq widget (widget-get widget :parent)))
+
+ You can check if a widget has been made inactive by examining the
+value of `:inactive' keyword. If this is non-nil, the widget itself has
+been deactivated. This is different from using the `:active' keyword,
+in that the later tell you if the widget *or* any of its ancestors have
+been deactivated. Do not attempt to set the `:inactive' keyword
+directly. Use the `:activate' `:deactivated' keywords instead.
+
+\1f
+File: widget.info, Node: Defining New Widgets, Next: Widget Browser, Prev: Widget Properties, Up: Top
+
+Defining New Widgets
+====================
+
+ You can define specialized widgets with `define-widget'. It allows
+you to create a shorthand for more complex widgets, including specifying
+component widgets and default new default values for the keyword
+arguments.
+
+ - Function: widget-define NAME CLASS DOC &rest ARGS
+ Define a new widget type named NAME from `class'.
+
+ NAME and class should both be symbols, `class' should be one of
+ the existing widget types.
+
+ The third argument DOC is a documentation string for the widget.
+
+ After the new widget has been defined, the following two calls will
+ create identical widgets:
+
+ * (widget-create NAME)
+
+ * (apply widget-create CLASS ARGS)
+
+
+ Using `widget-define' does just store the definition of the widget
+type in the `widget-type' property of NAME, which is what
+`widget-create' uses.
+
+ If you just want to specify defaults for keywords with no complex
+conversions, you can use `identity' as your conversion function.
+
+ The following additional keyword arguments are useful when defining
+new widgets:
+`:convert-widget'
+ Function to convert a widget type before creating a widget of that
+ type. It takes a widget type as an argument, and returns the
+ converted widget type. When a widget is created, this function is
+ called for the widget type and all the widgets parent types, most
+ derived first.
+
+ The following predefined functions can be used here:
+
+ - Function: widget-types-convert-widget WIDGET
+ Convert `:args' as widget types in WIDGET.
+
+ - Function: widget-value-convert-widget WIDGET
+ Initialize `:value' from `:args' in WIDGET.
+
+`:value-to-internal'
+ Function to convert the value to the internal format. The function
+ takes two arguments, a widget and an external value, and returns
+ the internal value. The function is called on the present `:value'
+ when the widget is created, and on any value set later with
+ `widget-value-set'.
+
+`:value-to-external'
+ Function to convert the value to the external format. The function
+ takes two arguments, a widget and an internal value, and returns
+ the internal value. The function is called on the present `:value'
+ when the widget is created, and on any value set later with
+ `widget-value-set'.
+
+`:create'
+ Function to create a widget from scratch. The function takes one
+ argument, a widget type, and create a widget of that type, insert
+ it in the buffer, and return a widget object.
+
+`:delete'
+ Function to delete a widget. The function takes one argument, a
+ widget, and should remove all traces of the widget from the buffer.
+
+`:value-create'
+ Function to expand the `%v' escape in the format string. It will
+ be called with the widget as its argument. Should insert a
+ representation of the widgets value in the buffer.
+
+`:value-delete'
+ Should remove the representation of the widgets value from the
+ buffer. It will be called with the widget as its argument. It
+ doesn't have to remove the text, but it should release markers and
+ delete nested widgets if such has been used.
+
+ The following predefined function can be used here:
+
+ - Function: widget-children-value-delete WIDGET
+ Delete all `:children' and `:buttons' in WIDGET.
+
+`:value-get'
+ Function to extract the value of a widget, as it is displayed in
+ the buffer.
+
+ The following predefined function can be used here:
+
+ - Function: widget-value-value-get WIDGET
+ Return the `:value' property of WIDGET.
+
+`:format-handler'
+ Function to handle unknown `%' escapes in the format string. It
+ will be called with the widget and the escape character as
+ arguments. You can set this to allow your widget to handle
+ non-standard escapes.
+
+ You should end up calling `widget-default-format-handler' to handle
+ unknown escape sequences, which will handle the `%h' and any future
+ escape sequences, as well as give an error for unknown escapes.
+
+`:action'
+ Function to handle user initiated events. By default, `:notify'
+ the parent.
+
+ The following predefined function can be used here:
+
+ - Function: widget-parent-action WIDGET &optional EVENT
+ Tell `:parent' of WIDGET to handle the `:action'.
+ Optional EVENT is the event that triggered the action.
+
+`:prompt-value'
+ Function to prompt for a value in the minibuffer. The function
+ should take four arguments, WIDGET, PROMPT, VALUE, and UNBOUND and
+ should return a value for widget entered by the user. PROMPT is
+ the prompt to use. VALUE is the default value to use, unless
+ UNBOUND is non-nil in which case there are no default value. The
+ function should read the value using the method most natural for
+ this widget, and does not have to check that it matches.
+
+ If you want to define a new widget from scratch, use the `default'
+widget as its base.
+
+ - Widget: default
+ Widget used as a base for other widgets.
+
+ It provides most of the functionality that is referred to as "by
+ default" in this text.
+
+\1f
+File: widget.info, Node: Widget Browser, Next: Widget Minor Mode, Prev: Defining New Widgets, Up: Top
+
+Widget Browser
+==============
+
+ There is a separate package to browse widgets. This is intended to
+help programmers who want to examine the content of a widget. The
+browser shows the value of each keyword, but uses links for certain
+keywords such as `:parent', which avoids printing cyclic structures.
+
+ - Command: widget-browse WIDGET
+ Create a widget browser for WIDGET. When called interactively,
+ prompt for WIDGET.
+
+ - Command: widget-browse-other-window WIDGET
+ Create a widget browser for WIDGET and show it in another window.
+ When called interactively, prompt for WIDGET.
+
+ - Command: widget-browse-at POS
+ Create a widget browser for the widget at POS. When called
+ interactively, use the position of point.
+
+\1f
+File: widget.info, Node: Widget Minor Mode, Next: Utilities, Prev: Widget Browser, Up: Top
+
+Widget Minor Mode
+=================
+
+ There is a minor mode for manipulating widgets in major modes that
+doesn't provide any support for widgets themselves. This is mostly
+intended to be useful for programmers doing experiments.
+
+ - Command: widget-minor-mode
+ Toggle minor mode for traversing widgets. With arg, turn widget
+ mode on if and only if arg is positive.
+
+ - Variable: widget-minor-mode-keymap
+ Keymap used in `widget-minor-mode'.
+
+\1f
+File: widget.info, Node: Utilities, Next: Widget Wishlist, Prev: Widget Minor Mode, Up: Top
+
+Utilities.
+==========
+
+ - Function: widget-prompt-value WIDGET PROMPT [ VALUE UNBOUND ]
+ Prompt for a value matching WIDGET, using PROMPT.
+ The current value is assumed to be VALUE, unless UNBOUND is
+ non-nil.
+
+ - Function: widget-get-sibling WIDGET
+ Get the item WIDGET is assumed to toggle.
+ This is only meaningful for radio buttons or checkboxes in a list.
+
+\1f
+File: widget.info, Node: Widget Wishlist, Prev: Utilities, Up: Top
+
+Wishlist
+========
+
+ * It should be possible to add or remove items from a list with `C-k'
+ and `C-o' (suggested by RMS).
+
+ * The `[INS]' and `[DEL]' buttons should be replaced by a single
+ dash (`-'). The dash should be a button that, when invoked, ask
+ whether you want to add or delete an item (RMS wanted to git rid of
+ the ugly buttons, the dash is my idea).
+
+ * The `menu-choice' tag should be prettier, something like the
+ abbreviated menus in Open Look.
+
+ * Finish `:tab-order'.
+
+ * Make indentation work with glyphs and proportional fonts.
+
+ * Add commands to show overview of object and class hierarchies to
+ the browser.
+
+ * Find a way to disable mouse highlight for inactive widgets.
+
+ * Find a way to make glyphs look inactive.
+
+ * Add `property-list' widget.
+
+ * Add `association-list' widget.
+
+ * Add `key-binding' widget.
+
+ * Add `widget' widget for editing widget specifications.
+
+ * Find clean way to implement variable length list. See
+ `TeX-printer-list' for an explanation.
+
+ * `C-h' in `widget-prompt-value' should give type specific help.
+
+ * A mailto widget.
+
+ * `C-e e' in a fixed size field should go to the end of the text in
+ the field, not the end of the field itself.
+
+ * Use and overlay instead of markers to delimit the widget. Create
+ accessors for the end points.
+
+ * Clicking on documentation links should call `describe-function' or
+ `widget-browse-other-window' and friends directly, instead of going
+ through `apropos'. If more than one function is valid for the
+ symbol, it should pop up a menu.
+
+
+\1f
+Tag Table:
+Node: Top\7f227
+Node: Introduction\7f607
+Node: User Interface\7f4090
+Node: Programming Example\7f8985
+Node: Setting Up the Buffer\7f12302
+Node: Basic Types\7f14019
+Node: link\7f20064
+Node: url-link\7f20578
+Node: info-link\7f20890
+Node: push-button\7f21181
+Node: editable-field\7f21754
+Node: text\7f23093
+Node: menu-choice\7f23391
+Node: radio-button-choice\7f24256
+Node: item\7f25835
+Node: choice-item\7f26223
+Node: toggle\7f26721
+Node: checkbox\7f27446
+Node: checklist\7f27752
+Node: editable-list\7f29196
+Node: group\7f30378
+Node: Sexp Types\7f30665
+Node: constants\7f30978
+Node: generic\7f32057
+Node: atoms\7f32590
+Node: composite\7f34537
+Node: Widget Properties\7f37003
+Node: Defining New Widgets\7f40066
+Node: Widget Browser\7f45366
+Node: Widget Minor Mode\7f46224
+Node: Utilities\7f46781
+Node: Widget Wishlist\7f47262
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
+1.68 from the input file xemacs-faq.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* FAQ: (xemacs-faq). XEmacs FAQ.
+END-INFO-DIR-ENTRY
+
+\1f
+Indirect:
+xemacs-faq.info-1: 221
+xemacs-faq.info-2: 48809
+xemacs-faq.info-3: 95901
+xemacs-faq.info-4: 145739
+xemacs-faq.info-5: 195532
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f221
+Node: Introduction\7f15614
+Node: Q1.0.1\7f19134
+Node: Q1.0.2\7f19670
+Node: Q1.0.3\7f20106
+Node: Q1.0.4\7f20364
+Node: Q1.0.5\7f21796
+Node: Q1.0.6\7f22485
+Node: Q1.0.7\7f23616
+Node: Q1.0.8\7f24015
+Node: Q1.0.9\7f24211
+Node: Q1.0.10\7f24489
+Node: Q1.0.11\7f25938
+Node: Q1.0.12\7f26395
+Node: Q1.0.13\7f26763
+Node: Q1.0.14\7f26998
+Node: Q1.1.1\7f27542
+Node: Q1.1.2\7f28737
+Node: Q1.1.3\7f29112
+Node: Q1.2.1\7f30060
+Node: Q1.2.2\7f31120
+Node: Q1.2.3\7f31550
+Node: Q1.3.1\7f32501
+Node: Q1.3.2\7f36419
+Node: Q1.3.3\7f37128
+Node: Q1.3.4\7f37370
+Node: Q1.3.5\7f38134
+Node: Q1.3.6\7f40549
+Node: Q1.3.7\7f42044
+Node: Q1.4.1\7f42979
+Node: Q1.4.2\7f43849
+Node: Q1.4.3\7f44190
+Node: Q1.4.4\7f44832
+Node: Q1.4.5\7f46372
+Node: Q1.4.6\7f46676
+Node: Q1.4.7\7f47684
+Node: Installation\7f48809
+Node: Q2.0.1\7f51217
+Node: Q2.0.2\7f52090
+Node: Q2.0.3\7f59300
+Node: Q2.0.4\7f60598
+Node: Q2.0.5\7f61187
+Node: Q2.0.6\7f61555
+Node: Q2.0.7\7f61936
+Node: Q2.0.8\7f62317
+Node: Q2.0.9\7f63892
+Node: Q2.0.10\7f65330
+Node: Q2.0.11\7f66174
+Node: Q2.0.12\7f67115
+Node: Q2.0.13\7f68638
+Node: Q2.0.14\7f69296
+Node: Q2.1.1\7f69864
+Node: Q2.1.2\7f72606
+Node: Q2.1.3\7f73783
+Node: Q2.1.4\7f75076
+Node: Q2.1.5\7f75875
+Node: Q2.1.6\7f76237
+Node: Q2.1.7\7f76714
+Node: Q2.1.8\7f77067
+Node: Q2.1.9\7f78583
+Node: Q2.1.10\7f79005
+Node: Q2.1.11\7f79762
+Node: Q2.1.12\7f80627
+Node: Q2.1.13\7f81582
+Node: Q2.1.14\7f82613
+Node: Q2.1.15\7f83721
+Node: Q2.1.16\7f89678
+Node: Q2.1.17\7f90356
+Node: Q2.1.18\7f90953
+Node: Q2.1.19\7f92750
+Node: Q2.1.20\7f93280
+Node: Q2.1.21\7f93662
+Node: Q2.1.22\7f93952
+Node: Q2.1.23\7f95249
+Node: Customization\7f95901
+Node: Q3.0.1\7f100795
+Node: Q3.0.2\7f101501
+Node: Q3.0.3\7f102065
+Node: Q3.0.4\7f102482
+Node: Q3.0.5\7f103315
+Node: Q3.0.6\7f104096
+Node: Q3.0.7\7f104676
+Node: Q3.0.8\7f105340
+Node: Q3.0.9\7f106186
+Node: Q3.1.1\7f106747
+Node: Q3.1.2\7f107484
+Node: Q3.1.3\7f107915
+Node: Q3.1.4\7f108500
+Node: Q3.1.5\7f109036
+Node: Q3.1.6\7f109420
+Node: Q3.1.7\7f110101
+Node: Q3.1.8\7f112325
+Node: Q3.2.1\7f112864
+Node: Q3.2.2\7f114272
+Node: Q3.2.3\7f115071
+Node: Q3.2.4\7f115673
+Node: Q3.2.5\7f116707
+Node: Q3.2.6\7f117174
+Node: Q3.3.1\7f118136
+Node: Q3.3.2\7f118529
+Node: Q3.3.3\7f119160
+Node: Q3.3.4\7f119541
+Node: Q3.3.5\7f120635
+Node: Q3.4.1\7f122129
+Node: Q3.4.2\7f122772
+Node: Q3.5.1\7f123284
+Node: Q3.5.2\7f124739
+Node: Q3.5.3\7f125157
+Node: Q3.5.4\7f125998
+Node: Q3.5.5\7f126830
+Node: Q3.5.6\7f127970
+Node: Q3.5.7\7f128960
+Node: Q3.5.8\7f130312
+Node: Q3.5.9\7f131059
+Node: Q3.5.10\7f131839
+Node: Q3.5.11\7f132472
+Node: Q3.6.1\7f133025
+Node: Q3.6.2\7f133765
+Node: Q3.6.3\7f134193
+Node: Q3.7.1\7f134693
+Node: Q3.7.2\7f135581
+Node: Q3.7.3\7f136240
+Node: Q3.7.4\7f136662
+Node: Q3.7.5\7f137005
+Node: Q3.7.6\7f137473
+Node: Q3.7.7\7f138188
+Node: Q3.7.8\7f139208
+Node: Q3.8.1\7f139627
+Node: Q3.8.2\7f140087
+Node: Q3.8.3\7f140550
+Node: Q3.8.4\7f141156
+Node: Q3.8.5\7f141875
+Node: Q3.9.1\7f142660
+Node: Q3.9.2\7f143600
+Node: Q3.9.3\7f144198
+Node: Q3.9.4\7f144860
+Node: Q3.10.1\7f145739
+Node: Q3.10.2\7f146557
+Node: Q3.10.3\7f147338
+Node: Q3.10.4\7f148066
+Node: Q3.10.5\7f148449
+Node: Subsystems\7f149459
+Node: Q4.0.1\7f151874
+Node: Q4.0.2\7f152399
+Node: Q4.0.3\7f152957
+Node: Q4.0.4\7f153278
+Node: Q4.0.5\7f153520
+Node: Q4.0.6\7f153751
+Node: Q4.0.7\7f154329
+Node: Q4.0.8\7f154654
+Node: Q4.0.9\7f155881
+Node: Q4.0.10\7f157919
+Node: Q4.0.11\7f158373
+Node: Q4.0.12\7f159223
+Node: Q4.1.1\7f160196
+Node: Q4.1.2\7f160599
+Node: Q4.1.3\7f160926
+Node: Q4.2.1\7f161235
+Node: Q4.2.2\7f161865
+Node: Q4.2.3\7f162105
+Node: Q4.2.4\7f162649
+Node: Q4.3.1\7f163302
+Node: Q4.3.2\7f163886
+Node: Q4.3.3\7f165602
+Node: Q4.3.4\7f165871
+Node: Q4.3.5\7f166560
+Node: Q4.4.1\7f167188
+Node: Q4.5.1\7f168695
+Node: Q4.6.1\7f169464
+Node: Q4.7.1\7f174724
+Node: Q4.7.2\7f175679
+Node: Q4.7.3\7f175976
+Node: Q4.7.4\7f176322
+Node: Q4.7.5\7f177206
+Node: Q4.7.6\7f178848
+Node: Miscellaneous\7f179397
+Node: Q5.0.1\7f182823
+Node: Q5.0.2\7f183557
+Node: Q5.0.3\7f184411
+Node: Q5.0.4\7f185113
+Node: Q5.0.5\7f186053
+Node: Q5.0.6\7f188033
+Node: Q5.0.7\7f188690
+Node: Q5.0.8\7f189295
+Node: Q5.0.9\7f189814
+Node: Q5.0.10\7f190328
+Node: Q5.0.11\7f190576
+Node: Q5.0.12\7f191137
+Node: Q5.0.13\7f192054
+Node: Q5.0.14\7f192738
+Node: Q5.0.15\7f193503
+Node: Q5.0.16\7f193804
+Node: Q5.0.17\7f194316
+Node: Q5.0.18\7f194581
+Node: Q5.0.19\7f195107
+Node: Q5.0.20\7f195532
+Node: Q5.1.1\7f196447
+Node: Q5.1.2\7f198516
+Node: Q5.1.3\7f199252
+Node: Q5.1.4\7f202646
+Node: Q5.1.5\7f203181
+Node: Q5.1.6\7f205275
+Node: Q5.1.7\7f206664
+Node: Q5.1.8\7f208265
+Node: Q5.1.9\7f208817
+Node: Q5.1.10\7f209702
+Node: Q5.1.11\7f210833
+Node: Q5.2.1\7f211379
+Node: Q5.2.2\7f211950
+Node: Q5.2.3\7f212367
+Node: Q5.2.4\7f212602
+Node: Q5.3.1\7f213512
+Node: Q5.3.2\7f214733
+Node: Q5.3.3\7f215509
+Node: Q5.3.4\7f215993
+Node: Q5.3.5\7f216660
+Node: Q5.3.6\7f217529
+Node: Q5.3.7\7f217774
+Node: Q5.3.8\7f219964
+Node: Q5.3.9\7f220211
+Node: Q5.3.10\7f221164
+Node: Q5.3.11\7f223359
+Node: Q5.3.12\7f224908
+Node: Current Events\7f226182
+Node: Q6.0.1\7f226839
+Node: Q6.0.2\7f227478
+Node: Q6.0.3\7f228552
+Node: Q6.0.4\7f228780
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
+1.68 from the input file xemacs-faq.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* FAQ: (xemacs-faq). XEmacs FAQ.
+END-INFO-DIR-ENTRY
+
+\1f
+File: xemacs-faq.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
+
+XEmacs FAQ
+**********
+
+Introduction
+************
+
+ This is the guide to the XEmacs Frequently Asked Questions list--a
+compendium of questions and answers pertaining to one of the finest
+programs ever written. It is much more than just a Text Editor.
+
+ This FAQ is freely redistributable. I take no liability for the
+correctness and safety of any procedures or advice given here. This
+FAQ is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE.
+
+ If you have a Web browser, the official hypertext version is at
+`http://www.xemacs.org/faq/xemacs-faq.html'.
+
+ This version is somewhat nicer than the unofficial hypertext versions
+that are archived at Utrecht, Oxford, Smart Pages, and other FAQ
+archives.
+
+* Menu:
+
+* Introduction:: Introduction, Policy, Credits.
+* Installation:: Installation and Trouble Shooting.
+* Customization:: Customization and Options.
+* Subsystems:: Major Subsystems.
+* Miscellaneous:: The Miscellaneous Stuff.
+* Current Events:: What the Future Holds.
+
+
+ -- The Detailed Node Listing --
+
+Introduction, Policy, Credits
+
+* Q1.0.1:: What is XEmacs?
+* Q1.0.2:: What is the current version of XEmacs?
+* Q1.0.3:: Where can I find it?
+* Q1.0.4:: Why Another Version of Emacs?
+* Q1.0.5:: Why Haven't XEmacs and GNU Emacs Merged?
+* Q1.0.6:: Where can I get help?
+* Q1.0.7:: Where is the mailing list archived?
+* Q1.0.8:: How do you pronounce XEmacs?
+* Q1.0.9:: What does XEmacs look like?
+* Q1.0.10:: Is there a port of XEmacs to Microsoft ('95 or NT)?
+* Q1.0.11:: Is there a port of XEmacs to the Macintosh?
+* Q1.0.12:: Is there a port of XEmacs to NextStep?
+* Q1.0.13:: Is there a port of XEmacs to OS/2?
+* Q1.0.14:: Where can I get a printed copy of the XEmacs users manual?
+
+Policies:
+* Q1.1.1:: What is the FAQ editorial policy?
+* Q1.1.2:: How do I become a Beta Tester?
+* Q1.1.3:: How do I contribute to XEmacs itself?
+
+Credits:
+* Q1.2.1:: Who wrote XEmacs?
+* Q1.2.2:: Who contributed to this version of the FAQ?
+* Q1.2.3:: Who contributed to the FAQ in the past?
+
+Internationalization:
+* Q1.3.1:: What is the status of XEmacs v20?
+* Q1.3.2:: What is the status of Asian-language support, aka MULE?
+* Q1.3.3:: How do I type non-ASCII characters?
+* Q1.3.4:: Can XEmacs messages come out in a different language?
+* Q1.3.5:: Please explain the various input methods in MULE/XEmacs 20.0
+* Q1.3.6:: How do I portably code for MULE/XEmacs 20.0?
+* Q1.3.7:: How about Cyrillic Modes?
+
+Getting Started:
+* Q1.4.1:: What is a `.emacs' and is there a sample one?
+* Q1.4.2:: Can I use the same `.emacs' with the other Emacs?
+* Q1.4.3:: Any good XEmacs tutorials around?
+* Q1.4.4:: May I see an example of a useful XEmacs Lisp function?
+* Q1.4.5:: And how do I bind it to a key?
+* Q1.4.6:: What's the difference between a macro and a function?
+* Q1.4.7:: Why options saved with 19.13 don't work with 19.14 or later?
+
+Installation and Trouble Shooting
+
+* Q2.0.1:: Running XEmacs without installing.
+* Q2.0.2:: XEmacs is too big.
+* Q2.0.3:: Compiling XEmacs with Netaudio.
+* Q2.0.4:: Problems with Linux and ncurses.
+* Q2.0.5:: Do I need X11 to run XEmacs?
+* Q2.0.6:: I'm having strange crashes. What do I do?
+* Q2.0.7:: Libraries in non-standard locations.
+* Q2.0.8:: can't resolve symbol _h_errno
+* Q2.0.9:: Where do I find external libraries?
+* Q2.0.10:: After I run configure I find a coredump, is something wrong?
+* Q2.0.11:: XEmacs can't resolve host names.
+* Q2.0.12:: Why can't I strip XEmacs?
+* Q2.0.13:: Can't link XEmacs on Solaris with Gcc.
+* Q2.0.14:: Make on HP/UX 9 fails after linking temacs
+
+Trouble Shooting:
+* Q2.1.1:: XEmacs just crashed on me!
+* Q2.1.2:: Cryptic Minibuffer messages.
+* Q2.1.3:: Translation Table Syntax messages at Startup.
+* Q2.1.4:: Startup warnings about deducing proper fonts?
+* Q2.1.5:: XEmacs cannot connect to my X Terminal.
+* Q2.1.6:: XEmacs just locked up my Linux X server.
+* Q2.1.7:: HP Alt key as Meta.
+* Q2.1.8:: got (wrong-type-argument color-instance-p nil)!
+* Q2.1.9:: XEmacs causes my OpenWindows 3.0 server to crash.
+* Q2.1.10:: Warnings from incorrect key modifiers.
+* Q2.1.11:: Can't instantiate image error... in toolbar
+* Q2.1.12:: Regular Expression Problems on DEC OSF1.
+* Q2.1.13:: HP/UX 10.10 and `create_process' failure
+* Q2.1.14:: `C-g' doesn't work for me. Is it broken?
+* Q2.1.15:: How to debug an XEmacs problem with a debugger.
+* Q2.1.16:: XEmacs crashes in `strcat' on HP/UX 10.
+* Q2.1.17:: `Marker does not point anywhere'.
+* Q2.1.18:: 19.14 hangs on HP/UX 10.10.
+* Q2.1.19:: XEmacs does not follow the local timezone.
+* Q2.1.20:: `Symbol's function definition is void: hkey-help-show.'
+* Q2.1.21:: Every so often the XEmacs frame freezes.
+* Q2.1.22:: XEmacs seems to take a really long time to do some things.
+* Q2.1.23:: Movemail on Linux does not work for XEmacs 19.15 and later.
+
+Customization and Options
+
+* Q3.0.1:: What version of Emacs am I running?
+* Q3.0.2:: How do I evaluate Elisp expressions?
+* Q3.0.3:: `(setq tab-width 6)' behaves oddly.
+* Q3.0.4:: How can I add directories to the `load-path'?
+* Q3.0.5:: How to check if a lisp function is defined?
+* Q3.0.6:: Can I force the output of `(face-list)' to a buffer?
+* Q3.0.7:: Font selections don't get saved after `Save Options'.
+* Q3.0.8:: How do I make a single minibuffer frame?
+* Q3.0.9:: What is `Customize'?
+
+X Window System & Resources:
+* Q3.1.1:: Where is a list of X resources?
+* Q3.1.2:: How can I detect a color display?
+* Q3.1.3:: `(set-screen-width)' worked in 19.6, but not in 19.13?
+* Q3.1.4:: Specifying `Emacs*EmacsScreen.geometry' in `.emacs' does not work in 19.15?
+* Q3.1.5:: How can I get the icon to just say `XEmacs'?
+* Q3.1.6:: How can I have the window title area display the full path?
+* Q3.1.7:: `xemacs -name junk' doesn't work?
+* Q3.1.8:: `-iconic' doesn't work.
+
+Textual Fonts & Colors:
+* Q3.2.1:: How can I set color options from `.emacs'?
+* Q3.2.2:: How do I set the text, menu and modeline fonts?
+* Q3.2.3:: How can I set the colors when highlighting a region?
+* Q3.2.4:: How can I limit color map usage?
+* Q3.2.5:: My tty supports color, but XEmacs doesn't use them.
+* Q3.2.6:: Can I have pixmap backgrounds in XEmacs?
+
+The Modeline:
+* Q3.3.1:: How can I make the modeline go away?
+* Q3.3.2:: How do you have XEmacs display the line number in the modeline?
+* Q3.3.3:: How do I get XEmacs to put the time of day on the modeline?
+* Q3.3.4:: How do I turn off current chapter from AUC TeX modeline?
+* Q3.3.5:: How can one change the modeline color based on the mode used?
+
+Multiple Device Support:
+* Q3.4.1:: How do I open a frame on another screen of my multi-headed display?
+* Q3.4.2:: Can I really connect to a running XEmacs after calling up over a modem? How?
+
+The Keyboard:
+* Q3.5.1:: How can I bind complex functions (or macros) to keys?
+* Q3.5.2:: How can I stop down-arrow from adding empty lines to the bottom of my buffers?
+* Q3.5.3:: How do I bind C-. and C-; to scroll one line up and down?
+* Q3.5.4:: Globally binding `Delete'?
+* Q3.5.5:: Scrolling one line at a time.
+* Q3.5.6:: How to map `Help' key alone on Sun type4 keyboard?
+* Q3.5.7:: How can you type in special characters in XEmacs?
+* Q3.5.8:: Why does `(global-set-key [delete-forward] 'delete-char)' complain?
+* Q3.5.9:: How do I make the Delete key delete forward?
+* Q3.5.10:: Can I turn on "sticky" modifier keys?
+* Q3.5.11:: How do I map the arrow keys?
+
+The Cursor:
+* Q3.6.1:: Is there a way to make the bar cursor thicker?
+* Q3.6.2:: Is there a way to get back the old block cursor where the cursor covers the character in front of the point?
+* Q3.6.3:: Can I make the cursor blink?
+
+The Mouse and Highlighting:
+* Q3.7.1:: How can I turn off Mouse pasting?
+* Q3.7.2:: How do I set control/meta/etc modifiers on mouse buttons?
+* Q3.7.3:: Clicking the left button does not do anything in buffer list.
+* Q3.7.4:: How can I get a list of buffers when I hit mouse button 3?
+* Q3.7.5:: Why does cut-and-paste not work between XEmacs and a cmdtool?
+* Q3.7.6:: How I can set XEmacs up so that it pastes where the text cursor is?
+* Q3.7.7:: How do I select a rectangular region?
+* Q3.7.8:: Why does `M-w' take so long?
+
+The Menubar and Toolbar:
+* Q3.8.1:: How do I get rid of the menu (or menubar)?
+* Q3.8.2:: Can I customize the basic menubar?
+* Q3.8.3:: How do I control how many buffers are listed in the menu `Buffers' list?
+* Q3.8.4:: Resources like `Emacs*menubar*font' are not working?
+* Q3.8.5:: How can I bind a key to a function to toggle the toolbar?
+
+Scrollbars:
+* Q3.9.1:: How can I disable the scrollbar?
+* Q3.9.2:: How can one use resources to change scrollbar colors?
+* Q3.9.3:: Moving the scrollbar can move the point; can I disable this?
+* Q3.9.4:: How can I get automatic horizontal scrolling?
+
+Text Selections:
+* Q3.10.1:: How can I turn off or change highlighted selections?
+* Q3.10.2:: How do I get that typing on an active region removes it?
+* Q3.10.3:: Can I turn off the highlight during isearch?
+* Q3.10.4:: How do I turn off highlighting after `C-x C-p' (mark-page)?
+* Q3.10.5:: The region disappears when I hit the end of buffer while scrolling.
+
+Major Subsystems
+
+* Q4.0.1:: How do I set up VM to retrieve remote mail using POP?
+* Q4.0.2:: How do I get VM to filter mail for me?
+* Q4.0.3:: How can I get VM to automatically check for new mail?
+* Q4.0.4:: [This question intentionally left blank]
+* Q4.0.5:: How do I get my outgoing mail archived?
+* Q4.0.6:: I have various addresses at which I receive mail. How can I tell VM to ignore them when doing a "reply-all"?
+* Q4.0.7:: Is there a mailing list or FAQ for VM?
+* Q4.0.8:: Remote mail reading with VM.
+* Q4.0.9:: rmail or VM gets an error incorporating new mail.
+* Q4.0.10:: How do I make VM stay in a single frame?
+* Q4.0.11:: How do I make VM or mh-e display graphical smilies?
+* Q4.0.12:: Customization of VM not covered in the manual or here.
+
+Web browsing with W3:
+* Q4.1.1:: What is W3?
+* Q4.1.2:: How do I run W3 from behind a firewall?
+* Q4.1.3:: Is it true that W3 supports style sheets and tables?
+
+Reading Netnews and Mail with Gnus:
+* Q4.2.1:: GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus, Quassia Gnus, argh!
+* Q4.2.2:: [This question intentionally left blank]
+* Q4.2.3:: How do I make Gnus stay within a single frame?
+* Q4.2.4:: How do I customize the From: line?
+
+Other Mail & News:
+* Q4.3.1:: How can I read and/or compose MIME messages?
+* Q4.3.2:: What is TM and where do I get it?
+* Q4.3.3:: Why isn't this `movemail' program working?
+* Q4.3.4:: Movemail is also distributed by Netscape? Can that cause problems?
+* Q4.3.5:: Where do I find pstogif (required by tm)?
+
+Sparcworks, EOS, and WorkShop:
+* Q4.4.1:: What is SPARCworks, EOS, and WorkShop
+
+Energize:
+* Q4.5.1:: What is/was Energize?
+
+Infodock:
+* Q4.6.1:: What is Infodock?
+
+Other Unbundled Packages:
+* Q4.7.1:: What is AUC TeX? Where do you get it?
+* Q4.7.2:: Are there any Emacs Lisp Spreadsheets?
+* Q4.7.3:: Byte compiling AUC TeX on XEmacs 19.14
+* Q4.7.4:: Problems installing AUC TeX
+* Q4.7.5:: Is there a reason for an Emacs package not to be included in XEmacs?
+* Q4.7.6:: Is there a MatLab mode?
+
+The Miscellaneous Stuff
+
+* Q5.0.1:: How can I do source code highlighting using font-lock?
+* Q5.0.2:: I do not like cc-mode. How do I use the old c-mode?
+* Q5.0.3:: How do I get `More' Syntax Highlighting on by default?
+* Q5.0.4:: How can I enable auto-indent?
+* Q5.0.5:: How can I get XEmacs to come up in text/auto-fill mode by default?
+* Q5.0.6:: How do I start up a second shell buffer?
+* Q5.0.7:: Telnet from shell filters too much.
+* Q5.0.8:: Why does edt emulation not work?
+* Q5.0.9:: How can I emulate VI and use it as my default mode?
+* Q5.0.10:: [This question intentionally left blank]
+* Q5.0.11:: Filladapt doesn't work in 19.15?
+* Q5.0.12:: How do I disable gnuserv from opening a new frame?
+* Q5.0.13:: How do I start gnuserv so that each subsequent XEmacs is a client?
+* Q5.0.14:: Strange things are happening in Shell Mode.
+* Q5.0.15:: Where do I get the latest CC Mode?
+* Q5.0.16:: I find auto-show-mode disconcerting. How do I turn it off?
+* Q5.0.17:: How can I get two instances of info?
+* Q5.0.18:: I upgraded to XEmacs 19.14 and gnuserv stopped working
+* Q5.0.19:: Is there something better than LaTeX mode?
+* Q5.0.20:: Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
+
+Emacs Lisp Programming Techniques:
+* Q5.1.1:: The difference in key sequences between XEmacs and GNU Emacs?
+* Q5.1.2:: Can I generate "fake" keyboard events?
+* Q5.1.3:: Could you explain `read-kbd-macro' in more detail?
+* Q5.1.4:: What is the performance hit of `let'?
+* Q5.1.5:: What is the recommended use of `setq'?
+* Q5.1.6:: What is the typical misuse of `setq' ?
+* Q5.1.7:: I like the the `do' form of cl, does it slow things down?
+* Q5.1.8:: I like recursion, does it slow things down?
+* Q5.1.9:: How do I put a glyph as annotation in a buffer?
+* Q5.1.10:: `map-extents' won't traverse all of my extents!
+* Q5.1.11:: My elisp program is horribly slow. Is there an easy way to find out where it spends time?
+
+Sound:
+* Q5.2.1:: How do I turn off the sound?
+* Q5.2.2:: How do I get funky sounds instead of a boring beep?
+* Q5.2.3:: What's NAS, how do I get it?
+* Q5.2.4:: Sunsite sounds don't play.
+
+Miscellaneous:
+* Q5.3.1:: How do you make XEmacs indent CL if-clauses correctly?
+* Q5.3.2:: Fontifying hangs when editing a postscript file.
+* Q5.3.3:: How can I print WYSIWYG a font-locked buffer?
+* Q5.3.4:: Getting `M-x lpr' to work with postscript printer.
+* Q5.3.5:: How do I specify the paths that XEmacs uses for finding files?
+* Q5.3.6:: [This question intentionally left blank]
+* Q5.3.7:: Can I have the end of the buffer delimited in some way?
+* Q5.3.8:: How do I insert today's date into a buffer?
+* Q5.3.9:: Are only certain syntactic character classes available for abbrevs?
+* Q5.3.10:: How can I get those oh-so-neat X-Face lines?
+* Q5.3.11:: How do I add new Info directories?
+* Q5.3.12:: What do I need to change to make printing work?
+
+What the Future Holds
+
+* Q6.0.1:: What is new in 20.2?
+* Q6.0.2:: What is new in 20.3?
+* Q6.0.3:: What is new in 20.4?
+* Q6.0.4:: Procedural changes in XEmacs development.
+
+\1f
+File: xemacs-faq.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
+
+1 Introduction, Policy, Credits
+*******************************
+
+ Learning XEmacs is a lifelong activity. Even people who have used
+Emacs for years keep discovering new features. Therefore this document
+cannot be complete. Instead it is aimed at the person who is either
+considering XEmacs for their own use, or has just obtained it and is
+wondering what to do next. It is also useful as a reference to
+available resources.
+
+ The previous maintainer of the FAQ was Anthony Rossini <rossini@stat.sc.edu>, who started it, after getting tired of hearing JWZ complain
+about repeatedly having to answer questions. Ben Wing <ben@666.com>
+and Chuck Thompson <cthomp@xemacs.org>, the principal authors of
+XEmacs, then took over and Ben did a massive update reorganizing the
+whole thing. At which point Anthony took back over, but then had to
+give it up again. Some of the other contributors to this FAQ are
+listed later in this document.
+
+ The previous version was converted to hypertext format, and edited by
+Steven L. Baur <steve@altair.xemacs.org>. It was converted back to
+texinfo by Hrvoje Niksic <hniksic@srce.hr>.
+
+ The FAQ was then maintained by Andreas Kaempf <andreas@sccon.com>,
+who passed it on to Christian Nybo/ <faq@xemacs.org>, the current FAQ
+maintainer.
+
+ If you notice any errors or items which should be added or amended to
+this FAQ please send email to Christian Nybo/ <faq@xemacs.org>. Include
+`XEmacs FAQ' on the Subject: line.
+
+* Menu:
+
+Introduction:
+* Q1.0.1:: What is XEmacs?
+* Q1.0.2:: What is the current version of XEmacs?
+* Q1.0.3:: Where can I find it?
+* Q1.0.4:: Why Another Version of Emacs?
+* Q1.0.5:: Why Haven't XEmacs and GNU Emacs Merged?
+* Q1.0.6:: Where can I get help?
+* Q1.0.7:: Where is the mailing list archived?
+* Q1.0.8:: How do you pronounce XEmacs?
+* Q1.0.9:: What does XEmacs look like?
+* Q1.0.10:: Is there a port of XEmacs to Microsoft ('95 or NT)?
+* Q1.0.11:: Is there a port of XEmacs to the Macintosh?
+* Q1.0.12:: Is there a port of XEmacs to NextStep?
+* Q1.0.13:: Is there a port of XEmacs to OS/2?
+* Q1.0.14:: Where can I get a printed copy of the XEmacs users manual?
+
+Policies:
+* Q1.1.1:: What is the FAQ editorial policy?
+* Q1.1.2:: How do I become a Beta Tester?
+* Q1.1.3:: How do I contribute to XEmacs itself?
+
+Credits:
+* Q1.2.1:: Who wrote XEmacs?
+* Q1.2.2:: Who contributed to this version of the FAQ?
+* Q1.2.3:: Who contributed to the FAQ in the past?
+
+Internationalization:
+* Q1.3.1:: What is the status of XEmacs v20?
+* Q1.3.2:: What is the status of Asian-language support, aka MULE?
+* Q1.3.3:: How do I type non-ASCII characters?
+* Q1.3.4:: Can XEmacs messages come out in a different language?
+* Q1.3.5:: Please explain the various input methods in MULE/XEmacs 20.0
+* Q1.3.6:: How do I portably code for MULE/XEmacs 20.0?
+* Q1.3.7:: How about Cyrillic Modes?
+
+Getting Started:
+* Q1.4.1:: What is a `.emacs' and is there a sample one?
+* Q1.4.2:: Can I use the same `.emacs' with the other Emacs?
+* Q1.4.3:: Any good XEmacs tutorials around?
+* Q1.4.4:: May I see an example of a useful XEmacs Lisp function?
+* Q1.4.5:: And how do I bind it to a key?
+* Q1.4.6:: What's the difference between a macro and a function?
+* Q1.4.7:: Why options saved with 19.13 don't work with 19.14 or later?
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.1, Next: Q1.0.2, Prev: Introduction, Up: Introduction
+
+1.0: Introduction
+=================
+
+Q1.0.1: What is XEmacs?
+-----------------------
+
+ An alternative to GNU Emacs, originally based on an early alpha
+version of FSF's version 19, and has diverged quite a bit since then.
+XEmacs was known as Lucid Emacs through version 19.10. Almost all
+features of GNU Emacs are supported in XEmacs. The maintainers of
+XEmacs actively track changes to GNU Emacs while also working to add
+new features.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.2, Next: Q1.0.3, Prev: Q1.0.1, Up: Introduction
+
+Q1.0.2: What is the current version of XEmacs?
+----------------------------------------------
+
+ XEmacs 20.4 is a minor upgrade from 20.3, containing many bugfixes.
+It was released in February 1998.
+
+ XEmacs 19.16 was the last release of v19, released in November, 1997,
+which was also the last version without international language support.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.3, Next: Q1.0.4, Prev: Q1.0.2, Up: Introduction
+
+Q1.0.3: Where can I find it?
+----------------------------
+
+ The canonical source and binaries is found via anonymous FTP at:
+
+ `ftp://ftp.xemacs.org/pub/xemacs/'
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.4, Next: Q1.0.5, Prev: Q1.0.3, Up: Introduction
+
+Q1.0.4: Why Another Version of Emacs?
+-------------------------------------
+
+ For a detailed description of the differences between GNU Emacs and
+XEmacs and a detailed history of XEmacs, check out the
+ NEWS file (http://www.xemacs.org/NEWS.html)
+
+ However, here is a list of some of the reasons why we think you might
+consider using it:
+
+ * It looks nicer.
+
+ * The XEmacs maintainers are generally more receptive to suggestions
+ than the GNU Emacs maintainers.
+
+ * Many more bundled packages than GNU Emacs
+
+ * Binaries are available for many common operating systems.
+
+ * Face support on TTY's.
+
+ * A built-in toolbar.
+
+ * Better Motif compliance.
+
+ * Some internationalization support (including full MULE support, if
+ compiled with it.)
+
+ * Variable-width fonts.
+
+ * Variable-height lines.
+
+ * Marginal annotations.
+
+ * ToolTalk support.
+
+ * XEmacs can be used as an Xt widget, and can be embedded within
+ another application.
+
+ * Horizontal and vertical scrollbars (using real toolkit scrollbars).
+
+ * Better APIs (and performance) for attaching fonts, colors, and
+ other properties to text.
+
+ * The ability to embed arbitrary graphics in a buffer.
+
+ * Completely compatible (at the C level) with the Xt-based toolkits.
+
+ * First production Web Browser supporting Style Sheets.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.5, Next: Q1.0.6, Prev: Q1.0.4, Up: Introduction
+
+Q1.0.5: Why Haven't XEmacs and GNU Emacs Merged?
+------------------------------------------------
+
+ There are currently irreconcilable differences in the views about
+technical, programming, design and organizational matters between RMS
+and the XEmacs development team which provide little hope for a merge to
+take place in the short-term future.
+
+ If you have a comment to add regarding the merge, it is a good idea
+to avoid posting to the newsgroups, because of the very heated
+flamewars that often result. Mail your questions to
+<xemacs-beta@xemacs.org> and <bug-gnu-emacs@prep.ai.mit.edu>.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.6, Next: Q1.0.7, Prev: Q1.0.5, Up: Introduction
+
+Q1.0.6: Where can I get help?
+-----------------------------
+
+ Probably the easiest way, if everything is installed, is to use
+info, by pressing `C-h i', or selecting `Manuals->Info' from the Help
+Menu.
+
+ Also, `M-x apropos' will look for commands for you.
+
+ Try reading this FAQ, examining the regular GNU Emacs FAQ (which can
+be found with the Emacs 19 distribution) as well as at
+`http://www.eecs.nwu.edu/emacs/faq/' and reading the Usenet group
+comp.emacs.xemacs.
+
+ If that does not help, try posting your question to
+comp.emacs.xemacs. Please *do not* post XEmacs related questions to
+gnu.emacs.help.
+
+ If you cannot post or read Usenet news, there is a corresponding
+mailing list which is available. It can be subscribed to by sending a
+message with a subject of `subscribe' to <xemacs-request@xemacs.org>
+for subscription information and <xemacs@xemacs.org> to send messages
+to the list.
+
+ To cancel a subscription, you *must* use the xemacs-request address.
+Send a message with a subject of `unsubscribe' to be removed.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.7, Next: Q1.0.8, Prev: Q1.0.6, Up: Introduction
+
+Q1.0.7: Where is the mailing list archived?
+-------------------------------------------
+
+ The mailing list was archived in the directory
+ `ftp://ftp.xemacs.org/pub/mlists/'.
+
+ However, this archive is out of date. The current mailing list
+server supports an `archive' feature, which may be utilized.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.8, Next: Q1.0.9, Prev: Q1.0.7, Up: Introduction
+
+Q1.0.8: How do you pronounce XEmacs?
+------------------------------------
+
+ I pronounce it `Eks eemax'.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.9, Next: Q1.0.10, Prev: Q1.0.8, Up: Introduction
+
+Q1.0.9: What does XEmacs look like?
+-----------------------------------
+
+ Screen snapshots are available in the WWW version of the FAQ.
+ `http://www.xemacs.org/faq/xemacs-faq.html'
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.10, Next: Q1.0.11, Prev: Q1.0.9, Up: Introduction
+
+Q1.0.10: Is there a port of XEmacs to Microsoft ('95 or NT)?
+------------------------------------------------------------
+
+ Thanks to efforts of many people, coordinated by David Hobley <davidh@wr.com.au> and Marc Paquette <marcpa@cam.org>, beta versions of
+XEmacs now run on 32-bit Windows platforms (NT and 95). The current
+betas require having an X server to run XEmacs; however, a native NT/95
+port is in alpha, thanks to Jonathan Harris <jhar@tardis.ed.ac.uk>.
+
+ Although some features are still unimplemented, XEmacs 21.0 will
+support MS-Windows.
+
+ The NT development is now coordinated by a mailing list at
+<xemacs-nt@xemacs.org>.
+
+ If you are willing to contribute or want to follow the progress,
+mail to <xemacs-nt-request@xemacs.org> to subscribe.
+
+ Furthermore, Altrasoft is seeking corporate and government sponsors
+to help fund a fully native port of XEmacs to Windows 95 and NT using
+full-time, senior-level staff working under a professionally managed
+project structure. See the Altrasoft web site (http://www.altrasoft.com/) for more details or contact Altrasoft directly at 1-888-ALTSOFT.
+
+ The closest existing port is "Win-Emacs", which is based on Lucid
+Emacs 19.6. Available from `http://www.pearlsoft.com/'.
+
+ There's a port of GNU Emacs (not XEmacs) at
+ `http://www.cs.washington.edu/homes/voelker/ntemacs.html'.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.11, Next: Q1.0.12, Prev: Q1.0.10, Up: Introduction
+
+Q1.0.11: Is there a port of XEmacs to the Macintosh?
+----------------------------------------------------
+
+ There has been a port to the MachTen environment of XEmacs 19.13,
+but no patches have been submitted to the maintainers to get this in the
+mainstream distribution.
+
+ For the MacOS, there is a port of
+Emacs 18.59 (ftp://ftp.cs.cornell.edu/pub/parmet/).
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.12, Next: Q1.0.13, Prev: Q1.0.11, Up: Introduction
+
+Q1.0.12: Is there a port of XEmacs to NextStep?
+-----------------------------------------------
+
+ Carl Edman, apparently no longer at <cedman@princeton.edu>, did the
+port of GNU Emacs to NeXTstep and expressed interest in doing the
+XEmacs port, but never went any farther.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.13, Next: Q1.0.14, Prev: Q1.0.12, Up: Introduction
+
+Q1.0.13: Is there a port of XEmacs to OS/2?
+-------------------------------------------
+
+ No, and there is no news of anyone working on it.
+
+\1f
+File: xemacs-faq.info, Node: Q1.0.14, Next: Q1.1.1, Prev: Q1.0.13, Up: Introduction
+
+Q1.0.14: Where can I obtain a printed copy of the XEmacs users manual?
+----------------------------------------------------------------------
+
+ Altrasoft Associates, a firm specializing in Emacs-related support
+and development, will be maintaining the XEmacs user manual. The firm
+plans to begin publishing printed copies of the manual soon.
+
+ Web: `http://www.xemacs.com'
+ E-mail: <info@xemacs.com>
+ Tel: +1 408 243 3300
+
+\1f
+File: xemacs-faq.info, Node: Q1.1.1, Next: Q1.1.2, Prev: Q1.0.14, Up: Introduction
+
+1.1: Policies
+=============
+
+Q1.1.1: What is the FAQ editorial policy?
+-----------------------------------------
+
+ The FAQ is actively maintained and modified regularly. All links
+should be up to date.
+
+ Changes are displayed on a monthly basis. "Months", for this
+purpose are defined as the 5th of the month through the 5th of the
+month. Preexisting questions that have been changed are marked as such.
+Brand new questions are tagged.
+
+ All submissions are welcome. E-mail submissions to Christian Nybo/ <faq@xemacs.org>.
+
+ Please make sure that `XEmacs FAQ' appears on the Subject: line. If
+you think you have a better way of answering a question, or think a
+question should be included, I'd like to hear about it. Questions and
+answers included into the FAQ will be edited for spelling and grammar,
+and will be attributed. Answers appearing without attribution are
+either from versions of the FAQ dated before May 1996, or are from one
+of the four people listed at the top of this document. Answers quoted
+from Usenet news articles will always be attributed, regardless of the
+author.
+
+\1f
+File: xemacs-faq.info, Node: Q1.1.2, Next: Q1.1.3, Prev: Q1.1.1, Up: Introduction
+
+Q1.1.2: How do I become a Beta Tester?
+--------------------------------------
+
+ Send an email message to <xemacs-beta-request@xemacs.org> with a
+subject line of `subscribe'.
+
+ Be prepared to get your hands dirty, as beta testers are expected to
+identify problems as best they can.
+
+\1f
+File: xemacs-faq.info, Node: Q1.1.3, Next: Q1.2.1, Prev: Q1.1.2, Up: Introduction
+
+Q1.1.3: How do I contribute to XEmacs itself?
+---------------------------------------------
+
+ Ben Wing <ben@666.com> writes:
+
+ BTW if you have a wish list of things that you want added, you
+ have to speak up about it! More specifically, you can do the
+ following if you want a feature added (in increasing order of
+ usefulness):
+
+ * Make a posting about a feature you want added.
+
+ * Become a beta tester and make more postings about those same
+ features.
+
+ * Convince us that you're going to use the features in some
+ cool and useful way.
+
+ * Come up with a clear and well-thought-out API concerning the
+ features.
+
+ * Write the code to implement a feature and send us a patch.
+
+ (not that we're necessarily requiring you to write the code, but
+ we can always hope :)
+
+\1f
+File: xemacs-faq.info, Node: Q1.2.1, Next: Q1.2.2, Prev: Q1.1.3, Up: Introduction
+
+1.2: Credits
+============
+
+Q1.2.1: Who wrote XEmacs?
+-------------------------
+
+ XEmacs is the result of the time and effort of many people. The
+developers responsible for the 19.16/20.x releases are:
+
+ * Martin Buchholz <martin@xemacs.org>
+
+ * Steve Baur <steve@altair.xemacs.org>
+
+ * Hrvoje Niksic <hniksic@srce.hr>
+
+ The developers responsible for the 19.14 release are:
+
+ * Chuck Thompson <cthomp@xemacs.org>
+
+ Chuck was Mr. XEmacs from 19.11 through 19.14, and is responsible
+ for XEmacs becoming a widely distributed program over the Internet.
+
+ * Ben Wing <ben@666.com>
+
+ * Jamie Zawinski <jwz@netscape.com>
+
+ Jamie Zawinski was Mr. Lucid Emacs from 19.0 through 19.10, the
+ last release actually named Lucid Emacs. Richard Mlynarik was
+ crucial to most of those releases.
+
+ * Richard Mlynarik <mly@adoc.xerox.com>
+
+ Along with many other contributors, partially enumerated in the
+`About XEmacs' option in the Help menu.
+
+\1f
+File: xemacs-faq.info, Node: Q1.2.2, Next: Q1.2.3, Prev: Q1.2.1, Up: Introduction
+
+Q1.2.2: Who contributed to this version of the FAQ?
+---------------------------------------------------
+
+ The following people contributed valuable suggestions to building
+this version of the FAQ (listed in alphabetical order):
+
+ * SL Baur <steve@xemacs.org>
+
+ * Hrvoje Niksic <hniksic@srce.hr>
+
+ * Aki Vehtari <Aki.Vehtari@hut.fi>
+
+\1f
+File: xemacs-faq.info, Node: Q1.2.3, Next: Q1.3.1, Prev: Q1.2.2, Up: Introduction
+
+Q1.2.3: Who contributed to the FAQ in the past?
+-----------------------------------------------
+
+ This is only a partial list, as many names were lost in a hard disk
+crash some time ago.
+
+ * Curtis.N.Bingham <binge@aloft.att.com>
+
+ * Richard Caley <rjc@cogsci.ed.ac.uk>
+
+ * Richard Cognot <cognot@ensg.u-nancy.fr>
+
+ * William G. Dubuque <wgd@martigny.ai.mit.edu>
+
+ * Eric Eide <eeide@cs.utah.edu>
+
+ * Chris Flatters <cflatter@nrao.edu>
+
+ * Evelyn Ginsparg <ginsparg@adra.com>
+
+ * Marty Hall <hall@aplcenmp.apl.jhu.edu>
+
+ * Darrell Kindred <dkindred@cmu.edu>
+
+ * David Moore <dmoore@ucsd.edu>
+
+ * Arup Mukherjee <arup+@cmu.edu>
+
+ * Juergen Nickelsen <nickel@prz.tu-berlin.de>
+
+ * Kevin R. Powell <powell@csl.ncsa.uiuc.edu>
+
+ * Justin Sheehy <dworkin@ccs.neu.edu>
+
+ * Stig <stig@hackvan.com>
+
+ * Aki Vehtari <Aki.Vehtari@hut.fi>
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.1, Next: Q1.3.2, Prev: Q1.2.3, Up: Introduction
+
+1.3: Internationalization
+=========================
+
+Q1.3.1: What is the status of XEmacs v20?
+-----------------------------------------
+
+ XEmacs v20 is the version of XEmacs that includes MULE
+(Asian-language) support. XEmacs 20.0 was released in February 1997,
+followed by XEmacs 20.2 in May, XEmacs 20.3 in November and XEmacs 20.4
+in February 1998. When compiled without MULE support, 20.4 is
+approximately as stable as 19.16, and probably faster (due to
+additional optimization work.)
+
+ As of XEmacs 20.3, version 20 is *the* supported version of XEmacs.
+This means that 19.16 will optionally receive stability fixes (if any),
+but that all the real development work will be done on the v20 tree.
+
+ The incompatible changes in XEmacs 20 include the additional
+byte-codes, new primitive data types (`character', `char-table', and
+`range-table'). This means that the character-integer equivalence
+inherent to all the previous Emacs and XEmacs releases no longer
+applies.
+
+ However, to avoid breaking old code, many functions that should
+normally accept characters work with integers, and vice versa. For more
+information, see the Lisp reference manual. Here is a relevant excerpt,
+for your convenience.
+
+ In XEmacs version 19, and in all versions of FSF GNU Emacs, a
+ "character" in XEmacs Lisp is nothing more than an integer. This
+ is yet another holdover from XEmacs Lisp's derivation from
+ vintage-1980 Lisps; modern versions of Lisp consider this
+ equivalence a bad idea, and have separate character types. In
+ XEmacs version 20, the modern convention is followed, and
+ characters are their own primitive types. (This change was
+ necessary in order for MULE, i.e. Asian-language, support to be
+ correctly implemented.)
+
+ Even in XEmacs version 20, remnants of the equivalence between
+ characters and integers still exist; this is termed the "char-int
+ confoundance disease". In particular, many functions such as `eq',
+ `equal', and `memq' have equivalent functions (`old-eq',
+ `old-equal', `old-memq', etc.) that pretend like characters are
+ integers are the same. Byte code compiled under any version 19
+ Emacs will have all such functions mapped to their `old-'
+ equivalents when the byte code is read into XEmacs 20. This is to
+ preserve compatibility - Emacs 19 converts all constant characters
+ to the equivalent integer during byte-compilation, and thus there
+ is no other way to preserve byte-code compatibility even if the
+ code has specifically been written with the distinction between
+ characters and integers in mind.
+
+ Every character has an equivalent integer, called the "character
+ code". For example, the character `A' is represented as the
+ integer 65, following the standard ASCII representation of
+ characters. If XEmacs was not compiled with MULE support, the
+ range of this integer will always be 0 to 255 - eight bits, or one
+ byte. (Integers outside this range are accepted but silently
+ truncated; however, you should most decidedly *not* rely on this,
+ because it will not work under XEmacs with MULE support.) When
+ MULE support is present, the range of character codes is much
+ larger. (Currently, 19 bits are used.)
+
+ FSF GNU Emacs uses kludgy character codes above 255 to represent
+ keyboard input of ASCII characters in combination with certain
+ modifiers. XEmacs does not use this (a more general mechanism is
+ used that does not distinguish between ASCII keys and other keys),
+ so you will never find character codes above 255 in a non-MULE
+ XEmacs.
+
+ Individual characters are not often used in programs. It is far
+ more common to work with *strings*, which are sequences composed of
+ characters.
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.2, Next: Q1.3.3, Prev: Q1.3.1, Up: Introduction
+
+Q1.3.2: What is the status of Asian-language support, aka MULE?
+---------------------------------------------------------------
+
+ The MULE support works OK but still needs a fair amount of work
+before it's really solid. We could definitely use some help here, esp.
+people who speak Japanese and will use XEmacs/MULE to work with
+Japanese and have some experience with E-Lisp.
+
+ As the fundings on Mule have stopped, the Mule part of XEmacs is
+currently looking for a full-time maintainer. If you can provide help
+here, or are willing to fund the work, please mail to
+<xemacs-beta@xemacs.org>.
+
+ *Note Q1.1.2::.
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.3, Next: Q1.3.4, Prev: Q1.3.2, Up: Introduction
+
+Q1.3.3: How do I type non-ASCII characters?
+-------------------------------------------
+
+ See question 3.5.7 (*note Q3.5.7::.) in part 3 of this FAQ.
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.4, Next: Q1.3.5, Prev: Q1.3.3, Up: Introduction
+
+Q1.3.4: Can XEmacs messages come out in a different language?
+-------------------------------------------------------------
+
+ The message-catalog support has mostly been written but doesn't
+currently work. The first release of XEmacs 20 will *not* support it.
+However, menubar localization *does* work, even in 19.14. To enable
+it, add to your `Emacs' file entries like this:
+
+ Emacs*XlwMenu.resourceLabels: True
+ Emacs*XlwMenu.file.labelString: Fichier
+ Emacs*XlwMenu.openInOtherWindow.labelString: In anderem Fenster offnen
+
+ The name of the resource is derived from the non-localized entry by
+removing punctuation and capitalizing as above.
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.5, Next: Q1.3.6, Prev: Q1.3.4, Up: Introduction
+
+Q1.3.5: Please explain the various input methods in MULE/XEmacs 20.0
+--------------------------------------------------------------------
+
+ MORIOKA Tomohiko <morioka@jaist.ac.jp> writes:
+
+ Original Mule supports the following input methods: Wnn4, Wnn6,
+ Canna, SJ3 and XIM. Interfaces for Wnn and SJ3 uses the `egg' user
+ interface. Interface for Canna does not use `egg'. I don't know
+ about XIM. It is to support ATOK, of course, it may work for
+ another servers.
+
+ Wnn supports Japanese, Chinese and Korean. It is made by OMRON and
+ Kyôto university. It is a powerful and complex system. Wnn4 is
+ free and Wnn6 is not free.
+
+ Canna supports only Japanese. It is made by NEC. It is a simple and
+ powerful system. Canna uses only grammar (Wnn uses grammar and
+ probability between words), so I think Wnn is cleverer than Canna,
+ however Canna users made a good grammar and dictionary. So for
+ standard modern Japanese, Canna seems cleverer than Wnn4. In
+ addition, the UNIX version of Canna is free (now there is a
+ Microsoft Windows version).
+
+ SJ3 supports only Japanese. It is made by Sony. XIM supports was
+ made to use ATOK (a major input method in personal computer
+ world). XIM is the standard for accessing input methods bundled
+ in Japanese versions of Solaris. (XEmacs 20 will support XIM
+ input).
+
+ Egg consists of following parts:
+
+ 1. Input character Translation System (ITS) layer. It
+ translates ASCII inputs to Kana/PinYin/Hangul characters.
+
+ 2. Kana/PinYin/Hangul to Kanji transfer layer. It is interface
+ layer for network Kana-Kanji server (Wnn and Sj3).
+
+ These input methods are modal, namely there are mode, alphabet
+ mode and Kana-Kanji transfer mode. However there are mode-less
+ input methods for Egg and Canna. `Boiled-egg' is a mode-less
+ input method running on Egg. For Canna, `canna.el' has a tiny
+ boiled-egg like command, `(canna-boil)', and there are some
+ boiled-egg like utilities. In addition, it was planned to make an
+ abstraction for all transfer type input methods. However authors
+ of input methods are busy, so maybe this plan is stopped. Perhaps
+ after Mule merged GNU Emacs will be released, it will be continued.
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.6, Next: Q1.3.7, Prev: Q1.3.5, Up: Introduction
+
+Q1.3.6: How do I portably code for MULE/XEmacs 20?
+--------------------------------------------------
+
+ MORIOKA Tomohiko <morioka@jaist.ac.jp> writes:
+
+ MULE and XEmacs are quite different. So the application
+ implementor must write separate code for these mule variants.
+
+ MULE and the next version of Emacs are similar but the symbols are
+ very different--requiring separate code as well.
+
+ Namely we must support 3 kinds of mule variants and 4 or 5 or 6
+ kinds of emacs variants... (;_;) I'm shocked, so I wrote a wrapper
+ package called `emu' to provide a common interface.
+
+ I have the following suggestions about dealing with mule variants:
+
+ * `(featurep 'mule)' `t' on all mule variants
+
+ * `(boundp 'MULE)' is `t' on only MULE. Maybe the next version
+ of Emacs will not have this symbol.
+
+ * MULE has a variable `mule-version'. Perhaps the next version
+ of Emacs will have this variable as well.
+
+ Following is a sample to distinguish mule variants:
+
+ (if (featurep 'mule)
+ (cond ((boundp 'MULE)
+ ;; for original Mule
+ )
+ ((string-match "XEmacs" emacs-version)
+ ;; for XEmacs with Mule
+ )
+ (t
+ ;; for next version of Emacs
+ ))
+ ;; for old emacs variants
+ )
+
+\1f
+File: xemacs-faq.info, Node: Q1.3.7, Next: Q1.4.1, Prev: Q1.3.6, Up: Introduction
+
+Q1.3.7: How about Cyrillic Modes?
+---------------------------------
+
+ Ilya Zakharevich <ilya@math.ohio-state.edu> writes:
+
+ There is a cyrillic mode in the file `mysetup.zip' in
+ `ftp://ftp.math.ohio-state.edu/pub/users/ilya/emacs/'. This is a
+ modification to Valery Alexeev's <ava@math.jhu.ed> `russian.el'
+ which can be obtained from
+
+ `http://ftpsearch.ntnu.no/?query=russian.el.Z'.
+
+ Dima Barsky <d.barsky@ee.surrey.ac.uk> writes:
+
+ There is another cyrillic mode for both GNU Emacs and XEmacs by
+ Dmitrii (Mitya) Manin <manin@camelot.mssm.edu> at
+ `http://kulichki-lat.rambler.ru/centrolit/manin/cyr.el'.
+
+ Rebecca Ore <rebecca.ore@op.net> writes:
+
+ The fullest resource I found on Russian language use (in and out of
+ XEmacs) is
+ `http://sunsite.oit.unc.edu/sergei/Software/Software.html'
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.1, Next: Q1.4.2, Prev: Q1.3.7, Up: Introduction
+
+1.4: Getting Started, Backing up & Recovery
+===========================================
+
+Q1.4.1: What is a `.emacs' and is there a sample one?
+-----------------------------------------------------
+
+ The `.emacs' file is used to customize XEmacs to your tastes. No
+two are alike, nor are they expected to be alike, but that's the point.
+The XEmacs distribution contains an excellent starter example in the etc
+directory called `sample.emacs'. Copy this file from there to your
+home directory and rename it `.emacs'. Then edit it to suit.
+
+ Starting with 19.14, you may bring the `sample.emacs' into an XEmacs
+buffer by selecting `Help->Samples->Sample .emacs' from the menubar.
+To determine the location of the `etc' directory type the command `C-h
+v data-directory <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.2, Next: Q1.4.3, Prev: Q1.4.1, Up: Introduction
+
+Q1.4.2: Can I use the same `.emacs' with the other Emacs?
+---------------------------------------------------------
+
+ Yes. The sample `.emacs' included in the XEmacs distribution will
+show you how to handle different versions and flavors of Emacs.
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.3, Next: Q1.4.4, Prev: Q1.4.2, Up: Introduction
+
+Q1.4.3: Any good tutorials around?
+----------------------------------
+
+ There's the XEmacs tutorial available from the Help Menu under
+`Basics->Tutorials', or by typing `C-h t'. To check whether it's
+available in a non-english language, type `C-u C-h t TAB', type the
+first letters of your preferred language, then type <RET>.
+
+ There's an Emacs Lisp tutorial at
+
+ `ftp://prep.ai.mit.edu/pub/gnu/emacs-lisp-intro-1.04.tar.gz'.
+
+ Erik Sundermann <erik@petaxp.rug.ac.be> has made a tutorial web page
+at `http://petaxp.rug.ac.be/~erik/xemacs/'.
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.4, Next: Q1.4.5, Prev: Q1.4.3, Up: Introduction
+
+Q1.4.4: May I see an example of a useful XEmacs Lisp function?
+--------------------------------------------------------------
+
+ The following function does a little bit of everything useful. It
+does something with the prefix argument, it examines the text around the
+cursor, and it's interactive so it may be bound to a key. It inserts
+copies of the current word the cursor is sitting on at the cursor. If
+you give it a prefix argument: `C-u 3 M-x double-word' then it will
+insert 3 copies.
+
+ (defun double-word (count)
+ "Insert a copy of the current word underneath the cursor"
+ (interactive "*p")
+ (let (here there string)
+ (save-excursion
+ (forward-word -1)
+ (setq here (point))
+ (forward-word 1)
+ (setq there (point))
+ (setq string (buffer-substring here there)))
+ (while (>= count 1)
+ (insert string)
+ (decf count))))
+
+ The best way to see what is going on here is to let XEmacs tell you.
+Put the code into an XEmacs buffer, and do a `C-h f' with the cursor
+sitting just to the right of the function you want explained. Eg. move
+the cursor to the SPACE between `interactive' and `"*p"' and hit `C-h
+f' to see what the function `interactive' does. Doing this will tell
+you that the `*' requires a writable buffer, and `p' converts the
+prefix argument to a number, and `interactive' allows you to execute
+the command with `M-x'.
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.5, Next: Q1.4.6, Prev: Q1.4.4, Up: Introduction
+
+Q1.4.5: And how do I bind it to a key?
+--------------------------------------
+
+ To bind to a key do:
+
+ (global-set-key "\C-cd" 'double-word)
+
+ Or interactively, `M-x global-set-key' and follow the prompts.
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.6, Next: Q1.4.7, Prev: Q1.4.5, Up: Introduction
+
+Q1.4.6: What's the difference between a macro and a function?
+-------------------------------------------------------------
+
+ Quoting from the Lisp Reference (a.k.a "Lispref") Manual:
+
+ "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.
+
+ Do not confuse the two terms with "keyboard macros", which are
+another matter, entirely. A keyboard macro is a key bound to several
+other keys. Refer to manual for details.
+
+\1f
+File: xemacs-faq.info, Node: Q1.4.7, Prev: Q1.4.6, Up: Introduction
+
+Q1.4.7: How come options saved with 19.13 don't work with 19.14 or later?
+-------------------------------------------------------------------------
+
+ There's a problem with options of the form:
+
+ (add-spec-list-to-specifier (face-property 'searchm-field 'font)
+ '((global (nil))))
+
+ saved by a 19.13 XEmacs that causes a 19.14 XEmacs grief. You must
+delete these options. XEmacs 19.14 and later no longer write the
+options directly to `.emacs' which should allow us to deal with version
+incompatibilities better in the future.
+
+ Options saved under XEmacs 19.13 are protected by code that
+specifically requires a version 19 XEmacs. This won't be a problem
+unless you're using XEmacs v20. You should consider changing the code
+to read:
+
+ (cond
+ ((and (string-match "XEmacs" emacs-version)
+ (boundp 'emacs-major-version)
+ (or (and (= emacs-major-version 19)
+ (>= emacs-minor-version 12))
+ (>= emacs-major-version 20)))
+ ...
+ ))
+
--- /dev/null
+This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
+1.68 from the input file xemacs-faq.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* FAQ: (xemacs-faq). XEmacs FAQ.
+END-INFO-DIR-ENTRY
+
+\1f
+File: xemacs-faq.info, Node: Installation, Next: Customization, Prev: Introduction, Up: Top
+
+2 Installation and Trouble Shooting
+***********************************
+
+ This is part 2 of the XEmacs Frequently Asked Questions list. This
+section is devoted to Installation, Maintenance and Trouble Shooting.
+
+* Menu:
+
+Installation:
+* Q2.0.1:: Running XEmacs without installing.
+* Q2.0.2:: XEmacs is too big.
+* Q2.0.3:: Compiling XEmacs with Netaudio.
+* Q2.0.4:: Problems with Linux and ncurses.
+* Q2.0.5:: Do I need X11 to run XEmacs?
+* Q2.0.6:: I'm having strange crashes. What do I do?
+* Q2.0.7:: Libraries in non-standard locations.
+* Q2.0.8:: can't resolve symbol _h_errno
+* Q2.0.9:: Where do I find external libraries?
+* Q2.0.10:: After I run configure I find a coredump, is something wrong?
+* Q2.0.11:: XEmacs can't resolve host names.
+* Q2.0.12:: Why can't I strip XEmacs?
+* Q2.0.13:: Can't link XEmacs on Solaris with Gcc.
+* Q2.0.14:: Make on HP/UX 9 fails after linking temacs
+
+Trouble Shooting:
+* Q2.1.1:: XEmacs just crashed on me!
+* Q2.1.2:: Cryptic Minibuffer messages.
+* Q2.1.3:: Translation Table Syntax messages at Startup.
+* Q2.1.4:: Startup warnings about deducing proper fonts?
+* Q2.1.5:: XEmacs cannot connect to my X Terminal.
+* Q2.1.6:: XEmacs just locked up my Linux X server.
+* Q2.1.7:: HP Alt key as Meta.
+* Q2.1.8:: got (wrong-type-argument color-instance-p nil)!
+* Q2.1.9:: XEmacs causes my OpenWindows 3.0 server to crash.
+* Q2.1.10:: Warnings from incorrect key modifiers.
+* Q2.1.11:: Can't instantiate image error... in toolbar
+* Q2.1.12:: Regular Expression Problems on DEC OSF1.
+* Q2.1.13:: HP/UX 10.10 and `create_process' failure
+* Q2.1.14:: `C-g' doesn't work for me. Is it broken?
+* Q2.1.15:: How to debug an XEmacs problem with a debugger.
+* Q2.1.16:: XEmacs crashes in `strcat' on HP/UX 10.
+* Q2.1.17:: `Marker does not point anywhere'.
+* Q2.1.18:: 19.14 hangs on HP/UX 10.10.
+* Q2.1.19:: XEmacs does not follow the local timezone.
+* Q2.1.20:: `Symbol's function definition is void: hkey-help-show.'
+* Q2.1.21:: Every so often the XEmacs frame freezes.
+* Q2.1.22:: XEmacs seems to take a really long time to do some things.
+* Q2.1.23:: Movemail on Linux does not work for XEmacs 19.15 and later.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.1, Next: Q2.0.2, Prev: Installation, Up: Installation
+
+2.0: Installation
+=================
+
+Q2.0.1: Running XEmacs without installing
+-----------------------------------------
+
+ The `INSTALL' file says that up to 108 MB of space is needed
+temporarily during installation! How can I just try it out?
+
+ XEmacs will run in place without requiring installation and copying
+of the Lisp directories, and without having to specify a special
+build-time flag. It's the copying of the Lisp directories that
+requires so much space. XEmacs is largely written in Lisp.
+
+ A good method is to make a shell alias for xemacs:
+
+ alias xemacs=/i/xemacs-20.2/src/xemacs
+
+ (You will obviously use whatever directory you downloaded the source
+tree to instead of `/i/xemacs-20.2').
+
+ This will let you run XEmacs without massive copying.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.2, Next: Q2.0.3, Prev: Q2.0.1, Up: Installation
+
+Q2.0.2: XEmacs is too big
+-------------------------
+
+ Although this entry has been written for XEmacs 19.13, most of it
+still stands true.
+
+ Steve Baur <steve@altair.xemacs.org> writes:
+
+ The 45MB of space required by the installation directories can be
+ reduced dramatically if desired. Gzip all the .el files. Remove
+ all the packages you'll never want to use (or even ones you do
+ like the two obsolete mailcrypts and Gnus 4 in 19.13). Remove the
+ TexInfo manuals. Remove the Info (and use just hardcopy versions
+ of the manual). Remove most of the stuff in etc. Remove or gzip
+ all the source code. Gzip or remove the C source code. Configure
+ it so that copies are not made of the support lisp. I'm not
+ advocating any of these things, just pointing out ways to reduce
+ the disk requirements if desired.
+
+ Now examine the space used by directory:
+
+ 0 /usr/local/bin/xemacs
+ 2048 /usr/local/bin/xemacs-19.13
+
+ 1546 /usr/local/lib/xemacs-19.13/i486-miranova-sco3.2v4.2
+ 1158 /usr/local/lib/xemacs-19.13/i486-unknown-linux1.2.13
+
+ You need to keep these. XEmacs isn't stripped by default in
+ installation, you should consider stripping. That will save you
+ about 5MB right there.
+
+ 207 /usr/local/lib/xemacs-19.13/etc/w3
+ 122 /usr/local/lib/xemacs-19.13/etc/sounds
+ 18 /usr/local/lib/xemacs-19.13/etc/sparcworks
+ 159 /usr/local/lib/xemacs-19.13/etc/vm
+ 6 /usr/local/lib/xemacs-19.13/etc/e
+ 21 /usr/local/lib/xemacs-19.13/etc/eos
+ 172 /usr/local/lib/xemacs-19.13/etc/toolbar
+ 61 /usr/local/lib/xemacs-19.13/etc/ns
+ 43 /usr/local/lib/xemacs-19.13/etc/gnus
+
+ These are support directories for various packages. In general
+ they match a directory under
+ ./xemacs-19.13/lib/xemacs-19.13/lisp/. If you do not require the
+ package, you may delete or gzip the support too.
+
+ 1959 /usr/local/lib/xemacs-19.13/etc
+ 175 /usr/local/lib/xemacs-19.13/lisp/bytecomp
+ 340 /usr/local/lib/xemacs-19.13/lisp/calendar
+ 342 /usr/local/lib/xemacs-19.13/lisp/comint
+ 517 /usr/local/lib/xemacs-19.13/lisp/dired
+ 42 /usr/local/lib/xemacs-19.13/lisp/electric
+ 212 /usr/local/lib/xemacs-19.13/lisp/emulators
+ 238 /usr/local/lib/xemacs-19.13/lisp/energize
+ 289 /usr/local/lib/xemacs-19.13/lisp/gnus
+ 457 /usr/local/lib/xemacs-19.13/lisp/ilisp
+ 1439 /usr/local/lib/xemacs-19.13/lisp/modes
+ 2276 /usr/local/lib/xemacs-19.13/lisp/packages
+ 1040 /usr/local/lib/xemacs-19.13/lisp/prim
+ 176 /usr/local/lib/xemacs-19.13/lisp/pcl-cvs
+ 154 /usr/local/lib/xemacs-19.13/lisp/rmail
+ 3 /usr/local/lib/xemacs-19.13/lisp/epoch
+ 45 /usr/local/lib/xemacs-19.13/lisp/term
+ 860 /usr/local/lib/xemacs-19.13/lisp/utils
+ 851 /usr/local/lib/xemacs-19.13/lisp/vm
+ 13 /usr/local/lib/xemacs-19.13/lisp/vms
+ 157 /usr/local/lib/xemacs-19.13/lisp/x11
+ 19 /usr/local/lib/xemacs-19.13/lisp/tooltalk
+ 14 /usr/local/lib/xemacs-19.13/lisp/sunpro
+ 291 /usr/local/lib/xemacs-19.13/lisp/games
+ 198 /usr/local/lib/xemacs-19.13/lisp/edebug
+ 619 /usr/local/lib/xemacs-19.13/lisp/w3
+ 229 /usr/local/lib/xemacs-19.13/lisp/eos
+ 55 /usr/local/lib/xemacs-19.13/lisp/iso
+ 59 /usr/local/lib/xemacs-19.13/lisp/mailcrypt
+ 187 /usr/local/lib/xemacs-19.13/lisp/eterm
+ 356 /usr/local/lib/xemacs-19.13/lisp/ediff
+ 408 /usr/local/lib/xemacs-19.13/lisp/hyperbole/kotl
+ 1262 /usr/local/lib/xemacs-19.13/lisp/hyperbole
+ 247 /usr/local/lib/xemacs-19.13/lisp/hm--html-menus
+ 161 /usr/local/lib/xemacs-19.13/lisp/mh-e
+ 299 /usr/local/lib/xemacs-19.13/lisp/viper
+ 53 /usr/local/lib/xemacs-19.13/lisp/oobr/tree-x
+ 4 /usr/local/lib/xemacs-19.13/lisp/oobr/tree-nx/English.lproj/DocWindow.nib
+ 3 /usr/local/lib/xemacs-19.13/lisp/oobr/tree-nx/English.lproj/InfoPanel.nib
+ 3 /usr/local/lib/xemacs-19.13/lisp/oobr/tree-nx/English.lproj/TreeView.nib
+ 11 /usr/local/lib/xemacs-19.13/lisp/oobr/tree-nx/English.lproj
+ 53 /usr/local/lib/xemacs-19.13/lisp/oobr/tree-nx
+ 466 /usr/local/lib/xemacs-19.13/lisp/oobr
+ 14142 /usr/local/lib/xemacs-19.13/lisp
+
+ These are all Emacs Lisp source code and bytecompiled object code.
+ You may safely gzip everything named *.el here. You may remove
+ any package you don't use. *Nothing bad will happen if you delete
+ a package that you do not use*. You must be sure you do not use
+ it though, so be conservative at first.
+
+ Possible candidates for deletion include w3 (newer versions exist,
+ or you may just use Lynx or Netscape for web browsing), games,
+ hyperbole, mh-e, hm-html-menus (better packages exist), vm, viper,
+ oobr, gnus (new versions exist), etc. Ask yourself, *Do I ever
+ want to use this package?* If the answer is no, then it is a
+ candidate for removal.
+
+ First, gzip all the .el files. Then go about package by package
+ and start gzipping the .elc files. Then run XEmacs and do
+ whatever it is you normally do. If nothing bad happens, then
+ delete the directory. Be conservative about deleting directories,
+ and it would be handy to have a backup tape around in case you get
+ too zealous.
+
+ `prim', `modes', `packages', and `utils' are four directories you
+ definitely do *not* want to delete, although certain packages can
+ be removed from them if you do not use them.
+
+ 1972 /usr/local/lib/xemacs-19.13/info
+
+ These are online texinfo sources. You may either gzip them or
+ remove them. In either case, `C-h i' (info mode) will no longer
+ work.
+
+ 20778 /usr/local/lib/xemacs-19.13
+
+ The 20MB achieved is less than half of what the full distribution
+ takes up, *and* can be achieved without deleting a single file.
+
+ Giacomo Boffi <boffi@hp735.stru.polimi.it> provides this procedure:
+
+ Substitute `/usr/local/lib/' with the path where the xemacs tree is
+ rooted, then use this script:
+
+ #!/bin/sh
+
+ r=/usr/local/lib/xemacs-19.13/lisp
+
+ cd $r ; rm -f cmpr ; touch cmpr
+
+ du -s .
+
+ for d in * ; do
+ if test -d $d ; then
+ cd $d
+ for f in *.el ; do
+ # compress (remove) only (ONLY) the sources that have a
+ # corresponding compiled file --- do not (DO NOT)
+ # touch other sources
+ if test -f ${f}c ; then gzip -v9 $f >> $r/cmpr ; fi
+ done
+ cd ..
+ fi
+ done
+
+ du -s .
+
+ A step beyond would be substituting `rm -f' for `gzip -v9', but
+ you have to be desperate for removing the sources (remember that
+ emacs can access compressed files transparently).
+
+ Also, a good megabyte could easily be trimmed from the $r/../etc
+ directory, e.g., the termcap files, some O+NEWS, others that I
+ don't remember as well.
+
+ XEmacs 21.0 will unbundle the lisp hierarchy and allow the
+ installer to choose exactly how much support code gets installed.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.3, Next: Q2.0.4, Prev: Q2.0.2, Up: Installation
+
+Q2.0.3: Compiling XEmacs with Netaudio.
+---------------------------------------
+
+ What is the best way to compile XEmacs with the netaudio system,
+since I have got the netaudio system compiled but installed at a weird
+place, I am not root. Also in the READMEs it does not say anything
+about compiling with the audioserver?
+
+ You should only need to add some stuff to the configure command line.
+To tell it to compile in netaudio support: `--with-sound=both', or
+`--with-sound=nas' if you don't want native sound support for some
+reason.) To tell it where to find the netaudio includes and libraries:
+
+ --site-libraries=WHATEVER
+ --site-includes=WHATEVER
+
+ Then (fingers crossed) it should compile and it will use netaudio if
+you have a server running corresponding to the X server. The netaudio
+server has to be there when XEmacs starts. If the netaudio server goes
+away and another is run, XEmacs should cope (fingers crossed, error
+handling in netaudio isn't perfect).
+
+ BTW, netaudio has been renamed as it has a name clash with something
+else, so if you see references to NAS or Network Audio System, it's the
+same thing. It also might be found at
+`ftp://ftp.x.org/contrib/audio/nas/'.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.4, Next: Q2.0.5, Prev: Q2.0.3, Up: Installation
+
+Q2.0.4: Problems with Linux and ncurses.
+----------------------------------------
+
+ On Linux 1.3.98 with termcap 2.0.8 and the ncurses that came with
+libc 5.2.18, XEmacs 20.0b20 is unable to open a tty device:
+
+ src/xemacs -nw -q
+ Initialization error:
+ Terminal type `xterm' undefined (or can't access database?)
+
+ Ben Wing <ben@666.com> writes:
+
+ Your ncurses configuration is messed up. Your /usr/lib/terminfo
+ is a bad pointer, perhaps to a CD-ROM that is not inserted.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.5, Next: Q2.0.6, Prev: Q2.0.4, Up: Installation
+
+Q2.0.5: Do I need X11 to run XEmacs?
+------------------------------------
+
+ No. The name "XEmacs" is unfortunate in the sense that it is *not*
+an X Window System-only version of Emacs. Starting with 19.14 XEmacs
+has full color support on a color-capable character terminal.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.6, Next: Q2.0.7, Prev: Q2.0.5, Up: Installation
+
+Q2.0.6: I'm having strange crashes. What do I do?
+--------------------------------------------------
+
+ There have been a variety of reports of crashes due to compilers with
+buggy optimizers. Please see the `PROBLEMS' file that comes with
+XEmacs to read what it says about your platform.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.7, Next: Q2.0.8, Prev: Q2.0.6, Up: Installation
+
+Q2.0.7: Libraries in non-standard locations
+-------------------------------------------
+
+ I have x-faces, jpeg, xpm etc. all in different places. I've tried
+space-separated, comma-separated, several -site-libraries, all to no
+avail.
+
+ --site-libraries='/path/one /path/two /path/etc'
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.8, Next: Q2.0.9, Prev: Q2.0.7, Up: Installation
+
+Q2.0.8: can't resolve symbol _h_errno
+-------------------------------------
+
+ You are using the Linux/ELF distribution of XEmacs 19.14, and your
+ELF libraries are out of date. You have the following options:
+
+ 1. Upgrade your libc to at least 5.2.16 (better is 5.2.18, 5.3.12, or
+ 5.4.10).
+
+ 2. Patch the XEmacs binary by replacing all occurrences of
+ `_h_errno^@' with `h_errno^@^@'. Any version of Emacs will
+ suffice. If you don't understand how to do this, don't do it.
+
+ 3. Rebuild XEmacs yourself - any working ELF version of libc should be
+ O.K.
+
+ Hrvoje Niksic <hniksic@srce.hr> writes:
+
+ Why not use a Perl one-liner for No. 2?
+
+ perl -pi -e 's/_h_errno\0/h_errno\0\0/g' \
+ /usr/local/bin/xemacs-19.14
+
+ NB: You *must* patch `/usr/local/bin/xemacs-19.14', and not
+ `xemacs' because `xemacs' is a link to `xemacs-19.14'; the Perl
+ `-i' option will cause unwanted side-effects if applied to a
+ symbolic link.
+
+ SL Baur <steve@xemacs.org> writes:
+
+ If you build against a recent libc-5.4 (late enough to have caused
+ problems earlier in the beta cycle) and then run with an earlier
+ version of libc, you get a
+
+ $ xemacs
+ xemacs: can't resolve symbol '__malloc_hook'
+ zsh: 7942 segmentation fault (core dumped) xemacs
+
+ (Example binary compiled against libc-5.4.23 and run with
+ libc-5.4.16).
+
+ The solution is to upgrade to at least libc-5.4.23. Sigh. Drat.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.9, Next: Q2.0.10, Prev: Q2.0.8, Up: Installation
+
+Q2.0.9: Where do I find external libraries?
+-------------------------------------------
+
+ All external libraries used by XEmacs can be found at the XEmacs FTP
+site `ftp://ftp.xemacs.org/pub/xemacs/aux/'.
+
+ The canonical locations (at the time of this writing) are as follows:
+
+JPEG
+ `ftp://ftp.uu.net/graphics/jpeg/'. Version 6a is current.
+
+XPM
+ `ftp://ftp.x.org/contrib/libraries/'. Version 3.4j is current.
+ Older versions of this package are known to cause XEmacs crashes.
+
+TIFF
+ `ftp://ftp.sgi.com/graphics/tiff/'. v3.4 is current. The latest
+ beta is v3.4b035. There is a HOWTO here.
+
+PNG
+ `ftp://ftp.uu.net/graphics/png/'. 0.89c is current. XEmacs
+ requires a fairly recent version to avoid using temporary files.
+
+ `ftp://swrinde.nde.swri.edu/pub/png/src/'
+
+Compface
+ `ftp://ftp.cs.indiana.edu/pub/faces/compface/'. This library has
+ been frozen for about 6 years, and is distributed without version
+ numbers. *It should be compiled with the same options that X11 was
+ compiled with on your system*. The version of this library at
+ XEmacs.org includes the `xbm2xface.pl' script, written by
+ <stig@hackvan.com>, which may be useful when generating your own
+ xface.
+
+NAS
+ `ftp://ftp.x.org/contrib/audio/nas/'. Version 1.2p5 is current.
+ There is a FAQ here.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.10, Next: Q2.0.11, Prev: Q2.0.9, Up: Installation
+
+Q2.0.10: After I run configure I find a core dump, is something wrong?
+----------------------------------------------------------------------
+
+ Not necessarily. If you have GNU sed 3.0 you should downgrade it to
+2.05. From the `README' at prep.ai.mit.edu:
+
+ sed 3.0 has been withdrawn from distribution. It has major
+ revisions, which mostly seem to be improvements; but it turns out
+ to have bugs too which cause trouble in some common cases.
+
+ Tom Lord won't be able to work fixing the bugs until May. So in
+ the mean time, we've decided to withdraw sed 3.0 from distribution
+ and make version 2.05 once again the recommended version.
+
+ It has also been observed that the vfork test on Solaris will leave a
+core dump.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.11, Next: Q2.0.12, Prev: Q2.0.10, Up: Installation
+
+Q2.0.11: XEmacs doesn't resolve hostnames.
+------------------------------------------
+
+ This is the result of a long-standing problem with SunOS and the fact
+that stock SunOS systems do not ship with DNS resolver code in libc.
+
+ Christopher Davis <ckd@loiosh.kei.com> writes:
+
+ That's correct [The SunOS 4.1.3 precompiled binaries don't do name
+ lookup]. Since Sun figured that everyone used NIS to do name
+ lookups (that DNS thing was apparently only a passing fad,
+ right?), the stock SunOS 4.x systems don't have DNS-based name
+ lookups in libc.
+
+ This is also why Netscape ships two binaries for SunOS 4.1.x.
+
+ The best solution is to compile it yourself; the configure script
+ will check to see if you've put DNS in the shared libc and will
+ then proceed to link against the DNS resolver library code.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.12, Next: Q2.0.13, Prev: Q2.0.11, Up: Installation
+
+Q2.0.12: Why can't I strip XEmacs?
+----------------------------------
+
+ Richard Cognot <cognot@fronsac.ensg.u-nancy.fr> writes:
+
+ Because of the way XEmacs (and every other Emacsen, AFAIK) is
+ built. The link gives you a bare-boned emacs (called temacs).
+ temacs is then run, preloading some of the lisp files. The result
+ is then dumped into a new executable, named xemacs, which will
+ contain all of the preloaded lisp functions and data.
+
+ Now, during the dump itself, the executable (code+data+symbols) is
+ written on disk using a special unexec() function. This function is
+ obviously heavily system dependent. And on some systems, it leads
+ to an executable which, although valid, cannot be stripped without
+ damage. If memory serves, this is especially the case for AIX
+ binaries. On other architecture it might work OK.
+
+ The Right Way to strip the emacs binary is to strip temacs prior to
+ dumping xemacs. This will always work, although you can do that
+ only if you install from sources (as temacs is `not' part of the
+ binary kits).
+
+ Nat Makarevitch <nat@nataa.fr.eu.org> writes:
+
+ Here is the trick:
+
+ 1. [ ./configure; make ]
+
+ 2. rm src/xemacs
+
+ 3. strip src/temacs
+
+ 4. make
+
+ 5. cp src/xemacs /usr/local/bin/xemacs
+
+ 6. cp lib-src/DOC-19.16-XEmacs
+ /usr/local/lib/xemacs-19.16/i586-unknown-linuxaout
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.13, Next: Q2.0.14, Prev: Q2.0.12, Up: Installation
+
+Q2.0.13: Problems linking with Gcc on Solaris
+---------------------------------------------
+
+ There are known difficulties linking with Gnu ld on Solaris. A
+typical error message might look like:
+
+ unexec(): dlopen(../dynodump/dynodump.so): ld.so.1: ./temacs:
+ fatal: relocation error:
+ symbol not found: main: referenced in ../dynodump/dynodump.so
+
+ Martin Buchholz <martin@xemacs.org> writes:
+
+ You need to specify `-fno-gnu-linker' as part of your flags to pass
+ to ld. Future releases of XEmacs will try to do this
+ automatically.
+
+\1f
+File: xemacs-faq.info, Node: Q2.0.14, Next: Q2.1.1, Prev: Q2.0.13, Up: Installation
+
+Q2.0.14: Make on HP/UX 9 fails after linking temacs
+---------------------------------------------------
+
+ Problem when building xemacs-19.16 on hpux 9:
+
+ Richard Cognot <cognot@ensg.u-nancy.fr> writes:
+
+ make on hpux fails after linking temacs with a message:
+
+ "make: don't know how to make .y."
+
+ Solution: This is a problem with HP make revision 70.X. Either
+ use GNU make, or install PHCO_6552, which will bring make to
+ revision 72.24.1.17.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.1, Next: Q2.1.2, Prev: Q2.0.14, Up: Installation
+
+2.1: Trouble Shooting
+=====================
+
+Q2.1.1: Help! XEmacs just crashed on me!
+-----------------------------------------
+
+ First of all, don't panic. Whenever XEmacs crashes, it tries
+extremely hard to auto-save all of your files before dying. (The main
+time that this will not happen is if the machine physically lost power
+or if you killed the XEmacs process using `kill -9'). The next time
+you try to edit those files, you will be informed that a more recent
+auto-save file exists. You can use `M-x recover-file' to retrieve the
+auto-saved version of the file.
+
+ Starting with 19.14, you may use the command `M-x recover-session'
+after a crash to pick up where you left off.
+
+ Now, XEmacs is not perfect, and there may occasionally be times, or
+particular sequences of actions, that cause it to crash. If you can
+come up with a reproducible way of doing this (or even if you have a
+pretty good memory of exactly what you were doing at the time), the
+maintainers would be very interested in knowing about it. Post a
+message to comp.emacs.xemacs or send mail to <crashes@xemacs.org>.
+Please note that the `crashes' address is exclusively for crash reports.
+
+ If at all possible, include a stack backtrace of the core dump that
+was produced. This shows where exactly things went wrong, and makes it
+much easier to diagnose problems. To do this, you need to locate the
+core file (it's called `core', and is usually sitting in the directory
+that you started XEmacs from, or your home directory if that other
+directory was not writable). Then, go to that directory and execute a
+command like:
+
+ gdb `which xemacs` core
+
+ and then issue the command `where' to get the stack backtrace. You
+might have to use `dbx' or some similar debugger in place of `gdb'. If
+you don't have any such debugger available, complain to your system
+administrator.
+
+ It's possible that a core file didn't get produced, in which case
+you're out of luck. Go complain to your system administrator and tell
+him not to disable core files by default. Also *Note Q2.1.15::, for
+tips and techniques for dealing with a debugger.
+
+ When making a problem report make sure that:
+
+ 1. Report *all* of the information output by XEmacs during the crash.
+
+ 2. You mention what O/S & Hardware you are running XEmacs on.
+
+ 3. What version of XEmacs you are running.
+
+ 4. What build options you are using.
+
+ 5. If the problem is related to graphics, we will also need to know
+ what version of the X Window System you are running, and what
+ window manager you are using.
+
+ 6. If the problem happened on a tty, please include the terminal type.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.2, Next: Q2.1.3, Prev: Q2.1.1, Up: Installation
+
+Q2.1.2: Cryptic Minibuffer messages.
+------------------------------------
+
+ When I try to use some particular option of some particular package,
+I get a cryptic error in the minibuffer.
+
+ If you can't figure out what's going on, select Options/General
+Options/Debug on Error from the Menubar and then try and make the error
+happen again. This will give you a backtrace that may be enlightening.
+If not, try reading through this FAQ; if that fails, you could try
+posting to comp.emacs.xemacs (making sure to include the backtrace) and
+someone may be able to help. If you can identify which Emacs lisp
+source file the error is coming from you can get a more detailed stack
+backtrace by doing the following:
+
+ 1. Visit the .el file in an XEmacs buffer.
+
+ 2. Issue the command `M-x eval-current-buffer'.
+
+ 3. Reproduce the error.
+
+ Depending on the version of XEmacs, you may either select Edit->Show
+Messages (19.13 and earlier) or Help->Recent Keystrokes/Messages (19.14
+and later) from the menubar to see the most recent messages. This
+command is bound to `C-h l' by default.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.3, Next: Q2.1.4, Prev: Q2.1.2, Up: Installation
+
+Q2.1.3: Translation Table Syntax messages at Startup
+----------------------------------------------------
+
+ I get tons of translation table syntax error messages during startup.
+How do I get rid of them?
+
+ There are two causes of this problem. The first usually only strikes
+people using the prebuilt binaries. The culprit in both cases is the
+file `XKeysymDB'.
+
+ * The binary cannot find the `XKeysymDB' file. The location is
+ hardcoded at compile time so if the system the binary was built on
+ puts it a different place than your system does, you have
+ problems. To fix, set the environment variable XKEYSYMDB to the
+ location of the `XKeysymDB' file on your system or to the location
+ of the one included with XEmacs which should be at
+ `<xemacs_root_directory>/lib/xemacs-19.16/etc/XKeysymDB'.
+
+ * The binary is finding the XKeysymDB but it is out-of-date on your
+ system and does not contain the necessary lines. Either ask your
+ system administrator to replace it with the one which comes with
+ XEmacs (which is the stock R6 version and is backwards compatible)
+ or set your XKEYSYMDB variable to the location of XEmacs's
+ described above.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.4, Next: Q2.1.5, Prev: Q2.1.3, Up: Installation
+
+Q2.1.4: Startup warnings about deducing proper fonts?
+-----------------------------------------------------
+
+ How can I avoid the startup warnings about deducing proper fonts?
+
+ This is highly dependent on your installation, but try with the
+following font as your base font for XEmacs and see what it does:
+
+-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
+
+ More precisely, do the following in your resource file:
+
+Emacs.default.attributeFont: \
+-adobe-courier-medium-r-*-*-*-120-*-*-*-*-iso8859-1
+
+ If you just don't want to see the `*Warnings*' buffer at startup
+time, you can set this:
+
+ (setq display-warning-minimum-level 'error)
+
+ The buffer still exists; it just isn't in your face.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.5, Next: Q2.1.6, Prev: Q2.1.4, Up: Installation
+
+Q2.1.5: XEmacs cannot connect to my X Terminal!
+-----------------------------------------------
+
+ Help! I can not get XEmacs to display on my Envizex X-terminal!
+
+ Try setting the DISPLAY variable using the numeric IP address of the
+host you are running XEmacs from.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.6, Next: Q2.1.7, Prev: Q2.1.5, Up: Installation
+
+Q2.1.6: XEmacs just locked up my Linux X server!
+------------------------------------------------
+
+ There have been several reports of the X server locking up under
+Linux. In all reported cases removing speedo and scaled fonts from the
+font path corrected the problem. This can be done with the command
+`xset'.
+
+ It is possible that using a font server may also solve the problem.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.7, Next: Q2.1.8, Prev: Q2.1.6, Up: Installation
+
+Q2.1.7: HP Alt key as Meta.
+---------------------------
+
+ How can I make XEmacs recognize the Alt key of my HP workstation as a
+Meta key?
+
+ Put the following line into a file and load it with xmodmap(1) before
+starting XEmacs:
+
+ remove Mod1 = Mode_switch
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.8, Next: Q2.1.9, Prev: Q2.1.7, Up: Installation
+
+Q2.1.8: got (wrong-type-argument color-instance-p nil)
+------------------------------------------------------
+
+ Natalie Kershaw <nataliek@rd.scitec.com.au> writes:
+
+ I am trying to run xemacs 19.13 under X11R4. Whenever I move the
+ mouse I get the following error. Has anyone seen anything like
+ this? This doesn't occur on X11R5.
+
+ Signalling:
+ (error "got (wrong-type-argument color-instance-p nil)
+ and I don't know why!")
+
+ dinos <map01kd@gold.ac.uk> writes:
+
+ I think this is due to undefined resources; You need to define
+ color backgrounds and foregrounds into your
+ `.../app-defaults/Emacs' like:
+
+ *Foreground: Black ;everything will be of black on grey95,
+ *Background: Grey95 ;unless otherwise specified.
+ *cursorColor: Red3 ;red3 cursor with grey95 border.
+ *pointerColor: Red3 ;red3 pointer with grey95 border.
+
+ Natalie Kershaw adds:
+
+ What fixed the problem was adding some more colors to the X color
+ database (copying the X11R5 colors over), and also defining the
+ following resources:
+
+ xemacs*cursorColor: black
+ xemacs*pointerColor: black
+
+ With the new colors installed the problem still occurs if the above
+ resources are not defined.
+
+ If the new colors are not present then an additional error occurs
+ on XEmacs startup, which says `Color Red3' not defined.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.9, Next: Q2.1.10, Prev: Q2.1.8, Up: Installation
+
+Q2.1.9: XEmacs causes my OpenWindows 3.0 server to crash.
+---------------------------------------------------------
+
+ The OpenWindows 3.0 server is incredibly buggy. Your best bet is to
+replace it with one from the generic MIT X11 release. You might also
+try disabling parts of your `.emacs', like enabling background pixmaps.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.10, Next: Q2.1.11, Prev: Q2.1.9, Up: Installation
+
+Q2.1.10: Warnings from incorrect key modifiers.
+-----------------------------------------------
+
+ The following information comes from the `PROBLEMS' file that comes
+with XEmacs.
+
+ If you're having troubles with HP/UX it is because HP/UX defines the
+modifiers wrong in X. Here is a shell script to fix the problem; be
+sure that it is run after VUE configures the X server.
+
+ #! /bin/sh
+ xmodmap 2> /dev/null - << EOF
+ keysym Alt_L = Meta_L
+ keysym Alt_R = Meta_R
+ EOF
+
+ xmodmap - << EOF
+ clear mod1
+ keysym Mode_switch = NoSymbol
+ add mod1 = Meta_L
+ keysym Meta_R = Mode_switch
+ add mod2 = Mode_switch
+ EOF
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.11, Next: Q2.1.12, Prev: Q2.1.10, Up: Installation
+
+Q2.1.11: `Can't instantiate image error...' in toolbar
+------------------------------------------------------
+
+ Dr. Ram Samudrala <expt@alanine.ram.org> writes:
+
+ I just installed the XEmacs (20.4-2) RPMS that I downloaded from
+`http://www.xemacs.org/'. Everything works fine, except that when I
+place my mouse over the toolbar, it beeps and gives me this message:
+
+ Can't instantiate image (probably cached):
+ [xbm :mask-file "/usr/include/X11/bitmaps/leftptrmsk :mask-data
+ (16 16 <strange control characters> ...
+
+ Kyle Jones <kyle_jones@wonderworks.com> writes:
+ This is problem specific to some Chips and Technologies video
+ chips, when running XFree86. Putting
+
+ `Option "sw_cursor"'
+
+ in `XF86Config' gets rid of the problem.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.12, Next: Q2.1.13, Prev: Q2.1.11, Up: Installation
+
+Q2.1.12: Problems with Regular Expressions on DEC OSF1.
+-------------------------------------------------------
+
+ I have xemacs 19.13 running on an alpha running OSF1 V3.2 148 and
+ispell would not run because it claimed the version number was incorrect
+although it was indeed OK. I traced the problem to the regular
+expression handler.
+
+ Douglas Kosovic <douglask@dstc.edu.au> writes:
+
+ Actually it's a DEC cc optimization bug that screws up the regexp
+ handling in XEmacs.
+
+ Rebuilding using the `-migrate' switch for DEC cc (which uses a
+ different sort of optimization) works fine.
+
+ See `xemacs-19_13-dunix-3_2c.patch' at the following URL on how to
+build with the `-migrate' flag:
+
+ `http://www-digital.cern.ch/carney/emacs/emacs.html'
+
+ NOTE: There have been a variety of other problems reported that are
+fixed in this fashion.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.13, Next: Q2.1.14, Prev: Q2.1.12, Up: Installation
+
+Q2.1.13: HP/UX 10.10 and `create_process' failure.
+--------------------------------------------------
+
+ Dave Carrigan <Dave.Carrigan@ipl.ca> writes:
+
+ With XEmacs 19.13 and HP/UX 10.10, anything that relies on the
+ `create_process' function fails. This breaks a lot of things
+ (shell-mode, compile, ange-ftp, to name a few).
+
+ Phil Johnson <johnson@dtc.hp.com> writes:
+
+ This is a problem specific to HP-UX 10.10. It only occurs when
+ XEmacs is compiled for shared libraries (the default), so you can
+ work around it by compiling a statically-linked binary (run
+ configure with `--dynamic=no').
+
+ I'm not sure whether the problem is with a particular shared
+ library or if it's a kernel problem which crept into 10.10.
+
+ Richard Cognot <cognot@ensg.u-nancy.fr> writes:
+
+ I had a few problems with 10.10. Apparently, some of them were
+ solved by forcing a static link of libc (manually).
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.14, Next: Q2.1.15, Prev: Q2.1.13, Up: Installation
+
+Q2.1.14: `C-g' doesn't work for me. Is it broken?
+--------------------------------------------------
+
+ Ben Wing <ben@666.com> writes:
+
+ `C-g' does work for most people in most circumstances. If it
+ doesn't, there are only two explanations:
+
+ 1. The code is wrapped with a binding of `inhibit-quit' to `t'.
+ `Ctrl-Shift-G' should still work, I think.
+
+ 2. SIGIO is broken on your system, but BROKEN_SIGIO isn't
+ defined.
+
+ To test #2, try executing `(while t)' from the `*scratch*' buffer.
+ If `C-g' doesn't interrupt, then you're seeing #2.
+
+ Morten Welinder <terra@diku.dk> writes:
+
+ On some (but *not* all) machines a hung XEmacs can be revived by
+ `kill -FPE <pid>'. This is a hack, of course, not a solution.
+ This technique works on a Sun4 running 4.1.3_U1. To see if it
+ works for you, start another XEmacs and test with that first. If
+ you get a core dump the method doesn't work and if you get
+ `Arithmetic error' then it does.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.15, Next: Q2.1.16, Prev: Q2.1.14, Up: Installation
+
+Q2.1.15: How to Debug an XEmacs problem with a debugger
+-------------------------------------------------------
+
+ If XEmacs does crash on you, one of the most productive things you
+can do to help get the bug fixed is to poke around a bit with the
+debugger. Here are some hints:
+
+ * First of all, if the crash is at all reproducible, consider very
+ strongly recompiling your XEmacs with debugging symbols, with no
+ optimization, and with the configure options `--debug=yes' and
+ `--error-checking=all'. This will make your XEmacs run somewhat
+ slower but make it a lot more likely to catch the problem earlier
+ (closer to its source), and a lot easier to determine what's going
+ on with a debugger.
+
+ * If you're able to run XEmacs under a debugger and reproduce the
+ crash (if it's inconvenient to do this because XEmacs is already
+ running or is running in batch mode as part of a bunch of scripts,
+ consider attaching to the existing process with your debugger;
+ most debuggers let you do this by substituting the process ID for
+ the core file when you invoke the debugger from the command line,
+ or by using the `attach' command or something similar), here are
+ some things you can do:
+
+ * If XEmacs is hitting an assertion failure, put a breakpoint on
+ `assert_failed()'.
+
+ * If XEmacs is hitting some weird Lisp error that's causing it to
+ crash (e.g. during startup), put a breakpoint on
+ `signal_1()'--this is declared static in eval.c.
+
+ * Internally, you will probably see lots of variables that hold
+ objects of type `Lisp_Object'. These are exactly what they appear
+ to be, i.e. references to Lisp objects. Printing them out with
+ the debugger probably won't be too useful--you'll likely just see
+ a number. To decode them, do this:
+
+ call debug_print (OBJECT)
+
+ where OBJECT is whatever you want to decode (it can be a variable,
+ a function call, etc.). This will print out a readable
+ representation on the TTY from which the xemacs process was
+ invoked.
+
+ * If you want to get a Lisp backtrace showing the Lisp call stack,
+ do this:
+
+ call debug_backtrace ()
+
+ * Using `debug_print' and `debug_backtrace' has two disadvantages -
+ it can only be used with a running xemacs process, and it cannot
+ display the internal C structure of a Lisp Object. Even if all
+ you've got is a core dump, all is not lost.
+
+ If you're using GDB, there are some macros in the file
+ `src/gdbinit' in the XEmacs source distribution that should make it
+ easier for you to decode Lisp objects. Copy this file to
+ `~/.gdbinit', or `source' it from `~/.gdbinit', and use the macros
+ defined therein. In particular, use the `pobj' macro to print the
+ internal C representation of a lisp object. This will work with a
+ core file or not-yet-run executable. The aliases `ldp' and `lbt'
+ are provided for conveniently calling `debug_print' and
+ `debug_backtrace'.
+
+ If you are using Sun's `dbx' debugger, there is an equivalent file
+ `src/dbxrc' to copy to or source from `~/.dbxrc'.
+
+ * If you're using a debugger to get a C stack backtrace and you're
+ seeing stack traces with some of the innermost frames mangled, it
+ may be due to dynamic linking. (This happens especially under
+ Linux.) Consider reconfiguring with `--dynamic=no'. Also,
+ sometimes (again under Linux), stack backtraces of core dumps will
+ have the frame where the fatal signal occurred mangled; if you can
+ obtain a stack trace while running the XEmacs process under a
+ debugger, the stack trace should be clean.
+
+ Curtiss <1CMC3466@ibm.mtsac.edu> suggests upgrading to ld.so
+ version 1.8 if dynamic linking and debugging is a problem on Linux.
+
+ * If you're using a debugger to get a C stack backtrace and you're
+ getting a completely mangled and bogus stack trace, it's probably
+ due to one of the following:
+
+ a. Your executable has been stripped. Bad news. Tell your
+ sysadmin not to do this--it doesn't accomplish anything
+ except to save a bit of disk space, and makes debugging much
+ much harder.
+
+ b. Your stack is getting trashed. Debugging this is hard; you
+ have to do a binary-search type of narrowing down where the
+ crash occurs, until you figure out exactly which line is
+ causing the problem. Of course, this only works if the bug
+ is highly reproducible.
+
+ c. If your stack trace has exactly one frame in it, with address
+ 0x0, this could simply mean that XEmacs attempted to execute
+ code at that address, e.g. through jumping to a null function
+ pointer. Unfortunately, under those circumstances, GDB under
+ Linux doesn't know how to get a stack trace. (Yes, this is
+ the third Linux-related problem I've mentioned. I have no
+ idea why GDB under Linux is so bogus. Complain to the GDB
+ authors, or to comp.os.linux.development.system). Again,
+ you'll have to use the narrowing-down process described above.
+
+ d. If you compiled 19.14 with `--debug' (or by default in later
+ versions), you will get a Lisp backtrace output when XEmacs
+ crashes, so you'll have something useful.
+
+
+ * If you compile with the newer gcc variants gcc-2.8 or egcs, you
+ will also need gdb 4.17. Earlier releases of gdb can't handle the
+ debug information generated by the newer compilers.
+
+ * The above information on using `src/gdbinit' works for XEmacs-21.0
+ and above. For older versions of XEmacs, there are different
+ `gdbinit' files provided in the `src' directory. Use the one
+ corresponding to the configure options used when building XEmacs.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.16, Next: Q2.1.17, Prev: Q2.1.15, Up: Installation
+
+Q2.1.16: XEmacs crashes in `strcat' on HP/UX 10
+-----------------------------------------------
+
+ >From the problems database (through
+`http://support.mayfield.hp.com/'):
+
+ Problem Report: 5003302299
+ Status: Open
+
+ System/Model: 9000/700
+ Product Name: HPUX S800 10.0X
+ Product Vers: 9245XB.10.00
+
+ Description: strcat(3C) may read beyond
+ end of source string, can cause SIGSEGV
+
+
+ *** PROBLEM TEXT ***
+ strcat(3C) may read beyond the source string onto an unmapped page,
+ causing a segmentation violation.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.17, Next: Q2.1.18, Prev: Q2.1.16, Up: Installation
+
+Q2.1.17: `Marker does not point anywhere'
+-----------------------------------------
+
+ As with other errors, set `debug-on-error' to `t' to get the
+backtrace when the error occurs. Specifically, two problems have been
+reported (and fixed).
+
+ 1. A problem with line-number-mode in XEmacs 19.14 affected a large
+ number of other packages. If you see this error message, turn off
+ line-number-mode.
+
+ 2. A problem with some early versions of Gnus 5.4 caused this error.
+ Upgrade your Gnus.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.18, Next: Q2.1.19, Prev: Q2.1.17, Up: Installation
+
+Q2.1.18: 19.14 hangs on HP/UX 10.10.
+------------------------------------
+
+ Richard Cognot <cognot@ensg.u-nancy.fr> writes:
+
+ For the record, compiling on hpux 10.10 leads to a hang in Gnus
+ when compiled with optimization on.
+
+ I've just discovered that my hpux 10.01 binary was working less
+ well than expected. In fact, on a 10.10 system, `(while t)' was not
+ interrupted by `C-g'. I defined `BROKEN_SIGIO' and recompiled on
+ 10.10, and... the hang is now gone.
+
+ As far as configure goes, this will be a bit tricky: `BROKEN_SIGIO'
+ is needed on 10.10, but *not* on 10.01: if I run my 10.01 binary
+ on a 10.01 machine, without `BROKEN_SIGIO' being defined, `C-g'
+ works as expected.
+
+ Richard Cognot <cognot@ensg.u-nancy.fr> adds:
+
+ Apparently somebody has found the reason why there is this `poll:
+ interrupted...' message for each event. For some reason, libcurses
+ reimplements a `select()' system call, in a highly broken fashion.
+ The fix is to add a -lc to the link line *before* the -lxcurses.
+ XEmacs will then use the right version of `select()'.
+
+ Alain Fauconnet <af@biomath.jussieu.fr> writes:
+
+ The *real* solution is to *not* link -lcurses in! I just changed
+ -lcurses to -ltermcap in the Makefile and it fixed:
+
+ 1. The `poll: interrupted system call' message.
+
+ 2. A more serious problem I had discovered in the meantime, that
+ is the fact that subprocess handling was seriously broken:
+ subprocesses e.g. started by AUC TeX for TeX compilation of a
+ buffer would *hang*. Actually they would wait forever for
+ emacs to read the socket which connects stdout...
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.19, Next: Q2.1.20, Prev: Q2.1.18, Up: Installation
+
+Q2.1.19: XEmacs does not follow the local timezone.
+---------------------------------------------------
+
+ When using one of the prebuilt binaries many users have observed that
+XEmacs uses the timezone under which it was built, but not the timezone
+under which it is running. The solution is to add:
+
+ (set-time-zone-rule "MET")
+
+ to your `.emacs' or the `site-start.el' file if you can. Replace
+`MET' with your local timezone.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.20, Next: Q2.1.21, Prev: Q2.1.19, Up: Installation
+
+Q2.1.20: `Symbol's function definition is void: hkey-help-show.'
+----------------------------------------------------------------
+
+ This is a problem with a partially loaded hyperbole. Try adding:
+
+ (require 'hmouse-drv)
+
+ where you load hyperbole and the problem should go away.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.21, Next: Q2.1.22, Prev: Q2.1.20, Up: Installation
+
+Q2.1.21: Every so often the XEmacs frame freezes
+------------------------------------------------
+
+ This problem has been fixed in 19.15, and was due to a not easily
+reproducible race condition.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.22, Next: Q2.1.23, Prev: Q2.1.21, Up: Installation
+
+Q2.1.22: XEmacs seems to take a really long time to do some things
+------------------------------------------------------------------
+
+ David Moore <dmoore@ucsd.edu> writes:
+
+ Two things you can do:
+
+ 1) C level:
+
+ When you see it going mad like this, you might want to use gdb
+ from an 'xterm' to attach to the running process and get a stack
+ trace. To do this just run:
+
+ gdb /path/to/xemacs/xemacs ####
+
+ Where `####' is the process id of your xemacs, instead of
+ specifying the core. When gdb attaches, the xemacs will stop [1]
+ and you can type `where' in gdb to get a stack trace as usual. To
+ get things moving again, you can just type `quit' in gdb. It'll
+ tell you the program is running and ask if you want to quit
+ anyways. Say 'y' and it'll quit and have your emacs continue from
+ where it was at.
+
+ 2) Lisp level:
+
+ Turn on debug-on-quit early on. When you think things are going
+ slow hit C-g and it may pop you in the debugger so you can see
+ what routine is running. Press `c' to get going again.
+
+ debug-on-quit doesn't work if something's turned on inhibit-quit
+ or in some other strange cases.
+
+\1f
+File: xemacs-faq.info, Node: Q2.1.23, Prev: Q2.1.22, Up: Installation
+
+Q2.1.23: Movemail on Linux does not work for XEmacs 19.15 and later.
+---------------------------------------------------------------------
+
+ Movemail used to work fine in 19.14 but has stopped working in 19.15
+and 20.x. I am using Linux.
+
+ SL Baur <steve@xemacs.org> writes:
+
+ Movemail on Linux used to default to using flock file locking.
+ With 19.15 and later versions it now defaults to using `.lock' file
+ locking. If this is not appropriate for your system, edit
+ src/s/linux.h and uncomment the line that reads:
+
+ #define MAIL_USE_FLOCK
+
--- /dev/null
+This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
+1.68 from the input file xemacs-faq.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* FAQ: (xemacs-faq). XEmacs FAQ.
+END-INFO-DIR-ENTRY
+
+\1f
+File: xemacs-faq.info, Node: Customization, Next: Subsystems, Prev: Installation, Up: Top
+
+3 Customization and Options
+***************************
+
+ This is part 3 of the XEmacs Frequently Asked Questions list. This
+section is devoted to Customization and screen settings.
+
+* Menu:
+
+Customization--Emacs Lisp and `.emacs':
+* Q3.0.1:: What version of Emacs am I running?
+* Q3.0.2:: How do I evaluate Elisp expressions?
+* Q3.0.3:: `(setq tab-width 6)' behaves oddly.
+* Q3.0.4:: How can I add directories to the `load-path'?
+* Q3.0.5:: How to check if a lisp function is defined?
+* Q3.0.6:: Can I force the output of `(face-list)' to a buffer?
+* Q3.0.7:: Font selections don't get saved after `Save Options'.
+* Q3.0.8:: How do I make a single minibuffer frame?
+* Q3.0.9:: What is `Customize'?
+
+X Window System & Resources:
+* Q3.1.1:: Where is a list of X resources?
+* Q3.1.2:: How can I detect a color display?
+* Q3.1.3:: `(set-screen-width)' worked in 19.6, but not in 19.13?
+* Q3.1.4:: Specifying `Emacs*EmacsScreen.geometry' in `.emacs' does not work in 19.15?
+* Q3.1.5:: How can I get the icon to just say `XEmacs'?
+* Q3.1.6:: How can I have the window title area display the full path?
+* Q3.1.7:: `xemacs -name junk' doesn't work?
+* Q3.1.8:: `-iconic' doesn't work.
+
+Textual Fonts & Colors:
+* Q3.2.1:: How can I set color options from `.emacs'?
+* Q3.2.2:: How do I set the text, menu and modeline fonts?
+* Q3.2.3:: How can I set the colors when highlighting a region?
+* Q3.2.4:: How can I limit color map usage?
+* Q3.2.5:: My tty supports color, but XEmacs doesn't use them.
+* Q3.2.6:: Can I have pixmap backgrounds in XEmacs?
+
+The Modeline:
+* Q3.3.1:: How can I make the modeline go away?
+* Q3.3.2:: How do you have XEmacs display the line number in the modeline?
+* Q3.3.3:: How do I get XEmacs to put the time of day on the modeline?
+* Q3.3.4:: How do I turn off current chapter from AUC TeX modeline?
+* Q3.3.5:: How can one change the modeline color based on the mode used?
+
+3.4 Multiple Device Support:
+* Q3.4.1:: How do I open a frame on another screen of my multi-headed display?
+* Q3.4.2:: Can I really connect to a running XEmacs after calling up over a modem? How?
+
+3.5 The Keyboard:
+* Q3.5.1:: How can I bind complex functions (or macros) to keys?
+* Q3.5.2:: How can I stop down-arrow from adding empty lines to the bottom of my buffers?
+* Q3.5.3:: How do I bind C-. and C-; to scroll one line up and down?
+* Q3.5.4:: Globally binding `Delete'?
+* Q3.5.5:: Scrolling one line at a time.
+* Q3.5.6:: How to map `Help' key alone on Sun type4 keyboard?
+* Q3.5.7:: How can you type in special characters in XEmacs?
+* Q3.5.8:: Why does `(global-set-key [delete-forward] 'delete-char)' complain?
+* Q3.5.9:: How do I make the Delete key delete forward?
+* Q3.5.10:: Can I turn on "sticky" modifier keys?
+* Q3.5.11:: How do I map the arrow keys?
+
+The Cursor:
+* Q3.6.1:: Is there a way to make the bar cursor thicker?
+* Q3.6.2:: Is there a way to get back the old block cursor where the cursor covers the character in front of the point?
+* Q3.6.3:: Can I make the cursor blink?
+
+The Mouse and Highlighting:
+* Q3.7.1:: How can I turn off Mouse pasting?
+* Q3.7.2:: How do I set control/meta/etc modifiers on mouse buttons?
+* Q3.7.3:: Clicking the left button does not do anything in buffer list.
+* Q3.7.4:: How can I get a list of buffers when I hit mouse button 3?
+* Q3.7.5:: Why does cut-and-paste not work between XEmacs and a cmdtool?
+* Q3.7.6:: How I can set XEmacs up so that it pastes where the text cursor is?
+* Q3.7.7:: How do I select a rectangular region?
+* Q3.7.8:: Why does `M-w' take so long?
+
+The Menubar and Toolbar:
+* Q3.8.1:: How do I get rid of the menu (or menubar)?
+* Q3.8.2:: Can I customize the basic menubar?
+* Q3.8.3:: How do I control how many buffers are listed in the menu `Buffers' list?
+* Q3.8.4:: Resources like `Emacs*menubar*font' are not working?
+* Q3.8.5:: How can I bind a key to a function to toggle the toolbar?
+
+Scrollbars:
+* Q3.9.1:: How can I disable the scrollbar?
+* Q3.9.2:: How can one use resources to change scrollbar colors?
+* Q3.9.3:: Moving the scrollbar can move the point; can I disable this?
+* Q3.9.4:: How can I get automatic horizontal scrolling?
+
+Text Selections:
+* Q3.10.1:: How can I turn off or change highlighted selections?
+* Q3.10.2:: How do I get that typing on an active region removes it?
+* Q3.10.3:: Can I turn off the highlight during isearch?
+* Q3.10.4:: How do I turn off highlighting after `C-x C-p' (mark-page)?
+* Q3.10.5:: The region disappears when I hit the end of buffer while scrolling.
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.1, Next: Q3.0.2, Prev: Customization, Up: Customization
+
+3.0: Customization - Emacs Lisp and .emacs
+==========================================
+
+Q3.0.1: What version of Emacs am I running?
+-------------------------------------------
+
+ How can `.emacs' determine which of the family of Emacsen I am using?
+
+ To determine if you are currently running GNU Emacs 18, GNU Emacs 19,
+XEmacs 19, XEmacs 20, or Epoch, and use appropriate code, check out the
+example given in `etc/sample.emacs'. There are other nifty things in
+there as well!
+
+ For all new code, all you really need to do is:
+
+ (defvar running-xemacs (string-match "XEmacs\\|Lucid" emacs-version))
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.2, Next: Q3.0.3, Prev: Q3.0.1, Up: Customization
+
+Q3.0.2: How can I evaluate Emacs-Lisp expressions?
+--------------------------------------------------
+
+ I know I can evaluate Elisp expressions from `*scratch*' buffer with
+`C-j' after the expression. How do I do it from another buffer?
+
+ Press `M-:' (the default binding of `eval-expression'), and enter
+the expression to the minibuffer. In XEmacs prior to 19.15
+`eval-expression' used to be a disabled command by default. If this is
+the case, upgrade your XEmacs.
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.3, Next: Q3.0.4, Prev: Q3.0.2, Up: Customization
+
+Q3.0.3: `(setq tab-width 6)' behaves oddly.
+-------------------------------------------
+
+ If you put `(setq tab-width 6)' in your `.emacs' file it does not
+work! Is there a reason for this? If you do it at the EVAL prompt it
+works fine!! How strange.
+
+ Use `setq-default' instead, since `tab-width' is all-buffer-local.
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.4, Next: Q3.0.5, Prev: Q3.0.3, Up: Customization
+
+Q3.0.4: How can I add directories to the `load-path'?
+-----------------------------------------------------
+
+ Here are two ways to do that, one that puts your directories at the
+front of the load-path, the other at the end:
+
+ ;;; Add things at the beginning of the load-path, do not add
+ ;;; duplicate directories:
+ (pushnew "bar" load-path :test 'equal)
+
+ (pushnew "foo" load-path :test 'equal)
+
+ ;;; Add things at the end, unconditionally
+ (setq load-path (nconc load-path '("foo" "bar")))
+
+ keith (k.p.) hanlan <keithh@nortel.ca> writes:
+
+ To add directories using Unix shell metacharacters use
+ `expand-file-name' like this:
+
+ (push (expand-file-name "~keithh/.emacsdir") load-path)
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.5, Next: Q3.0.6, Prev: Q3.0.4, Up: Customization
+
+Q3.0.5: How to check if a lisp function is defined?
+---------------------------------------------------
+
+ Use the following elisp:
+
+ (fboundp 'foo)
+
+ It's almost always a mistake to test `emacs-version' or any similar
+variables.
+
+ Instead, use feature-tests, such as `featurep', `boundp', `fboundp',
+or even simple behavioral tests, eg.:
+
+ (defvar foo-old-losing-code-p
+ (condition-case nil (progn (losing-code t) nil)
+ (wrong-number-of-arguments t)))
+
+ There is an incredible amount of broken code out there which could
+work much better more often in more places if it did the above instead
+of trying to divine its environment from the value of one variable.
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.6, Next: Q3.0.7, Prev: Q3.0.5, Up: Customization
+
+Q3.0.6: Can I force the output of `(face-list)' to a buffer?
+------------------------------------------------------------
+
+ It would be good having it in a buffer, as the output of
+`(face-list)' is too wide to fit to a minibuffer.
+
+ Evaluate the expression in the `*scratch*' buffer with point after
+the rightmost paren and typing `C-j'.
+
+ If the minibuffer smallness is the only problem you encounter, you
+can simply press `C-h l' to get the former minibuffer contents in a
+buffer.
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.7, Next: Q3.0.8, Prev: Q3.0.6, Up: Customization
+
+Q3.0.7: Font selections in don't get saved after `Save Options'.
+----------------------------------------------------------------
+
+ For XEmacs 19.14 and previous:
+
+ John Mann <mannj@ll.mit.edu> writes:
+
+ You have to go to Options->Frame Appearance and unselect
+ `Frame-Local Font Menu'. If this option is selected, font changes
+ are only applied to the *current* frame and do *not* get saved
+ when you save options.
+
+ For XEmacs 19.15 and later:
+
+ Implement the above as well as set the following in your `.emacs'
+
+ (setq options-save-faces t)
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.8, Next: Q3.0.9, Prev: Q3.0.7, Up: Customization
+
+Q3.0.8: How do I get a single minibuffer frame?
+-----------------------------------------------
+
+ Vin Shelton <acs@acm.org> writes:
+
+ (setq initial-frame-plist '(minibuffer nil))
+ (setq default-frame-plist '(minibuffer nil))
+ (setq default-minibuffer-frame
+ (make-frame
+ '(minibuffer only
+ width 86
+ height 1
+ menubar-visible-p nil
+ default-toolbar-visible-p nil
+ name "minibuffer"
+ top -2
+ left -2
+ has-modeline-p nil)))
+ (frame-notice-user-settings)
+
+ *Please note:* The single minibuffer frame may not be to everyone's
+taste, and there any number of other XEmacs options settings that may
+make it difficult or inconvenient to use.
+
+\1f
+File: xemacs-faq.info, Node: Q3.0.9, Next: Q3.1.1, Prev: Q3.0.8, Up: Customization
+
+Q3.0.9: What is `Customize'?
+----------------------------
+
+ Starting with XEmacs 20.2 there is new system 'Customize' for
+customizing XEmacs options.
+
+ You can access `Customize' from the `Options' menu or invoking one
+of customize commands by typing eg. `M-x customize', `M-x
+customize-face', `M-x customize-variable' or `M-x customize-apropos'.
+
+ Starting with XEmacs 20.3 there is also new `browser' mode for
+Customize. Try it out with `M-x customize-browse'
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.1, Next: Q3.1.2, Prev: Q3.0.9, Up: Customization
+
+3.1: X Window System & Resources
+================================
+
+Q3.1.1: Where is a list of X resources?
+---------------------------------------
+
+ Search through the `NEWS' file for `X Resources'. A fairly
+comprehensive list is given after it.
+
+ In addition, an `app-defaults' file is supplied, `etc/Emacs.ad'
+listing the defaults. The file `etc/sample.Xdefaults' gives a set of
+defaults that you might consider. It is essentially the same as
+`etc/Emacs.ad' but some entries are slightly altered. Be careful about
+installing the contents of this file into your `.Xdefaults' or
+`.Xresources' file if you use GNU Emacs under X11 as well.
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.2, Next: Q3.1.3, Prev: Q3.1.1, Up: Customization
+
+Q3.1.2: How can I detect a color display?
+-----------------------------------------
+
+ You can test the return value of the function `(device-class)', as
+in:
+
+ (when (eq (device-class) 'color)
+ (set-face-foreground 'font-lock-comment-face "Grey")
+ (set-face-foreground 'font-lock-string-face "Red")
+ ....
+ )
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.3, Next: Q3.1.4, Prev: Q3.1.2, Up: Customization
+
+Q3.1.3: `(set-screen-width)' worked in 19.6, but not in 19.13?
+--------------------------------------------------------------
+
+ In Lucid Emacs 19.6 I did `(set-screen-width CHARACTERS)' and
+`(set-screen-height LINES)' in my `.emacs' instead of specifying
+`Emacs*EmacsScreen.geometry' in my `.Xdefaults' but this does not work
+in XEmacs 19.13.
+
+ These two functions now take frame arguments:
+
+ (set-frame-width (selected-frame) CHARACTERS)
+ (set-frame-height (selected-frame) LINES)
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.4, Next: Q3.1.5, Prev: Q3.1.3, Up: Customization
+
+Q3.1.4: Specifying `Emacs*EmacsScreen.geometry' in `.emacs' does not work in 19.15?
+-----------------------------------------------------------------------------------
+
+ In XEmacs 19.11 I specified `Emacs*EmacsScreen.geometry' in my
+`.emacs' but this does not work in XEmacs 19.15.
+
+ We have switched from using the term "screen" to using the term
+"frame".
+
+ The correct entry for your `.Xdefaults' is now:
+
+ Emacs*EmacsFrame.geometry
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.5, Next: Q3.1.6, Prev: Q3.1.4, Up: Customization
+
+Q3.1.5: How can I get the icon to just say `XEmacs'?
+----------------------------------------------------
+
+ I'd like the icon to just say `XEmacs', and not include the name of
+the current file in it.
+
+ Add the following line to your `.emacs':
+
+ (setq frame-icon-title-format "XEmacs")
+
+\1f
+File: xemacs-faq.info, Node: Q3.1.6, Next: Q3.1.7, Prev: Q3.1.5, Up: Customization
+
+Q3.1.6: How can I have the window title area display the full path?
+-------------------------------------------------------------------
+
+ I'd like to have the window title area display the full
+directory/name of the current buffer file and not just the name.
+
+ Add the following line to your `.emacs':
+
+ (setq frame-title-format "%S: %f")
+
+ A more sophisticated title might be:
+
+ (setq frame-title-format
+ '("%S: " (buffer-file-name "%f"
+ (dired-directory dired-directory "%b"))))
+
+ That is, use the file name, or the dired-directory, or the buffer
+name.
+
+\1f
+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")))
+
+\1f
+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 <ben@666.com> 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...
+
+\1f
+File: xemacs-faq.info, Node: Q3.2.1, Next: Q3.2.2, Prev: Q3.1.8, Up: Customization
+
+3.2: Textual Fonts & Colors
+===========================
+
+Q3.2.1: How can I set color options from `.emacs'?
+--------------------------------------------------
+
+ How can I set the most commonly used color options from my `.emacs'
+instead of from my `.Xdefaults'?
+
+ Like this:
+
+ (set-face-background 'default "bisque") ; frame background
+ (set-face-foreground 'default "black") ; normal text
+ (set-face-background 'zmacs-region "red") ; When selecting w/
+ ; mouse
+ (set-face-foreground 'zmacs-region "yellow")
+ (set-face-font 'default "*courier-bold-r*120-100-100*")
+ (set-face-background 'highlight "blue") ; Ie when selecting
+ ; buffers
+ (set-face-foreground 'highlight "yellow")
+ (set-face-background 'modeline "blue") ; Line at bottom
+ ; of buffer
+ (set-face-foreground 'modeline "white")
+ (set-face-font 'modeline "*bold-r-normal*140-100-100*")
+ (set-face-background 'isearch "yellow") ; When highlighting
+ ; while searching
+ (set-face-foreground 'isearch "red")
+ (setq x-pointer-foreground-color "black") ; Adds to bg color,
+ ; so keep black
+ (setq x-pointer-background-color "blue") ; This is color
+ ; you really
+ ; want ptr/crsr
+
+\1f
+File: xemacs-faq.info, Node: Q3.2.2, Next: Q3.2.3, Prev: Q3.2.1, Up: Customization
+
+Q3.2.2: How do I set the text, menu and modeline fonts?
+-------------------------------------------------------
+
+ Note that you should use `Emacs.' and not `Emacs*' when setting face
+values.
+
+ In `.Xdefaults':
+
+ Emacs.default.attributeFont: -*-*-medium-r-*-*-*-120-*-*-m-*-*-*
+ Emacs*menubar*font: fixed
+ Emacs.modeline.attributeFont: fixed
+
+ This is confusing because modeline is a face, and can be found listed
+with all faces in the current mode by using `M-x set-face-font (enter)
+?'. It uses the face specification of `attributeFont', while menubar
+is a normal X thing that uses the specification `font'. With Motif it
+may be necessary to use `fontList' instead of `font'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.2.3, Next: Q3.2.4, Prev: Q3.2.2, Up: Customization
+
+Q3.2.3: How can I set the colors when highlighting a region?
+------------------------------------------------------------
+
+ How can I set the background/foreground colors when highlighting a
+region?
+
+ You can change the face `zmacs-region' either in your `.Xdefaults':
+
+ Emacs.zmacs-region.attributeForeground: firebrick
+ Emacs.zmacs-region.attributeBackground: lightseagreen
+
+ or in your `.emacs':
+
+ (set-face-background 'zmacs-region "red")
+ (set-face-foreground 'zmacs-region "yellow")
+
+\1f
+File: xemacs-faq.info, Node: Q3.2.4, Next: Q3.2.5, Prev: Q3.2.3, Up: Customization
+
+Q3.2.4: How can I limit color map usage?
+----------------------------------------
+
+ I'm using Netscape (or another color grabber like XEmacs); is there
+anyway to limit the number of available colors in the color map?
+
+ XEmacs 19.13 didn't have such a mechanism (unlike netscape, or other
+color-hogs). One solution is to start XEmacs prior to netscape, since
+this will prevent Netscape from grabbing all colors (but Netscape will
+complain). You can use the flags for Netscape, like -mono, -ncols <#>
+or -install (for mono, limiting to <#> colors, or for using a private
+color map). Since Netscape will take the entire colormap and never
+release it, the only reasonable way to run it is with `-install'.
+
+ If you have the money, another solution would be to use a truecolor
+or direct color video.
+
+ Starting with XEmacs 19.14, XEmacs uses the closest available color
+if the colormap is full, so it's O.K. now to start Netscape first.
+
+\1f
+File: xemacs-faq.info, Node: Q3.2.5, Next: Q3.2.6, Prev: Q3.2.4, Up: Customization
+
+Q3.2.5: My tty supports color, but XEmacs doesn't use them.
+-----------------------------------------------------------
+
+ XEmacs tries to automatically determine whether your tty supports
+color, but sometimes guesses wrong. In that case, you can make XEmacs
+Do The Right Thing using this Lisp code:
+
+ (if (eq 'tty (device-type))
+ (set-device-class nil 'color))
+
+\1f
+File: xemacs-faq.info, Node: Q3.2.6, Next: Q3.3.1, Prev: Q3.2.5, Up: Customization
+
+Q3.2.6: Can I have pixmap backgrounds in XEmacs?
+------------------------------------------------
+
+ Juan Villacis <jvillaci@wahnsinnig.extreme.indiana.edu> writes:
+
+ There are several ways to do it. For example, you could specify a
+ default pixmap image to use in your `~/.Xresources', e.g.,
+
+ Emacs*EmacsFrame.default.attributeBackgroundPixmap: /path/to/image.xpm
+
+ and then reload ~/.Xresources and restart XEmacs. Alternatively,
+ since each face can have its own pixmap background, a better way
+ would be to set a face's pixmap within your XEmacs init file, e.g.,
+
+ (set-face-background-pixmap 'default "/path/to/image.xpm")
+ (set-face-background-pixmap 'bold "/path/to/another_image.xpm")
+
+ and so on. You can also do this interactively via `M-x
+ edit-faces'.
+
+
+3.3: The Modeline
+=================
+
+\1f
+File: xemacs-faq.info, Node: Q3.3.1, Next: Q3.3.2, Prev: Q3.2.6, Up: Customization
+
+Q3.3.1: How can I make the modeline go away?
+--------------------------------------------
+
+ (set-specifier has-modeline-p nil)
+
+ Starting with XEmacs 19.14 the modeline responds to mouse clicks, so
+if you haven't liked or used the modeline in the past, you might want to
+try the new version out.
+
+\1f
+File: xemacs-faq.info, Node: Q3.3.2, Next: Q3.3.3, Prev: Q3.3.1, Up: Customization
+
+Q3.3.2: How do you have XEmacs display the line number in the modeline?
+-----------------------------------------------------------------------
+
+ Add the following line to your `.emacs' file to display the line
+number:
+
+ (line-number-mode 1)
+
+ Use the following to display the column number:
+
+ (column-number-mode 1)
+
+ Or select from the `Options' menu
+`Customize->Emacs->Editing->Basics->Line Number Mode' and/or
+`Customize->Emacs->Editing->Basics->Column Number Mode'
+
+ Or type `M-x customize <RET> editing-basics <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.3.3, Next: Q3.3.4, Prev: Q3.3.2, Up: Customization
+
+Q3.3.3: How do I get XEmacs to put the time of day on the modeline?
+-------------------------------------------------------------------
+
+ Add the following line to your `.emacs' file to display the time:
+
+ (display-time)
+
+ See `Customize' from the `Options' menu for customization.
+
+\1f
+File: xemacs-faq.info, Node: Q3.3.4, Next: Q3.3.5, Prev: Q3.3.3, Up: Customization
+
+Q3.3.4: How do I turn off current chapter from AUC TeX modeline?
+----------------------------------------------------------------
+
+ With AUC TeX, fast typing is hard because the current chapter,
+section etc. are given in the modeline. How can I turn this off?
+
+ It's not AUC TeX, it comes from `func-menu' in `func-menu.el'. Add
+this code to your `.emacs' to turn it off:
+
+ (setq fume-display-in-modeline-p nil)
+
+ Or just add a hook to `TeX-mode-hook' to turn it off only for TeX
+mode:
+
+ (add-hook 'TeX-mode-hook
+ '(lambda () (setq fume-display-in-modeline-p nil)))
+
+ David Hughes <dhughes@origin-at.co.uk> writes:
+
+ If you have 19.14 or later, try this instead; you'll still get the
+ function name displayed in the modeline, but it won't attempt to
+ keep track when you modify the file. To refresh when it gets out
+ of synch, you simply need click on the `Rescan Buffer' option in
+ the function-menu.
+
+ (setq-default fume-auto-rescan-buffer-p nil)
+
+\1f
+File: xemacs-faq.info, Node: Q3.3.5, Next: Q3.4.1, Prev: Q3.3.4, Up: Customization
+
+Q3.3.5: How can one change the modeline color based on the mode used?
+---------------------------------------------------------------------
+
+ You can use something like the following:
+
+ (add-hook 'lisp-mode-hook
+ (lambda ()
+ (set-face-background 'modeline "red" (current-buffer))))
+
+ Then, when editing a Lisp file (i.e. when in Lisp mode), the modeline
+colors change from the default set in your `.emacs'. The change will
+only be made in the buffer you just entered (which contains the Lisp
+file you are editing) and will not affect the modeline colors anywhere
+else.
+
+ Notes:
+
+ * The hook is the mode name plus `-hook'. eg. c-mode-hook,
+ c++-mode-hook, emacs-lisp-mode-hook (used for your `.emacs' or a
+ `xx.el' file), lisp-interaction-mode-hook (the `*scratch*'
+ buffer), text-mode-hook, etc.
+
+ * Be sure to use `add-hook', not `(setq c-mode-hook xxxx)',
+ otherwise you will erase anything that anybody has already put on
+ the hook.
+
+ * You can also do `(set-face-font 'modeline FONT)', eg.
+ `(set-face-font 'modeline "*bold-r-normal*140-100-100*"
+ (current-buffer))' if you wish the modeline font to vary based on
+ the current mode.
+
+ This works in 19.15 as well, but there are additional modeline faces,
+`modeline-buffer-id', `modeline-mousable', and
+`modeline-mousable-minor-mode', which you may want to customize.
+
+\1f
+File: xemacs-faq.info, Node: Q3.4.1, Next: Q3.4.2, Prev: Q3.3.5, Up: Customization
+
+3.4: Multiple Device Support
+============================
+
+Q3.4.1: How do I open a frame on another screen of my multi-headed display?
+---------------------------------------------------------------------------
+
+ The support for this was revamped for 19.14. Use the command `M-x
+make-frame-on-display'. This command is also on the File menu in the
+menubar.
+
+ XEmacs 19.14 and later also have the command `make-frame-on-tty'
+which will establish a connection to any tty-like device. Opening the
+TTY devices should be left to `gnuclient', though.
+
+\1f
+File: xemacs-faq.info, Node: Q3.4.2, Next: Q3.5.1, Prev: Q3.4.1, Up: Customization
+
+Q3.4.2: Can I really connect to a running XEmacs after calling up over a modem? How?
+-------------------------------------------------------------------------------------
+
+ If you're not running at least XEmacs 19.14, you can't. Otherwise
+check out the `gnuattach' program supplied with XEmacs. Starting with
+XEmacs 20.3, `gnuattach' and `gnudoit' functionality is provided by
+`gnuclient'.
+
+ Also *Note Q5.0.12::.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.1, Next: Q3.5.2, Prev: Q3.4.2, Up: Customization
+
+3.5: The Keyboard
+=================
+
+Q3.5.1: How can I bind complex functions (or macros) to keys?
+-------------------------------------------------------------
+
+ As an example, say you want the `paste' key on a Sun keyboard to
+insert the current Primary X selection at point. You can accomplish this
+with:
+
+ (define-key global-map [f18] 'x-insert-selection)
+
+ However, this only works if there is a current X selection (the
+selection will be highlighted). The functionality I like is for the
+`paste' key to insert the current X selection if there is one,
+otherwise insert the contents of the clipboard. To do this you need to
+pass arguments to `x-insert-selection'. This is done by wrapping the
+call in a 'lambda form:
+
+ (global-set-key [f18]
+ (lambda () (interactive) (x-insert-selection t nil)))
+
+ This binds the f18 key to a "generic" functional object. The
+interactive spec is required because only interactive functions can be
+bound to keys.
+
+ For the FAQ example you could use:
+
+ (global-set-key [(control ?.)]
+ (lambda () (interactive) (scroll-up 1)))
+ (global-set-key [(control ? ;)]
+ (lambda () (interactive) (scroll-up -1)))
+
+ This is fine if you only need a few functions within the lambda body.
+If you're doing more it's cleaner to define a separate function as in
+question 3.5.3 (*note Q3.5.3::.).
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.2, Next: Q3.5.3, Prev: Q3.5.1, Up: Customization
+
+Q3.5.2: How can I stop down-arrow from adding empty lines to the bottom of my buffers?
+--------------------------------------------------------------------------------------
+
+ Add the following line to your `.emacs' file:
+
+ (setq next-line-add-newlines nil)
+
+ This has been the default setting in XEmacs for some time.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.3, Next: Q3.5.4, Prev: Q3.5.2, Up: Customization
+
+Q3.5.3: How do I bind C-. and C-; to scroll one line up and down?
+-----------------------------------------------------------------
+
+ Add the following (Thanks to Richard Mlynarik <mly@adoc.xerox.com>
+and Wayne Newberry <wayne@zen.cac.stratus.com>) to `.emacs':
+
+ (defun scroll-up-one-line ()
+ (interactive)
+ (scroll-up 1))
+
+ (defun scroll-down-one-line ()
+ (interactive)
+ (scroll-down 1))
+
+ (global-set-key [(control ?.)] 'scroll-up-one-line) ; C-.
+ (global-set-key [(control ? ;)] 'scroll-down-one-line) ; C-;
+
+ The key point is that you can only bind simple functions to keys; you
+can not bind a key to a function that you're also passing arguments to.
+(*note Q3.5.1::. for a better answer).
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.4, Next: Q3.5.5, Prev: Q3.5.3, Up: Customization
+
+Q3.5.4: Globally binding `Delete'?
+----------------------------------
+
+ I cannot manage to globally bind my `Delete' key to something other
+than the default. How does one do this?
+
+ (defun foo ()
+ (interactive)
+ (message "You hit DELETE"))
+
+ (global-set-key 'delete 'foo)
+
+ However, some modes explicitly bind `Delete', so you would need to
+add a hook that does `local-set-key' for them. If what you want to do
+is make the Backspace and Delete keys work more PC/Motif-like, then
+take a look at the `delbs.el' package.
+
+ New in XEmacs 19.14 is a variable called `key-translation-map' which
+makes it easier to bind `Delete'. `delbs.el' is a good example of how
+to do this correctly.
+
+ Also *Note Q3.5.10::.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.5, Next: Q3.5.6, Prev: Q3.5.4, Up: Customization
+
+Q3.5.5: Scrolling one line at a time.
+-------------------------------------
+
+ Can the cursor keys scroll the screen a line at a time, rather than
+the default half page jump? I tend it to find it disorienting.
+
+ Try this:
+
+ (defun scroll-one-line-up (&optional arg)
+ "Scroll the selected window up (forward in the text) one line (or N lines)."
+ (interactive "p")
+ (scroll-up (or arg 1)))
+
+ (defun scroll-one-line-down (&optional arg)
+ "Scroll the selected window down (backward in the text) one line (or N)."
+ (interactive "p")
+ (scroll-down (or arg 1)))
+
+ (global-set-key [up] 'scroll-one-line-up)
+ (global-set-key [down] 'scroll-one-line-down)
+
+ The following will also work but will affect more than just the
+cursor keys (i.e. `C-n' and `C-p'):
+
+ (setq scroll-step 1)
+
+ Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu
+`Customize->Emacs->Environment->Windows->Scroll Step...' or type `M-x
+customize <RET> windows <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.6, Next: Q3.5.7, Prev: Q3.5.5, Up: Customization
+
+Q3.5.6: How to map `Help' key alone on Sun type4 keyboard?
+----------------------------------------------------------
+
+ The following works in GNU Emacs 19:
+
+ (global-set-key [help] 'help-command);; Help
+
+ The following works in XEmacs 19.15 with the addition of shift:
+
+ (global-set-key [(shift help)] 'help-command);; Help
+
+ But it doesn't work alone. This is in the file `PROBLEMS' which
+should have come with your XEmacs installation: *Emacs ignores the
+`help' key when running OLWM*.
+
+ OLWM grabs the `help' key, and retransmits it to the appropriate
+client using `XSendEvent'. Allowing Emacs to react to synthetic events
+is a security hole, so this is turned off by default. You can enable
+it by setting the variable `x-allow-sendevents' to t. You can also
+cause fix this by telling OLWM to not grab the help key, with the null
+binding `OpenWindows.KeyboardCommand.Help:'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.7, Next: Q3.5.8, Prev: Q3.5.6, Up: Customization
+
+Q3.5.7: How can you type in special characters in XEmacs?
+---------------------------------------------------------
+
+ One way is to use the package `x-compose'. Then you can use
+sequences like `Compose " a' to get ä, etc.
+
+ Another way is to use the `iso-insert' package, provided in XEmacs
+19.15 and later. Then you can use sequences like `C-x 8 " a' to get ä,
+etc.
+
+ Glynn Clements <glynn@sensei.co.uk> writes:
+
+ It depends upon your X server.
+
+ Generally, the simplest way is to define a key as Multi_key with
+ xmodmap, e.g.
+ xmodmap -e 'keycode 0xff20 = Multi_key'
+
+ You will need to pick an appropriate keycode. Use xev to find out
+ the keycodes for each key.
+
+ [NB: On a `Windows' keyboard, recent versions of XFree86
+ automatically define the right `Windows' key as Multi_key'.]
+
+ Once you have Multi_key defined, you can use e.g.
+ Multi a ' => á
+ Multi e " => ë
+ Multi c , => ç
+
+ etc.
+
+ Also, recent versions of XFree86 define various AltGr-<key>
+ combinations as dead keys, i.e.
+ AltGr [ => dead_diaeresis
+ AltGr ] => dead_tilde
+ AltGr ; => dead_acute
+ etc.
+
+ Running `xmodmap -pk' will list all of the defined keysyms.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.8, Next: Q3.5.9, Prev: Q3.5.7, Up: Customization
+
+Q3.5.8: Why does `(global-set-key [delete-forward] 'delete-char)' complain?
+---------------------------------------------------------------------------
+
+ Why does `(define-key global-map [ delete-forward ] 'delete-char)'
+complain of not being able to bind an unknown key?
+
+ Try this instead:
+
+ (define-key global-map [delete_forward] 'delete-char)
+
+ and it will work.
+
+ What you are seeing above is a bug due to code that is trying to
+check for GNU Emacs syntax like:
+
+ (define-key global-map [C-M-a] 'delete-char)
+
+ which otherwise would cause no errors but would not result in the
+expected behavior.
+
+ This bug has been fixed in 19.14.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.9, Next: Q3.5.10, Prev: Q3.5.8, Up: Customization
+
+Q3.5.9: How do I make the Delete key delete forward?
+----------------------------------------------------
+
+ With XEmacs-20.2 use the `delbs' package:
+
+ (require 'delbs)
+
+ This will give you the functions `delbs-enable-delete-forward' to
+set things up, and `delbs-disable-delete-forward' to revert to "normal"
+behavior. Note that `delbackspace' package is obsolete.
+
+ Starting with XEmacs-20.3 better solution is to set variable
+`delete-key-deletes-forward' to t. You can also change this with
+Customize. Select from the `Options' menu
+`Customize->Emacs->Editing->Basics->Delete Key Deletes Forward' or type
+`M-x customize <RET> editing-basics <RET>'.
+
+ Also *Note Q3.5.4::.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.10, Next: Q3.5.11, Prev: Q3.5.9, Up: Customization
+
+Q3.5.10: Can I turn on "sticky" modifier keys?
+----------------------------------------------
+
+ Yes, with `(setq modifier-keys-are-sticky t)'. This will give the
+effect of being able to press and release Shift and have the next
+character typed come out in upper case. This will affect all the other
+modifier keys like Control and Meta as well.
+
+ Ben Wing <ben@666.com> writes:
+
+ One thing about the sticky modifiers is that if you move the mouse
+ out of the frame and back in, it cancels all currently "stuck"
+ modifiers.
+
+\1f
+File: xemacs-faq.info, Node: Q3.5.11, Next: Q3.6.1, Prev: Q3.5.10, Up: Customization
+
+Q3.5.11: How do I map the arrow keys?
+-------------------------------------
+
+ Say you want to map `C-<right>' to forward-word:
+
+ Sam Steingold <sds@usa.net> writes:
+
+ ; both XEmacs and Emacs
+ (define-key global-map [(control right)] 'forward-word)
+ or
+ ; Emacs only
+ (define-key global-map [C-right] 'forward-word)
+ or
+ ; ver > 20, both
+ (define-key global-map (kbd "C-<right>") 'forward-word)
+
+\1f
+File: xemacs-faq.info, Node: Q3.6.1, Next: Q3.6.2, Prev: Q3.5.11, Up: Customization
+
+3.6: The Cursor
+===============
+
+Q3.6.1: Is there a way to make the bar cursor thicker?
+------------------------------------------------------
+
+ I'd like to have the bar cursor a little thicker, as I tend to
+"lose" it often.
+
+ For a 1 pixel bar cursor, use:
+
+ (setq bar-cursor t)
+
+ For a 2 pixel bar cursor, use:
+
+ (setq bar-cursor 'anything-else)
+
+ Starting with XEmacs-20.3 you can also change these with Customize.
+Select from the `Options' menu
+`Customize->Emacs->Environment->Display->Bar Cursor...' or type `M-x
+customize <RET> display <RET>'.
+
+ You can use a color to make it stand out better:
+
+ Emacs*cursorColor: Red
+
+\1f
+File: xemacs-faq.info, Node: Q3.6.2, Next: Q3.6.3, Prev: Q3.6.1, Up: Customization
+
+Q3.6.2: Is there a way to get back the block cursor?
+----------------------------------------------------
+
+ (setq bar-cursor nil)
+
+ Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu
+`Customize->Emacs->Environment->Display->Bar Cursor...' or type `M-x
+customize <RET> display <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.6.3, Next: Q3.7.1, Prev: Q3.6.2, Up: Customization
+
+Q3.6.3: Can I make the cursor blink?
+------------------------------------
+
+ If you are running a version of XEmacs older than 19.14, no.
+Otherwise you can do the following:
+
+ (blink-cursor-mode)
+
+ This function toggles between a steady cursor and a blinking cursor.
+You may also set this mode from the menu bar by selecting `Options =>
+Frame Appearance => Blinking Cursor'. Remember to save options.
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.1, Next: Q3.7.2, Prev: Q3.6.3, Up: Customization
+
+3.7: The Mouse and Highlighting
+===============================
+
+Q3.7.1: How can I turn off Mouse pasting?
+-----------------------------------------
+
+ I keep hitting the middle mouse button by accident and getting stuff
+pasted into my buffer so how can I turn this off?
+
+ Here is an alternative binding, whereby the middle mouse button
+selects (but does not cut) the expression under the mouse. Clicking
+middle on a left or right paren will select to the matching one. Note
+that you can use `define-key' or `global-set-key'.
+
+ (defun mouse-set-point-and-select (event)
+ "Sets the point at the mouse location, then marks following form"
+ (interactive "@e")
+ (mouse-set-point event)
+ (mark-sexp 1))
+ (define-key global-map [button2] 'mouse-set-point-and-select)
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.2, Next: Q3.7.3, Prev: Q3.7.1, Up: Customization
+
+Q3.7.2: How do I set control/meta/etc modifiers on mouse buttons?
+-----------------------------------------------------------------
+
+ Use, for instance, `[(meta button1)]'. For example, here is a common
+setting for Common Lisp programmers who use the bundled `ilisp'
+package, whereby meta-button1 on a function name will find the file
+where the function name was defined, and put you at that location in
+the source file.
+
+ [Inside a function that gets called by the lisp-mode-hook and
+ilisp-mode-hook]
+
+ (local-set-key [(meta button1)] 'edit-definitions-lisp)
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.3, Next: Q3.7.4, Prev: Q3.7.2, Up: Customization
+
+Q3.7.3: Clicking the left button does not do anything in buffer list.
+---------------------------------------------------------------------
+
+ I do `C-x C-b' to get a list of buffers and the entries get
+highlighted when I move the mouse over them but clicking the left mouse
+does not do anything.
+
+ Use the middle mouse button.
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.4, Next: Q3.7.5, Prev: Q3.7.3, Up: Customization
+
+Q3.7.4: How can I get a list of buffers when I hit mouse button 3?
+------------------------------------------------------------------
+
+ The following code will replace the default popup on button3:
+
+ (global-set-key [button3] 'popup-buffer-menu)
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.5, Next: Q3.7.6, Prev: Q3.7.4, Up: Customization
+
+Q3.7.5: Why does cut-and-paste not work between XEmacs and a cmdtool?
+---------------------------------------------------------------------
+
+ We don't know. It's a bug. There does seem to be a work-around,
+however. Try running xclipboard first. It appears to fix the problem
+even if you exit it. (This should be mostly fixed in 19.13, but we
+haven't yet verified that).
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.6, Next: Q3.7.7, Prev: Q3.7.5, Up: Customization
+
+Q3.7.6: How I can set XEmacs up so that it pastes where the text cursor is?
+---------------------------------------------------------------------------
+
+ By default XEmacs pastes X selections where the mouse pointer is.
+How do I disable this?
+
+ Examine the function `mouse-yank', by typing `C-h f mouse-yank
+<RET>'.
+
+ To get XEmacs to paste at the text cursor, add this your `.emacs':
+
+ (setq mouse-yank-at-point t)
+
+ Starting with XEmacs-20.2 you can also change this with Customize.
+Select from the `Options' menu `Customize->Emacs->Editing->Mouse->Yank
+At Point...' or type `M-x customize <RET> mouse <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.7, Next: Q3.7.8, Prev: Q3.7.6, Up: Customization
+
+Q3.7.7: How do I select a rectangular region?
+---------------------------------------------
+
+ Just select the region normally, then use the rectangle commands
+(e.g. `kill-rectangle' on it. The region does not highlight as a
+rectangle, but the commands work just fine.
+
+ To actually sweep out rectangular regions with the mouse you can use
+`mouse-track-do-rectangle' which is assigned to `M-button1'. Then use
+rectangle commands.
+
+ You can also do the following to change default behavior to sweep out
+rectangular regions:
+
+ (setq mouse-track-rectangle-p t)
+
+ Starting with XEmacs-20.2 you can also change this with Customize.
+Select from the `Options' menu `Customize->Emacs->Editing->Mouse->Track
+Rectangle...' or type `M-x customize <RET> mouse <RET>'.
+
+ mouse-track-do-rectangle: (event)
+ -- an interactive compiled Lisp function.
+ Like `mouse-track' but selects rectangles instead of regions.
+
+\1f
+File: xemacs-faq.info, Node: Q3.7.8, Next: Q3.8.1, Prev: Q3.7.7, Up: Customization
+
+Q3.7.8: Why does `M-w' take so long?
+------------------------------------
+
+ It actually doesn't. It leaves the region visible for a second so
+that you can see what area is being yanked. If you start working,
+though, it will immediately complete its operation. In other words, it
+will only delay for a second if you let it.
+
+\1f
+File: xemacs-faq.info, Node: Q3.8.1, Next: Q3.8.2, Prev: Q3.7.8, Up: Customization
+
+3.8: The Menubar and Toolbar
+============================
+
+Q3.8.1: How do I get rid of the menu (or menubar)?
+--------------------------------------------------
+
+ If you are running XEmacs 19.13 and earlier, add this command to your
+`.emacs'.
+
+ (set-menubar nil)
+
+ Starting with XEmacs 19.14 the preferred method is:
+
+ (set-specifier menubar-visible-p nil)
+
+\1f
+File: xemacs-faq.info, Node: Q3.8.2, Next: Q3.8.3, Prev: Q3.8.1, Up: Customization
+
+Q3.8.2: Can I customize the basic menubar?
+------------------------------------------
+
+ For an extensive menubar, add this line to your `.emacs':
+
+ (load "big-menubar")
+
+ If you'd like to write your own, this file provides as good a set of
+examples as any to start from. The file is located in
+`lisp/packages/big-menubar.el' in the XEmacs installation directory.
+
+\1f
+File: xemacs-faq.info, Node: Q3.8.3, Next: Q3.8.4, Prev: Q3.8.2, Up: Customization
+
+Q3.8.3: How do I control how many buffers are listed in the menu `Buffers List'?
+--------------------------------------------------------------------------------
+
+ Add the following to your `.emacs' (suit to fit):
+
+ (setq buffers-menu-max-size 20)
+
+ For no limit, use an argument of `nil'.
+
+ Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu
+`Customize->Emacs->Environment->Menu->Buffers Menu->Max Size...' or
+type `M-x customize <RET> buffers-menu <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q3.8.4, Next: Q3.8.5, Prev: Q3.8.3, Up: Customization
+
+Q3.8.4: Resources like `Emacs*menubar*font' are not working?
+------------------------------------------------------------
+
+ I am trying to use a resource like `Emacs*menubar*font' to set the
+font of the menubar but it's not working.
+
+ If you are using the real Motif menubar, this resource is not
+recognized; you have to say:
+
+ Emacs*menubar*fontList: FONT
+
+ If you are using the Lucid menubar, the former resource will be
+recognized only if the latter resource is unset. This means that the
+resource
+
+ *fontList: FONT
+
+ will override
+
+ Emacs*menubar*font: FONT
+
+ even though the latter is more specific.
+
+\1f
+File: xemacs-faq.info, Node: Q3.8.5, Next: Q3.9.1, Prev: Q3.8.4, Up: Customization
+
+Q3.8.5: How can I bind a key to a function to toggle the toolbar?
+-----------------------------------------------------------------
+
+ Try something like:
+
+ (defun my-toggle-toolbar ()
+ (interactive)
+ (set-specifier default-toolbar-visible-p
+ (not (specifier-instance default-toolbar-visible-p))))
+ (global-set-key "\C-xT" 'my-toggle-toolbar)
+
+ There are redisplay bugs in 19.14 that may make the preceding result
+in a messed-up display, especially for frames with multiple windows.
+You may need to resize the frame before XEmacs completely realizes the
+toolbar is really gone.
+
+ Thanks to Martin Buchholz <martin@xemacs.org> for the correct code.
+
+\1f
+File: xemacs-faq.info, Node: Q3.9.1, Next: Q3.9.2, Prev: Q3.8.5, Up: Customization
+
+3.9: Scrollbars
+===============
+
+Q3.9.1: How can I disable the scrollbar?
+----------------------------------------
+
+ To disable them for all frames, add the following line to your
+`.Xdefaults':
+
+ Emacs.scrollBarWidth: 0
+
+ Or select from the `Options' menu `Frame Appearance->Scrollbars'.
+Remember to save options.
+
+ To turn the scrollbar off on a per-frame basis, use the following
+function:
+
+ (set-specifier scrollbar-width 0 (selected-frame))
+
+ You can actually turn the scrollbars on at any level you want by
+substituting for (selected-frame) in the above command. For example, to
+turn the scrollbars off only in a single buffer:
+
+ (set-specifier scrollbar-width 0 (current-buffer))
+
+ In XEmacs versions prior to 19.14, you had to use the hairier
+construct:
+
+ (set-specifier scrollbar-width (cons (selected-frame) 0))
+
+\1f
+File: xemacs-faq.info, Node: Q3.9.2, Next: Q3.9.3, Prev: Q3.9.1, Up: Customization
+
+Q3.9.2: How can one use resources to change scrollbar colors?
+-------------------------------------------------------------
+
+ Here's a recap of how to use resources to change your scrollbar
+colors:
+
+ ! Motif scrollbars
+
+ Emacs*XmScrollBar.Background: skyblue
+ Emacs*XmScrollBar.troughColor: lightgray
+
+ ! Athena scrollbars
+
+ Emacs*Scrollbar.Foreground: skyblue
+ Emacs*Scrollbar.Background: lightgray
+
+ Note the capitalization of `Scrollbar' for the Athena widget.
+
+\1f
+File: xemacs-faq.info, Node: Q3.9.3, Next: Q3.9.4, Prev: Q3.9.2, Up: Customization
+
+Q3.9.3: Moving the scrollbar can move the point; can I disable this?
+--------------------------------------------------------------------
+
+ When I move the scrollbar in an XEmacs window, it moves the point as
+well, which should not be the default behavior. Is this a bug or a
+feature? Can I disable it?
+
+ The current behavior is a feature, not a bug. Point remains at the
+same buffer position as long as that position does not scroll off the
+screen. In that event, point will end up in either the upper-left or
+lower-left hand corner.
+
+ This cannot be changed.
+
+\1f
+File: xemacs-faq.info, Node: Q3.9.4, Next: Q3.10.1, Prev: Q3.9.3, Up: Customization
+
+Q3.9.4: How can I get automatic horizontal scrolling?
+-----------------------------------------------------
+
+ By the same token, how can I turn it off in specific modes?
+
+ To do this, add to your `.emacs' file:
+
+ (require 'auto-show)
+
+ Then do `(setq truncate-lines t)' in the mode-hooks for any modes in
+which you want lines truncated.
+
+ More precisely: If `truncate-lines' is nil, horizontal scrollbars
+will never appear. Otherwise, they will appear only if the value of
+`scrollbar-height' for that buffer/window/etc. is non-zero. If you do
+
+ (set-specifier scrollbar-height 0)
+
+ then horizontal scrollbars will not appear in truncated buffers
+unless the package specifically asked for them.
+
+ Automatic horizontal scrolling is now standard, starting with 19.14.
+
--- /dev/null
+This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
+1.68 from the input file xemacs-faq.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* FAQ: (xemacs-faq). XEmacs FAQ.
+END-INFO-DIR-ENTRY
+
+\1f
+File: xemacs-faq.info, Node: Q3.10.1, Next: Q3.10.2, Prev: Q3.9.4, Up: Customization
+
+3.10: Text Selections
+=====================
+
+Q3.10.1: How can I turn off or change highlighted selections?
+-------------------------------------------------------------
+
+ The `zmacs' mode allows for what some might call gratuitous
+highlighting for selected regions (either by setting mark or by using
+the mouse). This is the default behavior. To turn off, add the
+following line to your `.emacs' file:
+
+ (setq zmacs-regions nil)
+
+ Starting with XEmacs-20.2 you can also change this with Customize.
+Select from the `Options' menu `Customize->Emacs->Editing->Basics->Zmacs
+Regions' or type `M-x customize <RET> editing-basics <RET>'.
+
+ To change the face for selection, look at `Options->Customize' on
+the menubar.
+
+\1f
+File: xemacs-faq.info, Node: Q3.10.2, Next: Q3.10.3, Prev: Q3.10.1, Up: Customization
+
+Q3.10.2: How do I get that typing on an active region removes it?
+-----------------------------------------------------------------
+
+ I want to change things so that if I select some text and start
+typing, the typed text replaces the selected text, similar to Motif.
+
+ You want to use something called "pending delete". Pending delete
+is what happens when you select a region (with the mouse or keyboard)
+and you press a key to replace the selected region by the key you typed.
+Usually backspace kills the selected region.
+
+ To get this behavior, add the following line to your `.emacs':
+
+ (turn-on-pending-delete)
+
+ Note that this will work with both Backspace and Delete.
+
+\1f
+File: xemacs-faq.info, Node: Q3.10.3, Next: Q3.10.4, Prev: Q3.10.2, Up: Customization
+
+Q3.10.3: Can I turn off the highlight during isearch?
+-----------------------------------------------------
+
+ I do not like my text highlighted while I am doing isearch as I am
+not able to see what's underneath. How do I turn it off?
+
+ Put the following in your `.emacs':
+
+ (setq isearch-highlight nil)
+
+ Starting with XEmacs-20.2 you can also change this with Customize.
+Type `M-x customize-variable <RET> isearch-highlight <RET>'.
+
+ Note also that isearch-highlight affects query-replace and ispell.
+Instead of disabling isearch-highlight you may find that a better
+solution consists of customizing the `isearch' face.
+
+\1f
+File: xemacs-faq.info, Node: Q3.10.4, Next: Q3.10.5, Prev: Q3.10.3, Up: Customization
+
+Q3.10.4: How do I turn off highlighting after `C-x C-p' (mark-page)?
+--------------------------------------------------------------------
+
+ Put this in your `.emacs':
+
+ (setq zmacs-regions nil)
+
+ *Warning: This command turns off all region highlighting.*
+
+ Also *Note Q3.10.1::.
+
+\1f
+File: xemacs-faq.info, Node: Q3.10.5, Prev: Q3.10.4, Up: Customization
+
+Q3.10.5: The region disappears when I hit the end of buffer while scrolling.
+----------------------------------------------------------------------------
+
+ This has been fixed by default starting with XEmacs-20.3.
+
+ With older versions you can turn this feature (if it indeed is a
+feature) off like this:
+
+ (defadvice scroll-up (around scroll-up freeze)
+ (interactive "_P")
+ (let ((zmacs-region-stays t))
+ (if (interactive-p)
+ (condition-case nil
+ ad-do-it
+ (end-of-buffer (goto-char (point-max))))
+ ad-do-it)))
+
+ (defadvice scroll-down (around scroll-down freeze)
+ (interactive "_P")
+ (let ((zmacs-region-stays t))
+ (if (interactive-p)
+ (condition-case nil
+ ad-do-it
+ (beginning-of-buffer (goto-char (point-min))))
+ ad-do-it)))
+
+ Thanks to T. V. Raman <raman@adobe.com> for assistance in deriving
+this answer.
+
+\1f
+File: xemacs-faq.info, Node: Subsystems, Next: Miscellaneous, Prev: Customization, Up: Top
+
+4 Major Subsystems
+******************
+
+ This is part 4 of the XEmacs Frequently Asked Questions list. This
+section is devoted to major XEmacs subsystems.
+
+* Menu:
+
+Reading Mail with VM:
+* Q4.0.1:: How do I set up VM to retrieve remote mail using POP?
+* Q4.0.2:: How do I get VM to filter mail for me?
+* Q4.0.3:: How can I get VM to automatically check for new mail?
+* Q4.0.4:: [This question intentionally left blank]
+* Q4.0.5:: How do I get my outgoing mail archived?
+* Q4.0.6:: I have various addresses at which I receive mail. How can I tell VM to ignore them when doing a "reply-all"?
+* Q4.0.7:: Is there a mailing list or FAQ for VM?
+* Q4.0.8:: Remote mail reading with VM.
+* Q4.0.9:: rmail or VM gets an error incorporating new mail.
+* Q4.0.10:: How do I make VM stay in a single frame?
+* Q4.0.11:: How do I make VM or mh-e display graphical smilies?
+* Q4.0.12:: Customization of VM not covered in the manual or here.
+
+Web browsing with W3:
+* Q4.1.1:: What is W3?
+* Q4.1.2:: How do I run W3 from behind a firewall?
+* Q4.1.3:: Is it true that W3 supports style sheets and tables?
+
+Reading Netnews and Mail with Gnus:
+* Q4.2.1:: GNUS, (ding) Gnus, Gnus 5, September Gnus, Red Gnus,argh!
+* Q4.2.2:: [This question intentionally left blank]
+* Q4.2.3:: How do I make Gnus stay within a single frame?
+* Q4.2.4:: How do I customize the From: line?
+
+Other Mail & News:
+* Q4.3.1:: How can I read and/or compose MIME messages?
+* Q4.3.2:: What is TM and where do I get it?
+* Q4.3.3:: Why isn't this `movemail' program working?
+* Q4.3.4:: Movemail is also distributed by Netscape? Can that cause problems?
+* Q4.3.5:: Where do I find pstogif (required by tm)?
+
+Sparcworks, EOS, and WorkShop:
+* Q4.4.1:: What is SPARCworks, EOS, and WorkShop
+
+Energize:
+* Q4.5.1:: What is/was Energize?
+
+Infodock:
+* Q4.6.1:: What is Infodock?
+
+Other Unbundled Packages:
+* Q4.7.1:: What is AUC TeX? Where do you get it?
+* Q4.7.2:: Are there any Emacs Lisp Spreadsheets?
+* Q4.7.3:: Byte compiling AUC TeX on XEmacs 19.14
+* Q4.7.4:: Problems installing AUC TeX
+* Q4.7.5:: Is there a reason for an Emacs package not to be included in XEmacs?
+* Q4.7.6:: Is there a MatLab mode?
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.1, Next: Q4.0.2, Prev: Subsystems, Up: Subsystems
+
+4.0: Reading Mail with VM
+=========================
+
+Q4.0.1: How do I set up VM to retrieve mail from a remote site using POP?
+-------------------------------------------------------------------------
+
+ Use `vm-spool-files', like this for example:
+
+ (setq vm-spool-files '("/var/spool/mail/wing"
+ "netcom23.netcom.com:110:pass:wing:MYPASS"))
+
+ Of course substitute your actual password for MYPASS.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.2, Next: Q4.0.3, Prev: Q4.0.1, Up: Subsystems
+
+Q4.0.2: How do I get VM to filter mail for me?
+----------------------------------------------
+
+ One possibility is to use procmail to split your mail before it gets
+to VM. I prefer this personally, since there are many strange and
+wonderful things one can do with procmail. Procmail may be found at
+`ftp://ftp.informatik.rwth-aachen.de/pub/packages/procmail/'.
+
+ Also see the Mail Filtering FAQ at:
+`ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/filtering-faq'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.3, Next: Q4.0.4, Prev: Q4.0.2, Up: Subsystems
+
+Q4.0.3: How can I get VM to automatically check for new mail?
+-------------------------------------------------------------
+
+ John Turner <turner@lanl.gov> writes:
+
+ Use the following:
+
+ (setq vm-auto-get-new-mail 60)
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.4, Next: Q4.0.5, Prev: Q4.0.3, Up: Subsystems
+
+Q4.0.4: [This question intentionally left blank]
+------------------------------------------------
+
+ Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.5, Next: Q4.0.6, Prev: Q4.0.4, Up: Subsystems
+
+Q4.0.5: How do I get my outgoing mail archived?
+-----------------------------------------------
+
+ (setq mail-archive-file-name "~/outbox")
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.6, Next: Q4.0.7, Prev: Q4.0.5, Up: Subsystems
+
+Q4.0.6: I have various addresses at which I receive mail. How can I tell VM to ignore them when doing a "reply-all"?
+---------------------------------------------------------------------------------------------------------------------
+
+ Set `vm-reply-ignored-addresses' to a list, like
+
+ (setq vm-reply-ignored-addresses
+ '("wing@nuspl@nvwls.cc.purdue.edu,netcom[0-9]*.netcom.com"
+ "wing@netcom.com" "wing@666.com"))
+
+ Note that each string is a regular expression.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.7, Next: Q4.0.8, Prev: Q4.0.6, Up: Subsystems
+
+Q4.0.7: Is there a mailing list or FAQ for VM?
+----------------------------------------------
+
+ A FAQ for VM exists at `http://www.cyberpass.net/~gorkab/vmfaq.htm'.
+
+ VM has its own newsgroups gnu.emacs.vm.info and gnu.emacs.vm.bug.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.8, Next: Q4.0.9, Prev: Q4.0.7, Up: Subsystems
+
+Q4.0.8: Remote mail reading with VM.
+------------------------------------
+
+ My mailbox lives at the office on a big honkin server. My regular
+INBOX lives on my honkin desktop machine. I now can PPP to the office
+from home which is far from honking... I'd like to be able to read
+mail at home without storing it here and I'd like to use xemacs and VM
+at home... Is there a recommended setup?
+
+ Joseph J. Nuspl Jr. <nuspl@nvwls.cc.purdue.edu> writes:
+
+ There are several ways to do this.
+
+ 1. Set your display to your home machine and run dxpc or one of
+ the other X compressors.
+
+ 2. NFS mount your desktop machine on your home machine and
+ modify your pop command on your home machine to rsh to your
+ desktop machine and actually do the pop get's.
+
+ 3. Run a POP server on your desktop machine as well and do a
+ sort of two tiered POP get.
+
+ William Perry <wmperry@monolith.spry.com> adds:
+
+ Or you could run a pop script periodically on your desktop
+ machine, and just use ange-ftp or NFS to get to your mailbox. I
+ used to do this all the time back at IU.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.9, Next: Q4.0.10, Prev: Q4.0.8, Up: Subsystems
+
+Q4.0.9: rmail or VM gets an error incorporating new mail.
+---------------------------------------------------------
+
+ Quoting the XEmacs PROBLEMS file:
+
+ rmail and VM get new mail from `/usr/spool/mail/$USER' using a
+ program called `movemail'. This program interlocks with
+ `/bin/mail' using the protocol defined by `/bin/mail'.
+
+ There are two different protocols in general use. One of them
+ uses the `flock' system call. The other involves creating a lock
+ file; `movemail' must be able to write in `/usr/spool/mail' in
+ order to do this. You control which one is used by defining, or
+ not defining, the macro `MAIL_USE_FLOCK' in `config.h' or the m-
+ or s- file it includes.
+
+ *IF YOU DON'T USE THE FORM OF INTERLOCKING THAT IS NORMAL ON YOUR
+ SYSTEM, YOU CAN LOSE MAIL!*
+
+ If your system uses the lock file protocol, and fascist
+ restrictions prevent ordinary users from writing the lock files in
+ `/usr/spool/mail', you may need to make `movemail' setgid to a
+ suitable group such as `mail'. You can use these commands (as
+ root):
+
+ chgrp mail movemail
+ chmod 2755 movemail
+
+ If your system uses the lock file protocol, and fascist
+ restrictions prevent ordinary users from writing the lock files in
+ `/usr/spool/mail', you may need to make `movemail' setgid to a
+ suitable group such as `mail'. To do this, use the following
+ commands (as root) after doing the make install.
+
+ chgrp mail movemail
+ chmod 2755 movemail
+
+ Installation normally copies movemail from the build directory to
+ an installation directory which is usually under `/usr/local/lib'.
+ The installed copy of `movemail' is usually in the directory
+ `/usr/local/lib/emacs/VERSION/TARGET'. You must change the group
+ and mode of the installed copy; changing the group and mode of the
+ build directory copy is ineffective.
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.10, Next: Q4.0.11, Prev: Q4.0.9, Up: Subsystems
+
+Q4.0.10: How do I make VM stay in a single frame?
+-------------------------------------------------
+
+ John.John S Cooper <Cooper@Eng.Sun.COM> writes:
+
+ ; Don't use multiple frames
+ (setq vm-frame-per-composition nil)
+ (setq vm-frame-per-folder nil)
+ (setq vm-frame-per-edit nil)
+ (setq vm-frame-per-summary nil)
+
+\1f
+File: xemacs-faq.info, Node: Q4.0.11, Next: Q4.0.12, Prev: Q4.0.10, Up: Subsystems
+
+Q4.0.11: How do I make VM or mh-e display graphical smilies?
+------------------------------------------------------------
+
+ For mh-e use the following:
+
+ (add-hook 'mh-show-mode-hook '(lambda ()
+ (smiley-region (point-min)
+ (point-max))))
+
+ WJCarpenter <bill@carpenter.ORG> writes: For VM use the following:
+ (autoload 'smiley-region "smiley" nil t)
+ (add-hook 'vm-select-message-hook
+ '(lambda ()
+ (smiley-region (point-min)
+ (point-max))))
+
+ For tm use the following:
+ (autoload 'smiley-buffer "smiley" nil t)
+ (add-hook 'mime-viewer/plain-text-preview-hook 'smiley-buffer)
+
+\1f
+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 <boffi@hp735.stru.polimi.it> 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.
+
+\1f
+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'.
+
+\1f
+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".
+
+\1f
+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.
+
+\1f
+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/'
+
+\1f
+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.
+
+\1f
+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?
+------------------------------------------------------
+
+ The toolbar code to start Gnus opens the new frame--and it's a
+feature rather than a bug. If you don't like it, but would still like
+to click on the seemly icon, use the following code:
+
+ (defun toolbar-news ()
+ (gnus))
+
+ It will redefine the callback function of the icon to just call
+`gnus', without all the fancy frame stuff.
+
+\1f
+File: xemacs-faq.info, Node: Q4.2.4, Next: Q4.3.1, Prev: Q4.2.3, Up: Subsystems
+
+Q4.2.4: How do I customize the From: line?
+------------------------------------------
+
+ How do I change the `From:' line? I have set gnus-user-from-line to
+ Gail Gurman <gail.gurman@sybase.com>
+ , but XEmacs Gnus doesn't use it. Instead it uses
+ Gail Mara Gurman <gailg@deall>
+ and then complains that it's incorrect. Also, as you perhaps can see,
+my Message-ID is screwy. How can I change that?
+
+Lars Magne Ingebrigtsen <larsi@ifi.uio.no> writes:
+
+ Set `user-mail-address' to `gail.gurman@sybase.com' or
+ `mail-host-address' to `sybase.com'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.3.1, Next: Q4.3.2, Prev: Q4.2.4, Up: Subsystems
+
+4.3: Other Mail & News
+======================
+
+Q4.3.1: How can I read and/or compose MIME messages?
+----------------------------------------------------
+
+ VM supports MIME natively.
+
+ You probably want to use the Tools for MIME (tm). *Note Q4.3.2::,
+for details.
+
+ Trey Jackson <trey@cs.berkeley.edu> has an Emacs & MIME web page at
+`http://bmrc.berkeley.edu/~trey/emacs/mime.html'.
+
+ Another possibility is RMIME. You may find RMIME at
+`http://www.cinti.net/~rmoody/rmime/index.html'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.3.2, Next: Q4.3.3, Prev: Q4.3.1, Up: Subsystems
+
+Q4.3.2: What is TM and where do I get it?
+-----------------------------------------
+
+ TM stands for "Tools for MIME" and not Tiny MIME. TM integrates
+with all major XEmacs packages like Gnus (all flavors), VM, MH-E, and
+mailcrypt. It provides totally transparent and trouble-free MIME
+support. When appropriate a message will be decoded in place in an
+XEmacs buffer.
+
+ TM now comes as a package with XEmacs 19.16 and XEmacs 20.2.
+
+ TM was written by MORIOKA Tomohiko <morioka@jaist.ac.jp> and
+KOBAYASHI Shuhei <shuhei-k@jaist.ac.jp>.
+
+ It is based on the work of UMEDA Masanobu
+<umerin@mse.kyutech.ac.jp>, the original writer of GNUS.
+
+ The following information is from the `README':
+
+ "tm" is a MIME package for GNU Emacs. tm has following functions:
+
+ * MIME style multilingual header.
+
+ * MIME message viewer (mime/viewer-mode).
+
+ * MIME message composer (mime/editor-mode).
+
+ * MIME extenders for mh-e, GNUS, RMAIL and VM.
+
+ tm is available from following anonymous ftp sites:
+ * `ftp://ftp.jaist.ac.jp/pub/GNU/elisp/mime/' (Japan).
+
+ * `ftp://ftp.nis.co.jp/pub/gnu/emacs-lisp/tm/' (Japan).
+
+ * `ftp://ftp.nisiq.net/pub/gnu/emacs-lisp/tm/' (US).
+
+ * `ftp://ftp.miranova.com/pub/gnus/jaist.ac.jp/' (US).
+
+ * `ftp://ftp.unicamp.br/pub/mail/mime/tm/' (Brasil).
+
+ * `ftp://ftp.th-darmstadt.de/pub/editors/GNU-Emacs/lisp/mime/'
+ (Germany).
+
+ * `ftp://ftp.tnt.uni-hannover.de/pub/editors/xemacs/contrib/'
+ (Germany).
+
+ Don't let the installation procedure & instructions stop you from
+trying this package out--it's much simpler than it looks, and once
+installed, trivial to use.
+
+\1f
+File: xemacs-faq.info, Node: Q4.3.3, Next: Q4.3.4, Prev: Q4.3.2, Up: Subsystems
+
+Q4.3.3: Why isn't this `movemail' program working?
+--------------------------------------------------
+
+ Ben Wing <ben@666.com> writes:
+
+ It wasn't chown'ed/chmod'd correctly.
+
+\1f
+File: xemacs-faq.info, Node: Q4.3.4, Next: Q4.3.5, Prev: Q4.3.3, Up: Subsystems
+
+Q4.3.4: Movemail is also distributed by Netscape? Can that cause problems?
+---------------------------------------------------------------------------
+
+ Steve Baur <steve@altair.xemacs.org> writes:
+
+ Yes. Always use the movemail installed with your XEmacs. Failure
+ to do so can result in lost mail.
+
+ Please refer to Jamie Zawinski's <jwz@netscape.com> notes at
+`http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/movemail.html'.
+In particular, this document will show you how to make Netscape use the
+version of movemail configured for your system by the person who built
+XEmacs.
+
+\1f
+File: xemacs-faq.info, Node: Q4.3.5, Next: Q4.4.1, Prev: Q4.3.4, Up: Subsystems
+
+Q4.3.5: Where do I find pstogif (required by tm)?
+-------------------------------------------------
+
+ pstogif is part of the latex2html package.
+
+ Jan Vroonhof <vroonhof@math.ethz.ch> writes:
+
+ latex2html is best found at the CTAN hosts and their mirrors in
+`tex-archive/support/latex2html'.
+
+ CTAN hosts are:
+
+ * `ftp://ftp.tex.ac.uk/tex-archive/support/latex2html/'.
+
+ * `ftp://ftp.dante.de/tex-archive/support/latex2html/'.
+
+ There is a good mirror at ftp.cdrom.com;
+`ftp://ftp.cdrom.com/pub/tex/ctan/support/latex2html/'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.4.1, Next: Q4.5.1, Prev: Q4.3.5, Up: Subsystems
+
+4.4: Sparcworks, EOS, and WorkShop
+==================================
+
+Q4.4.1: What is SPARCworks, EOS, and WorkShop?
+----------------------------------------------
+
+ John Turner <turner@lanl.gov> writes:
+
+ SPARCworks is SunSoft's development environment, comprising
+ compilers (C, C++, FORTRAN 77, Fortran 90, Ada, and Pascal), a
+ debugger, and other tools such as TeamWare (for configuration
+ management), MakeTool, etc.
+
+ See `http://www.sun.com/software/Developer-products/' for more info.
+
+ EOS stands for "Era on SPARCworks", but I don't know what Era stands
+for.
+
+ EOS is the integration of XEmacs with the SPARCworks debugger. It
+allows one to use an XEmacs frame to view code (complete with
+fontification, etc.), set breakpoints, print variables, etc., while
+using the SPARCworks debugger. It works very well and I use it all the
+time.
+
+ Chuck Thompson <cthomp@xemacs.org> writes:
+
+ Era stood for "Emacs Rewritten Again". It was what we were
+ calling the modified version of Lucid Emacs for Sun when I was
+ dragged, er, allowed to work on this wonderful editor.
+
+ Martin Buchholz <martin@xemacs.org> writes:
+
+ EOS is being replaced with a new graphical development environment
+ called Sun WorkShop, which is currently (07/96) in Alpha Test.
+ For more details, check out
+
+
+
+
+
+
+
+ `http://www.sun.com/software/Products/Developer-products/programs.html'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.5.1, Next: Q4.6.1, Prev: Q4.4.1, Up: Subsystems
+
+4.5: Energize
+=============
+
+Q4.5.1: What is/was Energize?
+-----------------------------
+
+ David N Gray <gray@meteor.harlequin.com> writes:
+ The files in `lisp/energize' are to enable Emacs to interface with
+ the "Energize Programming System", a C and C++ development
+ environment, which was a product of Lucid, Inc. Tragically, Lucid
+ went out of business in 1994, so although Energize is still a
+ great system, if you don't already have it, there isn't any way to
+ get it now. (Unless you happen to be in Japan; INS Engineering
+ may still be selling it there. Tartan bought the rights to sell
+ it in the rest of the world, but never did so.)
+
+\1f
+File: xemacs-faq.info, Node: Q4.6.1, Next: Q4.7.1, Prev: Q4.5.1, Up: Subsystems
+
+4.6: Infodock
+=============
+
+Q4.6.1: What is Infodock?
+-------------------------
+
+ InfoDock is an integrated productivity toolset, mainly aimed at
+technical people. It is developed and supported by InfoDock
+Associates, a firm that offers custom support and development for
+InfoDock, XEmacs and GNU Emacs. ( `http://www.infodock.com',
+<info@infodock.com>, +1 408 243 3300).
+
+ InfoDock is built atop the XEmacs variant of GNU Emacs and so has
+all of the power of Emacs, but with an easier to use and more
+comprehensive menu-based user interface. The bottom portion of this
+text describes how it differs from XEmacs and GNU Emacs from the Free
+Software Foundation.
+
+ InfoDock is aimed at people who want a free, turn-key productivity
+environment. Although InfoDock is customizable, it is not intended for
+people who like basic versions of Emacs which need to be customized
+extensively for local use; standard Emacs distributions are better for
+such uses. InfoDock is for those people who want a complete,
+pre-customized environment in one package, which they need not touch
+more than once or twice a year to update to new revisions.
+
+ InfoDock is pre-built for SPARC SunOS/Solaris systems, PA-RISC HP-UX,
+and Intel Linux systems. It is intended for use on a color display,
+although most features will work on monochrome monitors. Simply unpack
+InfoDock according to the instructions in the ID-INSTALL file and you
+are ready to run.
+
+ The InfoDock Manual is concise, yet sufficient as a user guide for
+users who have never used an Emacs-type editor before. For users who
+are already familiar with Emacs, it supplements the information in the
+GNU Emacs Manual.
+
+ InfoDock menus are much more extensive and more mature than standard
+Emacs menus. Each menu offers a `Manual' item which displays
+documentation associated with the menu's functions.
+
+Four types of menubars are provided:
+ 1. An extensive menubar providing access to global InfoDock commands.
+
+ 2. Mode-specific menubars tailored to the current major mode.
+
+ 3. A simple menubar for basic editing to help novices get started
+ with InfoDock.
+
+ 4. The standard XEmacs menubar.
+
+ Most modes also include mode-specific popup menus. Additionally,
+region and rectangle popup menus are included.
+
+ `Hyperbole', the everyday information manager, is a core part of
+InfoDock. This provides context-sensitive mouse keys, a rolodex-type
+contact manager, programmable hypertext buttons, and an autonumbered
+outliner with embedded hyperlink anchors.
+
+ The `OO-Browser', a multi-language object-oriented code browser, is a
+standard part of InfoDock.
+
+ InfoDock saves a more extensive set of user options than other Emacs
+versions.
+
+ InfoDock inserts a useful file header in many file types, showing the
+author, summary, and last modification time of each file. A summary
+program can then be used to summarize all of the files in a directory,
+for easy MANIFEST file creation.
+
+ Your working set of buffers is automatically saved and restored (if
+you answer yes to a prompt) between InfoDock sessions.
+
+ Refined color choices for code highlighting are provided for both
+dark and light background display frames.
+
+ The `C-z' key prefix performs frame-based commands which parallel the
+`C-x' key prefix for window-based commands.
+
+ The Smart Menu system is included for producing command menus on dumb
+terminals.
+
+ Lisp libraries are better categorized according to function.
+
+ Extensions and improvements to many areas of Emacs are included,
+such as: paragraph filling, mail reading with Rmail, shell handling,
+outlining, code highlighting and browsing, and man page browsing.
+
+ InfoDock questions, answers and discussion should go to the mail list
+<infodock@infodock.com>. Use <infodock-request@infodock.com> to be
+added or removed from the list. Always include your InfoDock version
+number when sending help requests.
+
+ InfoDock is available across the Internet via anonymous FTP. To get
+it, first move to a directory into which you want the InfoDock archive
+files placed. We will call this <DIST-DIR>.
+
+ cd <DIST-DIR>
+
+ Ftp to ftp.xemacs.org (Internet Host ID = 128.174.252.16):
+
+ prompt> ftp ftp.xemacs.org
+
+ Login as `anonymous' with your own <user-id>@<site-name> as a
+password.
+
+ Name (ftp.xemacs.org): anonymous
+ 331 Guest login ok, send your complete e-mail address as password.
+ Password: -<your-user-id>@<your-domain>
+ 230 Guest login ok, access restrictions apply.
+
+ Move to the location of the InfoDock archives:
+
+ ftp> cd pub/infodock
+
+ Set your transfer mode to binary:
+
+ ftp> bin
+ 200 Type set to I.
+
+ Turn off prompting:
+
+ ftp> prompt
+ Interactive mode off.
+
+ Retrieve the InfoDock archives that you want, either by using a `get
+<file>' for each file you want or by using the following to get a
+complete distribution, including all binaries:
+
+ ftp> mget ID-INSTALL
+ ftp> mget id-*
+
+ Close the FTP connection:
+
+ ftp> quit
+ 221 Goodbye.
+
+ Read the `ID-INSTALL' file which you just retrieved for step-by-step
+installation instructions.
+
+\1f
+File: xemacs-faq.info, Node: Q4.7.1, Next: Q4.7.2, Prev: Q4.6.1, Up: Subsystems
+
+4.7: Other Unbundled Packages
+=============================
+
+Q4.7.1: What is AUC TeX? Where do you get it?
+----------------------------------------------
+
+ AUC TeX is a package written by Per Abrahamsen <abraham@dina.kvl.dk>.
+Starting with XEmacs 19.16, AUC TeX is bundled with XEmacs. The
+following information is from the `README' and website.
+
+ AUC TeX is an extensible package that supports writing and formatting
+TeX files for most variants of GNU Emacs. Many different macro packages
+are supported, including AMS TeX, LaTeX, and TeXinfo.
+
+ The most recent version is always available by ftp at
+`ftp://sunsite.auc.dk/packages/auctex/auctex.tar.gz'.
+
+ In case you don't have access to anonymous ftp, you can get it by an
+email request to <ftpmail@decwrl.dec.com>.
+
+ WWW users may want to check out the AUC TeX page at
+`http://sunsite.auc.dk/auctex/'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.7.2, Next: Q4.7.3, Prev: Q4.7.1, Up: Subsystems
+
+Q4.7.2: Are there any Emacs Lisp Spreadsheets?
+----------------------------------------------
+
+ Yes. Check out "dismal" (which stands for Dis' Mode Ain't Lotus) at
+`ftp://cs.nyu.edu/pub/local/fox/dismal/'.
+
+\1f
+File: xemacs-faq.info, Node: Q4.7.3, Next: Q4.7.4, Prev: Q4.7.2, Up: Subsystems
+
+Q4.7.3: Byte compiling AUC TeX on XEmacs 19.14.
+-----------------------------------------------
+
+ Georges Brun-Cottan <bruncott@dormeur.inria.fr> writes:
+
+ When byte compiling auctex-9.4g, you must use the command:
+
+ xemacs -batch -l lpath.el
+
+\1f
+File: xemacs-faq.info, Node: Q4.7.4, Next: Q4.7.5, Prev: Q4.7.3, Up: Subsystems
+
+Q4.7.4: Problems installing AUC TeX.
+------------------------------------
+
+ Jan Vroonhof <vroonhof@math.ethz.ch> writes:
+
+ AUC TeX works fine on both stock Emacs and XEmacs has been doing
+ so for a very very long time. This is mostly due to the work of
+ Per Abrahamsen <abraham@dina.kvl.dk> (clap clap) in particular his
+ `easymenu' package. Which leads to what is probably the problem...
+
+ Most problems with AUC TeX are one of two things:
+
+ * The TeX-lisp-directory in `tex-site.el' and the makefile don't
+ match.
+
+ Fix: make sure you configure AUC TeX properly *before* installing.
+
+ * You have an old version of easymenu.el in your path.
+
+ Fix: use `locate-library' and remove old versions to make sure it
+ *only* finds the one that came with XEmacs.
+
+\1f
+File: xemacs-faq.info, Node: Q4.7.5, Next: Q4.7.6, Prev: Q4.7.4, Up: Subsystems
+
+Q4.7.5: Is there a reason for an Emacs package not to be included in XEmacs?
+----------------------------------------------------------------------------
+
+ The reason for an Emacs package not to be included in XEmacs is
+usually one or more of the following:
+
+ 1. The package has not been ported to XEmacs. This will typically
+ happen when it uses GNU-Emacs-specific features, which make it
+ fail under XEmacs.
+
+ Porting a package to XEmacs can range from a trivial amount of
+ change to a partial or full rewrite. Fortunately, the authors of
+ modern packages usually choose to support both Emacsen themselves.
+
+ 2. The package has been decided not to be appropriate for XEmacs. It
+ may have an equivalent or better replacement within XEmacs, in
+ which case the developers may choose not to burden themselves with
+ supporting an additional package.
+
+ Each package bundled with XEmacs means more work for the
+ maintainers, whether they want it or not. If you are ready to
+ take over the maintenance responsibilities for the package you
+ port, be sure to say so - we will more likely include it.
+
+ 3. The package simply hasn't been noted by the XEmacs development. If
+ that's the case, the messages like yours are very useful for
+ attracting our attention.
+
+ 4. The package was noted by the developers, but they simply haven't
+ yet gotten around to including/porting it. Wait for the next
+ release or, even better, offer your help. It will be gladly
+ accepted and appreciated.
+
+\1f
+File: xemacs-faq.info, Node: Q4.7.6, Prev: Q4.7.5, Up: Subsystems
+
+Q4.7.5: Is there a MatLab mode?
+-------------------------------
+
+ Is there any way I can get syntax highlighting for MatLab .m files?
+Can I "teach" emacs what words are MatLab commands, comments, etc. ?
+
+ Ulrich Elsner <elsner@mathematik.tu-chemnitz.de> writes:
+ One way to do this (and much more) is by using the
+ matlab mode
+ (ftp://ftp.mathworks.com/pub/contrib/v5/tools/matlab.el).
+
+ Instructions on how to install this mode are included in this file.
+
+\1f
+File: xemacs-faq.info, Node: Miscellaneous, Next: Current Events, Prev: Subsystems, Up: Top
+
+5 The Miscellaneous Stuff
+*************************
+
+ This is part 5 of the XEmacs Frequently Asked Questions list. This
+section is devoted to anything that doesn't fit neatly into the other
+sections.
+
+* Menu:
+
+Major & Minor Modes:
+* Q5.0.1:: How can I do source code highlighting using font-lock?
+* Q5.0.2:: I do not like cc-mode. How do I use the old c-mode?
+* Q5.0.3:: How do I get `More' Syntax Highlighting on by default?
+* Q5.0.4:: How can I enable auto-indent?
+* Q5.0.5:: How can I get XEmacs to come up in text/auto-fill mode by default?
+* Q5.0.6:: How do I start up a second shell buffer?
+* Q5.0.7:: Telnet from shell filters too much.
+* Q5.0.8:: Why does edt emulation not work?
+* Q5.0.9:: How can I emulate VI and use it as my default mode?
+* Q5.0.10:: [This question intentionally left blank]
+* Q5.0.11:: Filladapt doesn't work in 19.15?
+* Q5.0.12:: How do I disable gnuserv from opening a new frame?
+* Q5.0.13:: How do I start gnuserv so that each subsequent XEmacs is a client?
+* Q5.0.14:: Strange things are happening in Shell Mode.
+* Q5.0.15:: Where do I get the latest CC Mode?
+* Q5.0.16:: I find auto-show-mode disconcerting. How do I turn it off?
+* Q5.0.17:: How can I get two instances of info?
+* Q5.0.18:: I upgraded to XEmacs 19.14 and gnuserv stopped working
+* Q5.0.19:: Is there something better than LaTeX mode?
+* Q5.0.20:: Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
+
+Emacs Lisp Programming Techniques:
+* Q5.1.1:: The difference in key sequences between XEmacs and GNU Emacs?
+* Q5.1.2:: Can I generate "fake" keyboard events?
+* Q5.1.3:: Could you explain `read-kbd-macro' in more detail?
+* Q5.1.4:: What is the performance hit of `let'?
+* Q5.1.5:: What is the recommended use of `setq'?
+* Q5.1.6:: What is the typical misuse of `setq'?
+* Q5.1.7:: I like the the `do' form of cl, does it slow things down?
+* Q5.1.8:: I like recursion, does it slow things down?
+* Q5.1.9:: How do I put a glyph as annotation in a buffer?
+* Q5.1.10:: `map-extents' won't traverse all of my extents!
+* Q5.1.11:: My elisp program is horribly slow. Is there an easy way to find out where it spends time?
+
+Sound:
+* Q5.2.1:: How do I turn off the sound?
+* Q5.2.2:: How do I get funky sounds instead of a boring beep?
+* Q5.2.3:: What's NAS, how do I get it?
+* Q5.2.4:: Sunsite sounds don't play.
+
+Miscellaneous:
+* Q5.3.1:: How do you make XEmacs indent CL if-clauses correctly?
+* Q5.3.2:: Fontifying hangs when editing a postscript file.
+* Q5.3.3:: How can I print WYSIWYG a font-locked buffer?
+* Q5.3.4:: Getting `M-x lpr' to work with postscript printer.
+* Q5.3.5:: How do I specify the paths that XEmacs uses for finding files?
+* Q5.3.6:: [This question intentionally left blank]
+* Q5.3.7:: Can I have the end of the buffer delimited in some way?
+* Q5.3.8:: How do I insert today's date into a buffer?
+* Q5.3.9:: Are only certain syntactic character classes available for abbrevs?
+* Q5.3.10:: How can I get those oh-so-neat X-Face lines?
+* Q5.3.11:: How do I add new Info directories?
+* Q5.3.12:: What do I need to change to make printing work?
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.1, Next: Q5.0.2, Prev: Miscellaneous, Up: Miscellaneous
+
+5.0: Major & Minor Modes
+========================
+
+Q5.0.1: How can I do source code highlighting using font-lock?
+--------------------------------------------------------------
+
+ For most modes, font-lock is already set up and just needs to be
+turned on. This can be done by `M-x font-lock-mode', or by having
+XEmacs automatically start it by adding lines like:
+
+ (add-hook 'emacs-lisp-mode-hook 'turn-on-font-lock)
+ (add-hook 'dired-mode-hook 'turn-on-font-lock)
+
+ to your `.emacs'. See the file `etc/sample.emacs' for more examples.
+
+ See also `Syntax Highlighting' from the `Options' menu. Remember to
+save options.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.2, Next: Q5.0.3, Prev: Q5.0.1, Up: Miscellaneous
+
+Q5.0.2: I do not like cc-mode. How do I use the old c-mode?
+------------------------------------------------------------
+
+ Well, first off, consider if you really want to do this. cc-mode is
+much more powerful than the old c-mode. If you're having trouble
+getting your old offsets to work, try using `c-set-offset' instead.
+You might also consider using the package `cc-compat'.
+
+ But, if you still insist, add the following lines to your `.emacs':
+
+ (fmakunbound 'c-mode)
+ (makunbound 'c-mode-map)
+ (fmakunbound 'c++-mode)
+ (makunbound 'c++-mode-map)
+ (makunbound 'c-style-alist)
+ (load-library "old-c-mode")
+ (load-library "old-c++-mode")
+
+ This must be done before any other reference is made to either
+c-mode or c++-mode.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.3, Next: Q5.0.4, Prev: Q5.0.2, Up: Miscellaneous
+
+Q5.0.3: How do I get `More' Syntax Highlighting on by default?
+--------------------------------------------------------------
+
+ Use the following code in your `.emacs':
+
+ (setq-default font-lock-maximum-decoration t)
+
+ In versions of XEmacs prior to 19.14, you had to use a kludgy
+solution like this:
+
+ (setq c-font-lock-keywords c-font-lock-keywords-2
+ c++-font-lock-keywords c++-font-lock-keywords-2
+ lisp-font-lock-keywords lisp-font-lock-keywords-2)
+
+ It will work for C, C++ and Lisp.
+
+ See also `Syntax Highlighting' from the `Options' menu. Remember to
+save options.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.4, Next: Q5.0.5, Prev: Q5.0.3, Up: Miscellaneous
+
+Q5.0.4: How can I enable auto-indent?
+-------------------------------------
+
+ Put the following line in your `.emacs':
+
+ (setq indent-line-function 'indent-relative-maybe)
+
+ If you want to get fancy, try the `filladapt' package available
+standard with XEmacs. Put this into your `.emacs':
+
+ (require 'filladapt)
+ (add-hook 'text-mode-hook 'turn-on-filladapt-mode)
+ ;;; and others ...
+
+ You can customize filling and adaptive filling with Customize.
+Select from the `Options' menu
+`Customize->Emacs->->Editing->Fill->Fill...' or type `M-x customize
+<RET> fill <RET>'.
+
+ Note that well-behaving text-lookalike modes will run
+`text-mode-hook' by default (e.g. that's what Message does). For the
+nasty ones, you'll have to provide the `add-hook's yourself.
+
+ Please note that the `fa-extras' package is no longer useful.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.5, Next: Q5.0.6, Prev: Q5.0.4, Up: Miscellaneous
+
+Q5.0.5: How can I get XEmacs to come up in text/auto-fill mode by default?
+--------------------------------------------------------------------------
+
+ Try the following lisp in your `.emacs':
+
+ (setq default-major-mode 'text-mode)
+ (setq text-mode-hook 'turn-on-auto-fill)
+
+ *WARNING*: note that changing the value of `default-major-mode' from
+`fundamental-mode' can break a large amount of built-in code that
+expects newly created buffers to be in `fundamental-mode'. (Changing
+from `fundamental-mode' to `text-mode' might not wreak too much havoc,
+but changing to something more exotic like a lisp-mode would break many
+Emacs packages).
+
+ Note that Emacs by default starts up in buffer `*scratch*' in
+`initial-major-mode', which defaults to `lisp-interaction-mode'. Thus
+adding the following form to your Emacs init file will cause the
+initial `*scratch*' buffer to be put into auto-fill'ed `text-mode':
+
+ (setq initial-major-mode
+ (lambda ()
+ (text-mode)
+ (turn-on-auto-fill)))
+
+ Note that after your init file is loaded, if
+`inhibit-startup-message' is `nil' (the default) and the startup buffer
+is `*scratch*' then the startup message will be inserted into
+`*scratch*'; it will be removed after a timeout by erasing the entire
+`*scratch*' buffer. Keep in mind this default usage of `*scratch*' if
+you desire any prior manipulation of `*scratch*' from within your Emacs
+init file. In particular, anything you insert into `*scratch*' from
+your init file will be later erased. Also, if you change the mode of
+the `*scratch*' buffer, be sure that this will not interfere with
+possible later insertion of the startup message (e.g. if you put
+`*scratch*' into a nonstandard mode that has automatic font lock rules,
+then the startup message might get fontified in a strange foreign
+manner, e.g. as code in some programming language).
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.6, Next: Q5.0.7, Prev: Q5.0.5, Up: Miscellaneous
+
+Q5.0.6: How do I start up a second shell buffer?
+------------------------------------------------
+
+ In the `*shell*' buffer:
+
+ M-x rename-buffer <RET> *shell-1* <RET>
+ M-x shell RET
+
+ This will then start a second shell. The key is that no buffer named
+`*shell*' can exist. It might be preferable to use `M-x
+rename-uniquely' to rename the `*shell*' buffer instead of `M-x
+rename-buffer'.
+
+ Alternately, you can set the variable `shell-multiple-shells'. If
+the value of this variable is non-nil, each time shell mode is invoked,
+a new shell is made
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.7, Next: Q5.0.8, Prev: Q5.0.6, Up: Miscellaneous
+
+Q5.0.7: Telnet from shell filters too much
+------------------------------------------
+
+ I'm using the Emacs `M-x shell' function, and I would like to invoke
+and use a telnet session within it. Everything works fine except that
+now all `^M''s are filtered out by Emacs. Fixes?
+
+ Use `M-x rsh' or `M-x telnet' to open remote sessions rather than
+doing rsh or telnet within the local shell buffer. Starting with
+XEmacs-20.3 you can also use `M-x ssh' to open secure remote session if
+you have `ssh' installed.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.8, Next: Q5.0.9, Prev: Q5.0.7, Up: Miscellaneous
+
+Q5.0.8: Why does edt emulation not work?
+----------------------------------------
+
+ We don't know, but you can use tpu-edt emulation instead, which works
+fine and is a little fancier than the standard edt emulation. To do
+this, add the following line to your `.emacs':
+
+ (tpu-edt)
+
+ If you don't want it to replace `C-h' with an edt-style help menu
+add this as well:
+
+ (global-set-key [(control h)] 'help-for-help)
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.9, Next: Q5.0.10, Prev: Q5.0.8, Up: Miscellaneous
+
+Q5.0.9: How can I emulate VI and use it as my default mode?
+-----------------------------------------------------------
+
+ Our recommended VI emulator is viper. To make viper-mode the default,
+add this to your `.emacs':
+
+ (viper-mode)
+
+ Michael Kifer <kifer@CS.SunySB.EDU> writes:
+
+ This should be added as close to the top of `.emacs' as you can get
+ it, otherwise some minor modes may not get viper-ized.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.10, Next: Q5.0.11, Prev: Q5.0.9, Up: Miscellaneous
+
+Q5.0.10: [This question intentionally left blank]
+-------------------------------------------------
+
+ Obsolete question, left blank to avoid renumbering
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.11, Next: Q5.0.12, Prev: Q5.0.10, Up: Miscellaneous
+
+Q5.0.11: Filladapt doesn't work in 19.15
+----------------------------------------
+
+ Filladapt 2.x is included in 19.15. In it filladapt is now a minor
+mode and minor modes are traditionally off by default. The following
+added to your `.emacs' will turn it on for all buffers:
+
+ (setq-default filladapt-mode t)
+
+ Use `turn-on-filladapt-mode' to turn Filladapt on in particular
+major modes, like this:
+
+ (add-hook 'text-mode-hook 'turn-on-filladapt-mode)
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.12, Next: Q5.0.13, Prev: Q5.0.11, Up: Miscellaneous
+
+Q5.0.12: How do I disable gnuserv from opening a new frame?
+-----------------------------------------------------------
+
+ If you set the `gnuserv-frame' variable to the frame that should be
+used to display buffers that are pulled up, a new frame will not be
+created. For example, you could put
+
+ (setq gnuserv-frame (selected-frame))
+
+ early on in your `.emacs', to ensure that the first frame created is
+the one used for your gnuserv buffers.
+
+ Starting in 19.15, there is an option to set the gnuserv target to
+the current frame. See `Options->"Other Window" Location->Make current
+frame gnuserv target'
+
+ Starting with XEmacs-20.3 you can also change this with Customize.
+Select from the `Options' menu
+`Customize->Emacs->Environment->Gnuserv->Gnuserv Frame...' or type `M-x
+customize <RET> gnuserv <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.13, Next: Q5.0.14, Prev: Q5.0.12, Up: Miscellaneous
+
+Q5.0.13: How do I start gnuserv so that each subsequent XEmacs is a client?
+---------------------------------------------------------------------------
+
+ Put the following in your `.emacs' file to start the server:
+
+ (gnuserv-start)
+
+ Start your first XEmacs as usual. After that, you can do:
+
+ gnuclient randomfilename
+
+ from the command line to get your existing XEmacs process to open a
+new frame and visit randomfilename in that window. When you're done
+editing randomfilename, hit `C-x #' to kill the buffer and get rid of
+the frame.
+
+ See also man page of gnuclient.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.14, Next: Q5.0.15, Prev: Q5.0.13, Up: Miscellaneous
+
+Q5.0.14: Strange things are happening in Shell Mode.
+----------------------------------------------------
+
+ Sometimes (i.e. it's not repeatable, and I can't work out why it
+happens) when I'm typing into shell mode, I hit return and only a
+portion of the command is given to the shell, and a blank prompt is
+returned. If I hit return again, the rest of the previous command is
+given to the shell.
+
+ Martin Buchholz <martin@xemacs.org> writes:
+
+ There is a known problem with interaction between `csh' and the
+ `filec' option and XEmacs. You should add the following to your
+ `.cshrc':
+
+ if ( "$TERM" == emacs || "$TERM" == unknown ) unset filec
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.15, Next: Q5.0.16, Prev: Q5.0.14, Up: Miscellaneous
+
+Q5.0.15: Where do I get the latest CC Mode?
+-------------------------------------------
+
+ Barry A. Warsaw <bwarsaw@cnri.reston.va.us> writes:
+
+ This can be had from `http://www.python.org/ftp/emacs/'.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.16, Next: Q5.0.17, Prev: Q5.0.15, Up: Miscellaneous
+
+Q5.0.16: I find auto-show-mode disconcerting. How do I turn it off?
+--------------------------------------------------------------------
+
+ `auto-show-mode' controls whether or not a horizontal scrollbar
+magically appears when a line is too long to be displayed. This is
+enabled by default. To turn it off, put the following in your `.emacs':
+
+ (setq auto-show-mode nil)
+ (setq-default auto-show-mode nil)
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.17, Next: Q5.0.18, Prev: Q5.0.16, Up: Miscellaneous
+
+Q5.0.17: How can I get two instances of info?
+---------------------------------------------
+
+ You can't. The `info' package does not provide for multiple info
+buffers.
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.18, Next: Q5.0.19, Prev: Q5.0.17, Up: Miscellaneous
+
+Q5.0.18: I upgraded to XEmacs 19.14 and gnuserv stopped working.
+----------------------------------------------------------------
+
+ Mark Daku <daku@nortel.ca> writes:
+
+ It turns out I was using an older version of gnuserv. The
+ installation didn't put the binary into the public bin directory.
+ It put it in `lib/xemacs-19.14/hppa1.1-hp-hpux9.05/gnuserv'.
+ Shouldn't it have been put in `bin/hppa1.1-hp-hpux9.0'?
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.19, Next: Q5.0.20, Prev: Q5.0.18, Up: Miscellaneous
+
+Q5.0.19: Is there something better than LaTeX mode?
+---------------------------------------------------
+
+ David Kastrup <dak@fsnif.neuroinformatik.ruhr-uni-bochum.de> writes:
+
+ The standard TeX modes leave much to be desired, and are somewhat
+ leniently maintained. Serious TeX users use AUC TeX (*note
+ Q4.7.1::.).
+
--- /dev/null
+This is Info file ../info/xemacs-faq.info, produced by Makeinfo version
+1.68 from the input file xemacs-faq.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* FAQ: (xemacs-faq). XEmacs FAQ.
+END-INFO-DIR-ENTRY
+
+\1f
+File: xemacs-faq.info, Node: Q5.0.20, Next: Q5.1.1, Prev: Q5.0.19, Up: Miscellaneous
+
+Q5.0.20: Is there a way to start a new XEmacs if there's no gnuserv running, and otherwise use gnuclient?
+---------------------------------------------------------------------------------------------------------
+
+ Jan Vroonhof <vroonhof@math.ethz.ch> writes:
+ Here is one of the solutions, we have this in a script called
+ `etc/editclient.sh'.
+ #!/bin/sh
+ if gnuclient -batch -eval t >/dev/null 2>&1
+ then
+ exec gnuclient ${1+"$@"}
+ else
+ xemacs -unmapped -f gnuserv-start &
+ until gnuclient -batch -eval t >/dev/null 2>&1
+ do
+ sleep 1
+ done
+ exec gnuclient ${1+"$@"}
+ fi
+
+ Note that there is a known problem when running XEmacs and
+ 'gnuclient -nw' on the same TTY.
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.1, Next: Q5.1.2, Prev: Q5.0.20, Up: Miscellaneous
+
+5.1: Emacs Lisp Programming Techniques
+======================================
+
+Q5.1.1: What is the difference in key sequences between XEmacs and GNU Emacs?
+-----------------------------------------------------------------------------
+
+ Erik Naggum <clerik@naggum.no> writes;
+
+ Emacs has a legacy of keyboards that produced characters with
+ modifier bits, and therefore map a variety of input systems into
+ this scheme even today. XEmacs is instead optimized for X events.
+ This causes an incompatibility in the way key sequences are
+ specified, but both Emacs and XEmacs will accept a key sequence as
+ a vector of lists of modifiers that ends with a key, e.g., to bind
+ `M-C-a', you would say `[(meta control a)]' in both Emacsen.
+ XEmacs has an abbreviated form for a single key, just (meta
+ control a). Emacs has an abbreviated form for the Control and the
+ Meta modifiers to string-characters (the ASCII characters), as in
+ `\M-\C-a'. XEmacs users need to be aware that the abbreviated
+ form works only for one-character key sequences, while Emacs users
+ need to be aware that the string-character is rather limited.
+ Specifically, the string-character can accommodate only 256
+ different values, 128 of which have the Meta modifier and 128 of
+ which have not. In each of these blocks, only 32 characters have
+ the Control modifier. Whereas `[(meta control A)]' differs from
+ `[(meta control a)]' because the case differs, `\M-\C-a' and
+ `\M-\C-A' do not. Programmers are advised to use the full common
+ form, both because it is more readable and less error-prone, and
+ because it is supported by both Emacsen.
+
+ Another (even safer) way to be sure of the key-sequences is to use
+the `read-kbd-macro' function, which takes a string like `C-c <up>',
+and converts it to the internal key representation of the Emacs you
+use. The function is available both on XEmacs and GNU Emacs.
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.2, Next: Q5.1.3, Prev: Q5.1.1, Up: Miscellaneous
+
+Q5.1.2: Can I generate "fake" keyboard events?
+----------------------------------------------
+
+ I wonder if there is an interactive function that can generate
+"fake" keyboard events. This way, I could simply map them inside
+XEmacs.
+
+ This seems to work:
+
+ (defun cg--generate-char-event (ch)
+ "Generate an event, as if ch has been typed"
+ (dispatch-event (character-to-event ch)))
+
+ ;; Backspace and Delete stuff
+ (global-set-key [backspace]
+ (lambda () (interactive) (cg--generate-char-event 127)))
+ (global-set-key [unknown_keysym_0x4]
+ (lambda () (interactive) (cg--generate-char-event 4)))
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.3, Next: Q5.1.4, Prev: Q5.1.2, Up: Miscellaneous
+
+Q5.1.3: Could you explain `read-kbd-macro' in more detail?
+----------------------------------------------------------
+
+ The `read-kbd-macro' function returns the internal Emacs
+representation of a human-readable string (which is its argument).
+Thus:
+
+ (read-kbd-macro "C-c C-a")
+ => [(control ?c) (control ?a)]
+
+ (read-kbd-macro "C-c C-. <up>")
+ => [(control ?c) (control ?.) up]
+
+ In GNU Emacs the same forms will be evaluated to what GNU Emacs
+understands internally--the sequences `"\C-x\C-c"' and `[3 67108910
+up]', respectively.
+
+ The exact "human-readable" syntax is defined in the docstring of
+`edmacro-mode'. I'll repeat it here, for completeness.
+
+ Format of keyboard macros during editing:
+
+ Text is divided into "words" separated by whitespace. Except for
+ the words described below, the characters of each word go directly
+ as characters of the macro. The whitespace that separates words is
+ ignored. Whitespace in the macro must be written explicitly, as in
+ `foo <SPC> bar <RET>'.
+
+ * The special words `RET', `SPC', `TAB', `DEL', `LFD', `ESC',
+ and `NUL' represent special control characters. The words
+ must be written in uppercase.
+
+ * A word in angle brackets, e.g., `<return>', `<down>', or
+ `<f1>', represents a function key. (Note that in the standard
+ configuration, the function key `<return>' and the control key
+ <RET> are synonymous.) You can use angle brackets on the
+ words <RET>, <SPC>, etc., but they are not required there.
+
+ * Keys can be written by their ASCII code, using a backslash
+ followed by up to six octal digits. This is the only way to
+ represent keys with codes above \377.
+
+ * One or more prefixes `M-' (meta), `C-' (control), `S-'
+ (shift), `A-' (alt), `H-' (hyper), and `s-' (super) may
+ precede a character or key notation. For function keys, the
+ prefixes may go inside or outside of the brackets: `C-<down>'
+ == `<C-down>'. The prefixes may be written in any order:
+ `M-C-x' == `C-M-x'.
+
+ Prefixes are not allowed on multi-key words, e.g., `C-abc',
+ except that the Meta prefix is allowed on a sequence of
+ digits and optional minus sign: `M--123' == `M-- M-1 M-2 M-3'.
+
+ * The `^' notation for control characters also works: `^M' ==
+ `C-m'.
+
+ * Double angle brackets enclose command names: `<<next-line>>'
+ is shorthand for `M-x next-line <RET>'.
+
+ * Finally, `REM' or `;;' causes the rest of the line to be
+ ignored as a comment.
+
+ Any word may be prefixed by a multiplier in the form of a decimal
+ number and `*': `3*<right>' == `<right> <right> <right>', and
+ `10*foo' == `foofoofoofoofoofoofoofoofoofoo'.
+
+ Multiple text keys can normally be strung together to form a word,
+ but you may need to add whitespace if the word would look like one
+ of the above notations: `; ; ;' is a keyboard macro with three
+ semicolons, but `;;;' is a comment. Likewise, `\ 1 2 3' is four
+ keys but `\123' is a single key written in octal, and `< right >'
+ is seven keys but `<right>' is a single function key. When in
+ doubt, use whitespace.
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.4, Next: Q5.1.5, Prev: Q5.1.3, Up: Miscellaneous
+
+Q5.1.4: What is the performance hit of `let'?
+---------------------------------------------
+
+ In most cases, not noticeable. Besides, there's no avoiding
+`let'--you have to bind your local variables, after all. Some pose a
+question whether to nest `let's, or use one `let' per function. I
+think because of clarity and maintenance (and possible future
+implementation), `let'-s should be used (nested) in a way to provide
+the clearest code.
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.5, Next: Q5.1.6, Prev: Q5.1.4, Up: Miscellaneous
+
+Q5.1.5: What is the recommended use of `setq'?
+----------------------------------------------
+
+ * Global variables
+
+ You will typically `defvar' your global variable to a default
+ value, and use `setq' to set it later.
+
+ It is never a good practice to `setq' user variables (like
+ `case-fold-search', etc.), as it ignores the user's choice
+ unconditionally. Note that `defvar' doesn't change the value of a
+ variable if it was bound previously. If you wish to change a
+ user-variable temporarily, use `let':
+
+ (let ((case-fold-search nil))
+ ... ; code with searches that must be case-sensitive
+ ...)
+
+ You will notice the user-variables by their docstrings beginning
+ with an asterisk (a convention).
+
+ * Local variables
+
+ Bind them with `let', which will unbind them (or restore their
+ previous value, if they were bound) after exiting from the `let'
+ form. Change the value of local variables with `setq' or whatever
+ you like (e.g. `incf', `setf' and such). The `let' form can even
+ return one of its local variables.
+
+ Typical usage:
+
+ ;; iterate through the elements of the list returned by
+ ;; `hairy-function-that-returns-list'
+ (let ((l (hairy-function-that-returns-list)))
+ (while l
+ ... do something with (car l) ...
+ (setq l (cdr l))))
+
+ Another typical usage includes building a value simply to work
+ with it.
+
+ ;; Build the mode keymap out of the key-translation-alist
+ (let ((inbox (file-truename (expand-file-name box)))
+ (i 0))
+ ... code dealing with inbox ...
+ inbox)
+
+ This piece of code uses the local variable `inbox', which becomes
+ unbound (or regains old value) after exiting the form. The form
+ also returns the value of `inbox', which can be reused, for
+ instance:
+
+ (setq foo-processed-inbox
+ (let .....))
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.6, Next: Q5.1.7, Prev: Q5.1.5, Up: Miscellaneous
+
+Q5.1.6: What is the typical misuse of `setq' ?
+----------------------------------------------
+
+ A typical misuse is probably `setq'ing a variable that was meant to
+be local. Such a variable will remain bound forever, never to be
+garbage-collected. For example, the code doing:
+
+ (defun my-function (whatever)
+ (setq a nil)
+ ... build a large list ...
+ ... and exit ...)
+
+ does a bad thing, as `a' will keep consuming memory, never to be
+unbound. The correct thing is to do it like this:
+
+ (defun my-function (whatever)
+ (let (a) ; default initialization is to nil
+ ... build a large list ...
+ ... and exit, unbinding `a' in the process ...)
+
+ Not only is this prettier syntactically, but it makes it possible for
+Emacs to garbage-collect the objects which `a' used to reference.
+
+ Note that even global variables should not be `setq'ed without
+`defvar'ing them first, because the byte-compiler issues warnings. The
+reason for the warning is the following:
+
+ (defun flurgoze nil) ; ok, global internal variable
+ ...
+
+ (setq flurghoze t) ; ops! a typo, but semantically correct.
+ ; however, the byte-compiler warns.
+
+ While compiling toplevel forms:
+ ** assignment to free variable flurghoze
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.7, Next: Q5.1.8, Prev: Q5.1.6, Up: Miscellaneous
+
+Q5.1.7: I like the the `do' form of cl, does it slow things down?
+-----------------------------------------------------------------
+
+ It shouldn't. Here is what Dave Gillespie has to say about cl.el
+performance:
+
+ Many of the advanced features of this package, such as `defun*',
+ `loop', and `setf', are implemented as Lisp macros. In
+ byte-compiled code, these complex notations will be expanded into
+ equivalent Lisp code which is simple and efficient. For example,
+ the forms
+
+ (incf i n)
+ (push x (car p))
+
+ are expanded at compile-time to the Lisp forms
+
+ (setq i (+ i n))
+ (setcar p (cons x (car p)))
+
+ which are the most efficient ways of doing these respective
+ operations in Lisp. Thus, there is no performance penalty for
+ using the more readable `incf' and `push' forms in your compiled
+ code.
+
+ *Interpreted* code, on the other hand, must expand these macros
+ every time they are executed. For this reason it is strongly
+ recommended that code making heavy use of macros be compiled. (The
+ features labelled "Special Form" instead of "Function" in this
+ manual are macros.) A loop using `incf' a hundred times will
+ execute considerably faster if compiled, and will also
+ garbage-collect less because the macro expansion will not have to
+ be generated, used, and thrown away a hundred times.
+
+ You can find out how a macro expands by using the `cl-prettyexpand'
+ function.
+
+\1f
+File: xemacs-faq.info, Node: Q5.1.8, Next: Q5.1.9, Prev: Q5.1.7, Up: Miscellaneous
+
+Q5.1.8: I like recursion, does it slow things down?
+---------------------------------------------------
+
+ Yes. Emacs byte-compiler cannot do much to optimize recursion. But
+think well whether this is a real concern in Emacs. Much of the Emacs
+slowness comes from internal mechanisms such as redisplay, or from the
+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.
+
+\1f
+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)'.
+
+\1f
+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))
+
+\1f
+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 <hniksic@srce.hr> writes:
+ Under XEmacs 20.4 and later you can use `M-x
+ profile-key-sequence', press a key (say <RET> 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.
+
+\1f
+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?
+------------------------------------
+
+ Add the following line to your `.emacs':
+
+ (setq bell-volume 0)
+ (setq sound-alist nil)
+
+ That will make your XEmacs totally silent - even the default ding
+sound (TTY beep on TTY-s) will be gone.
+
+ Starting with XEmacs-20.2 you can also change these with Customize.
+Select from the `Options' menu
+`Customize->Emacs->Environment->Sound->Sound...' or type `M-x customize
+<RET> sound <RET>'.
+
+\1f
+File: xemacs-faq.info, Node: Q5.2.2, Next: Q5.2.3, Prev: Q5.2.1, Up: Miscellaneous
+
+Q5.2.2: How do I get funky sounds instead of a boring beep?
+-----------------------------------------------------------
+
+ Make sure your XEmacs was compiled with sound support, and then put
+this in your `.emacs':
+
+ (load-default-sounds)
+
+ The sound support in XEmacs 19.14 was greatly improved over previous
+versions.
+
+\1f
+File: xemacs-faq.info, Node: Q5.2.3, Next: Q5.2.4, Prev: Q5.2.2, Up: Miscellaneous
+
+Q5.2.3: What's NAS, how do I get it?
+------------------------------------
+
+ *Note Q2.0.3::, for an explanation of the "Network Audio System".
+
+\1f
+File: xemacs-faq.info, Node: Q5.2.4, Next: Q5.3.1, Prev: Q5.2.3, Up: Miscellaneous
+
+Q5.2.4: Sunsite sounds don't play.
+----------------------------------
+
+ I'm having some trouble with sounds I've downloaded from sunsite.
+They play when I run them through `showaudio' or cat them directly to
+`/dev/audio', but XEmacs refuses to play them.
+
+ Markus Gutschke <gutschk@uni-muenster.de> writes:
+
+ [Many of] These files have an (erroneous) 24byte header that tells
+ about the format that they have been recorded in. If you cat them
+ to `/dev/audio', the header will be ignored and the default
+ behavior for /dev/audio will be used. This happens to be 8kHz
+ uLaw. It is probably possible to fix the header by piping through
+ `sox' and passing explicit parameters for specifying the sampling
+ format; you then need to perform a 'null' conversion from SunAudio
+ to SunAudio.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.1, Next: Q5.3.2, Prev: Q5.2.4, Up: Miscellaneous
+
+5.3: Miscellaneous
+==================
+
+Q5.3.1: How do you make XEmacs indent CL if-clauses correctly?
+--------------------------------------------------------------
+
+ I'd like XEmacs to indent all the clauses of a Common Lisp `if' the
+same amount instead of indenting the 3rd clause differently from the
+first two.
+
+ One way is to add, to `.emacs':
+
+ (put 'if 'lisp-indent-function nil)
+
+ However, note that the package `cl-indent' that comes with XEmacs
+sets up this kind of indentation by default. `cl-indent' also knows
+about many other CL-specific forms. To use `cl-indent', one can do
+this:
+
+ (load "cl-indent")
+ (setq lisp-indent-function (function common-lisp-indent-function))
+
+ One can also customize `cl-indent.el' so it mimics the default `if'
+indentation `then' indented more than the `else'. Here's how:
+
+ (put 'if 'common-lisp-indent-function '(nil nil &body))
+
+ Also, a new version (1.2) of `cl-indent.el' was posted to
+comp.emacs.xemacs on 12/9/94. This version includes more documentation
+than previous versions. This may prove useful if you need to customize
+any indent-functions.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.2, Next: Q5.3.3, Prev: Q5.3.1, Up: Miscellaneous
+
+Q5.3.2: Fontifying hang when editing a postscript file.
+-------------------------------------------------------
+
+ When I try to edit a postscript file it gets stuck saying:
+`fontifying 'filename' (regexps....)' and it just sits there. If I
+press `C-c' in the window where XEmacs was started, it suddenly becomes
+alive again.
+
+ This was caused by a bug in the Postscript font-lock regular
+expressions. It was fixed in 19.13. For earlier versions of XEmacs,
+have a look at your `.emacs' file. You will probably have a line like:
+
+ (add-hook 'postscript-mode-hook 'turn-on-font-lock)
+
+ Take it out, restart XEmacs, and it won't try to fontify your
+postscript files anymore.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.3, Next: Q5.3.4, Prev: Q5.3.2, Up: Miscellaneous
+
+Q5.3.3: How can I print WYSIWYG a font-locked buffer?
+-----------------------------------------------------
+
+ Font-lock looks nice. How can I print (WYSIWYG) the highlighted
+document?
+
+ The package `ps-print', which is now included with XEmacs, provides
+the ability to do this. The source code contains complete instructions
+on its use, in `<xemacs_src_root>/lisp/packages/ps-print.el'.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.4, Next: Q5.3.5, Prev: Q5.3.3, Up: Miscellaneous
+
+Q5.3.4: Getting `M-x lpr' to work with postscript printer.
+----------------------------------------------------------
+
+ My printer is a Postscript printer and `lpr' only works for
+Postscript files, so how do I get `M-x lpr-region' and `M-x lpr-buffer'
+to work?
+
+ Put something like this in your `.emacs':
+
+ (setq lpr-command "a2ps")
+ (setq lpr-switches '("-p" "-1"))
+
+ If you don't use a2ps to convert ASCII to postscript (why not, it's
+free?), replace with the command you do use. Note also that some
+versions of a2ps require a `-Pprinter' to ensure spooling.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.5, Next: Q5.3.6, Prev: Q5.3.4, Up: Miscellaneous
+
+Q5.3.5: How do I specify the paths that XEmacs uses for finding files?
+----------------------------------------------------------------------
+
+ You can specify what paths to use by using a number of different
+flags when running configure. See the section MAKE VARIABLES in the
+top-level file INSTALL in the XEmacs distribution for a listing of
+those flags.
+
+ Most of the time, however, the simplest fix is: *do not* specify
+paths as you might for GNU Emacs. XEmacs can generally determine the
+necessary paths dynamically at run time. The only path that generally
+needs to be specified is the root directory to install into. That can
+be specified by passing the `--prefix' flag to configure. For a
+description of the XEmacs install tree, please consult the `NEWS' file.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.6, Next: Q5.3.7, Prev: Q5.3.5, Up: Miscellaneous
+
+Q5.3.6: [This question intentionally left blank]
+------------------------------------------------
+
+ Obsolete question, left blank to avoid renumbering.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.7, Next: Q5.3.8, Prev: Q5.3.6, Up: Miscellaneous
+
+Q5.3.7: Can I have the end of the buffer delimited in some way?
+---------------------------------------------------------------
+
+ Say, with: `[END]'?
+
+ Try this:
+
+ (let ((ext (make-extent (point-min) (point-max))))
+ (set-extent-property ext 'start-closed t)
+ (set-extent-property ext 'end-closed t)
+ (set-extent-property ext 'detachable nil)
+ (set-extent-end-glyph ext (make-glyph [string :data "[END]"])))
+
+ Since this is XEmacs, you can specify an icon to be shown on
+window-system devices. To do so, change the `make-glyph' call to
+something like this:
+
+ (make-glyph '([xpm :file "~/something.xpm"]
+ [string :data "[END]"]))
+
+ You can inline the XPM definition yourself by specifying `:data'
+instead of `:file'. Here is such a full-featured version that works on
+both X and TTY devices:
+
+ (let ((ext (make-extent (point-min) (point-max))))
+ (set-extent-property ext 'start-closed t)
+ (set-extent-property ext 'end-closed t)
+ (set-extent-property ext 'detachable nil)
+ (set-extent-end-glyph ext (make-glyph '([xpm :data "\
+ /* XPM */
+ static char* eye = {
+ \"20 11 7 2\",
+ \"__ c None\"
+ \"_` c #7f7f7f\",
+ \"_a c #fefefe\",
+ \"_b c #7f0000\",
+ \"_c c #fefe00\",
+ \"_d c #fe0000\",
+ \"_e c #bfbfbf\",
+ \"___________`_`_`___b_b_b_b_________`____\",
+ \"_________`_`_`___b_c_c_c_b_b____________\",
+ \"_____`_`_`_e___b_b_c_c_c___b___b_______`\",
+ \"___`_`_e_a___b_b_d___b___b___b___b______\",
+ \"_`_`_e_a_e___b_b_d_b___b___b___b___b____\",
+ \"_`_`_a_e_a___b_b_d___b___b___b___b___b__\",
+ \"_`_`_e_a_e___b_b_d_b___b___b___b___b_b__\",
+ \"___`_`_e_a___b_b_b_d_c___b___b___d_b____\",
+ \"_____`_`_e_e___b_b_b_d_c___b_b_d_b______\",
+ \"_`_____`_`_`_`___b_b_b_d_d_d_d_b________\",
+ \"___`_____`_`_`_`___b_b_b_b_b_b__________\",
+ } ;"]
+ [string :data "[END]"]))))
+
+ Note that you might want to make this a function, and put it to a
+hook. We leave that as an exercise for the reader.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.8, Next: Q5.3.9, Prev: Q5.3.7, Up: Miscellaneous
+
+Q5.3.8: How do I insert today's date into a buffer?
+---------------------------------------------------
+
+ Like this:
+
+ (insert (current-time-string))
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.9, Next: Q5.3.10, Prev: Q5.3.8, Up: Miscellaneous
+
+Q5.3.9: Are only certain syntactic character classes available for abbrevs?
+---------------------------------------------------------------------------
+
+ Markus Gutschke <gutschk@uni-muenster.de> writes:
+
+ Yes, abbrevs only expands word-syntax strings. While XEmacs does
+ not prevent you from defining (e.g. with `C-x a g' or `C-x a l')
+ abbrevs that contain special characters, it will refuse to expand
+ them. So you need to ensure, that the abbreviation contains
+ letters and digits only. This means that `xd', `d5', and `5d' are
+ valid abbrevs, but `&d', and `x d' are not.
+
+ If this sounds confusing to you, (re-)read the online
+ documentation for abbrevs (`C-h i m XEmacs <RET> m Abbrevs
+ <RET>'), and then come back and read this question/answer again.
+
+ Starting with XEmacs 20.3 this restriction has been lifted.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.10, Next: Q5.3.11, Prev: Q5.3.9, Up: Miscellaneous
+
+Q5.3.10: How can I get those oh-so-neat X-Face lines?
+-----------------------------------------------------
+
+ Firstly there is an ftp site which describes X-faces and has the
+associated tools mentioned below, at
+`ftp://ftp.cs.indiana.edu:/pub/faces/'.
+
+ Then the steps are
+
+ 1. Create 48x48x1 bitmap with your favorite tool
+
+ 2. Convert to "icon" format using one of xbm2ikon, pbmtoicon, etc.,
+ and then compile the face.
+
+ 3. cat file.xbm | xbm2ikon |compface > file.face
+
+ 4. Then be sure to quote things that are necessary for emacs strings:
+
+ cat ./file.face | sed 's/\\/\\\\/g'
+ | sed 's/\"/\\\"/g' > ./file.face.quoted
+
+ 5. Then set up emacs to include the file as a mail header - there
+ were a couple of suggestions here--either something like:
+
+ (setq mail-default-headers
+ "X-Face: <Ugly looking text string here>")
+
+ Or, alternatively, as:
+
+ (defun mail-insert-x-face ()
+ (save-excursion
+ (goto-char (point-min))
+ (search-forward mail-header-separator)
+ (beginning-of-line)
+ (insert "X-Face:")
+ (insert-file-contents "~/.face")))
+
+ (add-hook 'mail-setup-hook 'mail-insert-x-face)
+
+ However, 2 things might be wrong:
+
+ Some versions of pbmtoicon produces some header lines that is not
+expected by the version of compface that I grabbed. So I found I had to
+include a `tail +3' in the pipeline like this:
+
+ cat file.xbm | xbm2ikon | tail +3 |compface > file.face
+
+ Some people have also found that if one uses the `(insert-file)'
+method, one should NOT quote the face string using the sed script .
+
+ It might also be helpful to use Stig's <stig@hackvan.com> script
+(included in the compface distribution at XEmacs.org) to do the
+conversion. For convenience xbm2xface is available for anonymous FTP at
+`ftp://ftp.miranova.com/pub/xemacs/xbm2xface.pl'.
+
+ Contributors for this item:
+
+ Paul Emsley, Ricardo Marek, Amir J. Katz, Glen McCort, Heinz Uphoff,
+Peter Arius, Paul Harrison, and Vegard Vesterheim
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.11, Next: Q5.3.12, Prev: Q5.3.10, Up: Miscellaneous
+
+Q5.3.11: How do I add new Info directories?
+-------------------------------------------
+
+ You use something like:
+
+ (setq Info-directory-list (cons
+ (expand-file-name "~/info")
+ Info-default-directory-list))
+
+ David Masterson <davidm@prism.kla.com> writes:
+
+ Emacs Info and XEmacs Info do many things differently. If you're
+ trying to support a number of versions of Emacs, here are some
+ notes to remember:
+
+ 1. Emacs Info scans `Info-directory-list' from right-to-left
+ while XEmacs Info reads it from left-to-right, so append to
+ the *correct* end of the list.
+
+ 2. Use `Info-default-directory-list' to initialize
+ `Info-directory-list' *if* it is available at startup, but not
+ all Emacsen define it.
+
+ 3. Emacs Info looks for a standard `dir' file in each of the
+ directories scanned from #1 and magically concatenates them
+ together.
+
+ 4. XEmacs Info looks for a `localdir' file (which consists of
+ just the menu entries from a `dir' file) in each of the
+ directories scanned from #1 (except the first), does a simple
+ concatenation of them, and magically attaches the resulting
+ list to the end of the menu in the `dir' file in the first
+ directory.
+
+ Another alternative is to convert the documentation to HTML with
+ texi2html and read it from a web browser like Lynx or W3.
+
+\1f
+File: xemacs-faq.info, Node: Q5.3.12, Prev: Q5.3.11, Up: Miscellaneous
+
+Q5.3.12: What do I need to change to make printing work?
+--------------------------------------------------------
+
+ For regular printing there are two variables that can be customized.
+
+`lpr-command'
+ This should be set to a command that takes standard input and sends
+ it to a printer. Something like:
+
+ (setq lpr-command "lp")
+
+`lpr-switches'
+ This should be set to a list that contains whatever the print
+ command requires to do its job. Something like:
+
+ (setq lpr-switches '("-depson"))
+
+ For postscript printing there are three analogous variables to
+customize.
+
+`ps-lpr-command'
+ This should be set to a command that takes postscript on standard
+ input and directs it to a postscript printer.
+
+`ps-lpr-switches'
+ This should be set to a list of switches required for
+ `ps-lpr-command' to do its job.
+
+`ps-print-color-p'
+ This boolean variable should be set `t' if printing will be done in
+ color, otherwise it should be set to `nil'.
+
+ NOTE: It is an undocumented limitation in XEmacs that postscript
+printing (the `Pretty Print Buffer' menu item) *requires* a window
+system environment. It cannot be used outside of X11.
+
+\1f
+File: xemacs-faq.info, Node: Current Events, Prev: Miscellaneous, Up: Top
+
+6 What the Future Holds
+***********************
+
+ This is part 6 of the XEmacs Frequently Asked Questions list. This
+section will change monthly, and contains any interesting items that
+have transpired over the previous month. If you are reading this from
+the XEmacs distribution, please see the version on the Web or archived
+at the various FAQ FTP sites, as this file is surely out of date.
+
+* Menu:
+
+* Q6.0.1:: What is new in 20.2?
+* Q6.0.2:: What is new in 20.3?
+* Q6.0.3:: What is new in 20.4?
+* Q6.0.4:: Procedural changes in XEmacs development.
+
+\1f
+File: xemacs-faq.info, Node: Q6.0.1, Next: Q6.0.2, Prev: Current Events, Up: Current Events
+
+6.0: Changes
+============
+
+Q6.0.1: What is new in 20.2?
+----------------------------
+
+ The biggest changes in 20.2 include integration of EFS (the next
+generation of ange-ftp) and AUC Tex (the Emacs subsystem that includes a
+major mode for editing Tex and LaTeX, and a lot of other stuff). Many
+bugs from 20.0 have been fixed for this release. 20.2 also contains a
+new system for customizing XEmacs options, invoked via `M-x customize'.
+
+ XEmacs 20.2 is the development release (20.0 was beta), and is no
+longer considered unstable.
+
+\1f
+File: xemacs-faq.info, Node: Q6.0.2, Next: Q6.0.3, Prev: Q6.0.1, Up: Current Events
+
+Q6.0.2: What is new in 20.3?
+----------------------------
+
+ XEmacs 20.3 was released in November 1997. It contains many bugfixes,
+and a number of new features, including Autoconf 2 based configuration,
+additional support for Mule (Multi-language extensions to Emacs), many
+more customizations, multiple frames on TTY-s, support for multiple info
+directories, an enhanced gnuclient, improvements to regexp matching,
+increased MIME support, and many, many synches with GNU Emacs 20.
+
+ The XEmacs/Mule support has been only seriously tested in a Japanese
+locale, and no doubt many problems still remain. The support for
+ISO-Latin-1 and Japanese is fairly strong. MULE support comes at a
+price - about a 30% slowdown from 19.16. We're making progress on
+improving performance and XEmacs 20.3 compiled without Mule (which is
+the default) is definitely faster than XEmacs 19.16.
+
+ XEmacs 20.3 is the first non-beta v20 release, and will be the basis
+for all further development.
+
+\1f
+File: xemacs-faq.info, Node: Q6.0.3, Next: Q6.0.4, Prev: Q6.0.2, Up: Current Events
+
+Q6.0.3: What's new in XEmacs 20.4?
+----------------------------------
+
+ XEmacs 20.4 is a bugfix release with no user-visible changes.
+
+\1f
+File: xemacs-faq.info, Node: Q6.0.4, Prev: Q6.0.3, Up: Current Events
+
+Q6.0.4: Procedural changes in XEmacs development.
+-------------------------------------------------
+
+ 1. Discussion about the development of XEmacs occurs on the
+ xemacs-beta mailing list. Subscriptions to this list will now be
+ fully automated instead of being handled by hand. Send a mail
+ message to <xemacs-beta-request@xemacs.org> with `subscribe' as the
+ BODY of the message to join the list. Please note this is a
+ developers mailing list for people who have an active interest in
+ the development process.
+
+ The discussion of NT XEmacs development is taking place on a
+ separate mailing list. Send mail to
+ <xemacs-nt-request@xemacs.org> to subscribe.
+
+ 2. Due to the long development cycle in between releases, it has been
+ decided that intermediate versions will be made available in
+ source only form for the truly interested.
+
+ XEmacs 19.16 was the last 19 release, basically consisting of
+ 19.15 plus the collected bugfixes.
+
+ 3. As of December 1996, Steve Baur <steve@altair.xemacs.org> has
+ become the lead maintainer of XEmacs.
+
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+Indirect:
+xemacs.info-1: 1372
+xemacs.info-2: 47958
+xemacs.info-3: 95918
+xemacs.info-4: 144030
+xemacs.info-5: 192248
+xemacs.info-6: 241615
+xemacs.info-7: 290442
+xemacs.info-8: 339995
+xemacs.info-9: 385290
+xemacs.info-10: 433122
+xemacs.info-11: 482303
+xemacs.info-12: 528200
+xemacs.info-13: 577026
+xemacs.info-14: 625173
+xemacs.info-15: 673936
+xemacs.info-16: 723464
+xemacs.info-17: 772031
+xemacs.info-18: 815954
+xemacs.info-19: 857130
+xemacs.info-20: 905126
+xemacs.info-21: 945846
+\1f
+Tag Table:
+(Indirect)
+Node: Top\7f1372
+Node: License\7f22524
+Node: Distrib\7f35806
+Node: Intro\7f37470
+Node: Frame\7f40341
+Node: Point\7f43613
+Node: Echo Area\7f45580
+Node: Mode Line\7f47958
+Node: XEmacs under X\7f52389
+Node: Keystrokes\7f55567
+Node: Intro to Keystrokes\7f56411
+Node: Representing Keystrokes\7f58514
+Node: Key Sequences\7f59871
+Node: String Key Sequences\7f63211
+Node: Meta Key\7f63594
+Node: Super and Hyper Keys\7f65067
+Node: Character Representation\7f71291
+Node: Commands\7f72311
+Node: Pull-down Menus\7f75160
+Node: File Menu\7f78509
+Node: Edit Menu\7f82331
+Node: Apps Menu\7f84716
+Node: Options Menu\7f85206
+Node: Buffers Menu\7f89186
+Node: Tools Menu\7f89493
+Node: Help Menu\7f89984
+Node: Menu Customization\7f90385
+Node: Entering Emacs\7f94615
+Node: Exiting\7f95918
+Node: Command Switches\7f99010
+Node: Startup Paths\7f108199
+Node: Basic\7f115775
+Node: Blank Lines\7f125258
+Node: Continuation Lines\7f126684
+Node: Position Info\7f128118
+Node: Arguments\7f131252
+Node: Undo\7f134389
+Node: Minibuffer\7f137336
+Node: Minibuffer File\7f139820
+Node: Minibuffer Edit\7f141457
+Node: Completion\7f144030
+Node: Repetition\7f150905
+Node: M-x\7f153697
+Node: Help\7f158791
+Node: Mark\7f168713
+Node: Setting Mark\7f170567
+Node: Using Region\7f173689
+Node: Marking Objects\7f174434
+Node: Mark Ring\7f176275
+Node: Mouse Selection\7f177991
+Node: Additional Mouse Operations\7f179999
+Node: Killing\7f184203
+Node: Yanking\7f189843
+Node: Kill Ring\7f190646
+Node: Appending Kills\7f192248
+Node: Earlier Kills\7f194285
+Node: Using X Selections\7f196898
+Node: X Clipboard Selection\7f198148
+Node: X Selection Commands\7f200325
+Node: X Cut Buffers\7f201411
+Node: Active Regions\7f202770
+Node: Accumulating Text\7f207350
+Node: Rectangles\7f210423
+Node: Registers\7f213942
+Node: RegPos\7f214977
+Node: RegText\7f215880
+Node: RegRect\7f216964
+Node: Display\7f217704
+Node: Scrolling\7f219199
+Node: Horizontal Scrolling\7f223342
+Node: Selective Display\7f224538
+Node: Display Vars\7f225757
+Node: Search\7f228435
+Node: Incremental Search\7f229628
+Node: Non-Incremental Search\7f238555
+Node: Word Search\7f239997
+Node: Regexp Search\7f241615
+Node: Regexps\7f243151
+Node: Search Case\7f253452
+Node: Replace\7f254233
+Node: Unconditional Replace\7f255181
+Node: Regexp Replace\7f256317
+Node: Replacement and Case\7f257252
+Node: Query Replace\7f258232
+Node: Other Repeating Search\7f261465
+Node: Fixit\7f262720
+Node: Kill Errors\7f263300
+Node: Transpose\7f264633
+Node: Fixing Case\7f267038
+Node: Spelling\7f267684
+Node: Files\7f269145
+Node: File Names\7f270453
+Node: Visiting\7f274791
+Node: Saving\7f281481
+Node: Backup\7f286404
+Node: Backup Names\7f287800
+Node: Backup Deletion\7f289283
+Node: Backup Copying\7f290442
+Node: Interlocking\7f292149
+Node: Reverting\7f296277
+Node: Auto Save\7f298190
+Node: Auto Save Files\7f299157
+Node: Auto Save Control\7f300998
+Node: Recover\7f302837
+Node: Version Control\7f303992
+Node: Concepts of VC\7f306030
+Node: Editing with VC\7f307640
+Node: Variables for Check-in/out\7f312896
+Node: Log Entries\7f314795
+Node: Change Logs and VC\7f315975
+Node: Old Versions\7f319243
+Node: VC Status\7f321247
+Node: Renaming and VC\7f322961
+Node: Snapshots\7f323642
+Node: Making Snapshots\7f324143
+Node: Snapshot Caveats\7f325437
+Node: Version Headers\7f327246
+Node: ListDir\7f329945
+Node: Comparing Files\7f331994
+Node: Dired\7f333527
+Node: Dired Enter\7f334198
+Node: Dired Edit\7f335023
+Node: Dired Deletion\7f336770
+Node: Dired Immed\7f339995
+Node: Misc File Ops\7f341271
+Node: Buffers\7f343760
+Node: Select Buffer\7f345920
+Node: List Buffers\7f347717
+Node: Misc Buffer\7f349463
+Node: Kill Buffer\7f351107
+Node: Several Buffers\7f352237
+Node: Windows\7f356103
+Node: Basic Window\7f356814
+Node: Split Window\7f358533
+Node: Other Window\7f360666
+Node: Pop Up Window\7f363096
+Node: Change Window\7f364603
+Node: Mule\7f367511
+Node: Mule Intro\7f368774
+Node: Language Environments\7f369790
+Node: Input Methods\7f371898
+Node: Select Input Method\7f375618
+Node: Coding Systems\7f377773
+Node: Recognize Coding\7f381961
+Node: Specify Coding\7f385290
+Node: Major Modes\7f390221
+Node: Choosing Modes\7f392443
+Node: Indentation\7f394833
+Node: Indentation Commands\7f396928
+Node: Tab Stops\7f399657
+Node: Just Spaces\7f401506
+Node: Text\7f402321
+Node: Text Mode\7f404304
+Node: Nroff Mode\7f406385
+Node: TeX Mode\7f408029
+Node: TeX Editing\7f410281
+Node: TeX Print\7f413716
+Node: Outline Mode\7f416936
+Node: Outline Format\7f418417
+Node: Outline Motion\7f421217
+Node: Outline Visibility\7f422770
+Node: Words\7f425691
+Node: Sentences\7f428638
+Node: Paragraphs\7f430834
+Node: Pages\7f433122
+Node: Filling\7f435722
+Node: Auto Fill\7f436293
+Node: Fill Commands\7f438441
+Node: Fill Prefix\7f440607
+Node: Case\7f442795
+Node: Programs\7f444823
+Node: Program Modes\7f447381
+Node: Lists\7f449613
+Node: Defuns\7f455453
+Node: Grinding\7f458106
+Node: Basic Indent\7f458734
+Node: Multi-line Indent\7f460755
+Node: Lisp Indent\7f462371
+Node: C Indent\7f465821
+Node: Matching\7f471061
+Node: Comments\7f472583
+Node: Balanced Editing\7f479035
+Node: Lisp Completion\7f480049
+Node: Documentation\7f481064
+Node: Change Log\7f482303
+Node: Tags\7f484881
+Node: Tag Syntax\7f486458
+Node: Create Tags Table\7f489832
+Node: Select Tags Table\7f495930
+Node: Find Tag\7f499672
+Node: Tags Search\7f502636
+Node: List Tags\7f506093
+Node: Fortran\7f507122
+Node: Fortran Motion\7f508198
+Node: Fortran Indent\7f509018
+Node: ForIndent Commands\7f509703
+Node: ForIndent Num\7f510848
+Node: ForIndent Conv\7f512122
+Node: ForIndent Vars\7f512898
+Node: Fortran Comments\7f514066
+Node: Fortran Columns\7f517665
+Node: Fortran Abbrev\7f519088
+Node: Asm Mode\7f519998
+Node: Running\7f520550
+Node: Compilation\7f521520
+Node: Lisp Modes\7f526371
+Node: Lisp Libraries\7f527645
+Node: Loading\7f528200
+Node: Compiling Libraries\7f532660
+Node: Mocklisp\7f535551
+Node: Lisp Eval\7f536228
+Node: Lisp Debug\7f539868
+Node: Lisp Interaction\7f545294
+Node: External Lisp\7f546649
+Node: Packages\7f548724
+Node: Package Terminology\7f549465
+Node: Using Packages\7f550823
+Node: Building Packages\7f559612
+Node: Abbrevs\7f562134
+Node: Defining Abbrevs\7f564334
+Node: Expanding Abbrevs\7f566781
+Node: Editing Abbrevs\7f569483
+Node: Saving Abbrevs\7f571351
+Node: Dynamic Abbrevs\7f573291
+Node: Picture\7f574593
+Node: Basic Picture\7f577026
+Node: Insert in Picture\7f579313
+Node: Tabs in Picture\7f580735
+Node: Rectangles in Picture\7f582256
+Node: Sending Mail\7f584165
+Node: Mail Format\7f585876
+Node: Mail Headers\7f587226
+Node: Mail Mode\7f593636
+Node: Reading Mail\7f597249
+Node: Calendar/Diary\7f598824
+Node: Calendar Motion\7f600496
+Node: Calendar Unit Motion\7f601379
+Node: Move to Beginning or End\7f603702
+Node: Specified Dates\7f604835
+Node: Scroll Calendar\7f605724
+Node: Mark and Region\7f607515
+Node: General Calendar\7f609422
+Node: LaTeX Calendar\7f611030
+Node: Holidays\7f613044
+Node: Sunrise/Sunset\7f616147
+Node: Lunar Phases\7f619190
+Node: Other Calendars\7f620575
+Node: Calendar Systems\7f622062
+Node: To Other Calendar\7f625173
+Node: From Other Calendar\7f627164
+Node: Mayan Calendar\7f629470
+Node: Diary\7f632666
+Node: Diary Commands\7f634416
+Node: Format of Diary File\7f637725
+Node: Date Formats\7f640595
+Node: Adding to Diary\7f643169
+Node: Special Diary Entries\7f644800
+Node: Calendar Customization\7f650140
+Node: Calendar Customizing\7f651002
+Node: Holiday Customizing\7f654222
+Node: Date Display Format\7f660690
+Node: Time Display Format\7f661648
+Node: Daylight Savings\7f662786
+Node: Diary Customizing\7f665974
+Node: Hebrew/Islamic Entries\7f670596
+Node: Fancy Diary Display\7f673936
+Node: Included Diary Files\7f675833
+Node: Sexp Diary Entries\7f676814
+Node: Appt Customizing\7f681904
+Node: Sorting\7f682950
+Node: Shell\7f687756
+Node: Single Shell\7f689049
+Node: Interactive Shell\7f690648
+Node: Shell Mode\7f694413
+Node: Terminal emulator\7f696904
+Node: Term Mode\7f699214
+Node: Paging in Term\7f700128
+Node: Narrowing\7f700926
+Node: Hardcopy\7f702876
+Node: Recursive Edit\7f703848
+Node: Dissociated Press\7f706835
+Node: CONX\7f709398
+Node: Amusements\7f710422
+Node: Emulation\7f710902
+Node: Customization\7f712746
+Node: Minor Modes\7f714470
+Node: Variables\7f716102
+Node: Examining\7f718060
+Node: Easy Customization\7f719521
+Node: Customization Groups\7f720535
+Node: Changing an Option\7f723464
+Node: Face Customization\7f729720
+Node: Specific Customization\7f731485
+Node: Edit Options\7f734092
+Node: Locals\7f735676
+Node: File Variables\7f738855
+Node: Keyboard Macros\7f743382
+Node: Basic Kbd Macro\7f745553
+Node: Save Kbd Macro\7f747485
+Node: Kbd Macro Query\7f749157
+Node: Key Bindings\7f751099
+Node: Keymaps\7f751973
+Node: Rebinding\7f755823
+Node: Interactive Rebinding\7f756519
+Node: Programmatic Rebinding\7f758711
+Node: Key Bindings Using Strings\7f761518
+Node: Disabling\7f763124
+Node: Syntax\7f764896
+Node: Syntax Entry\7f765777
+Node: Syntax Change\7f769861
+Node: Init File\7f772031
+Node: Init Syntax\7f773539
+Node: Init Examples\7f775892
+Node: Terminal Init\7f780083
+Node: Audible Bell\7f781793
+Node: Faces\7f785224
+Node: X Resources\7f790061
+Node: Geometry Resources\7f791682
+Node: Iconic Resources\7f794130
+Node: Resource List\7f794602
+Node: Face Resources\7f801109
+Node: Widgets\7f804786
+Node: Menubar Resources\7f805725
+Node: Quitting\7f806658
+Node: Lossage\7f809637
+Node: Stuck Recursive\7f810280
+Node: Screen Garbled\7f810986
+Node: Text Garbled\7f812120
+Node: Unasked-for Search\7f812759
+Node: Emergency Escape\7f813544
+Node: Total Frustration\7f815323
+Node: Bugs\7f815954
+Node: Glossary\7f825489
+Node: Manifesto\7f857130
+Node: Key Index\7f880606
+Node: Command Index\7f905126
+Node: Variable Index\7f945846
+Node: Concept Index\7f961797
+\1f
+End Tag Table
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Top, Next: License, Up: (dir)
+
+ The XEmacs Editor *****************
+
+ XEmacs is the extensible, customizable, self-documenting real-time
+display editor. This Info file describes how to edit with Emacs and
+some of how to customize it, but not how to extend it. It corresponds
+to XEmacs version 21.0.
+
+ This manual is intended as a detailed reference to XEmacs. If you
+are looking for an introductory manual, see the New User's Guide.
+
+* Menu:
+
+* License:: The GNU General Public License gives you permission
+ to redistribute XEmacs on certain terms; and also
+ explains that there is no warranty.
+* Distrib:: How to get XEmacs.
+* Intro:: An introduction to XEmacs concepts.
+* Glossary:: The glossary.
+* Manifesto:: What's GNU? Gnu's Not Unix!
+
+Indices, nodes containing large menus
+* Key Index:: An item for each standard XEmacs key sequence.
+* Command Index:: An item for each command name.
+* Variable Index:: An item for each documented variable.
+* Concept Index:: An item for each concept.
+
+Important General Concepts
+* Frame:: How to interpret what you see on the screen.
+* Keystrokes:: Keyboard gestures XEmacs recognizes.
+* Pull-down Menus::
+ The XEmacs Pull-down Menus available under X.
+* Entering Emacs::
+ Starting Emacs from the shell.
+* Exiting:: Stopping or killing XEmacs.
+* Command Switches::
+ Hairy startup options.
+* Startup Paths::
+ How XEmacs finds Directories and Files
+
+Fundamental Editing Commands
+* Basic:: The most basic editing commands.
+* Undo:: Undoing recently made changes in the text.
+* Minibuffer:: Entering arguments that are prompted for.
+* M-x:: Invoking commands by their names.
+* Help:: Commands for asking XEmacs about its commands.
+
+Important Text-Changing Commands
+* Mark:: The mark: how to delimit a "region" of text.
+* Mouse Selection::
+ Selecting text with the mouse.
+* Additional Mouse Operations::
+ Other operations available from the mouse.
+* Killing:: Killing text.
+* Yanking:: Recovering killed text. Moving text.
+* Using X Selections::
+ Using primary selection, cut buffers, and highlighted regions.
+* Accumulating Text::
+ Other ways of copying text.
+* Rectangles:: Operating on the text inside a rectangle on the screen.
+* Registers:: Saving a text string or a location in the buffer.
+* Display:: Controlling what text is displayed.
+* Search:: Finding or replacing occurrences of a string.
+* Fixit:: Commands especially useful for fixing typos.
+
+Larger Units of Text
+* Files:: All about handling files.
+* Buffers:: Multiple buffers; editing several files at once.
+* Windows:: Viewing two pieces of text at once.
+* Mule:: Using world scripts.
+
+Advanced Features
+* Major Modes:: Text mode vs. Lisp mode vs. C mode ...
+* Indentation:: Editing the white space at the beginnings of lines.
+* Text:: Commands and modes for editing English.
+* Programs:: Commands and modes for editing programs.
+* Running:: Compiling, running and debugging programs.
+* Packages:: How to add new packages to XEmacs.
+* Abbrevs:: How to define text abbreviations to reduce
+ the number of characters you must type.
+* Picture:: Editing pictures made up of characters
+ using the quarter-plane screen model.
+* Sending Mail:: Sending mail in XEmacs.
+* Reading Mail:: Reading mail in XEmacs.
+* Calendar/Diary:: A Calendar and diary facility in XEmacs.
+* Sorting:: Sorting lines, paragraphs or pages within XEmacs.
+* Shell:: Executing shell commands from XEmacs.
+* Narrowing:: Restricting display and editing to a portion
+ of the buffer.
+* Hardcopy:: Printing buffers or regions.
+* Recursive Edit::
+ A command can allow you to do editing
+ "within the command". This is called a
+ `recursive editing level'.
+* Dissociated Press:: Dissociating text for fun.
+* CONX:: A different kind of dissociation.
+* Amusements:: Various games and hacks.
+* Emulation:: Emulating some other editors with XEmacs.
+* Customization:: Modifying the behavior of XEmacs.
+
+Recovery from Problems.
+* Quitting:: Quitting and aborting.
+* Lossage:: What to do if XEmacs is hung or malfunctioning.
+* Bugs:: How and when to report a bug.
+
+Here are some other nodes which are really inferiors of the ones
+already listed, mentioned here so you can get to them in one step:
+
+ -- The Detailed Node Listing --
+
+The Organization of the Frame
+
+* Point:: The place in the text where editing commands operate.
+* Echo Area:: Short messages appear at the bottom of the frame.
+* Mode Line:: Interpreting the mode line.
+* XEmacs under X:: Some information on using XEmacs under the X
+ Window System.
+
+Keystrokes
+
+* Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
+* Representing Keystrokes:: Using lists of modifiers and keysyms to
+ represent keystrokes.
+* Key Sequences:: Combine key strokes into key sequences you can
+ bind to commands.
+* String Key Sequences:: Available for upward compatibility.
+* Meta Key:: Using <ESC> to represent <Meta>
+* Super and Hyper Keys:: Adding modifier keys on certain keyboards.
+* Character Representation:: How characters appear in XEmacs buffers.
+* Commands:: How commands are bound to key sequences.
+
+Pull-down Menus
+
+* File Menu:: Items on the File menu.
+* Edit Menu:: Items on the Edit menu.
+* Apps Menu:: Items on the Apps menu.
+* Options Menu:: Items on the Options menu.
+* Buffers Menu:: Information about the Buffers menu.
+* Tools Menu:: Items on the Tools menu.
+* Help Menu:: Items on the Help menu.
+* Menu Customization:: Adding and removing menu items and related
+ operations.
+
+Basic Editing Commands
+
+* Blank Lines:: Commands to make or delete blank lines.
+* Continuation Lines:: Lines too wide for the frame.
+* Position Info:: What page, line, row, or column is point on?
+* Arguments:: Numeric arguments for repeating a command.
+
+The Minibuffer
+
+* File: Minibuffer File. Entering file names with the minibuffer.
+* Edit: Minibuffer Edit. How to edit in the minibuffer.
+* Completion:: An abbreviation facility for minibuffer input.
+* Repetition:: Re-executing commands that used the minibuffer.
+
+The Mark and the Region
+
+* Setting Mark:: Commands to set the mark.
+* Using Region:: Summary of ways to operate on contents of the region.
+* Marking Objects:: Commands to put region around textual units.
+* Mark Ring:: Previous mark positions saved so you can go back there.
+
+Yanking
+
+* Kill Ring:: Where killed text is stored. Basic yanking.
+* Appending Kills:: Several kills in a row all yank together.
+* Earlier Kills:: Yanking something killed some time ago.
+
+Using X Selections
+
+* X Clipboard Selection:: Pasting to the X clipboard.
+* X Selection Commands:: Other operations on the selection.
+* X Cut Buffers:: X cut buffers are available for compatibility.
+* Active Regions:: Using zmacs-style highlighting of the
+ selected region.
+
+Registers
+
+* RegPos:: Saving positions in registers.
+* RegText:: Saving text in registers.
+* RegRect:: Saving rectangles in registers.
+
+Controlling the Display
+
+* Scrolling:: Moving text up and down in a window.
+* Horizontal Scrolling:: Moving text left and right in a window.
+* Selective Display:: Hiding lines with lots of indentation.
+* Display Vars:: Information on variables for customizing display.
+
+Searching and Replacement
+
+* Incremental Search:: Search happens as you type the string.
+* Non-Incremental Search:: Specify entire string and then search.
+* Word Search:: Search for sequence of words.
+* Regexp Search:: Search for match for a regexp.
+* Regexps:: Syntax of regular expressions.
+* Search Case:: To ignore case while searching, or not.
+* Replace:: Search, and replace some or all matches.
+* Other Repeating Search:: Operating on all matches for some regexp.
+
+Replacement Commands
+
+* Unconditional Replace:: Replacing all matches for a string.
+* Regexp Replace:: Replacing all matches for a regexp.
+* Replacement and Case:: How replacements preserve case of letters.
+* Query Replace:: How to use querying.
+
+Commands for Fixing Typos
+
+* Kill Errors:: Commands to kill a batch of recently entered text.
+* Transpose:: Exchanging two characters, words, lines, lists...
+* Fixing Case:: Correcting case of last word entered.
+* Spelling:: Apply spelling checker to a word, or a whole file.
+
+File Handling
+
+* File Names:: How to type and edit file name arguments.
+* Visiting:: Visiting a file prepares XEmacs to edit the file.
+* Saving:: Saving makes your changes permanent.
+* Reverting:: Reverting cancels all the changes not saved.
+* Auto Save:: Auto Save periodically protects against loss of data.
+* Version Control:: Version control systems (RCS and SCCS).
+* ListDir:: Listing the contents of a file directory.
+* Comparing Files:: Finding where two files differ.
+* Dired:: "Editing" a directory to delete, rename, etc.
+ the files in it.
+* Misc File Ops:: Other things you can do on files.
+
+Saving Files
+
+* Backup:: How XEmacs saves the old version of your file.
+* Interlocking:: How XEmacs protects against simultaneous editing
+ of one file by two users.
+
+Backup Files
+
+* Names: Backup Names. How backup files are named;
+ Choosing single or numbered backup files.
+* Deletion: Backup Deletion. XEmacs deletes excess numbered backups.
+* Copying: Backup Copying. Backups can be made by copying or renaming.
+
+Auto-Saving: Protection Against Disasters
+
+* Files: Auto Save Files.
+* Control: Auto Save Control.
+* Recover:: Recovering text from auto-save files.
+
+Version Control
+
+* Concepts of VC:: Basic version control information;
+ checking files in and out.
+* Editing with VC:: Commands for editing a file maintained
+ with version control.
+* Variables for Check-in/out:: Variables that affect the commands used
+ to check files in or out.
+* Log Entries:: Logging your changes.
+* Change Logs and VC:: Generating a change log file from log
+ entries.
+* Old Versions:: Examining and comparing old versions.
+* VC Status:: Commands to view the VC status of files and
+ look at log entries.
+* Renaming and VC:: A command to rename both the source and
+ master file correctly.
+* Snapshots:: How to make and use snapshots, a set of
+ file versions that can be treated as a unit.
+* Version Headers:: Inserting version control headers into
+ working files.
+
+Snapshots
+
+* Making Snapshots:: The snapshot facilities.
+* Snapshot Caveats:: Things to be careful of when using snapshots.
+
+Dired, the Directory Editor
+
+* Enter: Dired Enter. How to invoke Dired.
+* Edit: Dired Edit. Editing the Dired buffer.
+* Deletion: Dired Deletion. Deleting files with Dired.
+* Immed: Dired Immed. Other file operations through Dired.
+
+Using Multiple Buffers
+
+* Select Buffer:: Creating a new buffer or reselecting an old one.
+* List Buffers:: Getting a list of buffers that exist.
+* Misc Buffer:: Renaming; changing read-onliness; copying text.
+* Kill Buffer:: Killing buffers you no longer need.
+* Several Buffers:: How to go through the list of all buffers
+ and operate variously on several of them.
+
+Multiple Windows
+
+* Basic Window:: Introduction to XEmacs windows.
+* Split Window:: New windows are made by splitting existing windows.
+* Other Window:: Moving to another window or doing something to it.
+* Pop Up Window:: Finding a file or buffer in another window.
+* Change Window:: Deleting windows and changing their sizes.
+
+Major Modes
+
+* Choosing Modes:: How major modes are specified or chosen.
+
+Indentation
+
+* Indentation Commands:: Various commands and techniques for indentation.
+* Tab Stops:: You can set arbitrary "tab stops" and then
+ indent to the next tab stop when you want to.
+* Just Spaces:: You can request indentation using just spaces.
+
+Commands for Human Languages
+
+* Text Mode:: The major modes for editing text files.
+* Nroff Mode:: The major mode for editing input to the formatter nroff.
+* TeX Mode:: The major modes for editing input to the formatter TeX.
+* Outline Mode:: The major mode for editing outlines.
+* Words:: Moving over and killing words.
+* Sentences:: Moving over and killing sentences.
+* Paragraphs:: Moving over paragraphs.
+* Pages:: Moving over pages.
+* Filling:: Filling or justifying text
+* Case:: Changing the case of text
+
+TeX Mode
+
+* Editing: TeX Editing. Special commands for editing in TeX mode.
+* Printing: TeX Print. Commands for printing part of a file with TeX.
+
+Outline Mode
+
+* Format: Outline Format. What the text of an outline looks like.
+* Motion: Outline Motion. Special commands for moving through outlines.
+* Visibility: Outline Visibility. Commands to control what is visible.
+
+Filling Text
+
+* Auto Fill:: Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix:: Filling when every line is indented or in a comment, etc.
+
+Editing Programs
+
+* Program Modes:: Major modes for editing programs.
+* Lists:: Expressions with balanced parentheses.
+ There are editing commands to operate on them.
+* Defuns:: Each program is made up of separate functions.
+ There are editing commands to operate on them.
+* Grinding:: Adjusting indentation to show the nesting.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+* Comments:: Inserting, filling and aligning comments.
+* Balanced Editing:: Inserting two matching parentheses at once, etc.
+* Lisp Completion:: Completion on symbol names in Lisp code.
+* Documentation:: Getting documentation of functions you plan to call.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go directly to any function in your program in one
+ command. Tags remembers which file it is in.
+* Fortran:: Fortran mode and its special features.
+* Asm Mode:: Asm mode and its special features.
+
+Indentation for Programs
+
+* Basic Indent::
+* Multi-line Indent:: Commands to reindent many lines at once.
+* Lisp Indent:: Specifying how each Lisp function should be indented.
+* C Indent:: Choosing an indentation style for C code.
+
+Tags Tables
+
+* Tag Syntax:: Tag syntax for various types of code and text files.
+* Create Tags Table:: Creating a tags table with `etags'.
+* Select Tags Table:: How to visit a tags table.
+* Find Tag:: Commands to find the definition of a specific tag.
+* Tags Search:: Using a tags table for searching and replacing.
+* List Tags:: Listing and finding tags defined in a file.
+
+Fortran Mode
+
+* Motion: Fortran Motion. Moving point by statements or subprograms.
+* Indent: Fortran Indent. Indentation commands for Fortran.
+* Comments: Fortran Comments. Inserting and aligning comments.
+* Columns: Fortran Columns. Measuring columns for valid Fortran.
+* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
+
+Fortran Indentation
+
+* Commands: ForIndent Commands. Commands for indenting Fortran.
+* Numbers: ForIndent Num. How line numbers auto-indent.
+* Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
+* Vars: ForIndent Vars. Variables controlling Fortran indent style.
+
+Compiling and Testing Programs
+
+* Compilation:: Compiling programs in languages other than Lisp
+ (C, Pascal, etc.)
+* Modes: Lisp Modes. Various modes for editing Lisp programs, with
+ different facilities for running the Lisp programs.
+* Libraries: Lisp Libraries. Creating Lisp programs to run in XEmacs.
+* Eval: Lisp Eval. Executing a single Lisp expression in XEmacs.
+* Debug: Lisp Debug. Debugging Lisp programs running in XEmacs.
+* Interaction: Lisp Interaction. Executing Lisp in an XEmacs buffer.
+* External Lisp:: Communicating through XEmacs with a separate Lisp.
+
+Lisp Libraries
+
+* Loading:: Loading libraries of Lisp code into XEmacs for use.
+* Compiling Libraries:: Compiling a library makes it load and run faster.
+* Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
+
+Packages
+
+* Packages:: Introduction to XEmacs Packages.
+* Package Terminology:: Understanding different kinds of packages.
+* Using Packages:: How to install and use packages.
+* Building Packages:: Building packages from sources.
+
+Abbrevs
+
+* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
+* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
+* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
+* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
+* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
+
+Editing Pictures
+
+* Basic Picture:: Basic concepts and simple commands of Picture Mode.
+* Insert in Picture:: Controlling direction of cursor motion
+ after "self-inserting" characters.
+* Tabs in Picture:: Various features for tab stops and indentation.
+* Rectangles in Picture:: Clearing and superimposing rectangles.
+
+Sending Mail
+
+* Format: Mail Format. Format of the mail being composed.
+* Headers: Mail Headers. Details of allowed mail header fields.
+* Mode: Mail Mode. Special commands for editing mail being composed.
+
+Running Shell Commands from XEmacs
+
+* Single Shell:: How to run one shell command and return.
+* Interactive Shell:: Permanent shell taking input via XEmacs.
+* Shell Mode:: Special XEmacs commands used with permanent shell.
+
+Customization
+
+* Minor Modes:: Each minor mode is one feature you can turn on
+ independently of any others.
+* Variables:: Many XEmacs commands examine XEmacs variables
+ to decide what to do; by setting variables,
+ you can control their functioning.
+* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
+ to be replayed with a single command.
+* Key Bindings:: The keymaps say what command each key runs.
+ By changing them, you can "redefine keys".
+* Syntax:: The syntax table controls how words and expressions
+ are parsed.
+* Init File:: How to write common customizations in the `.emacs'
+ file.
+* Audible Bell:: Changing how XEmacs sounds the bell.
+* Faces:: Changing the fonts and colors of a region of text.
+* X Resources:: X resources controlling various aspects of the
+ behavior of XEmacs.
+
+Variables
+
+* Examining:: Examining or setting one variable's value.
+* Easy Customization:: Convenient and easy customization of variables.
+* Edit Options:: Examining or editing list of all variables' values.
+* Locals:: Per-buffer values of variables.
+* File Variables:: How files can specify variable values.
+
+Keyboard Macros
+
+* 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.
+
+Customizing Key Bindings
+
+* Keymaps:: Definition of the keymap data structure.
+ Names of XEmacs's standard keymaps.
+* Rebinding:: How to redefine one key's meaning conveniently.
+* Disabling:: Disabling a command means confirmation is required
+ before it can be executed. This is done to protect
+ beginners from surprises.
+
+The Syntax Table
+
+* Entry: Syntax Entry. What the syntax table records for each character.
+* Change: Syntax Change. How to change the information.
+
+The Init File, `~/.emacs'
+
+* Init Syntax:: Syntax of constants in Emacs Lisp.
+* Init Examples:: How to do some things with an init file.
+* Terminal Init:: Each terminal type can have an init file.
+
+Dealing with XEmacs Trouble
+
+* Stuck Recursive:: `[...]' in mode line around the parentheses.
+* Screen Garbled:: Garbage on the screen.
+* Text Garbled:: Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Emergency Escape:: Emergency escape--
+ What to do if XEmacs stops responding.
+* Total Frustration:: When you are at your wits' end.
+
+\1f
+File: xemacs.info, Node: License, Next: Distrib, Prev: Top, Up: Top
+
+GNU GENERAL PUBLIC LICENSE
+**************************
+
+ Version 1, February 1989
+
+ Copyright (C) 1989 Free Software Foundation, Inc.
+ 675 Mass Ave, Cambridge, MA 02139, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+Preamble
+========
+
+ The license agreements of most software companies try to keep users
+at the mercy of those companies. By contrast, our General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. The
+General Public License applies to the Free Software Foundation's
+software and to any other program whose authors commit to using it.
+You can use it for your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Specifically, the General Public License is designed to make
+sure that you have the freedom to give away or sell copies of free
+software, that you receive source code or can get it if you want it,
+that you can change the software or use pieces of it in new free
+programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of a such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must tell them their rights.
+
+ We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS
+
+ 1. This License Agreement applies to any program or other work which
+ contains a notice placed by the copyright holder saying it may be
+ distributed under the terms of this General Public License. The
+ "Program", below, refers to any such program or work, and a "work
+ based on the Program" means either the Program or any work
+ containing the Program or a portion of it, either verbatim or with
+ modifications. Each licensee is addressed as "you".
+
+ 2. You may copy and distribute verbatim copies of the Program's source
+ code as you receive it, in any medium, provided that you
+ conspicuously and appropriately publish on each copy an
+ appropriate copyright notice and disclaimer of warranty; keep
+ intact all the notices that refer to this General Public License
+ and to the absence of any warranty; and give any other recipients
+ of the Program a copy of this General Public License along with
+ the Program. You may charge a fee for the physical act of
+ transferring a copy.
+
+ 3. You may modify your copy or copies of the Program or any portion of
+ it, and copy and distribute such modifications under the terms of
+ Paragraph 1 above, provided that you also do the following:
+
+ * cause the modified files to carry prominent notices stating
+ that you changed the files and the date of any change; and
+
+ * cause the whole of any work that you distribute or publish,
+ that in whole or in part contains the Program or any part
+ thereof, either with or without modifications, to be licensed
+ at no charge to all third parties under the terms of this
+ General Public License (except that you may choose to grant
+ warranty protection to some or all third parties, at your
+ option).
+
+ * If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the simplest and most usual way, to print
+ or display an announcement including an appropriate copyright
+ notice and a notice that there is no warranty (or else,
+ saying that you provide a warranty) and that users may
+ redistribute the program under these conditions, and telling
+ the user how to view a copy of this General Public License.
+
+ * You may charge a fee for the physical act of transferring a
+ copy, and you may at your option offer warranty protection in
+ exchange for a fee.
+
+ Mere aggregation of another independent work with the Program (or
+ its derivative) on a volume of a storage or distribution medium
+ does not bring the other work under the scope of these terms.
+
+ 4. You may copy and distribute the Program (or a portion or
+ derivative of it, under Paragraph 2) in object code or executable
+ form under the terms of Paragraphs 1 and 2 above provided that you
+ also do one of the following:
+
+ * accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of
+ Paragraphs 1 and 2 above; or,
+
+ * accompany it with a written offer, valid for at least three
+ years, to give any third party free (except for a nominal
+ charge for the cost of distribution) a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Paragraphs 1 and 2 above; or,
+
+ * accompany it with the information you received as to where the
+ corresponding source code may be obtained. (This alternative
+ is allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form alone.)
+
+ Source code for a work means the preferred form of the work for
+ making modifications to it. For an executable file, complete
+ source code means all the source code for all modules it contains;
+ but, as a special exception, it need not include source code for
+ modules which are standard libraries that accompany the operating
+ system on which the executable file runs, or for standard header
+ files or definitions files that accompany that operating system.
+
+ 5. You may not copy, modify, sublicense, distribute or transfer the
+ Program except as expressly provided under this General Public
+ License. Any attempt otherwise to copy, modify, sublicense,
+ distribute or transfer the Program is void, and will automatically
+ terminate your rights to use the Program under this License.
+ However, parties who have received copies, or rights to use
+ copies, from you under this General Public License will not have
+ their licenses terminated so long as such parties remain in full
+ compliance.
+
+ 6. By copying, distributing or modifying the Program (or any work
+ based on the Program) you indicate your acceptance of this license
+ to do so, and all its terms and conditions.
+
+ 7. Each time you redistribute the Program (or any work based on the
+ Program), the recipient automatically receives a license from the
+ original licensor to copy, distribute or modify the Program
+ subject to these terms and conditions. You may not impose any
+ further restrictions on the recipients' exercise of the rights
+ granted herein.
+
+ 8. The Free Software Foundation may publish revised and/or new
+ versions of the General Public License from time to time. Such
+ new versions will be similar in spirit to the present version, but
+ may differ in detail to address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+ Program specifies a version number of the license which applies to
+ it and "any later version", you have the option of following the
+ terms and conditions either of that version or of any later
+ version published by the Free Software Foundation. If the Program
+ does not specify a version number of the license, you may choose
+ any version ever published by the Free Software Foundation.
+
+ 9. If you wish to incorporate parts of the Program into other free
+ programs whose distribution conditions are different, write to the
+ author to ask for permission. For software which is copyrighted
+ by the Free Software Foundation, write to the Free Software
+ Foundation; we sometimes make exceptions for this. Our decision
+ will be guided by the two goals of preserving the free status of
+ all derivatives of our free software and of promoting the sharing
+ and reuse of software generally.
+
+ NO WARRANTY
+
+ 10. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+ WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+ LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+ HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+ WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+ NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
+ QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+ PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+ SERVICING, REPAIR OR CORRECTION.
+
+ 11. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+ WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+ MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+ LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+ INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+ INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+ DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+ OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+ OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+ ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+Appendix: How to Apply These Terms to Your New Programs
+=======================================================
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to humanity, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+ ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
+ Copyright (C) 19YY NAME OF AUTHOR
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 1, or (at your option)
+ any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+ Also add information on how to contact you by electronic and paper
+mail.
+
+ If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+ The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+ You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary. Here a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the
+ program `Gnomovision' (a program to direct compilers to make passes
+ at assemblers) written by James Hacker.
+
+ SIGNATURE OF TY COON, 1 April 1989
+ Ty Coon, President of Vice
+
+ That's all there is to it!
+
+\1f
+File: xemacs.info, Node: Distrib, Next: Intro, Prev: License, Up: Top
+
+Distribution
+************
+
+ XEmacs is "free"; this means that everyone is free to use it and
+free to redistribute it on a free basis. XEmacs is not in the public
+domain; it is copyrighted and there are restrictions on its
+distribution, but these restrictions are designed to permit everything
+that a good cooperating citizen would want to do. What is not allowed
+is to try to prevent others from further sharing any version of XEmacs
+that they might get from you. The precise conditions are found in the
+GNU General Public License that comes with XEmacs and also appears
+following this section.
+
+ The easiest way to get a copy of XEmacs is from someone else who has
+it. You need not ask for permission to do so, or tell any one else;
+just copy it.
+
+ If you have access to the Internet, you can get the latest version of
+XEmacs from the anonymous FTP server `ftp.xemacs.org' in the directory
+`/pub/xemacs'. It can also be found at numerous other archive sites
+around the world; check the file `etc/DISTRIB' in an XEmacs
+distribution for the latest known list.
+
+Getting Other Versions of Emacs
+===============================
+
+ The Free Software Foundation's version of Emacs (called "FSF Emacs"
+in this manual and often referred to as "GNU Emacs") is available by
+anonymous FTP from `prep.ai.mit.edu'.
+
+ Win-Emacs, an older version of XEmacs that runs on Microsoft Windows
+and Windows NT, is available by anonymous FTP from `ftp.netcom.com' in
+the directory `/pub/pe/pearl', or from `ftp.cica.indiana.edu' as the
+files `wemdemo*.zip' in the directory `/pub/pc/win3/demo'.
+
+\1f
+File: xemacs.info, Node: Intro, Next: Glossary, Prev: Distrib, Up: Top
+
+Introduction
+************
+
+ You are reading about XEmacs, an incarnation of the advanced,
+self-documenting, customizable, extensible real-time display editor
+Emacs. XEmacs provides many powerful display and user-interface
+capabilities not found in other Emacsen and is mostly upwardly
+compatible with GNU Emacs from the Free Software Foundation (referred
+to as "FSF Emacs" in this manual). XEmacs also comes standard with a
+great number of useful packages.
+
+ We say that XEmacs is a "display" editor because normally the text
+being edited is visible on the screen and is updated automatically as
+you type. *Note Display: Frame.
+
+ We call XEmacs a "real-time" editor because the display is updated
+very frequently, usually after each character or pair of characters you
+type. This minimizes the amount of information you must keep in your
+head as you edit. *Note Real-time: Basic.
+
+ We call XEmacs advanced because it provides facilities that go beyond
+simple insertion and deletion: filling of text; automatic indentation of
+programs; viewing two or more files at once; and dealing in terms of
+characters, words, lines, sentences, paragraphs, and pages, as well as
+expressions and comments in several different programming languages.
+It is much easier to type one command meaning "go to the end of the
+paragraph" than to find that spot with simple cursor keys.
+
+ "Self-documenting" means that at any time you can type a special
+character, `Control-h', to find out what your options are. You can
+also use `C-h' to find out what a command does, or to find all the
+commands relevant to a topic. *Note Help::.
+
+ "Customizable" means you can change the definitions of XEmacs
+commands. For example, if you use a programming language in which
+comments start with `<**' and end with `**>', you can tell the XEmacs
+comment manipulation commands to use those strings (*note Comments::.).
+Another sort of customization is rearrangement of the command set.
+For example, you can set up the four basic cursor motion commands (up,
+down, left and right) on keys in a diamond pattern on the keyboard if
+you prefer. *Note Customization::.
+
+ "Extensible" means you can go beyond simple customization and write
+entirely new commands, programs in the Lisp language to be run by
+XEmacs's own Lisp interpreter. XEmacs is an "on-line extensible"
+system: it is divided into many functions that call each other. You can
+redefine any function in the middle of an editing session and replace
+any part of XEmacs without making a separate copy of all of XEmacs.
+Most of the editing commands of XEmacs are written in Lisp; the few
+exceptions could have been written in Lisp but are written in C for
+efficiency. Only a programmer can write an extension to XEmacs, but
+anybody can use it afterward.
+
+\1f
+File: xemacs.info, Node: Frame, Next: Keystrokes, Prev: Concept Index, Up: Top
+
+The XEmacs Frame
+****************
+
+Frame
+ In many environments, such as a tty terminal, an XEmacs frame
+ literally takes up the whole screen. If you are running XEmacs in
+ a multi-window system like the X Window System, the XEmacs frame
+ takes up one X window. *Note XEmacs under X::, for more
+ information.
+
+Window
+ No matter what environment you are running in, XEmacs allows you
+ to look at several buffers at the same time by having several
+ windows be part of the frame. Often, the whole frame is taken up
+ by just one window, but you can split the frame into two or more
+ subwindows. If you are running XEmacs under the X window system,
+ that means you can have several "XEmacs windows" inside the X
+ window that contains the XEmacs frame. You can even have multiple
+ frames in different X windows, each with their own set of
+ subwindows.
+
+ Each XEmacs frame displays a variety of information:
+ * The biggest area usually displays the text you are editing. It may
+ consist of one window or of two or more windows if you need to
+ look at two buffers a the same time.
+
+ * Below each text window's last line is a "mode line" (*note Mode
+ Line::.), which describes what is going on in that window. The
+ mode line is in inverse video if the terminal supports that. If
+ there are several XEmacs windows in one frame, each window has its
+ own mode line.
+
+ * At the bottom of each XEmacs frame is the "echo area" or
+ "minibuffer window"(*note Echo Area::.). It is used by XEmacs to
+ exchange information with the user. There is only one echo area
+ per XEmacs frame.
+
+ * If you are running XEmacs under the X Window System, a menu bar at
+ the top of the frame makes shortcuts to several of the commands
+ available (*note Pull-down Menus::.).
+
+ You can subdivide the XEmacs frame into multiple text windows, and
+use each window for a different file (*note Windows::.). Multiple
+XEmacs windows are tiled vertically on the XEmacs frame. The upper
+XEmacs window is separated from the lower window by its mode line.
+
+ When there are multiple, tiled XEmacs windows on a single XEmacs
+frame, the XEmacs window receiving input from the keyboard has the
+"keyboard focus" and is called the "selected window". The selected
+window contains the cursor, which indicates the insertion point. If
+you are working in an environment that permits multiple XEmacs frames,
+and you move the focus from one XEmacs frame into another, the selected
+window is the one that was last selected in that frame.
+
+ The same text can be displayed simultaneously in several XEmacs
+windows, which can be in different XEmacs frames. If you alter the text
+in an XEmacs buffer by editing it in one XEmacs window, the changes are
+visible in all XEmacs windows containing that buffer.
+
+* Menu:
+
+* Point:: The place in the text where editing commands operate.
+* Echo Area:: Short messages appear at the bottom of the frame.
+* Mode Line:: Interpreting the mode line.
+* XEmacs under X:: Some information on using XEmacs under the X
+ Window System.
+
+\1f
+File: xemacs.info, Node: Point, Next: Echo Area, Prev: Frame, Up: Frame
+
+Point
+=====
+
+ When XEmacs is running, the cursor shows the location at which
+editing commands will take effect. This location is called "point".
+You can use keystrokes or the mouse cursor to move point through the
+text and edit the text at different places.
+
+ While the cursor appears to point AT a character, you should think
+of point as BETWEEN two characters: it points BEFORE the character on
+which the cursor appears. The exception is at the end of the line,
+where the cursor appears after the last character of the line. Where
+the display is capable, the cursor at the end of the line will appear
+differently from a cursor over whitespace at the end of the line. (In
+an X Windows frame, the end-of-line cursor is half the width of a
+within-line cursor.) Sometimes people speak of "the cursor" when they
+mean "point," or speak of commands that move point as "cursor motion"
+commands.
+
+ Each XEmacs frame has only one cursor. When output is in progress,
+the cursor must appear where the typing is being done. This does not
+mean that point is moving. It is only that XEmacs has no way to show
+you the location of point except when the terminal is idle.
+
+ If you are editing several files in XEmacs, each file has its own
+point location. A file that is not being displayed remembers where
+point is. Point becomes visible at the correct location when you look
+at the file again.
+
+ When there are multiple text windows, each window has its own point
+location. The cursor shows the location of point in the selected
+window. The visible cursor also shows you which window is selected. If
+the same buffer appears in more than one window, point can be moved in
+each window independently.
+
+ The term `point' comes from the character `.', which was the command
+in TECO (the language in which the original Emacs was written) for
+accessing the value now called `point'.
+
+\1f
+File: xemacs.info, Node: Echo Area, Next: Mode Line, Prev: Point, Up: Frame
+
+The Echo Area
+=============
+
+ The line at the bottom of the frame (below the mode line) is the
+"echo area". XEmacs uses this area to communicate with the user:
+
+ * "Echoing" means printing out the characters that the user types.
+ XEmacs never echoes single-character commands. Multi-character
+ commands are echoed only if you pause while typing them: As soon
+ as you pause for more than one second in the middle of a command,
+ all the characters of the command so far are echoed. This is
+ intended to "prompt" you for the rest of the command. Once
+ echoing has started, the rest of the command is echoed immediately
+ as you type it. This behavior is designed to give confident users
+ fast response, while giving hesitant users maximum feedback. You
+ can change this behavior by setting a variable (*note Display
+ Vars::.).
+
+ * If you issue a command that cannot be executed, XEmacs may print
+ an "error message" in the echo area. Error messages are
+ accompanied by a beep or by flashing the frame. Any input you
+ have typed ahead is thrown away when an error happens.
+
+ * Some commands print informative messages in the echo area. These
+ messages look similar to error messages, but are not announced
+ with a beep and do not throw away input. Sometimes a message
+ tells you what the command has done, when this is not obvious from
+ looking at the text being edited. Sometimes the sole purpose of a
+ command is to print a message giving you specific information.
+ For example, the command `C-x =' is used to print a message
+ describing the character position of point in the text and its
+ current column in the window. Commands that take a long time
+ often display messages ending in `...' while they are working, and
+ add `done' at the end when they are finished.
+
+ * The echo area is also used to display the "minibuffer", a window
+ that is used for reading arguments to commands, such as the name
+ of a file to be edited. When the minibuffer is in use, the echo
+ area displays with a prompt string that usually ends with a colon.
+ The cursor appears after the prompt. You can always get out of
+ the minibuffer by typing `C-g'. *Note Minibuffer::.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
+
+Pages
+=====
+
+ Files are often thought of as divided into "pages" by the "formfeed"
+character (ASCII Control-L, octal code 014). For example, if a file is
+printed on a line printer, each "page" of the file starts on a new page
+of paper. Emacs treats a page-separator character just like any other
+character. It can be inserted with `C-q C-l' or deleted with <DEL>.
+You are free to paginate your file or not. However, since pages are
+often meaningful divisions of the file, commands are provided to move
+over them and operate on them.
+
+`C-x ['
+ Move point to previous page boundary (`backward-page').
+
+`C-x ]'
+ Move point to next page boundary (`forward-page').
+
+`C-x C-p'
+ Put point and mark around this page (or another page)
+ (`mark-page').
+
+`C-x l'
+ Count the lines in this page (`count-lines-page').
+
+ The `C-x [' (`backward-page') command moves point to immediately
+after the previous page delimiter. If point is already right after a
+page delimiter, the command skips that one and stops at the previous
+one. A numeric argument serves as a repeat count. The `C-x ]'
+(`forward-page') command moves forward past the next page delimiter.
+
+ The `C-x C-p' command (`mark-page') puts point at the beginning of
+the current page and the mark at the end. The page delimiter at the end
+is included (the mark follows it). The page delimiter at the front is
+excluded (point follows it). You can follow this command by `C-w' to
+kill a page you want to move elsewhere. If you insert the page after a
+page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
+page will be properly delimited before and after once again.
+
+ A numeric argument to `C-x C-p' is used to specify which page to go
+to, relative to the current one. Zero means the current page. One
+means the next page, and -1 means the previous one.
+
+ The `C-x l' command (`count-lines-page') can help you decide where
+to break a page in two. It prints the total number of lines in the
+current page in the echo area, then divides the lines into those
+preceding the current line and those following it, for example
+
+ Page has 96 (72+25) lines
+
+Notice that the sum is off by one; this is correct if point is not at
+the beginning of a line.
+
+ The variable `page-delimiter' should have as its value a regexp that
+matches the beginning of a line that separates pages. This defines
+where pages begin. The normal value of this variable is `"^\f"', which
+matches a formfeed character at the beginning of a line.
+
+\1f
+File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
+
+Filling Text
+============
+
+ If you use Auto Fill mode, Emacs "fills" text (breaks it up into
+lines that fit in a specified width) as you insert it. When you alter
+existing text it is often no longer be properly filled afterwards and
+you can use explicit commands for filling.
+
+* Menu:
+
+* Auto Fill:: Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix:: Filling when every line is indented or in a comment, etc.
+
+\1f
+File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
+
+Auto Fill Mode
+--------------
+
+ "Auto Fill" mode is a minor mode in which lines are broken
+automatically when they become too wide. Breaking happens only when
+you type a <SPC> or <RET>.
+
+`M-x auto-fill-mode'
+ Enable or disable Auto Fill mode.
+
+`<SPC>'
+`<RET>'
+ In Auto Fill mode, break lines when appropriate.
+
+ `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
+if it was on. With a positive numeric argument the command always turns
+Auto Fill mode on, and with a negative argument it always turns it off.
+The presence of the word `Fill' in the mode line, inside the
+parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
+is a minor mode; you can turn it on or off for each buffer individually.
+*Note Minor Modes::.
+
+ In Auto Fill mode, lines are broken automatically at spaces when
+they get longer than desired. Line breaking and rearrangement takes
+place only when you type <SPC> or <RET>. To insert a space or newline
+without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
+(recall that a newline is really a linefeed). `C-o' inserts a newline
+without line breaking.
+
+ Auto Fill mode works well with Lisp mode: when it makes a new line in
+Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
+comment gets too long, the text of the comment is split into two
+comment lines. Optionally, new comment delimiters are inserted at the
+end of the first line and the beginning of the second, so that each line
+is a separate comment. The variable `comment-multi-line' controls the
+choice (*note Comments::.).
+
+ Auto Fill mode does not refill entire paragraphs. It can break
+lines but cannot merge lines. Editing in the middle of a paragraph can
+result in a paragraph that is not correctly filled. The easiest way to
+make the paragraph properly filled again is using an explicit fill
+commands.
+
+ Many users like Auto Fill mode and want to use it in all text files.
+The section on init files explains how you can arrange this permanently
+for yourself. *Note Init File::.
+
+\1f
+File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
+
+Explicit Fill Commands
+----------------------
+
+`M-q'
+ Fill current paragraph (`fill-paragraph').
+
+`M-g'
+ Fill each paragraph in the region (`fill-region').
+
+`C-x f'
+ Set the fill column (`set-fill-column').
+
+`M-x fill-region-as-paragraph'
+ Fill the region, considering it as one paragraph.
+
+`M-s'
+ Center a line.
+
+ To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
+It causes the paragraph containing point, or the one after point if
+point is between paragraphs, to be refilled. All line breaks are
+removed, and new ones are inserted where necessary. `M-q' can be
+undone with `C-_'. *Note Undo::.
+
+ To refill many paragraphs, use `M-g' (`fill-region'), which divides
+the region into paragraphs and fills each of them.
+
+ `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
+paragraph boundaries (*note Paragraphs::.). For more control, you can
+use `M-x fill-region-as-paragraph', which refills everything between
+point and mark. This command recognizes only blank lines as paragraph
+separators.
+
+ A numeric argument to `M-g' or `M-q' causes it to "justify" the text
+as well as filling it. Extra spaces are inserted to make the right
+margin line up exactly at the fill column. To remove the extra spaces,
+use `M-q' or `M-g' with no argument.
+
+ The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
+match lines that should not be auto-filled.
+
+ The command `Meta-s' (`center-line') centers the current line within
+the current fill column. With an argument, it centers several lines
+individually and moves past them.
+
+ The maximum line width for filling is in the variable `fill-column'.
+Altering the value of `fill-column' makes it local to the current
+buffer; until then, the default value--initially 70--is in effect.
+*Note Locals::.
+
+ The easiest way to set `fill-column' is to use the command `C-x f'
+(`set-fill-column'). With no argument, it sets `fill-column' to the
+current horizontal position of point. With a numeric argument, it uses
+that number as the new fill column.
+
+\1f
+File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
+
+The Fill Prefix
+---------------
+
+ To fill a paragraph in which each line starts with a special marker
+(which might be a few spaces, giving an indented paragraph), use the
+"fill prefix" feature. The fill prefix is a string which is not
+included in filling. Emacs expects every line to start with a fill
+prefix.
+
+`C-x .'
+ Set the fill prefix (`set-fill-prefix').
+
+`M-q'
+ Fill a paragraph using current fill prefix (`fill-paragraph').
+
+`M-x fill-individual-paragraphs'
+ Fill the region, considering each change of indentation as
+ starting a new paragraph.
+
+ To specify a fill prefix, move to a line that starts with the desired
+prefix, put point at the end of the prefix, and give the command
+`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
+off the fill prefix, specify an empty prefix: type `C-x .' with point
+at the beginning of a line.
+
+ When a fill prefix is in effect, the fill commands remove the fill
+prefix from each line before filling and insert it on each line after
+filling. Auto Fill mode also inserts the fill prefix inserted on new
+lines it creates. Lines that do not start with the fill prefix are
+considered to start paragraphs, both in `M-q' and the paragraph
+commands; this is just right if you are using paragraphs with hanging
+indentation (every line indented except the first one). Lines which are
+blank or indented once the prefix is removed also separate or start
+paragraphs; this is what you want if you are writing multi-paragraph
+comments with a comment delimiter on each line.
+
+ The fill prefix is stored in the variable `fill-prefix'. Its value
+is a string, or `nil' when there is no fill prefix. This is a
+per-buffer variable; altering the variable affects only the current
+buffer, but there is a default value which you can change as well.
+*Note Locals::.
+
+ Another way to use fill prefixes is through `M-x
+fill-individual-paragraphs'. This function divides the region into
+groups of consecutive lines with the same amount and kind of
+indentation and fills each group as a paragraph, using its indentation
+as a fill prefix.
+
+\1f
+File: xemacs.info, Node: Case, Prev: Filling, Up: Text
+
+Case Conversion Commands
+========================
+
+ Emacs has commands for converting either a single word or any
+arbitrary range of text to upper case or to lower case.
+
+`M-l'
+ Convert following word to lower case (`downcase-word').
+
+`M-u'
+ Convert following word to upper case (`upcase-word').
+
+`M-c'
+ Capitalize the following word (`capitalize-word').
+
+`C-x C-l'
+ Convert region to lower case (`downcase-region').
+
+`C-x C-u'
+ Convert region to upper case (`upcase-region').
+
+ The word conversion commands are used most frequently. `Meta-l'
+(`downcase-word') converts the word after point to lower case, moving
+past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
+(`upcase-word') converts to all capitals instead, while `Meta-c'
+(`capitalize-word') puts the first letter of the word into upper case
+and the rest into lower case. The word conversion commands convert
+several words at once if given an argument. They are especially
+convenient for converting a large amount of text from all upper case to
+mixed case: you can move through the text using `M-l', `M-u', or `M-c'
+on each word as appropriate, occasionally using `M-f' instead to skip a
+word.
+
+ When given a negative argument, the word case conversion commands
+apply to the appropriate number of words before point, but do not move
+point. This is convenient when you have just typed a word in the wrong
+case: you can give the case conversion command and continue typing.
+
+ If a word case conversion command is given in the middle of a word,
+it applies only to the part of the word which follows point. This is
+just like what `Meta-d' (`kill-word') does. With a negative argument,
+case conversion applies only to the part of the word before point.
+
+ The other case conversion commands are `C-x C-u' (`upcase-region')
+and `C-x C-l' (`downcase-region'), which convert everything between
+point and mark to the specified case. Point and mark do not move.
+
+\1f
+File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
+
+Editing Programs
+****************
+
+ Emacs has many commands designed to understand the syntax of
+programming languages such as Lisp and C. These commands can:
+
+ * Move over or kill balanced expressions or "sexps" (*note Lists::.).
+
+ * Move over or mark top-level balanced expressions ("defuns", in
+ Lisp; functions, in C).
+
+ * Show how parentheses balance (*note Matching::.).
+
+ * Insert, kill, or align comments (*note Comments::.).
+
+ * Follow the usual indentation conventions of the language (*note
+ Grinding::.).
+
+ The commands available for words, sentences, and paragraphs are
+useful in editing code even though their canonical application is for
+editing human language text. Most symbols contain words (*note
+Words::.); sentences can be found in strings and comments (*note
+Sentences::.). Paragraphs per se are not present in code, but the
+paragraph commands are useful anyway, because Lisp mode and C mode
+define paragraphs to begin and end at blank lines (*note
+Paragraphs::.). Judicious use of blank lines to make the program
+clearer also provides interesting chunks of text for the paragraph
+commands to work on.
+
+ The selective display feature is useful for looking at the overall
+structure of a function (*note Selective Display::.). This feature
+causes only the lines that are indented less than a specified amount to
+appear on the screen.
+
+* Menu:
+
+* Program Modes:: Major modes for editing programs.
+* Lists:: Expressions with balanced parentheses.
+ There are editing commands to operate on them.
+* Defuns:: Each program is made up of separate functions.
+ There are editing commands to operate on them.
+* Grinding:: Adjusting indentation to show the nesting.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+* Comments:: Inserting, illing and aligning comments.
+* Balanced Editing:: Inserting two matching parentheses at once, etc.
+* Lisp Completion:: Completion on symbol names in Lisp code.
+* Documentation:: Getting documentation of functions you plan to call.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go direct to any function in your program in one
+ command. Tags remembers which file it is in.
+* Fortran:: Fortran mode and its special features.
+* Asm Mode:: Asm mode and its special features.
+
+\1f
+File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
+
+Major Modes for Programming Languages
+=====================================
+
+ Emacs has several major modes for the programming languages Lisp,
+Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
+mode should be implemented for each programming language you might want
+to edit with Emacs; but often the mode for one language can serve for
+other syntactically similar languages. The language modes that exist
+are those that someone decided to take the trouble to write.
+
+ There are several variants of Lisp mode, which differ in the way they
+interface to Lisp execution. *Note Lisp Modes::.
+
+ Each of the programming language modes defines the <TAB> key to run
+an indentation function that knows the indentation conventions of that
+language and updates the current line's indentation accordingly. For
+example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
+normally defined to do <RET> followed by <TAB>; thus it, too, indents
+in a mode-specific fashion.
+
+ In most programming languages, indentation is likely to vary from
+line to line. So the major modes for those languages rebind <DEL> to
+treat a tab as if it were the equivalent number of spaces (using the
+command `backward-delete-char-untabify'). This makes it possible to
+rub out indentation one column at a time without worrying whether it is
+made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
+tab character before point.
+
+ Programming language modes define paragraphs to be separated only by
+blank lines, so that the paragraph commands remain useful. Auto Fill
+mode, if enabled in a programming language major mode, indents the new
+lines which it creates.
+
+ Turning on a major mode calls a user-supplied function called the
+"mode hook", which is the value of a Lisp variable. For example,
+turning on C mode calls the value of the variable `c-mode-hook' if that
+value exists and is non-`nil'. Mode hook variables for other
+programming language modes include `lisp-mode-hook',
+`emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
+`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
+receives no arguments.
+
+\1f
+File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
+
+Lists and Sexps
+===============
+
+ By convention, Emacs keys for dealing with balanced expressions are
+usually `Control-Meta-' characters. They tend to be analogous in
+function to their `Control-' and `Meta-' equivalents. These commands
+are usually thought of as pertaining to expressions in programming
+languages, but can be useful with any language in which some sort of
+parentheses exist (including English).
+
+ The commands fall into two classes. Some commands deal only with
+"lists" (parenthetical groupings). They see nothing except
+parentheses, brackets, braces (depending on what must balance in the
+language you are working with), and escape characters that might be used
+to quote those.
+
+ The other commands deal with expressions or "sexps". The word `sexp'
+is derived from "s-expression", the term for a symbolic expression in
+Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
+refers to an expression in the language your program is written in.
+Each programming language has its own major mode, which customizes the
+syntax tables so that expressions in that language count as sexps.
+
+ Sexps typically include symbols, numbers, and string constants, as
+well as anything contained in parentheses, brackets, or braces.
+
+ In languages that use prefix and infix operators, such as C, it is
+not possible for all expressions to be sexps. For example, C mode does
+not recognize `foo + bar' as an sexp, even though it is a C expression;
+it recognizes `foo' as one sexp and `bar' as another, with the `+' as
+punctuation between them. This is a fundamental ambiguity: both `foo +
+bar' and `foo' are legitimate choices for the sexp to move over if
+point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
+
+ Some languages have obscure forms of syntax for expressions that
+nobody has bothered to make Emacs understand properly.
+
+`C-M-f'
+ Move forward over an sexp (`forward-sexp').
+
+`C-M-b'
+ Move backward over an sexp (`backward-sexp').
+
+`C-M-k'
+ Kill sexp forward (`kill-sexp').
+
+`C-M-u'
+ Move up and backward in list structure (`backward-up-list').
+
+`C-M-d'
+ Move down and forward in list structure (`down-list').
+
+`C-M-n'
+ Move forward over a list (`forward-list').
+
+`C-M-p'
+ Move backward over a list (`backward-list').
+
+`C-M-t'
+ Transpose expressions (`transpose-sexps').
+
+`C-M-@'
+ Put mark after following expression (`mark-sexp').
+
+ To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
+first significant character after point is an opening delimiter (`(' in
+Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
+delimiter. If the character begins a symbol, string, or number,
+`C-M-f' moves over that. If the character after point is a closing
+delimiter, `C-M-f' just moves past it. (This last is not really moving
+across an sexp; it is an exception which is included in the definition
+of `C-M-f' because it is as useful a behavior as anyone can think of
+for that situation.)
+
+ The command `C-M-b' (`backward-sexp') moves backward over a sexp.
+The detailed rules are like those above for `C-M-f', but with
+directions reversed. If there are any prefix characters (single quote,
+back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
+over them as well.
+
+ `C-M-f' or `C-M-b' with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
+
+ In languages such as C where the comment-terminator can be
+recognized, the sexp commands move across comments as if they were
+whitespace. In Lisp and other languages where comments run until the
+end of a line, it is very difficult to ignore comments when parsing
+backwards; therefore, in such languages the sexp commands treat the
+text of comments as if it were code.
+
+ Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
+`C-M-k' kills the characters that `C-M-f' would move over.
+
+ The "list commands", `C-M-n' (`forward-list') and `C-M-p'
+(`backward-list'), move over lists like the sexp commands but skip over
+any number of other kinds of sexps (symbols, strings, etc). In some
+situations, these commands are useful because they usually ignore
+comments, since the comments usually do not contain any lists.
+
+ `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
+is possible. To move up one (or N) levels, use `C-M-u'
+(`backward-up-list'). `C-M-u' moves backward up past one unmatched
+opening delimiter. A positive argument serves as a repeat count; a
+negative argument reverses direction of motion and also requests
+repetition, so it moves forward and up one or more levels.
+
+ To move down in list structure, use `C-M-d' (`down-list'). In Lisp
+mode, where `(' is the only opening delimiter, this is nearly the same
+as searching for a `('. An argument specifies the number of levels of
+parentheses to go down.
+
+ `C-M-t' (`transpose-sexps') drags the previous sexp across the next
+one. An argument serves as a repeat count, and a negative argument
+drags backwards (thus canceling out the effect of `C-M-t' with a
+positive argument). An argument of zero, rather than doing nothing,
+transposes the sexps ending after point and the mark.
+
+ To make the region be the next sexp in the buffer, use `C-M-@'
+(`mark-sexp') which sets the mark at the same place that `C-M-f' would
+move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
+negative argument is useful for putting the mark at the beginning of
+the previous sexp.
+
+ The list and sexp commands' understanding of syntax is completely
+controlled by the syntax table. Any character can, for example, be
+declared to be an opening delimiter and act like an open parenthesis.
+*Note Syntax::.
+
+\1f
+File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
+
+Defuns
+======
+
+ In Emacs, a parenthetical grouping at the top level in the buffer is
+called a "defun". The name derives from the fact that most top-level
+lists in Lisp are instances of the special form `defun', but Emacs
+calls any top-level parenthetical grouping counts a defun regardless of
+its contents or the programming language. For example, in C, the body
+of a function definition is a defun.
+
+`C-M-a'
+ Move to beginning of current or preceding defun
+ (`beginning-of-defun').
+
+`C-M-e'
+ Move to end of current or following defun (`end-of-defun').
+
+`C-M-h'
+ Put region around whole current or following defun (`mark-defun').
+
+ The commands to move to the beginning and end of the current defun
+are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
+
+ To operate on the current defun, use `C-M-h' (`mark-defun') which
+puts point at the beginning and the mark at the end of the current or
+next defun. This is the easiest way to prepare for moving the defun to
+a different place. In C mode, `C-M-h' runs the function
+`mark-c-function', which is almost the same as `mark-defun', but which
+backs up over the argument declarations, function name, and returned
+data type so that the entire C function is inside the region.
+
+ To compile and evaluate the current defun, use `M-x compile-defun'.
+This function prints the results in the minibuffer. If you include an
+argument, it inserts the value in the current buffer after the defun.
+
+ Emacs assumes that any open-parenthesis found in the leftmost column
+is the start of a defun. Therefore, never put an open-parenthesis at
+the left margin in a Lisp file unless it is the start of a top level
+list. Never put an open-brace or other opening delimiter at the
+beginning of a line of C code unless it starts the body of a function.
+The most likely problem case is when you want an opening delimiter at
+the start of a line inside a string. To avoid trouble, put an escape
+character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
+before the opening delimiter. It will not affect the contents of the
+string.
+
+ The original Emacs found defuns by moving upward a level of
+parentheses until there were no more levels to go up. This required
+scanning back to the beginning of the buffer for every function. To
+speed this up, Emacs was changed to assume that any `(' (or other
+character assigned the syntactic class of opening-delimiter) at the
+left margin is the start of a defun. This heuristic is nearly always
+right; however, it mandates the convention described above.
+
+\1f
+File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
+
+Indentation for Programs
+========================
+
+ The best way to keep a program properly indented ("ground") is to
+use Emacs to re-indent it as you change the program. Emacs has commands
+to indent properly either a single line, a specified number of lines, or
+all of the lines inside a single parenthetical grouping.
+
+* Menu:
+
+* Basic Indent::
+* Multi-line Indent:: Commands to reindent many lines at once.
+* Lisp Indent:: Specifying how each Lisp function should be indented.
+* C Indent:: Choosing an indentation style for C code.
+
+\1f
+File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
+
+Basic Program Indentation Commands
+----------------------------------
+
+`<TAB>'
+ Adjust indentation of current line.
+
+`<LFD>'
+ Equivalent to <RET> followed by <TAB> (`newline-and-indent').
+
+ The basic indentation command is <TAB>, which gives the current line
+the correct indentation as determined from the previous lines. The
+function that <TAB> runs depends on the major mode; it is
+`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
+functions understand different syntaxes for different languages, but
+they all do about the same thing. <TAB> in any programming language
+major mode inserts or deletes whitespace at the beginning of the
+current line, independent of where point is in the line. If point is
+inside the whitespace at the beginning of the line, <TAB> leaves it at
+the end of that whitespace; otherwise, <TAB> leaves point fixed with
+respect to the characters around it.
+
+ Use `C-q <TAB>' to insert a tab at point.
+
+ When entering a large amount of new code, use <LFD>
+(`newline-and-indent'), which is equivalent to a <RET> followed by a
+<TAB>. <LFD> creates a blank line, then gives it the appropriate
+indentation.
+
+ <TAB> indents the second and following lines of the body of a
+parenthetical grouping each under the preceding one; therefore, if you
+alter one line's indentation to be nonstandard, the lines below tend to
+follow it. This is the right behavior in cases where the standard
+result of <TAB> does not look good.
+
+ Remember that Emacs assumes that an open-parenthesis, open-brace, or
+other opening delimiter at the left margin (including the indentation
+routines) is the start of a function. You should therefore never have
+an opening delimiter in column zero that is not the beginning of a
+function, not even inside a string. This restriction is vital for
+making the indentation commands fast. *Note Defuns::, for more
+information on this behavior.
+
+\1f
+File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
+
+Indenting Several Lines
+-----------------------
+
+ Several commands are available to re-indent several lines of code
+which have been altered or moved to a different level in a list
+structure.
+
+`C-M-q'
+ Re-indent all the lines within one list (`indent-sexp').
+
+`C-u <TAB>'
+ Shift an entire list rigidly sideways so that its first line is
+ properly indented.
+
+`C-M-\'
+ Re-indent all lines in the region (`indent-region').
+
+ To re-indent the contents of a single list, position point before the
+beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
+Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
+functions in other modes. The indentation of the line the sexp starts
+on is not changed; therefore, only the relative indentation within the
+list, and not its position, is changed. To correct the position as
+well, type a <TAB> before `C-M-q'.
+
+ If the relative indentation within a list is correct but the
+indentation of its beginning is not, go to the line on which the list
+begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
+it moves all the lines in the group, starting on the current line,
+sideways the same amount that the current line moves. The command does
+not move lines that start inside strings, or C preprocessor lines when
+in C mode.
+
+ Another way to specify a range to be re-indented is with point and
+mark. The command `C-M-\' (`indent-region') applies <TAB> to every
+line whose first character is between point and mark.
+
+\1f
+File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
+
+Customizing Lisp Indentation
+----------------------------
+
+ The indentation pattern for a Lisp expression can depend on the
+function called by the expression. For each Lisp function, you can
+choose among several predefined patterns of indentation, or define an
+arbitrary one with a Lisp program.
+
+ The standard pattern of indentation is as follows: the second line
+of the expression is indented under the first argument, if that is on
+the same line as the beginning of the expression; otherwise, the second
+line is indented underneath the function name. Each following line is
+indented under the previous line whose nesting depth is the same.
+
+ If the variable `lisp-indent-offset' is non-`nil', it overrides the
+usual indentation pattern for the second line of an expression, so that
+such lines are always indented `lisp-indent-offset' more columns than
+the containing list.
+
+ Certain functions override the standard pattern. Functions whose
+names start with `def' always indent the second line by
+`lisp-body-indention' extra columns beyond the open-parenthesis
+starting the expression.
+
+ Individual functions can override the standard pattern in various
+ways, according to the `lisp-indent-function' property of the function
+name. (Note: `lisp-indent-function' was formerly called
+`lisp-indent-hook'). There are four possibilities for this property:
+
+`nil'
+ This is the same as no property; the standard indentation pattern
+ is used.
+
+`defun'
+ The pattern used for function names that start with `def' is used
+ for this function also.
+
+a number, NUMBER
+ The first NUMBER arguments of the function are "distinguished"
+ arguments; the rest are considered the "body" of the expression.
+ A line in the expression is indented according to whether the
+ first argument on it is distinguished or not. If the argument is
+ part of the body, the line is indented `lisp-body-indent' more
+ columns than the open-parenthesis starting the containing
+ expression. If the argument is distinguished and is either the
+ first or second argument, it is indented twice that many extra
+ columns. If the argument is distinguished and not the first or
+ second argument, the standard pattern is followed for that line.
+
+a symbol, SYMBOL
+ SYMBOL should be a function name; that function is called to
+ calculate the indentation of a line within this expression. The
+ function receives two arguments:
+ STATE
+ The value returned by `parse-partial-sexp' (a Lisp primitive
+ for indentation and nesting computation) when it parses up to
+ the beginning of this line.
+
+ POS
+ The position at which the line being indented begins.
+
+ It should return either a number, which is the number of columns of
+ indentation for that line, or a list whose first element is such a
+ number. The difference between returning a number and returning a
+ list is that a number says that all following lines at the same
+ nesting level should be indented just like this one; a list says
+ that following lines might call for different indentations. This
+ makes a difference when the indentation is computed by `C-M-q'; if
+ the value is a number, `C-M-q' need not recalculate indentation
+ for the following lines until the end of the list.
+
+\1f
+File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
+
+Customizing C Indentation
+-------------------------
+
+ Two variables control which commands perform C indentation and when.
+
+ If `c-auto-newline' is non-`nil', newlines are inserted both before
+and after braces that you insert and after colons and semicolons.
+Correct C indentation is done on all the lines that are made this way.
+
+ If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
+does indentation only if point is at the left margin or within the
+line's indentation. If there is non-whitespace to the left of point,
+<TAB> just inserts a tab character in the buffer. Normally, this
+variable is `nil', and <TAB> always reindents the current line.
+
+ C does not have anything analogous to particular function names for
+which special forms of indentation are desirable. However, it has a
+different need for customization facilities: many different styles of C
+indentation are in common use.
+
+ There are six variables you can set to control the style that Emacs C
+mode will use.
+
+`c-indent-level'
+ Indentation of C statements within surrounding block. The
+ surrounding block's indentation is the indentation of the line on
+ which the open-brace appears.
+
+`c-continued-statement-offset'
+ Extra indentation given to a substatement, such as the then-clause
+ of an `if' or body of a `while'.
+
+`c-brace-offset'
+ Extra indentation for lines that start with an open brace.
+
+`c-brace-imaginary-offset'
+ An open brace following other text is treated as if it were this
+ far to the right of the start of its line.
+
+`c-argdecl-indent'
+ Indentation level of declarations of C function arguments.
+
+`c-label-offset'
+ Extra indentation for a line that is a label, case, or default.
+
+ The variable `c-indent-level' controls the indentation for C
+statements with respect to the surrounding block. In the example:
+
+ {
+ foo ();
+
+the difference in indentation between the lines is `c-indent-level'.
+Its standard value is 2.
+
+ If the open-brace beginning the compound statement is not at the
+beginning of its line, the `c-indent-level' is added to the indentation
+of the line, not the column of the open-brace. For example,
+
+ if (losing) {
+ do_this ();
+
+One popular indentation style is that which results from setting
+`c-indent-level' to 8 and putting open-braces at the end of a line in
+this way. Another popular style prefers to put the open-brace on a
+separate line.
+
+ In fact, the value of the variable `c-brace-imaginary-offset' is
+also added to the indentation of such a statement. Normally this
+variable is zero. Think of this variable as the imaginary position of
+the open brace, relative to the first non-blank character on the line.
+By setting the variable to 4 and `c-indent-level' to 0, you can get
+this style:
+
+ if (x == y) {
+ do_it ();
+ }
+
+ When `c-indent-level' is zero, the statements inside most braces
+line up exactly under the open brace. An exception are braces in column
+zero, like those surrounding a function's body. The statements inside
+those braces are not placed at column zero. Instead, `c-brace-offset'
+and `c-continued-statement-offset' (see below) are added to produce a
+typical offset between brace levels, and the statements are indented
+that far.
+
+ `c-continued-statement-offset' controls the extra indentation for a
+line that starts within a statement (but not within parentheses or
+brackets). These lines are usually statements inside other statements,
+like the then-clauses of `if' statements and the bodies of `while'
+statements. The `c-continued-statement-offset' parameter determines
+the difference in indentation between the two lines in:
+
+ if (x == y)
+ do_it ();
+
+The default value for `c-continued-statement-offset' is 2. Some
+popular indentation styles correspond to a value of zero for
+`c-continued-statement-offset'.
+
+ `c-brace-offset' is the extra indentation given to a line that
+starts with an open-brace. Its standard value is zero; compare:
+
+ if (x == y)
+ {
+
+with:
+
+ if (x == y)
+ do_it ();
+
+If you set `c-brace-offset' to 4, the first example becomes:
+
+ if (x == y)
+ {
+
+ `c-argdecl-indent' controls the indentation of declarations of the
+arguments of a C function. It is absolute: argument declarations
+receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
+results in code like this:
+
+ char *
+ index (string, char)
+ char *string;
+ int char;
+
+ `c-label-offset' is the extra indentation given to a line that
+contains a label, a case statement, or a `default:' statement. Its
+standard value is -2 and results in code like this:
+
+ switch (c)
+ {
+ case 'x':
+
+If `c-label-offset' were zero, the same code would be indented as:
+
+ switch (c)
+ {
+ case 'x':
+
+This example assumes that the other variables above also have their
+default values.
+
+ Using the indentation style produced by the default settings of the
+variables just discussed and putting open braces on separate lines
+produces clear and readable files. For an example, look at any of the C
+source files of XEmacs.
+
+\1f
+File: xemacs.info, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
+
+Automatic Display of Matching Parentheses
+=========================================
+
+ The Emacs parenthesis-matching feature shows you automatically how
+parentheses match in the text. Whenever a self-inserting character that
+is a closing delimiter is typed, the cursor moves momentarily to the
+location of the matching opening delimiter, provided that is visible on
+the screen. If it is not on the screen, some text starting with that
+opening delimiter is displayed in the echo area. Either way, you see
+the grouping you are closing off.
+
+ In Lisp, automatic matching applies only to parentheses. In C, it
+also applies to braces and brackets. Emacs knows which characters to
+regard as matching delimiters based on the syntax table set by the major
+mode. *Note Syntax::.
+
+ If the opening delimiter and closing delimiter are mismatched--as in
+`[x)'--the echo area displays a warning message. The correct matches
+are specified in the syntax table.
+
+ Two variables control parenthesis matching displays.
+`blink-matching-paren' turns the feature on or off. The default is `t'
+(match display is on); `nil' turns it off.
+`blink-matching-paren-distance' specifies how many characters back
+Emacs searches to find a matching opening delimiter. If the match is
+not found in the specified region, scanning stops, and nothing is
+displayed. This prevents wasting lots of time scanning when there is no
+match. The default is 4000.
+
+\1f
+File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs
+
+Manipulating Comments
+=====================
+
+ The comment commands insert, kill and align comments.
+
+`M-;'
+ Insert or align comment (`indent-for-comment').
+
+`C-x ;'
+ Set comment column (`set-comment-column').
+
+`C-u - C-x ;'
+ Kill comment on current line (`kill-comment').
+
+`M-<LFD>'
+ Like <RET> followed by inserting and aligning a comment
+ (`indent-new-comment-line').
+
+ The command that creates a comment is `Meta-;'
+(`indent-for-comment'). If there is no comment already on the line, a
+new comment is created and aligned at a specific column called the
+"comment column". Emacs creates the comment by inserting the string at
+the value of `comment-start'; see below. Point is left after that
+string. If the text of the line extends past the comment column,
+indentation is done to a suitable boundary (usually, at least one space
+is inserted). If the major mode has specified a string to terminate
+comments, that string is inserted after point, to keep the syntax valid.
+
+ You can also use `Meta-;' to align an existing comment. If a line
+already contains the string that starts comments, `M-;' just moves
+point after it and re-indents it to the conventional place. Exception:
+comments starting in column 0 are not moved.
+
+ Some major modes have special rules for indenting certain kinds of
+comments in certain contexts. For example, in Lisp code, comments which
+start with two semicolons are indented as if they were lines of code,
+instead of at the comment column. Comments which start with three
+semicolons are supposed to start at the left margin. Emacs understands
+these conventions by indenting a double-semicolon comment using <TAB>
+and by not changing the indentation of a triple-semicolon comment at
+all.
+
+ ;; This function is just an example.
+ ;;; Here either two or three semicolons are appropriate.
+ (defun foo (x)
+ ;;; And now, the first part of the function:
+ ;; The following line adds one.
+ (1+ x)) ; This line adds one.
+
+ In C code, a comment preceded on its line by nothing but whitespace
+is indented like a line of code.
+
+ Even when an existing comment is properly aligned, `M-;' is still
+useful for moving directly to the start of the comment.
+
+ `C-u - C-x ;' (`kill-comment') kills the comment on the current
+line, if there is one. The indentation before the start of the comment
+is killed as well. If there does not appear to be a comment in the
+line, nothing happens. To reinsert the comment on another line, move
+to the end of that line, type first `C-y', and then `M-;' to realign
+the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x
+;' (`set-comment-column') with a negative argument. That command is
+programmed to call `kill-comment' when called with a negative argument.
+However, `kill-comment' is a valid command which you could bind
+directly to a key if you wanted to.
+
+Multiple Lines of Comments
+--------------------------
+
+ If you are typing a comment and want to continue it on another line,
+use the command `Meta-<LFD>' (`indent-new-comment-line'), which
+terminates the comment you are typing, creates a new blank line
+afterward, and begins a new comment indented under the old one. If
+Auto Fill mode is on and you go past the fill column while typing, the
+comment is continued in just this fashion. If point is not at the end
+of the line when you type `M-<LFD>', the text on the rest of the line
+becomes part of the new comment line.
+
+Options Controlling Comments
+----------------------------
+
+ The comment column is stored in the variable `comment-column'. You
+can explicitly set it to a number. Alternatively, the command `C-x ;'
+(`set-comment-column') sets the comment column to the column point is
+at. `C-u C-x ;' sets the comment column to match the last comment
+before point in the buffer, and then calls `Meta-;' to align the
+current line's comment under the previous one. Note that `C-u - C-x ;'
+runs the function `kill-comment' as described above.
+
+ `comment-column' is a per-buffer variable; altering the variable
+affects only the current buffer. You can also change the default value.
+*Note Locals::. Many major modes initialize this variable for the
+current buffer.
+
+ The comment commands recognize comments based on the regular
+expression that is the value of the variable `comment-start-skip'.
+This regexp should not match the null string. It may match more than
+the comment starting delimiter in the strictest sense of the word; for
+example, in C mode the value of the variable is `"/\\*+ *"', which
+matches extra stars and spaces after the `/*' itself. (Note that `\\'
+is needed in Lisp syntax to include a `\' in the string, which is needed
+to deny the first star its special meaning in regexp syntax. *Note
+Regexps::.)
+
+ When a comment command makes a new comment, it inserts the value of
+`comment-start' to begin it. The value of `comment-end' is inserted
+after point and will follow the text you will insert into the comment.
+In C mode, `comment-start' has the value `"/* "' and `comment-end' has
+the value `" */"'.
+
+ `comment-multi-line' controls how `M-<LFD>'
+(`indent-new-comment-line') behaves when used inside a comment. If
+`comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
+terminates the comment on the starting line and starts a new comment on
+the new following line. If `comment-multi-line' is not `nil', then
+`M-<LFD>' sets up the new following line as part of the same comment
+that was found on the starting line. This is done by not inserting a
+terminator on the old line and not inserting a starter on the new line.
+In languages where multi-line comments are legal, the value you choose
+for this variable is a matter of taste.
+
+ The variable `comment-indent-hook' should contain a function that is
+called to compute the indentation for a newly inserted comment or for
+aligning an existing comment. Major modes set this variable
+differently. The function is called with no arguments, but with point
+at the beginning of the comment, or at the end of a line if a new
+comment is to be inserted. The function should return the column in
+which the comment ought to start. For example, in Lisp mode, the
+indent hook function bases its decision on the number of semicolons
+that begin an existing comment and on the code in the preceding lines.
+
+\1f
+File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs
+
+Editing Without Unbalanced Parentheses
+======================================
+
+`M-('
+ Put parentheses around next sexp(s) (`insert-parentheses').
+
+`M-)'
+ Move past next close parenthesis and re-indent
+ (`move-over-close-and-reindent').
+
+ The commands `M-(' (`insert-parentheses') and `M-)'
+(`move-over-close-and-reindent') are designed to facilitate a style of
+editing which keeps parentheses balanced at all times. `M-(' inserts a
+pair of parentheses, either together as in `()', or, if given an
+argument, around the next several sexps, and leaves point after the open
+parenthesis. Instead of typing `( F O O )', you can type `M-( F O O',
+which has the same effect except for leaving the cursor before the
+close parenthesis. You can then type `M-)', which moves past the close
+parenthesis, deletes any indentation preceding it (in this example
+there is none), and indents with <LFD> after it.
+
+\1f
+File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs
+
+Completion for Lisp Symbols
+===========================
+
+ Completion usually happens in the minibuffer. An exception is
+completion for Lisp symbol names, which is available in all buffers.
+
+ The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
+Lisp symbol before point to be an abbreviation, and compares it against
+all non-trivial Lisp symbols currently known to Emacs. Any additional
+characters that they all have in common are inserted at point.
+Non-trivial symbols are those that have function definitions, values, or
+properties.
+
+ If there is an open-parenthesis immediately before the beginning of
+the partial symbol, only symbols with function definitions are
+considered as completions.
+
+ If the partial name in the buffer has more than one possible
+completion and they have no additional characters in common, a list of
+all possible completions is displayed in another window.
+
+\1f
+File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs
+
+Documentation Commands
+======================
+
+ As you edit Lisp code to be run in Emacs, you can use the commands
+`C-h f' (`describe-function') and `C-h v' (`describe-variable') to
+print documentation of functions and variables you want to call. These
+commands use the minibuffer to read the name of a function or variable
+to document, and display the documentation in a window.
+
+ For extra convenience, these commands provide default arguments
+based on the code in the neighborhood of point. `C-h f' sets the
+default to the function called in the innermost list containing point.
+`C-h v' uses the symbol name around or adjacent to point as its default.
+
+ The `M-x manual-entry' command gives you access to documentation on
+Unix commands, system calls, and libraries. The command reads a topic
+as an argument, and displays the Unix manual page for that topic.
+`manual-entry' always searches all 8 sections of the manual and
+concatenates all the entries it finds. For example, the topic
+`termcap' finds the description of the termcap library from section 3,
+followed by the description of the termcap data base from section 5.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs
+
+Change Logs
+===========
+
+ The Emacs command `M-x add-change-log-entry' helps you keep a record
+of when and why you have changed a program. It assumes that you have a
+file in which you write a chronological sequence of entries describing
+individual changes. The default is to store the change entries in a
+file called `ChangeLog' in the same directory as the file you are
+editing. The same `ChangeLog' file therefore records changes for all
+the files in a directory.
+
+ A change log entry starts with a header line that contains your name
+and the current date. Except for these header lines, every line in the
+change log starts with a tab. One entry can describe several changes;
+each change starts with a line starting with a tab and a star. `M-x
+add-change-log-entry' visits the change log file and creates a new entry
+unless the most recent entry is for today's date and your name. In
+either case, it adds a new line to start the description of another
+change just after the header line of the entry. When `M-x
+add-change-log-entry' is finished, all is prepared for you to edit in
+the description of what you changed and how. You must then save the
+change log file yourself.
+
+ The change log file is always visited in Indented Text mode, which
+means that <LFD> and auto-filling indent each new line like the previous
+line. This is convenient for entering the contents of an entry, which
+must be indented. *Note Text Mode::.
+
+ Here is an example of the formatting conventions used in the change
+log for Emacs:
+
+ Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
+
+ * xdisp.c (try_window_id):
+ If C-k is done at end of next-to-last line,
+ this fn updates window_end_vpos and cannot leave
+ window_end_pos nonnegative (it is zero, in fact).
+ If display is preempted before lines are output,
+ this is inconsistent. Fix by setting
+ blank_end_of_window to nonzero.
+
+ Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
+
+ * cmds.c (Fnewline):
+ Call the auto fill hook if appropriate.
+
+ * xdisp.c (try_window_id):
+ If point is found by compute_motion after xp, record that
+ permanently. If display_text_line sets point position wrong
+ (case where line is killed, point is at eob and that line is
+ not displayed), set it again in final compute_motion.
+
+\1f
+File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs
+
+Tags Tables
+===========
+
+ A "tags table" is a description of how a multi-file program is
+broken up into files. It lists the names of the component files and the
+names and positions of the functions (or other named subunits) in each
+file. Grouping the related files makes it possible to search or replace
+through all the files with one command. Recording the function names
+and positions makes possible the `M-.' command which finds the
+definition of a function by looking up which of the files it is in.
+
+ Tags tables are stored in files called "tags table files". The
+conventional name for a tags table file is `TAGS'.
+
+ Each entry in the tags table records the name of one tag, the name
+of the file that the tag is defined in (implicitly), and the position
+in that file of the tag's definition.
+
+ Just what names from the described files are recorded in the tags
+table depends on the programming language of the described file. They
+normally include all functions and subroutines, and may also include
+global variables, data types, and anything else convenient. Each name
+recorded is called a "tag".
+
+* Menu:
+
+* Tag Syntax:: Tag syntax for various types of code and text files.
+* Create Tags Table:: Creating a tags table with `etags'.
+* Select Tags Table:: How to visit a tags table.
+* Find Tag:: Commands to find the definition of a specific tag.
+* Tags Search:: Using a tags table for searching and replacing.
+* List Tags:: Listing and finding tags defined in a file.
+
+\1f
+File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags
+
+Source File Tag Syntax
+----------------------
+
+ Here is how tag syntax is defined for the most popular languages:
+
+ * In C code, any C function or typedef is a tag, and so are
+ definitions of `struct', `union' and `enum'. `#define' macro
+ definitions and `enum' constants are also tags, unless you specify
+ `--no-defines' when making the tags table. Similarly, global
+ variables are tags, unless you specify `--no-globals'. Use of
+ `--no-globals' and `--no-defines' can make the tags table file
+ much smaller.
+
+ * In C++ code, in addition to all the tag constructs of C code,
+ member functions are also recognized, and optionally member
+ variables if you use the `--members' option. Tags for variables
+ and functions in classes are named `CLASS::VARIABLE' and
+ `CLASS::FUNCTION'.
+
+ * In Java code, tags include all the constructs recognized in C++,
+ plus the `extends' and `implements' constructs. Tags for variables
+ and functions in classes are named `CLASS.VARIABLE' and
+ `CLASS.FUNCTION'.
+
+ * In LaTeX text, the argument of any of the commands `\chapter',
+ `\section', `\subsection', `\subsubsection', `\eqno', `\label',
+ `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
+ `\index', is a tag.
+
+ Other commands can make tags as well, if you specify them in the
+ environment variable `TEXTAGS' before invoking `etags'. The value
+ of this environment variable should be a colon-separated list of
+ commands names. For example,
+
+ TEXTAGS="def:newcommand:newenvironment"
+ export TEXTAGS
+
+ specifies (using Bourne shell syntax) that the commands `\def',
+ `\newcommand' and `\newenvironment' also define tags.
+
+ * In Lisp code, any function defined with `defun', any variable
+ defined with `defvar' or `defconst', and in general the first
+ argument of any expression that starts with `(def' in column zero,
+ is a tag.
+
+ * In Scheme code, tags include anything defined with `def' or with a
+ construct whose name starts with `def'. They also include
+ variables set with `set!' at top level in the file.
+
+ Several other languages are also supported:
+
+ * In assembler code, labels appearing at the beginning of a line,
+ followed by a colon, are tags.
+
+ * In Bison or Yacc input files, each rule defines as a tag the
+ nonterminal it constructs. The portions of the file that contain
+ C code are parsed as C code.
+
+ * In Cobol code, paragraphs names are the tags, i.e. any word
+ starting in column 8 and followed by a full stop.
+
+ * In Erlang code, the tags are the functions, records, and macros
+ defined in the file.
+
+ * In Fortran code, functions and subroutines are tags.
+
+ * In Objective C code, tags include Objective C definitions for
+ classes, class categories, methods and protocols.
+
+ * In Pascal code, the tags are the functions and procedures defined
+ in the file.
+
+ * In Perl code, the tags are the procedures defined by the `sub'
+ keyword.
+
+ * In Postscript code, the tags are the functions.
+
+ * In Prolog code, a tag name appears at the left margin.
+
+ You can also generate tags based on regexp matching (*note Create
+Tags Table::.) to handle other formats and languages.
+
+\1f
+File: xemacs.info, Node: Create Tags Table, Next: Select Tags Table, Prev: Tag Syntax, Up: Tags
+
+Creating Tags Tables
+--------------------
+
+ The `etags' program is used to create a tags table file. It knows
+the syntax of several languages, as described in *Note Tag Syntax::.
+Here is how to run `etags':
+
+ etags INPUTFILES...
+
+The `etags' program reads the specified files, and writes a tags table
+named `TAGS' in the current working directory. `etags' recognizes the
+language used in an input file based on its file name and contents.
+You can specify the language with the `--language=NAME' option,
+described below.
+
+ If the tags table data become outdated due to changes in the files
+described in the table, the way to update the tags table is the same
+way it was made in the first place. It is not necessary to do this
+often.
+
+ If the tags table fails to record a tag, or records it for the wrong
+file, then Emacs cannot possibly find its definition. However, if the
+position recorded in the tags table becomes a little bit wrong (due to
+some editing in the file that the tag definition is in), the only
+consequence is a slight delay in finding the tag. Even if the stored
+position is very wrong, Emacs will still find the tag, but it must
+search the entire file for it.
+
+ So you should update a tags table when you define new tags that you
+want to have listed, or when you move tag definitions from one file to
+another, or when changes become substantial. Normally there is no need
+to update the tags table after each edit, or even every day.
+
+ One tags table can effectively include another. Specify the included
+tags file name with the `--include=FILE' option when creating the file
+that is to include it. The latter file then acts as if it contained
+all the files specified in the included file, as well as the files it
+directly contains.
+
+ If you specify the source files with relative file names when you run
+`etags', the tags file will contain file names relative to the
+directory where the tags file was initially written. This way, you can
+move an entire directory tree containing both the tags file and the
+source files, and the tags file will still refer correctly to the source
+files.
+
+ If you specify absolute file names as arguments to `etags', then the
+tags file will contain absolute file names. This way, the tags file
+will still refer to the same files even if you move it, as long as the
+source files remain in the same place. Absolute file names start with
+`/', or with `DEVICE:/' on MS-DOS and Windows.
+
+ When you want to make a tags table from a great number of files, you
+may have problems listing them on the command line, because some systems
+have a limit on its length. The simplest way to circumvent this limit
+is to tell `etags' to read the file names from its standard input, by
+typing a dash in place of the file names, like this:
+
+ find . -name "*.[chCH]" -print | etags -
+
+ Use the option `--language=NAME' to specify the language explicitly.
+You can intermix these options with file names; each one applies to
+the file names that follow it. Specify `--language=auto' to tell
+`etags' to resume guessing the language from the file names and file
+contents. Specify `--language=none' to turn off language-specific
+processing entirely; then `etags' recognizes tags by regexp matching
+alone. `etags --help' prints the list of the languages `etags' knows,
+and the file name rules for guessing the language.
+
+ The `--regex' option provides a general way of recognizing tags
+based on regexp matching. You can freely intermix it with file names.
+Each `--regex' option adds to the preceding ones, and applies only to
+the following files. The syntax is:
+
+ --regex=/TAGREGEXP[/NAMEREGEXP]/
+
+where TAGREGEXP is used to match the lines to tag. It is always
+anchored, that is, it behaves as if preceded by `^'. If you want to
+account for indentation, just match any initial number of blanks by
+beginning your regular expression with `[ \t]*'. In the regular
+expressions, `\' quotes the next character, and `\t' stands for the tab
+character. Note that `etags' does not handle the other C escape
+sequences for special characters.
+
+ The syntax of regular expressions in `etags' is the same as in
+Emacs, augmented with the "interval operator", which works as in `grep'
+and `ed'. The syntax of an interval operator is `\{M,N\}', and its
+meaning is to match the preceding expression at least M times and up to
+N times.
+
+ You should not match more characters with TAGREGEXP than that needed
+to recognize what you want to tag. If the match is such that more
+characters than needed are unavoidably matched by TAGREGEXP, you may
+find useful to add a NAMEREGEXP, in order to narrow the tag scope. You
+can find some examples below.
+
+ The `-R' option deletes all the regexps defined with `--regex'
+options. It applies to the file names following it, as you can see
+from the following example:
+
+ etags --regex=/REG1/ voo.doo --regex=/REG2/ \
+ bar.ber -R --lang=lisp los.er
+
+Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
+according to their contents. `etags' also uses REG1 to recognize
+additional tags in `voo.doo', and both REG1 and REG2 to recognize
+additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
+regexp matching, to recognize tags in `los.er'.
+
+ Here are some more examples. The regexps are quoted to protect them
+from shell interpretation.
+
+Tag the `DEFVAR' macros in the emacs source files:
+
+ --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+
+Tag VHDL files (this example is a single long line, broken here for
+formatting reasons):
+
+ --language=none
+ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
+ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+
+Tag TCL files (this last example shows the usage of a NAMEREGEXP):
+
+ --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
+
+ For a list of the other available `etags' options, execute `etags
+--help'.
+
+\1f
+File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Create Tags Table, Up: Tags
+
+Selecting a Tags Table
+----------------------
+
+ At any time Emacs has one "selected" tags table, and all the commands
+for working with tags tables use the selected one. To select a tags
+table, use the variable `tag-table-alist'.
+
+ The value of `tag-table-alist' is a list that determines which
+`TAGS' files should be active for a given buffer. This is not really
+an association list, in that all elements are checked. The car of each
+element of this list is a pattern against which the buffers file name
+is compared; if it matches, then the cdr of the list should be the name
+of the tags table to use. If more than one element of this list
+matches the buffers file name, all of the associated tags tables are
+used. Earlier ones are searched first.
+
+ If the car of elements of this list are strings, they are treated as
+regular-expressions against which the file is compared (like the
+`auto-mode-alist'). If they are not strings, they are evaluated. If
+they evaluate to non-`nil', the current buffer is considered to match.
+
+ If the cdr of the elements of this list are strings, they are
+assumed to name a tags file. If they name a directory, the string
+`tags' is appended to them to get the file name. If they are not
+strings, they are evaluated and must return an appropriate string.
+
+ For example:
+
+ (setq tag-table-alist
+ '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
+ ("\\.el$" . "/usr/local/emacs/src/")
+ ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
+ ("" . "/usr/local/emacs/src/")
+ ))
+
+ The example defines the tags table alist in the following way:
+
+ * Anything in the directory `/usr/src/public/perl/' should use the
+ `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'.
+
+ * Files ending in `.el' should use the `TAGS' file
+ `/usr/local/emacs/src/TAGS'.
+
+ * Anything in or below the directory `/jbw/gnu/' should use the
+ `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'.
+
+ If you had a file called `/usr/jbw/foo.el', it would use both `TAGS'
+files,
+`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in
+that order), because it matches both patterns.
+
+ If the buffer-local variable `buffer-tag-table' is set, it names a
+tags table that is searched before all others when `find-tag' is
+executed from this buffer.
+
+ If there is a file called `TAGS' in the same directory as the file
+in question, then that tags file will always be used as well (after the
+`buffer-tag-table' but before the tables specified by this list).
+
+ If the variable `tags-file-name' is set, the `TAGS' file it names
+will apply to all buffers (for backwards compatibility.) It is searched
+first.
+
+ If the value of the variable `tags-always-build-completion-table' is
+`t', the tags file will always be added to the completion table without
+asking first, regardless of the size of the tags file.
+
+ The function `M-x visit-tags-table', is largely made obsolete by the
+variable `tag-table-alist', tells tags commands to use the tags table
+file FILE first. The FILE should be the name of a file created with
+the `etags' program. A directory name is also acceptable; it means the
+file `TAGS' in that directory. The function only stores the file name
+you provide in the variable `tags-file-name'. Emacs does not actually
+read in the tags table contents until you try to use them. You can set
+the variable explicitly instead of using `visit-tags-table'. The value
+of the variable `tags-file-name' is the name of the tags table used by
+all buffers. This is for backward compatibility, and is largely
+supplanted by the variable `tag-table-alist'.
+
+\1f
+File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags
+
+Finding a Tag
+-------------
+
+ The most important thing that a tags table enables you to do is to
+find the definition of a specific tag.
+
+`M-. TAG &OPTIONAL OTHER-WINDOW'
+ Find first definition of TAG (`find-tag').
+
+`C-u M-.'
+ Find next alternate definition of last tag specified.
+
+`C-x 4 . TAG'
+ Find first definition of TAG, but display it in another window
+ (`find-tag-other-window').
+
+ `M-.' (`find-tag') is the command to find the definition of a
+specified tag. It searches through the tags table for that tag, as a
+string, then uses the tags table information to determine the file in
+which the definition is used and the approximate character position of
+the definition in the file. Then `find-tag' visits the file, moves
+point to the approximate character position, and starts searching
+ever-increasing distances away for the text that should appear at the
+beginning of the definition.
+
+ If an empty argument is given (by typing <RET>), the sexp in the
+buffer before or around point is used as the name of the tag to find.
+*Note Lists::, for information on sexps.
+
+ The argument to `find-tag' need not be the whole tag name; it can be
+a substring of a tag name. However, there can be many tag names
+containing the substring you specify. Since `find-tag' works by
+searching the text of the tags table, it finds the first tag in the
+table that the specified substring appears in. To find other tags that
+match the substring, give `find-tag' a numeric argument, as in `C-u
+M-.'. This does not read a tag name, but continues searching the tag
+table's text for another tag containing the same substring last used.
+If your keyboard has a real <META> key, `M-0 M-.' is an easier
+alternative to `C-u M-.'.
+
+ If the optional second argument OTHER-WINDOW is non-`nil', it uses
+another window to display the tag. Multiple active tags tables and
+completion are supported.
+
+ Variables of note include the following:
+
+`tag-table-alist'
+ Controls which tables apply to which buffers.
+
+`tags-file-name'
+ Stores a default tags table.
+
+`tags-build-completion-table'
+ Controls completion behavior.
+
+`buffer-tag-table'
+ Specifies a buffer-local table.
+
+`make-tags-files-invisible'
+ Sets whether tags tables should be very hidden.
+
+`tag-mark-stack-max'
+ Specifies how many tags-based hops to remember.
+
+ Like most commands that can switch buffers, `find-tag' has another
+similar command that displays the new buffer in another window. `C-x 4
+.' invokes the function `find-tag-other-window'. (This key sequence
+ends with a period.)
+
+ Emacs comes with a tags table file `TAGS' (in the directory
+containing Lisp libraries) that includes all the Lisp libraries and all
+the C sources of Emacs. By specifying this file with `visit-tags-table'
+and then using `M-.' you can quickly look at the source of any Emacs
+function.
+
+\1f
+File: xemacs.info, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags
+
+Searching and Replacing with Tags Tables
+----------------------------------------
+
+ The commands in this section visit and search all the files listed
+in the selected tags table, one by one. For these commands, the tags
+table serves only to specify a sequence of files to search. A related
+command is `M-x grep' (*note Compilation::.).
+
+`M-x tags-search <RET> REGEXP <RET>'
+ Search for REGEXP through the files in the selected tags table.
+
+`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
+ Perform a `query-replace-regexp' on each file in the selected tags
+ table.
+
+`M-,'
+ Restart one of the commands above, from the current location of
+ point (`tags-loop-continue').
+
+ `M-x tags-search' reads a regexp using the minibuffer, then searches
+for matches in all the files in the selected tags table, one file at a
+time. It displays the name of the file being searched so you can
+follow its progress. As soon as it finds an occurrence, `tags-search'
+returns.
+
+ Having found one match, you probably want to find all the rest. To
+find one more match, type `M-,' (`tags-loop-continue') to resume the
+`tags-search'. This searches the rest of the current buffer, followed
+by the remaining files of the tags table.
+
+ `M-x tags-query-replace' performs a single `query-replace-regexp'
+through all the files in the tags table. It reads a regexp to search
+for and a string to replace with, just like ordinary `M-x
+query-replace-regexp'. It searches much like `M-x tags-search', but
+repeatedly, processing matches according to your input. *Note
+Replace::, for more information on query replace.
+
+ It is possible to get through all the files in the tags table with a
+single invocation of `M-x tags-query-replace'. But often it is useful
+to exit temporarily, which you can do with any input event that has no
+special query replace meaning. You can resume the query replace
+subsequently by typing `M-,'; this command resumes the last tags search
+or replace command that you did.
+
+ The commands in this section carry out much broader searches than the
+`find-tag' family. The `find-tag' commands search only for definitions
+of tags that match your substring or regexp. The commands
+`tags-search' and `tags-query-replace' find every occurrence of the
+regexp, as ordinary search commands and replace commands do in the
+current buffer.
+
+ These commands create buffers only temporarily for the files that
+they have to search (those which are not already visited in Emacs
+buffers). Buffers in which no match is found are quickly killed; the
+others continue to exist.
+
+ It may have struck you that `tags-search' is a lot like `grep'. You
+can also run `grep' itself as an inferior of Emacs and have Emacs show
+you the matching lines one by one. This works much like running a
+compilation; finding the source locations of the `grep' matches works
+like finding the compilation errors. *Note Compilation::.
+
+ If you wish to process all the files in a selected tags table, but
+`M-x tags-search' and `M-x tags-query-replace' are not giving you the
+desired result, you can use `M-x next-file'.
+
+`C-u M-x next-file'
+ With a numeric argument, regardless of its value, visit the first
+ file in the tags table and prepare to advance sequentially by
+ files.
+
+`M-x next-file'
+ Visit the next file in the selected tags table.
+
+\1f
+File: xemacs.info, Node: List Tags, Prev: Tags Search, Up: Tags
+
+Tags Table Inquiries
+--------------------
+
+`M-x list-tags'
+ Display a list of the tags defined in a specific program file.
+
+`M-x tags-apropos'
+ Display a list of all tags matching a specified regexp.
+
+ `M-x list-tags' reads the name of one of the files described by the
+selected tags table, and displays a list of all the tags defined in that
+file. The "file name" argument is really just a string to compare
+against the names recorded in the tags table; it is read as a string
+rather than a file name. Therefore, completion and defaulting are not
+available, and you must enter the string the same way it appears in the
+tag table. Do not include a directory as part of the file name unless
+the file name recorded in the tags table contains that directory.
+
+ `M-x tags-apropos' is like `apropos' for tags. It reads a regexp,
+then finds all the tags in the selected tags table whose entries match
+that regexp, and displays the tag names found.
+
+\1f
+File: xemacs.info, Node: Fortran, Next: Asm Mode, Prev: Tags, Up: Programs
+
+Fortran Mode
+============
+
+ Fortran mode provides special motion commands for Fortran statements
+and subprograms, and indentation commands that understand Fortran
+conventions of nesting, line numbers, and continuation statements.
+
+ Special commands for comments are provided because Fortran comments
+are unlike those of other languages.
+
+ Built-in abbrevs optionally save typing when you insert Fortran
+keywords.
+
+ Use `M-x fortran-mode' to switch to this major mode. Doing so calls
+the value of `fortran-mode-hook' as a function of no arguments if that
+variable has a non-`nil' value.
+
+* Menu:
+
+* Motion: Fortran Motion. Moving point by statements or subprograms.
+* Indent: Fortran Indent. Indentation commands for Fortran.
+* Comments: Fortran Comments. Inserting and aligning comments.
+* Columns: Fortran Columns. Measuring columns for valid Fortran.
+* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
+
+ Fortran mode was contributed by Michael Prange.
+
+\1f
+File: xemacs.info, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran
+
+Motion Commands
+---------------
+
+ Fortran mode provides special commands to move by subprograms
+(functions and subroutines) and by statements. There is also a command
+to put the region around one subprogram, which is convenient for
+killing it or moving it.
+
+`C-M-a'
+ Move to beginning of subprogram
+ (`beginning-of-fortran-subprogram').
+
+`C-M-e'
+ Move to end of subprogram (`end-of-fortran-subprogram').
+
+`C-M-h'
+ Put point at beginning of subprogram and mark at end
+ (`mark-fortran-subprogram').
+
+`C-c C-n'
+ Move to beginning of current or next statement (`fortran-next-
+ statement').
+
+`C-c C-p'
+ Move to beginning of current or previous statement (`fortran-
+ previous-statement').
+
+\1f
+File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran
+
+Fortran Indentation
+-------------------
+
+ Special commands and features are available for indenting Fortran
+code. They make sure various syntactic entities (line numbers, comment
+line indicators, and continuation line flags) appear in the columns
+that are required for standard Fortran.
+
+* Menu:
+
+* Commands: ForIndent Commands. Commands for indenting Fortran.
+* Numbers: ForIndent Num. How line numbers auto-indent.
+* Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
+* Vars: ForIndent Vars. Variables controlling Fortran indent style.
+
+\1f
+File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent
+
+Fortran Indentation Commands
+............................
+
+`<TAB>'
+ Indent the current line (`fortran-indent-line').
+
+`M-<LFD>'
+ Break the current line and set up a continuation line.
+
+`C-M-q'
+ Indent all the lines of the subprogram point is in
+ (`fortran-indent-subprogram').
+
+ <TAB> is redefined by Fortran mode to reindent the current line for
+Fortran (`fortran-indent-line'). Line numbers and continuation markers
+are indented to their required columns, and the body of the statement
+is independently indented, based on its nesting in the program.
+
+ The key `C-M-q' is redefined as `fortran-indent-subprogram', a
+command that reindents all the lines of the Fortran subprogram
+(function or subroutine) containing point.
+
+ The key `M-<LFD>' is redefined as `fortran-split-line', a command to
+split a line in the appropriate fashion for Fortran. In a non-comment
+line, the second half becomes a continuation line and is indented
+accordingly. In a comment line, both halves become separate comment
+lines.
+
+\1f
+File: xemacs.info, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Commands, Up: Fortran Indent
+
+Line Numbers and Continuation
+.............................
+
+ If a number is the first non-whitespace in the line, it is assumed
+to be a line number and is moved to columns 0 through 4. (Columns are
+always counted from 0 in XEmacs.) If the text on the line starts with
+the conventional Fortran continuation marker `$', it is moved to column
+5. If the text begins with any non whitespace character in column 5,
+it is assumed to be an unconventional continuation marker and remains
+in column 5.
+
+ Line numbers of four digits or less are normally indented one space.
+This amount is controlled by the variable `fortran-line-number-indent',
+which is the maximum indentation a line number can have. Line numbers
+are indented to right-justify them to end in column 4 unless that would
+require more than the maximum indentation. The default value of the
+variable is 1.
+
+ Simply inserting a line number is enough to indent it according to
+these rules. As each digit is inserted, the indentation is recomputed.
+To turn off this feature, set the variable
+`fortran-electric-line-number' to `nil'. Then inserting line numbers
+is like inserting anything else.
+
+\1f
+File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
+
+Syntactic Conventions
+.....................
+
+ Fortran mode assumes that you follow certain conventions that
+simplify the task of understanding a Fortran program well enough to
+indent it properly:
+
+ * Two nested `do' loops never share a `continue' statement.
+
+ * The same character appears in column 5 of all continuation lines.
+ It is the value of the variable `fortran-continuation-char'. By
+ default, this character is `$'.
+
+If you fail to follow these conventions, the indentation commands may
+indent some lines unaesthetically. However, a correct Fortran program
+will retain its meaning when reindented even if the conventions are not
+followed.
+
+\1f
+File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
+
+Variables for Fortran Indentation
+.................................
+
+ Several additional variables control how Fortran indentation works.
+
+`fortran-do-indent'
+ Extra indentation within each level of `do' statement (the default
+ is 3).
+
+`fortran-if-indent'
+ Extra indentation within each level of `if' statement (the default
+ is 3).
+
+`fortran-continuation-indent'
+ Extra indentation for bodies of continuation lines (the default is
+ 5).
+
+`fortran-check-all-num-for-matching-do'
+ If this is `nil', indentation assumes that each `do' statement
+ ends on a `continue' statement. Therefore, when computing
+ indentation for a statement other than `continue', it can save
+ time by not checking for a `do' statement ending there. If this
+ is non-`nil', indenting any numbered statement must check for a
+ `do' that ends there. The default is `nil'.
+
+`fortran-minimum-statement-indent'
+ Minimum indentation for Fortran statements. For standard Fortran,
+ this is 6. Statement bodies are always indented at least this
+ much.
+
+\1f
+File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran
+
+Comments
+--------
+
+ The usual Emacs comment commands assume that a comment can follow a
+line of code. In Fortran, the standard comment syntax requires an
+entire line to be just a comment. Therefore, Fortran mode replaces the
+standard Emacs comment commands and defines some new variables.
+
+ Fortran mode can also handle a non-standard comment syntax where
+comments start with `!' and can follow other text. Because only some
+Fortran compilers accept this syntax, Fortran mode will not insert such
+comments unless you have specified to do so in advance by setting the
+variable `comment-start' to `"!"' (*note Variables::.).
+
+`M-;'
+ Align comment or insert new comment (`fortran-comment-indent').
+
+`C-x ;'
+ Applies to nonstandard `!' comments only.
+
+`C-c ;'
+ Turn all lines of the region into comments, or (with arg) turn
+ them back into real code (`fortran-comment-region').
+
+ `M-;' in Fortran mode is redefined as the command
+`fortran-comment-indent'. Like the usual `M-;' command, it recognizes
+an existing comment and aligns its text appropriately. If there is no
+existing comment, a comment is inserted and aligned.
+
+ Inserting and aligning comments is not the same in Fortran mode as in
+other modes. When a new comment must be inserted, a full-line comment
+is inserted if the current line is blank. On a non-blank line, a
+non-standard `!' comment is inserted if you previously specified you
+wanted to use them. Otherwise a full-line comment is inserted on a new
+line before the current line.
+
+ Non-standard `!' comments are aligned like comments in other
+languages, but full-line comments are aligned differently. In a
+standard full-line comment, the comment delimiter itself must always
+appear in column zero. What can be aligned is the text within the
+comment. You can choose from three styles of alignment by setting the
+variable `fortran-comment-indent-style' to one of these values:
+
+`fixed'
+ The text is aligned at a fixed column, which is the value of
+ `fortran-comment-line-column'. This is the default.
+
+`relative'
+ The text is aligned as if it were a line of code, but with an
+ additional `fortran-comment-line-column' columns of indentation.
+
+`nil'
+ Text in full-line columns is not moved automatically.
+
+ You can also specify the character to be used to indent within
+full-line comments by setting the variable `fortran-comment-indent-char'
+to the character you want to use.
+
+ Fortran mode introduces two variables `comment-line-start' and
+`comment-line-start-skip', which do for full-line comments what
+`comment-start' and `comment-start-skip' do for ordinary text-following
+comments. Normally these are set properly by Fortran mode, so you do
+not need to change them.
+
+ The normal Emacs comment command `C-x ;' has not been redefined. It
+can therefore be used if you use `!' comments, but is useless in
+Fortran mode otherwise.
+
+ The command `C-c ;' (`fortran-comment-region') turns all the lines
+of the region into comments by inserting the string `C$$$' at the front
+of each one. With a numeric arg, the region is turned back into live
+code by deleting `C$$$' from the front of each line. You can control
+the string used for the comments by setting the variable
+`fortran-comment-region'. Note that here we have an example of a
+command and a variable with the same name; the two uses of the name
+never conflict because in Lisp and in Emacs it is always clear from the
+context which one is referred to.
+
+\1f
+File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran
+
+Columns
+-------
+
+`C-c C-r'
+ Displays a "column ruler" momentarily above the current line
+ (`fortran-column-ruler').
+
+`C-c C-w'
+ Splits the current window horizontally so that it is 72 columns
+ wide. This may help you avoid going over that limit
+ (`fortran-window-create').
+
+ The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
+above the current line. The comment ruler consists of two lines of
+text that show you the locations of columns with special significance
+in Fortran programs. Square brackets show the limits of the columns for
+line numbers, and curly brackets show the limits of the columns for the
+statement body. Column numbers appear above them.
+
+ Note that the column numbers count from zero, as always in XEmacs.
+As a result, the numbers may not be those you are familiar with; but the
+actual positions in the line are standard Fortran.
+
+ The text used to display the column ruler is the value of the
+variable `fortran-comment-ruler'. By changing this variable, you can
+change the display.
+
+ For even more help, use `C-c C-w' (`fortran-window-create'), a
+command which splits the current window horizontally, resulting in a
+window 72 columns wide. When you edit in this window, you can
+immediately see when a line gets too wide to be correct Fortran.
+
+\1f
+File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran
+
+Fortran Keyword Abbrevs
+-----------------------
+
+ Fortran mode provides many built-in abbrevs for common keywords and
+declarations. These are the same sort of abbrevs that you can define
+yourself. To use them, you must turn on Abbrev mode. *note Abbrevs::..
+
+ The built-in abbrevs are unusual in one way: they all start with a
+semicolon. You cannot normally use semicolon in an abbrev, but Fortran
+mode makes this possible by changing the syntax of semicolon to "word
+constituent".
+
+ For example, one built-in Fortran abbrev is `;c' for `continue'. If
+you insert `;c' and then insert a punctuation character such as a space
+or a newline, the `;c' changes automatically to `continue', provided
+Abbrev mode is enabled.
+
+ Type `;?' or `;C-h' to display a list of all built-in Fortran
+abbrevs and what they stand for.
+
+\1f
+File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs
+
+Asm Mode
+========
+
+ Asm mode is a major mode for editing files of assembler code. It
+defines these commands:
+
+`<TAB>'
+ `tab-to-tab-stop'.
+
+`<LFD>'
+ Insert a newline and then indent using `tab-to-tab-stop'.
+
+`:'
+ Insert a colon and then remove the indentation from before the
+ label preceding colon. Then do `tab-to-tab-stop'.
+
+`;'
+ Insert or align a comment.
+
+ The variable `asm-comment-char' specifies which character starts
+comments in assembler syntax.
+
+\1f
+File: xemacs.info, Node: Running, Next: Packages, Prev: Programs, Up: Top
+
+Compiling and Testing Programs
+******************************
+
+ The previous chapter discusses the Emacs commands that are useful for
+making changes in programs. This chapter deals with commands that
+assist in the larger process of developing and maintaining programs.
+
+* Menu:
+
+* Compilation:: Compiling programs in languages other than Lisp
+ (C, Pascal, etc.)
+* Modes: Lisp Modes. Various modes for editing Lisp programs, with
+ different facilities for running the Lisp programs.
+* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs.
+* Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
+* Debug: Lisp Debug. Debugging Lisp programs running in Emacs.
+* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
+* External Lisp:: Communicating through Emacs with a separate Lisp.
+
+\1f
+File: xemacs.info, Node: Compilation, Next: Lisp Modes, Prev: Running, Up: Running
+
+Running "make", or Compilers Generally
+======================================
+
+ Emacs can run compilers for non-interactive languages like C and
+Fortran as inferior processes, feeding the error log into an Emacs
+buffer. It can also parse the error messages and visit the files in
+which errors are found, moving point to the line where the error
+occurred.
+
+`M-x compile'
+ Run a compiler asynchronously under Emacs, with error messages to
+ `*compilation*' buffer.
+
+`M-x grep'
+ Run `grep' asynchronously under Emacs, with matching lines listed
+ in the buffer named `*compilation*'.
+
+`M-x kill-compilation'
+ Kill the process made by the `M-x compile' command.
+
+`M-x kill-grep'
+ Kill the running compilation or `grep' subprocess.
+
+`C-x `'
+ Visit the next compiler error message or `grep' match.
+
+ To run `make' or another compiler, type `M-x compile'. This command
+reads a shell command line using the minibuffer, then executes the
+specified command line in an inferior shell with output going to the
+buffer named `*compilation*'. By default, the current buffer's default
+directory is used as the working directory for the execution of the
+command; therefore, the makefile comes from this directory.
+
+ When the shell command line is read, the minibuffer appears
+containing a default command line (the command you used the last time
+you typed `M-x compile'). If you type just <RET>, the same command
+line is used again. The first `M-x compile' provides `make -k' as the
+default. The default is taken from the variable `compile-command'; if
+the appropriate compilation command for a file is something other than
+`make -k', it can be useful to have the file specify a local value for
+`compile-command' (*note File Variables::.).
+
+ When you start a compilation, the buffer `*compilation*' is
+displayed in another window but not selected. Its mode line displays
+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
+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
+compilation prompts for confirmation before actually killing a
+compilation that is running.
+
+ To parse the compiler error messages, type `C-x `' (`next-error').
+The character following `C-x' is the grave accent, not the single
+quote. The command displays the buffer `*compilation*' in one window
+and the buffer in which the next error occurred in another window.
+Point in that buffer is moved to the line where the error was found.
+The corresponding error message is scrolled to the top of the window in
+which `*compilation*' is displayed.
+
+ The first time you use `C-x `' after the start of a compilation, it
+parses all the error messages, visits all the files that have error
+messages, and creates markers pointing at the lines the error messages
+refer to. It then moves to the first error message location.
+Subsequent uses of `C-x `' advance down the data set up by the first
+use. When the preparsed error messages are exhausted, the next `C-x `'
+checks for any more error messages that have come in; this is useful if
+you start editing compiler errors while compilation is still going on.
+If no additional error messages have come in, `C-x `' reports an error.
+
+ `C-u C-x `' discards the preparsed error message data and parses the
+`*compilation*' buffer again, then displays the first error. This way,
+you can process the same set of errors again.
+
+ Instead of running a compiler, you can run `grep' and see the lines
+on which matches were found. To do this, type `M-x grep' with an
+argument line that contains the same arguments you would give to
+`grep': a `grep'-style regexp (usually in single quotes to quote the
+shell's special characters) followed by filenames, which may use
+wildcard characters. The output from `grep' goes in the
+`*compilation*' buffer. You can use `C-x `' to find the lines that
+match as if they were compilation errors.
+
+ Note: a shell is used to run the compile command, but the shell is
+not run in interactive mode. In particular, this means that the shell
+starts up with no prompt. If you find your usual shell prompt making an
+unsightly appearance in the `*compilation*' buffer, it means you have
+made a mistake in your shell's initialization file (`.cshrc' or `.shrc'
+or ...) by setting the prompt unconditionally. The shell
+initialization file should set the prompt only if there already is a
+prompt. Here's how to do it in `csh':
+
+ if ($?prompt) set prompt = ...
+
+\1f
+File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running
+
+Major Modes for Lisp
+====================
+
+ Emacs has four different major modes for Lisp. They are the same in
+terms of editing commands, but differ in the commands for executing Lisp
+expressions.
+
+Emacs-Lisp mode
+ The mode for editing source files of programs to run in Emacs Lisp.
+ This mode defines `C-M-x' to evaluate the current defun. *Note
+ Lisp Libraries::.
+
+Lisp Interaction mode
+ The mode for an interactive session with Emacs Lisp. It defines
+ <LFD> to evaluate the sexp before point and insert its value in the
+ buffer. *Note Lisp Interaction::.
+
+Lisp mode
+ The mode for editing source files of programs that run in other
+ dialects of Lisp than Emacs Lisp. This mode defines `C-M-x' to
+ send the current defun to an inferior Lisp process. *Note
+ External Lisp::.
+
+Inferior Lisp mode
+ The mode for an interactive session with an inferior Lisp process.
+ This mode combines the special features of Lisp mode and Shell mode
+ (*note Shell Mode::.).
+
+Scheme mode
+ Like Lisp mode but for Scheme programs.
+
+Inferior Scheme mode
+ The mode for an interactive session with an inferior Scheme
+ process.
+
+\1f
+File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
+
+Libraries of Lisp Code for Emacs
+================================
+
+ Lisp code for Emacs editing commands is stored in files whose names
+conventionally end in `.el'. This ending tells Emacs to edit them in
+Emacs-Lisp mode (*note Lisp Modes::.).
+
+* Menu:
+
+* Loading:: Loading libraries of Lisp code into Emacs for use.
+* Compiling Libraries:: Compiling a library makes it load and run faster.
+* Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
+
+Loading Libraries
+-----------------
+
+`M-x load-file FILE'
+ Load the file FILE of Lisp code.
+
+`M-x load-library LIBRARY'
+ Load the library named LIBRARY.
+
+`M-x locate-library LIBRARY &optional NOSUFFIX'
+ Show the full path name of Emacs library LIBRARY.
+
+ To execute a file of Emacs Lisp, use `M-x load-file'. This command
+reads the file name you provide in the minibuffer, then executes the
+contents of that file as Lisp code. It is not necessary to visit the
+file first; in fact, this command reads the file as found on disk, not
+the text in an Emacs buffer.
+
+ Once a file of Lisp code is installed in the Emacs Lisp library
+directories, users can load it using `M-x load-library'. Programs can
+load it by calling `load-library', or with `load', a more primitive
+function that is similar but accepts some additional arguments.
+
+ `M-x load-library' differs from `M-x load-file' in that it searches
+a sequence of directories and tries three file names in each directory.
+The three names are: first, the specified name with `.elc' appended;
+second, the name with `.el' appended; third, the specified name alone.
+A `.elc' file would be the result of compiling the Lisp file into byte
+code; if possible, it is loaded in preference to the Lisp file itself
+because the compiled file loads and runs faster.
+
+ Because the argument to `load-library' is usually not in itself a
+valid file name, file name completion is not available. In fact, when
+using this command, you usually do not know exactly what file name will
+be used.
+
+ The sequence of directories searched by `M-x load-library' is
+specified by the variable `load-path', a list of strings that are
+directory names. The elements of this list may not begin with "`~'",
+so you must call `expand-file-name' on them before adding them to the
+list. The default value of the list contains the directory where the
+Lisp code for Emacs itself is stored. If you have libraries of your
+own, put them in a single directory and add that directory to
+`load-path'. `nil' in this list stands for the current default
+directory, but it is probably not a good idea to put `nil' in the list.
+If you start wishing that `nil' were in the list, you should probably
+use `M-x load-file' for this case.
+
+ The variable is initialized by the EMACSLOADPATH environment
+variable. If no value is specified, the variable takes the default value
+specified in the file `paths.h' when Emacs was built. If a path isn't
+specified in `paths.h', a default value is obtained from the file
+system, near the directory in which the Emacs executable resides.
+
+ Like `M-x load-library', `M-x locate-library' searches the
+directories in `load-path' to find the file that `M-x load-library'
+would load. If the optional second argument NOSUFFIX is non-`nil', the
+suffixes `.elc' or `.el' are not added to the specified name LIBRARY
+(like calling `load' instead of `load-library').
+
+ You often do not have to give any command to load a library, because
+the commands defined in the library are set up to "autoload" that
+library. Running any of those commands causes `load' to be called to
+load the library; this replaces the autoload definitions with the real
+ones from the library.
+
+ If autoloading a file does not finish, either because of an error or
+because of a `C-g' quit, all function definitions made by the file are
+undone automatically. So are any calls to `provide'. As a
+consequence, the entire file is loaded a second time if you use one of
+the autoloadable commands again. This prevents problems when the
+command is no longer autoloading but is working incorrectly because the
+file was only partially loaded. Function definitions are undone only
+for autoloading; explicit calls to `load' do not undo anything if
+loading is not completed.
+
+ The variable `after-load-alist' takes an alist of expressions to be
+evaluated when particular files are loaded. Each element has the form
+`(FILENAME forms...)'. When `load' is run and the filename argument is
+FILENAME, the forms in the corresponding element are executed at the
+end of loading.
+
+ FILENAME must match exactly. Normally FILENAME is the name of a
+library, with no directory specified, since that is how load is
+normally called. An error in `forms' does not undo the load, but it
+does prevent execution of the rest of the `forms'.
+
+\1f
+File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries
+
+Compiling Libraries
+-------------------
+
+ Emacs Lisp code can be compiled into byte-code which loads faster,
+takes up less space when loaded, and executes faster.
+
+`M-x batch-byte-compile'
+ Run byte-compile-file on the files remaining on the command line.
+
+`M-x byte-compile-buffer &optional BUFFER'
+ Byte-compile and evaluate contents of BUFFER (default is current
+ buffer).
+
+`M-x byte-compile-file'
+ Compile a file of Lisp code named FILENAME into a file of byte
+ code.
+
+`M-x byte-compile-and-load-file FILENAME'
+ Compile a file of Lisp code named FILENAME into a file of byte
+ code and load it.
+
+`M-x byte-recompile-directory DIRECTORY'
+ Recompile every `.el' file in DIRECTORY that needs recompilation.
+
+`M-x disassemble'
+ Print disassembled code for OBJECT on (optional) STREAM.
+
+`M-x make-obsolete FUNCTION NEW'
+ Make the byte-compiler warn that FUNCTION is obsolete and NEW
+ should be used instead.
+
+ `byte-compile-file' creates a byte-code compiled file from an
+Emacs-Lisp source file. The default argument for this function is the
+file visited in the current buffer. The function reads the specified
+file, compiles it into byte code, and writes an output file whose name
+is made by appending `c' to the input file name. Thus, the file
+`rmail.el' would be compiled into `rmail.elc'. To compile a file of
+Lisp code named FILENAME into a file of byte code and then load it, use
+`byte-compile-and-load-file'. To compile and evaluate Lisp code in a
+given buffer, use `byte-compile-buffer'.
+
+ To recompile all changed Lisp files in a directory, use `M-x
+byte-recompile-directory'. Specify just the directory name as an
+argument. Each `.el' file that has been byte-compiled before is
+byte-compiled again if it has changed since the previous compilation.
+A numeric argument to this command tells it to offer to compile each
+`.el' file that has not been compiled yet. You must answer `y' or `n'
+to each offer.
+
+ You can use the function `batch-byte-compile' to invoke Emacs
+non-interactively from the shell to do byte compilation. When you use
+this function, the files to be compiled are specified with command-line
+arguments. Use a shell command of the form:
+
+ emacs -batch -f batch-byte-compile FILES...
+
+ Directory names may also be given as arguments; in that case,
+`byte-recompile-directory' is invoked on each such directory.
+`batch-byte-compile' uses all remaining command-line arguments as file
+or directory names, then kills the Emacs process.
+
+ `M-x disassemble' explains the result of byte compilation. Its
+argument is a function name. It displays the byte-compiled code in a
+help window in symbolic form, one instruction per line. If the
+instruction refers to a variable or constant, that is shown, too.
+
+\1f
+File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
+
+Converting Mocklisp to Lisp
+---------------------------
+
+ XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
+To convert a Mocklisp file, visit it and then type `M-x
+convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file
+in a file whose name ends in `.el' and use the new file as a Lisp
+library.
+
+ You cannot currently byte-compile converted Mocklisp code. The
+reason is that converted Mocklisp code uses some special Lisp features
+to deal with Mocklisp's incompatible ideas of how arguments are
+evaluated and which values signify "true" or "false".
+
+\1f
+File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
+
+Evaluating Emacs-Lisp Expressions
+=================================
+
+ Lisp programs intended to be run in Emacs should be edited in
+Emacs-Lisp mode; this will happen automatically for file names ending in
+`.el'. By contrast, Lisp mode itself should be used for editing Lisp
+programs intended for other Lisp systems. Emacs-Lisp mode can be
+selected with the command `M-x emacs-lisp-mode'.
+
+ For testing of Lisp programs to run in Emacs, it is useful to be able
+to evaluate part of the program as it is found in the Emacs buffer. For
+example, if you change the text of a Lisp function definition and then
+evaluate the definition, Emacs installs the change for future calls to
+the function. Evaluation of Lisp expressions is also useful in any
+kind of editing task for invoking non-interactive functions (functions
+that are not commands).
+
+`M-<ESC>'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the minibuffer (`eval-expression').
+
+`C-x C-e'
+ Evaluate the Lisp expression before point, and print the value in
+ the minibuffer (`eval-last-sexp').
+
+`C-M-x'
+ Evaluate the defun containing point or after point, and print the
+ value in the minibuffer (`eval-defun').
+
+`M-x eval-region'
+ Evaluate all the Lisp expressions in the region.
+
+`M-x eval-current-buffer'
+ Evaluate all the Lisp expressions in the buffer.
+
+ `M-<ESC>' (`eval-expression') is the most basic command for
+evaluating a Lisp expression interactively. It reads the expression
+using the minibuffer, so you can execute any expression on a buffer
+regardless of what the buffer contains. When evaluation is complete,
+the current buffer is once again the buffer that was current when
+`M-<ESC>' was typed.
+
+ `M-<ESC>' can easily confuse users, especially on keyboards with
+autorepeat, where it can result from holding down the <ESC> key for too
+long. Therefore, `eval-expression' is normally a disabled command.
+Attempting to use this command asks for confirmation and gives you the
+option of enabling it; once you enable the command, you are no longer
+required to confirm. *Note Disabling::.
+
+ In Emacs-Lisp mode, the key `C-M-x' is bound to the function
+`eval-defun', which parses the defun containing point or following point
+as a Lisp expression and evaluates it. The value is printed in the echo
+area. This command is convenient for installing in the Lisp environment
+changes that you have just made in the text of a function definition.
+
+ The command `C-x C-e' (`eval-last-sexp') performs a similar job but
+is available in all major modes, not just Emacs-Lisp mode. It finds
+the sexp before point, reads it as a Lisp expression, evaluates it, and
+prints the value in the echo area. It is sometimes useful to type in an
+expression and then, with point still after it, type `C-x C-e'.
+
+ If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
+value by inserting it into the current buffer at point, rather than in
+the echo area. The argument value does not matter.
+
+ The most general command for evaluating Lisp expressions from a
+buffer is `eval-region'. `M-x eval-region' parses the text of the
+region as one or more Lisp expressions, evaluating them one by one.
+`M-x eval-current-buffer' is similar, but it evaluates the entire
+buffer. This is a reasonable way to install the contents of a file of
+Lisp code that you are just ready to test. After finding and fixing a
+bug, use `C-M-x' on each function that you change, to keep the Lisp
+world in step with the source file.
+
+\1f
+File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
+
+The Emacs-Lisp Debugger
+=======================
+
+ XEmacs contains a debugger for Lisp programs executing inside it.
+This debugger is normally not used; many commands frequently get Lisp
+errors when invoked in inappropriate contexts (such as `C-f' at the end
+of the buffer) and it would be unpleasant to enter a special debugging
+mode in this case. When you want to make Lisp errors invoke the
+debugger, you must set the variable `debug-on-error' to non-`nil'.
+Quitting with `C-g' is not considered an error, and `debug-on-error'
+has no effect on the handling of `C-g'. However, if you set
+`debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This
+can be useful for debugging an infinite loop; type `C-g' once the loop
+has had time to reach its steady state. `debug-on-quit' has no effect
+on errors.
+
+ You can make Emacs enter the debugger when a specified function is
+called or at a particular place in Lisp code. Use `M-x debug-on-entry'
+with argument FUN-NAME to have Emacs enter the debugger as soon as
+FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
+function stop entering the debugger when called. (Redefining the
+function also does this.) To enter the debugger from some other place
+in Lisp code, you must insert the expression `(debug)' there and
+install the changed code with `C-M-x'. *Note Lisp Eval::.
+
+ When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named `*Backtrace*' in another
+window. The backtrace buffer contains one line for each level of Lisp
+function execution currently going on. At the beginning of the buffer
+is a message describing the reason that the debugger was invoked, for
+example, an error message if it was invoked due to an error.
+
+ The backtrace buffer is read-only and is in Backtrace mode, a special
+major mode in which letters are defined as debugger commands. The
+usual Emacs editing commands are available; you can switch windows to
+examine the buffer that was being edited at the time of the error, and
+you can switch buffers, visit files, and perform any other editing
+operations. However, the debugger is a recursive editing level (*note
+Recursive Edit::.); it is a good idea to return to the backtrace buffer
+and explictly exit the debugger when you don't want to use it any more.
+Exiting the debugger kills the backtrace buffer.
+
+ The contents of the backtrace buffer show you the functions that are
+executing and the arguments that were given to them. It also allows you
+to specify a stack frame by moving point to the line describing that
+frame. The frame whose line point is on is considered the "current
+frame". Some of the debugger commands operate on the current frame.
+Debugger commands are mainly used for stepping through code one
+expression at a time. Here is a list of them:
+
+`c'
+ Exit the debugger and continue execution. In most cases,
+ execution of the program continues as if the debugger had never
+ been entered (aside from the effect of any variables or data
+ structures you may have changed while inside the debugger). This
+ includes entry to the debugger due to function entry or exit,
+ explicit invocation, and quitting or certain errors. Most errors
+ cannot be continued; trying to continue an error usually causes
+ the same error to occur again.
+
+`d'
+ Continue execution, but enter the debugger the next time a Lisp
+ function is called. This allows you to step through the
+ subexpressions of an expression, and see what the subexpressions
+ do and what values they compute.
+
+ When you enter the debugger this way, Emacs flags the stack frame
+ for the function call from which you entered. The same function
+ is then called when you exit the frame. To cancel this flag, use
+ `u'.
+
+`b'
+ Set up to enter the debugger when the current frame is exited.
+ Frames that invoke the debugger on exit are flagged with stars.
+
+`u'
+ Don't enter the debugger when the current frame is exited. This
+ cancels a `b' command on a frame.
+
+`e'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the echo area. This is equivalent to the command
+ `M-<ESC>', except that `e' is not normally disabled like `M-<ESC>'.
+
+`q'
+ Terminate the program being debugged; return to top-level Emacs
+ command execution.
+
+ If the debugger was entered due to a `C-g' but you really want to
+ quit, not to debug, use the `q' command.
+
+`r'
+ Return a value from the debugger. The value is computed by
+ reading an expression with the minibuffer and evaluating it.
+
+ The value returned by the debugger makes a difference when the
+ debugger was invoked due to exit from a Lisp call frame (as
+ requested with `b'); then the value specified in the `r' command
+ is used as the value of that frame.
+
+ The debugger's return value also matters with many errors. For
+ example, `wrong-type-argument' errors will use the debugger's
+ return value instead of the invalid argument; `no-catch' errors
+ will use the debugger value as a throw tag instead of the tag that
+ was not found. If an error was signaled by calling the Lisp
+ function `signal', the debugger's return value is returned as the
+ value of `signal'.
+
+\1f
+File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
+
+Lisp Interaction Buffers
+========================
+
+ The buffer `*scratch*', which is selected when Emacs starts up, is
+provided for evaluating Lisp expressions interactively inside Emacs.
+Both the expressions you evaluate and their output goes in the buffer.
+
+ The `*scratch*' buffer's major mode is Lisp Interaction mode, which
+is the same as Emacs-Lisp mode except for one command, <LFD>. In
+Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
+mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
+the Lisp expression before point, evaluates it, and inserts the value
+in printed representation before point.
+
+ The way to use the `*scratch*' buffer is to insert Lisp expressions
+at the end, ending each one with <LFD> so that it will be evaluated.
+The result is a complete typescript of the expressions you have
+evaluated and their values.
+
+ The rationale for this feature is that Emacs must have a buffer when
+it starts up, but that buffer is not useful for editing files since a
+new buffer is made for every file that you visit. The Lisp interpreter
+typescript is the most useful thing I can think of for the initial
+buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
+Interaction mode.
+
+\1f
+File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running
+
+Running an External Lisp
+========================
+
+ Emacs has facilities for running programs in other Lisp systems.
+You can run a Lisp process as an inferior of Emacs, and pass
+expressions to it to be evaluated. You can also pass changed function
+definitions directly from the Emacs buffers in which you edit the Lisp
+programs to the inferior Lisp process.
+
+ To run an inferior Lisp process, type `M-x run-lisp'. This runs the
+program named `lisp', the same program you would run by typing `lisp'
+as a shell command, with both input and output going through an Emacs
+buffer named `*lisp*'. In other words, any "terminal output" from Lisp
+will go into the buffer, advancing point, and any "terminal input" for
+Lisp comes from text in the buffer. To give input to Lisp, go to the
+end of the buffer and type the input, terminated by <RET>. The
+`*lisp*' buffer is in Inferior Lisp mode, which has all the special
+characteristics of Lisp mode and Shell mode (*note Shell Mode::.).
+
+ Use Lisp mode to run the source files of programs in external Lisps.
+You can select this mode with `M-x lisp-mode'. It is used automatically
+for files whose names end in `.l' or `.lisp', as most Lisp systems
+usually expect.
+
+ When you edit a function in a Lisp program you are running, the
+easiest way to send the changed definition to the inferior Lisp process
+is the key `C-M-x'. In Lisp mode, this key runs the function
+`lisp-send-defun', which finds the defun around or following point and
+sends it as input to the Lisp process. (Emacs can send input to any
+inferior process regardless of what buffer is current.)
+
+ Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
+to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
+programs to be run in Emacs): in both modes it has the effect of
+installing the function definition that point is in, but the way of
+doing so is different according to where the relevant Lisp environment
+is found. *Note Lisp Modes::.
+
+\1f
+File: xemacs.info, Node: Packages, Next: Abbrevs, Prev: Running, Up: Top
+
+Packages
+========
+
+ The XEmacs 21 distribution comes only with a very basic set of
+built-in modes and packages. Most of the packages that were part of
+the distribution of earlier versions of XEmacs are now available
+separately. The installer as well as the user can choose which
+packages to install; the actual installation process is easy. This
+gives an installer the ability to tailor an XEmacs installation for
+local needs with safe removal of unnecessary code.
+
+* Menu:
+
+* Package Terminology:: Understanding different kinds of packages.
+* Using Packages:: How to install and use packages.
+* Building Packages:: Building packages from sources.
+
+\1f
+File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages
+
+Package Flavors
+---------------
+
+ There are two main flavors of packages.
+
+ * Regular Packages A regular package is one in which multiple files
+ are involved and one may not in general safely remove any of them.
+
+ * Single-File Packages A single-file package is an aggregate
+ collection of thematically related but otherwise independent lisp
+ files. These files are bundled together for download convenience
+ and individual files may be deleted at will without any loss of
+ functionality.
+
+Package Distributions
+---------------------
+
+ XEmacs Lisp packages are distributed in two ways, depending on the
+intended use. Binary Packages are for installers and end-users and may
+be installed directly into an XEmacs package directory. Source Packages
+are for developers and include all files necessary for rebuilding
+bytecompiled lisp and creating tarballs for distribution.
+
+Binary Packages
+---------------
+
+ Binary packages may be installed directly into an XEmacs package
+hierarchy.
+
+Source Packages
+---------------
+
+ Source packages contain all of the Package author's (where
+appropriate in regular packages) source code plus all of the files
+necessary to build distribution tarballs (Unix Tar format files,
+gzipped for space savings).
+
+\1f
+File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
+
+Getting Started
+---------------
+
+ When you first download XEmacs 21, you will usually first grab the
+"core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the
+21.0 by the current version number.) The core distribution contains
+the sources of XEmacs and a minimal set of Emacs Lisp files, which are
+in the subdirectory named `lisp'. This subdirectory used to contain
+all Emacs Lisp files distributed with XEmacs. Now, to conserve disk
+space, most non-essential packages were made optional.
+
+Choosing the Packages You Need
+------------------------------
+
+ The available packages can currently be found in the same ftp
+directory where you grabbed the core distribution from, and are located
+in the subdirectory `packages/binary-packages'. Package file names
+follow the naming convention `<package-name>-<version>-pkg.tar.gz'.
+
+ If you have EFS *Note (EFS)::, packages can be installed over the
+network. Alternatively, if you have copies of the packages locally,
+you can install packages from a local disk or CDROM.
+
+ The file `etc/PACKAGES' in the core distribution contains a list of
+the packages available at the time of the XEmacs release. Packages are
+also listed on the `Options' menu under:
+
+ Options->Customize->Emacs->Packages
+
+ However, don't select any of these menu picks unless you actually
+want to install the given package (and have properly configured your
+system to do so).
+
+ You can also get a list of available packages, and whether or not
+they are installed, using the visual package browser and installer.
+You can access it via the menus:
+
+ Options->Manage Packages->List & Install
+
+ Or, you can get to it via the keyboard:
+
+ M-x pui-list-packages
+
+ Hint to system administrators of multi-user systems: it might be a
+good idea to install all packages and not interfere with the wishes of
+your users.
+
+ If you can't find which package provides the feature you require, try
+using the `package-get-package-provider' function. Eg., if you know
+that you need `thingatpt', type:
+
+ M-x package-get-package-provider RET thingatpt
+
+ which will return something like (fsf-compat "1.06"). You can the use
+one of the methods above for installing the package you want.
+
+XEmacs and Installing Packages
+------------------------------
+
+ Normally, packages are installed over the network, using EFS *Note
+(EFS)::. However, you may not have network access, or you may already
+have some or all of the packages on a local disk, such as a CDROM. If
+you want to install from a local disk, you must first tell XEmacs where
+to find the package binaries. This is done by adding a line like the
+following to your `.emacs' file:
+
+ (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
+ package-get-remote))
+
+ Here, you'd change `/my/path/to/package/binaries' to be the path to
+your local package binaries. Next, restart XEmacs, and you're ready to
+go (advanced users can just re-evaluate the sexp).
+
+ If you are installing from a temporary, one-time directory, you can
+also add these directory names to `package-get-remote' using:
+
+ M-x pui-add-install-directory
+
+ Note, however, that any directories added using this function are not
+saved; this information will be lost when you quit XEmacs.
+
+ If you're going to install over the network, you only have to insure
+that EFS *Note (EFS):: works, and that it can get outside a firewall, if
+you happen to be behind one. You shouldn't have to do anything else;
+XEmacs already knows where to go. However you can add your own mirrors
+to this list. See `package-get-remote'.
+
+ The easiest way to install a package is to use the visual package
+browser and installer, using the menu pick:
+
+ Options->Manage Packages->List & Install
+ or
+ Options->Manage Packages->Using Custom->Select-> ...
+
+ You can also access it using the keyboard:
+
+ M-x pui-list-packages
+
+ The visual package browser will then display a list of all packages.
+Help information will be displayed at the very bottom of the buffer; you
+may have to scroll down to see it. You can also press `?' to get the
+same help. From this buffer, you can tell the package status by the
+character in the first column:
+
+`-'
+ The package has not been installed.
+
+`*'
+ The package has been installed, but a newer version is available.
+ The current version is out-of-date.
+
+`+'
+ The package has been marked for installation/update.
+
+ If there is no character in the first column, the package has been
+installed and is up-to-date.
+
+ From here, you can select or unselect packages for installation using
+the <RET> key, the `Mouse-2' button or selecting "Select" from the
+(Popup) Menu. Once you've finished selecting the packages, you can
+press the `x' key (or use the menu) to actually install the packages.
+Note that you will have to restart XEmacs for XEmacs to recognize any
+new packages.
+
+ Key summary:
+
+`?'
+ Display simple help.
+
+`<RET>'
+`<Mouse-2>'
+ Toggle between selecting and unselecting a package for
+ installation.
+
+`x'
+ Install selected packages.
+
+`<SPC>'
+ View, in the minibuffer, additional information about the package,
+ such as the package date (not the build date) and the package
+ author. Moving the mouse over a package name will also do the
+ same thing.
+
+`v'
+ Toggle between verbose and non-verbose package display.
+
+`g'
+ Refresh the package display.
+
+`q'
+ Kill the package buffer.
+
+ Moving the mouse over a package will also cause additional
+information about the package to be displayed in the minibuffer.
+
+Other package installation interfaces
+-------------------------------------
+
+ For an alternative package interface, you can select packages from
+the customize menus, under:
+
+ Options->Customize->Emacs->Packages-> ...
+ or
+ Options->Manage Packages->Using Custom->Select-> ...
+
+ Set their state to on, and then do:
+
+ Options->Manage Packages->Using Custom->Update Packages
+
+ This will automatically retrieve the packages you have selected from
+the XEmacs ftp site or your local disk, and install them into XEmacs.
+Additionally it will update any packages you already have installed to
+the newest version. Note that if a package is newly installed you will
+have to restart XEmacs for the change to take effect.
+
+ You can also install packages using a semi-manual interface:
+
+ M-x package-get-all <return>
+
+ Enter the name of the package (e.g., `prog-modes'), and XEmacs will
+search for the latest version (as listed in the lisp file
+`lisp/package-get-base.el'), and install it and any packages that it
+depends upon.
+
+Manual Binary Package Installation
+----------------------------------
+
+ Pre-compiled, binary packages can be installed in either a system
+package directory (this is determined when XEmacs is compiled), or in
+one of the following subdirectories of your `$HOME' directory:
+
+ ~/.xemacs/mule-packages
+ ~/.xemacs/xemacs-packages
+
+ Packages in the former directory will only be found by a Mule-enabled
+XEmacs.
+
+ XEmacs does not have to be running to install binary packages,
+although XEmacs will not know about any newly-installed packages until
+you restart XEmacs. Note, however, that installing a newer version of a
+package while XEmacs is running could cause strange errors in XEmacs;
+it's best to exit XEmacs before upgrading an existing package.
+
+ To install binary packages manually:
+
+ 1. Download the package(s) that you want to install. Each binary
+ package will typically be a gzip'd tarball.
+
+ 2. Decide where to install the packages: in the system package
+ directory, or in `~/.xemacs/mule-packages' or
+ `~/.xemacs/xemacs-packages', respectively. If you want to install
+ the packages in the system package directory, make sure you can
+ write into that directory. If you want to install in your `$HOME'
+ directory, create the directory, `~/.xemacs/mule-packages' or
+ `~/.xemacs/xemacs-packages', respectively.
+
+ 3. Next, `cd' to the directory under which you want to install the
+ package(s).
+
+ 4. From this directory, uncompress and extract each of the gzip'd
+ tarballs that you downloaded in step 1. Unix and Cygnus cygwin
+ users will typically do this using the commands:
+
+ gunzip < package.tar.gz | tar xvf -
+
+ Above, replace `package.tar.gz' with the filename of the package
+ that you downloaded in step 1.
+
+ Of course, if you use GNU `tar', you could also use:
+
+ tar xvzf package.tar.gz
+
+ 5. That's it. Quit and restart XEmacs to get it to recognize any new
+ or changed packages.
+
+
+\1f
+File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
+
+ Source packages are available from the `packages/source-packages'
+subdirectory of your favorite XEmacs distribution site. Alternatively,
+they are available via CVS from `cvs.xemacs.org'. Look at
+`http://cvs.xemacs.org' for instructions.
+
+Prerequisites for Building Source Packages
+------------------------------------------
+
+ You must have GNU `cp', GNU `install' (or a BSD compatible `install'
+program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from
+`texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The
+source packages will untar into a correct directory structure. At the
+top level you must have `XEmacs.rules' and `package-compile.el'. These
+files are available from the XEmacs FTP site from the same place you
+obtained your source package distributions.
+
+What You Can Do With Source Packages
+------------------------------------
+
+ NB: A global build operation doesn't exist yet as of 13 January
+1998.
+
+ Source packages are most useful for creating XEmacs package tarballs
+for installation into your own XEmacs installations or for distributing
+to others.
+
+ Supported operations from `make' are:
+
+`clean'
+ Remove all built files except `auto-autoloads.el' and
+ `custom-load.el'.
+
+`distclean'
+ Remove XEmacs backups as well as the files deleted by `make clean'.
+
+`all'
+ Bytecompile all files, build and bytecompile byproduct files like
+ `auto-autoloads.el' and `custom-load.el'. Create info version of
+ TeXinfo documentation if present.
+
+`srckit'
+ Usually aliased to `make srckit-std'. This does a `make
+ distclean' and creates a package source tarball in the staging
+ directory. This is generally only of use for package maintainers.
+
+`binkit'
+ May be aliased to `binkit-sourceonly', `binkit-sourceinfo',
+ `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
+ indicates there is nothing to install in a data directory or info
+ directory. `sourceinfo' indicates that source and info files are
+ to be installed. `sourcedata' indicates that source and etc
+ (data) files are to be installed. `sourcedatainfo' indicates
+ source, etc (data), and info files are to be installed. A few
+ packages have needs beyond the basic templates so this is not yet
+ complete.
+
+`dist'
+ Runs the rules `srckit' followed by `binkit'. This is primarily
+ of use by XEmacs maintainers producing files for distribution.
+
+\1f
+File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top
+
+Abbrevs
+*******
+
+ An "abbrev" is a word which "expands" into some different text.
+Abbrevs are defined by the user to expand in specific ways. For
+example, you might define `foo' as an abbrev expanding to `find outer
+otter'. With this abbrev defined, you would be able to get `find outer
+otter ' into the buffer by typing `f o o <SPC>'.
+
+ Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
+Disabling Abbrev mode does not cause abbrev definitions to be discarded,
+but they do not expand until Abbrev mode is enabled again. The command
+`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
+turns Abbrev mode on if the argument is positive, off otherwise. *Note
+Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
+when the variable is non-`nil'. The variable `abbrev-mode'
+automatically becomes local to the current buffer when it is set.
+
+ Abbrev definitions can be "mode-specific"--active only in one major
+mode. Abbrevs can also have "global" definitions that are active in
+all major modes. The same abbrev can have a global definition and
+various mode-specific definitions for different major modes. A
+mode-specific definition for the current major mode overrides a global
+definition.
+
+ You can define Abbrevs interactively during an editing session. You
+can also save lists of abbrev definitions in files and reload them in
+later sessions. Some users keep extensive lists of abbrevs that they
+load in every session.
+
+ A second kind of abbreviation facility is called the "dynamic
+expansion". Dynamic abbrev expansion happens only when you give an
+explicit command and the result of the expansion depends only on the
+current contents of the buffer. *Note Dynamic Abbrevs::.
+
+* Menu:
+
+* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
+* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
+* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
+* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
+* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
+
+\1f
+File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
+
+Defining Abbrevs
+================
+
+`C-x a g'
+ Define an abbrev to expand into some text before point
+ (`add-global-abbrev').
+
+`C-x a l'
+ Similar, but define an abbrev available only in the current major
+ mode (`add-mode-abbrev').
+
+`C-x a i g'
+ Define a word in the buffer as an abbrev
+ (`inverse-add-global-abbrev').
+
+`C-x a i l'
+ Define a word in the buffer as a mode-specific abbrev
+ (`inverse-add-mode-abbrev').
+
+`M-x kill-all-abbrevs'
+ After this command, no abbrev definitions remain in effect.
+
+ The usual way to define an abbrev is to enter the text you want the
+abbrev to expand to, position point after it, and type `C-x a g'
+(`add-global-abbrev'). This reads the abbrev itself using the
+minibuffer, and then defines it as an abbrev for one or more words
+before point. Use a numeric argument to say how many words before point
+should be taken as the expansion. For example, to define the abbrev
+`foo' as in the example above, insert the text `find outer otter', then
+type
+`C-u 3 C-x a g f o o <RET>'.
+
+ An argument of zero to `C-x a g' means to use the contents of the
+region as the expansion of the abbrev being defined.
+
+ The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
+mode-specific abbrev. Mode-specific abbrevs are active only in a
+particular major mode. `C-x a l' defines an abbrev for the major mode
+in effect at the time `C-x a l' is typed. The arguments work the same
+way they do for `C-x a g'.
+
+ If the text of an abbrev you want is already in the buffer instead of
+the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
+instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
+instead of `C-x a l'. These commands are called "inverse" because they
+invert the meaning of the argument found in the buffer and the argument
+read using the minibuffer.
+
+ To change the definition of an abbrev, just add the new definition.
+You will be asked to confirm if the abbrev has a prior definition. To
+remove an abbrev definition, give a negative argument to `C-x a g' or
+`C-x a l'. You must choose the command to specify whether to kill a
+global definition or a mode-specific definition for the current mode,
+since those two definitions are independent for one abbrev.
+
+ `M-x kill-all-abbrevs' removes all existing abbrev definitions.
+
+\1f
+File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
+
+Controlling Abbrev Expansion
+============================
+
+ An abbrev expands whenever it is in a buffer just before point and
+you type a self-inserting punctuation character (<SPC>, comma, etc.).
+Most often an abbrev is used by inserting the abbrev followed by
+punctuation.
+
+ Abbrev expansion preserves case; thus, `foo' expands into `find
+outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
+OTTER' or `Find Outer Otter' according to the variable
+`abbrev-all-caps' (a non-`nil' value chooses the first of the two
+expansions).
+
+ Two commands are available to control abbrev expansion:
+
+`M-''
+ Separate a prefix from a following abbrev to be expanded
+ (`abbrev-prefix-mark').
+
+`C-x a e'
+ Expand the abbrev before point (`expand-abbrev'). This is
+ effective even when Abbrev mode is not enabled.
+
+`M-x unexpand-abbrev'
+ Undo last abbrev expansion.
+
+`M-x expand-region-abbrevs'
+ Expand some or all abbrevs found in the region.
+
+ You may wish to expand an abbrev with a prefix attached. For
+example, if `cnst' expands into `construction', you may want to use it
+to enter `reconstruction'. It does not work to type `recnst', because
+that is not necessarily a defined abbrev. Instead, you can use the
+command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the
+abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a
+minus sign in the buffer to indicate that it has done its work. Then
+insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now
+insert a punctuation character to expand the abbrev `cnst' into
+`construction'. The minus sign is deleted at this point by `M-''. The
+resulting text is the desired `reconstruction'.
+
+ If you actually want the text of the abbrev in the buffer, rather
+than its expansion, insert the following punctuation with `C-q'. Thus,
+`foo C-q -' leaves `foo-' in the buffer.
+
+ If you expand an abbrev by mistake, you can undo the expansion
+(replace the expansion by the original abbrev text) with `M-x
+unexpand-abbrev'. You can also use `C-_' (`undo') to undo the
+expansion; but that will first undo the insertion of the punctuation
+character.
+
+ `M-x expand-region-abbrevs' searches through the region for defined
+abbrevs, and offers to replace each one it finds with its expansion.
+This command is useful if you have typed text using abbrevs but forgot
+to turn on Abbrev mode first. It may also be useful together with a
+special set of abbrev definitions for making several global
+replacements at once. The command is effective even if Abbrev mode is
+not enabled.
+
+\1f
+File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
+
+Examining and Editing Abbrevs
+=============================
+
+`M-x list-abbrevs'
+ Print a list of all abbrev definitions.
+
+`M-x edit-abbrevs'
+ Edit a list of abbrevs; you can add, alter, or remove definitions.
+
+ The output from `M-x list-abbrevs' looks like this:
+
+ (lisp-mode-abbrev-table)
+ "dk" 0 "define-key"
+ (global-abbrev-table)
+ "dfn" 0 "definition"
+
+(Some blank lines of no semantic significance, and some other abbrev
+tables, have been omitted.)
+
+ A line containing a name in parentheses is the header for abbrevs in
+a particular abbrev table; `global-abbrev-table' contains all the global
+abbrevs, and the other abbrev tables that are named after major modes
+contain the mode-specific abbrevs.
+
+ Within each abbrev table, each non-blank line defines one abbrev.
+The word at the beginning is the abbrev. The number that appears is
+the number of times the abbrev has been expanded. Emacs keeps track of
+this to help you see which abbrevs you actually use, in case you want
+to eliminate those that you don't use often. The string at the end of
+the line is the expansion.
+
+ `M-x edit-abbrevs' allows you to add, change or kill abbrev
+definitions by editing a list of them in an Emacs buffer. The list has
+the format described above. The buffer of abbrevs is called
+`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key
+`C-c C-c' to install the abbrev definitions as specified in the buffer.
+The `edit-abbrevs-redefine' command does this. Any abbrevs not
+described in the buffer are eliminated when this is done.
+
+ `edit-abbrevs' is actually the same as `list-abbrevs', except that
+it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely
+displays it in another window.
+
+\1f
+File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
+
+Saving Abbrevs
+==============
+
+ These commands allow you to keep abbrev definitions between editing
+sessions.
+
+`M-x write-abbrev-file'
+ Write a file describing all defined abbrevs.
+
+`M-x read-abbrev-file'
+ Read such an abbrev file and define abbrevs as specified there.
+
+`M-x quietly-read-abbrev-file'
+ Similar, but do not display a message about what is going on.
+
+`M-x define-abbrevs'
+ Define abbrevs from buffer.
+
+`M-x insert-abbrevs'
+ Insert all abbrevs and their expansions into the buffer.
+
+ Use `M-x write-abbrev-file' to save abbrev definitions for use in a
+later session. The command reads a file name using the minibuffer and
+writes a description of all current abbrev definitions into the
+specified file. The text stored in the file looks like the output of
+`M-x list-abbrevs'.
+
+ `M-x read-abbrev-file' prompts for a file name using the minibuffer
+and reads the specified file, defining abbrevs according to its
+contents. `M-x quietly-read-abbrev-file' is the same but does not
+display a message in the echo area; it is actually useful primarily in
+the `.emacs' file. If you give an empty argument to either of these
+functions, the file name Emacs uses is the value of the variable
+`abbrev-file-name', which is by default `"~/.abbrev_defs"'.
+
+ Emacs offers to save abbrevs automatically if you have changed any of
+them, whenever it offers to save all files (for `C-x s' or `C-x C-c').
+Set the variable `save-abbrevs' to `nil' to inhibit this feature.
+
+ The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
+similar to the previous commands but work on text in an Emacs buffer.
+`M-x insert-abbrevs' inserts text into the current buffer before point,
+describing all current abbrev definitions; `M-x define-abbrevs' parses
+the entire current buffer and defines abbrevs accordingly.
+
+\1f
+File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs
+
+Dynamic Abbrev Expansion
+========================
+
+ The abbrev facility described above operates automatically as you
+insert text, but all abbrevs must be defined explicitly. By contrast,
+"dynamic abbrevs" allow the meanings of abbrevs to be determined
+automatically from the contents of the buffer, but dynamic abbrev
+expansion happens only when you request it explicitly.
+
+`M-/'
+ Expand the word in the buffer before point as a "dynamic abbrev",
+ by searching in the buffer for words starting with that
+ abbreviation (`dabbrev-expand').
+
+ For example, if the buffer contains `does this follow ' and you type
+`f o M-/', the effect is to insert `follow' because that is the last
+word in the buffer that starts with `fo'. A numeric argument to `M-/'
+says to take the second, third, etc. distinct expansion found looking
+backward from point. Repeating `M-/' searches for an alternative
+expansion by looking farther back. After the entire buffer before
+point has been considered, the buffer after point is searched.
+
+ Dynamic abbrev expansion is completely independent of Abbrev mode;
+the expansion of a word with `M-/' is completely independent of whether
+it has a definition as an ordinary abbrev.
+
+\1f
+File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top
+
+Editing Pictures
+****************
+
+ If you want to create a picture made out of text characters (for
+example, a picture of the division of a register into fields, as a
+comment in a program), use the command `edit-picture' to enter Picture
+mode.
+
+ In Picture mode, editing is based on the "quarter-plane" model of
+text. In this model, the text characters lie studded on an area that
+stretches infinitely far to the right and downward. The concept of the
+end of a line does not exist in this model; the most you can say is
+where the last non-blank character on the line is found.
+
+ Of course, Emacs really always considers text as a sequence of
+characters, and lines really do have ends. But in Picture mode most
+frequently-used keys are rebound to commands that simulate the
+quarter-plane model of text. They do this by inserting spaces or by
+converting tabs to spaces.
+
+ Most of the basic editing commands of Emacs are redefined by Picture
+mode to do essentially the same thing but in a quarter-plane way. In
+addition, Picture mode defines various keys starting with the `C-c'
+prefix to run special picture editing commands.
+
+ One of these keys, `C-c C-c', is pretty important. Often a picture
+is part of a larger file that is usually edited in some other major
+mode. `M-x edit-picture' records the name of the previous major mode.
+You can then use the `C-c C-c' command (`picture-mode-exit') to restore
+that mode. `C-c C-c' also deletes spaces from the ends of lines,
+unless you give it a numeric argument.
+
+ The commands used in Picture mode all work in other modes (provided
+the `picture' library is loaded), but are only bound to keys in
+Picture mode. Note that the descriptions below talk of moving "one
+column" and so on, but all the picture mode commands handle numeric
+arguments as their normal equivalents do.
+
+ Turning on Picture mode calls the value of the variable
+`picture-mode-hook' as a function, with no arguments, if that value
+exists and is non-`nil'.
+
+* Menu:
+
+* Basic Picture:: Basic concepts and simple commands of Picture Mode.
+* Insert in Picture:: Controlling direction of cursor motion
+ after "self-inserting" characters.
+* Tabs in Picture:: Various features for tab stops and indentation.
+* Rectangles in Picture:: Clearing and superimposing rectangles.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture
+
+Basic Editing in Picture Mode
+=============================
+
+ Most keys do the same thing in Picture mode that they usually do,
+but do it in a quarter-plane style. For example, `C-f' is rebound to
+run `picture-forward-column', which moves point one column to the
+right, by inserting a space if necessary, so that the actual end of the
+line makes no difference. `C-b' is rebound to run
+`picture-backward-column', which always moves point left one column,
+converting a tab to multiple spaces if necessary. `C-n' and `C-p' are
+rebound to run `picture-move-down' and `picture-move-up', which can
+either insert spaces or convert tabs as necessary to make sure that
+point stays in exactly the same column. `C-e' runs
+`picture-end-of-line', which moves to after the last non-blank
+character on the line. There was no need to change `C-a', as the choice
+of screen model does not affect beginnings of lines.
+
+ Insertion of text is adapted to the quarter-plane screen model
+through the use of Overwrite mode (*note Minor Modes::.).
+Self-inserting characters replace existing text, column by column,
+rather than pushing existing text to the right. <RET> runs
+`picture-newline', which just moves to the beginning of the following
+line so that new text will replace that line.
+
+ Text is erased instead of deleted and killed. <DEL>
+(`picture-backward-clear-column') replaces the preceding character with
+a space rather than removing it. `C-d' (`picture-clear-column') does
+the same in a forward direction. `C-k' (`picture-clear-line') really
+kills the contents of lines, but never removes the newlines from a
+buffer.
+
+ To do actual insertion, you must use special commands. `C-o'
+(`picture-open-line') creates a blank line, but does so after the
+current line; it never splits a line. `C-M-o', `split-line', makes
+sense in Picture mode, so it remains unchanged. <LFD>
+(`picture-duplicate-line') inserts another line with the same contents
+below the current line.
+
+ To actually delete parts of the picture, use `C-w', or with `C-c
+C-d' (which is defined as `delete-char', as `C-d' is in other modes),
+or with one of the picture rectangle commands (*note Rectangles in
+Picture::.).
+
+\1f
+File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture
+
+Controlling Motion After Insert
+===============================
+
+ Since "self-inserting" characters just overwrite and move point in
+Picture mode, there is no essential restriction on how point should be
+moved. Normally point moves right, but you can specify any of the eight
+orthogonal or diagonal directions for motion after a "self-inserting"
+character. This is useful for drawing lines in the buffer.
+
+`C-c <'
+ Move left after insertion (`picture-movement-left').
+
+`C-c >'
+ Move right after insertion (`picture-movement-right').
+
+`C-c ^'
+ Move up after insertion (`picture-movement-up').
+
+`C-c .'
+ Move down after insertion (`picture-movement-down').
+
+`C-c `'
+ Move up and left ("northwest") after insertion
+ (`picture-movement-nw').
+
+`C-c ''
+ Move up and right ("northeast") after insertion
+ (`picture-movement-ne').
+
+`C-c /'
+ Move down and left ("southwest") after insertion
+ (`picture-movement-sw').
+
+`C-c \'
+ Move down and right ("southeast") after insertion
+ (`picture-movement-se').
+
+ Two motion commands move based on the current Picture insertion
+direction. The command `C-c C-f' (`picture-motion') moves in the same
+direction as motion after "insertion" currently does, while `C-c C-b'
+(`picture-motion-reverse') moves in the opposite direction.
+
+\1f
+File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture
+
+Picture Mode Tabs
+=================
+
+ Two kinds of tab-like action are provided in Picture mode.
+Context-based tabbing is done with `M-<TAB>' (`picture-tab-search').
+With no argument, it moves to a point underneath the next "interesting"
+character that follows whitespace in the previous non-blank line.
+"Next" here means "appearing at a horizontal position greater than the
+one point starts out at". With an argument, as in `C-u M-<TAB>', the
+command moves to the next such interesting character in the current
+line. `M-<TAB>' does not change the text; it only moves point.
+"Interesting" characters are defined by the variable
+`picture-tab-chars', which contains a string of characters considered
+interesting. Its default value is `"!-~"'.
+
+ <TAB> itself runs `picture-tab', which operates based on the current
+tab stop settings; it is the Picture mode equivalent of
+`tab-to-tab-stop'. Without arguments it just moves point, but with a
+numeric argument it clears the text that it moves over.
+
+ The context-based and tab-stop-based forms of tabbing are brought
+together by the command `C-c <TAB>' (`picture-set-tab-stops'.) This
+command sets the tab stops to the positions which `M-<TAB>' would
+consider significant in the current line. If you use this command with
+<TAB>, you can get the effect of context-based tabbing. But `M-<TAB>'
+is more convenient in the cases where it is sufficient.
+
+\1f
+File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture
+
+Picture Mode Rectangle Commands
+===============================
+
+ Picture mode defines commands for working on rectangular pieces of
+the text in ways that fit with the quarter-plane model. The standard
+rectangle commands may also be useful (*note Rectangles::.).
+
+`C-c C-k'
+ Clear out the region-rectangle (`picture-clear-rectangle'). With
+ argument, kill it.
+
+`C-c C-w R'
+ Similar but save rectangle contents in register R first
+ (`picture-clear-rectangle-to-register').
+
+`C-c C-y'
+ Copy last killed rectangle into the buffer by overwriting, with
+ upper left corner at point (`picture-yank-rectangle'). With
+ argument, insert instead.
+
+`C-c C-x R'
+ Similar, but use the rectangle in register R
+ (`picture-yank-rectangle-from-register').
+
+ The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
+and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
+standard rectangle commands in that they normally clear the rectangle
+instead of deleting it; this is analogous with the way `C-d' is changed
+in Picture mode.
+
+ However, deletion of rectangles can be useful in Picture mode, so
+these commands delete the rectangle if given a numeric argument.
+
+ The Picture mode commands for yanking rectangles differ from the
+standard ones in overwriting instead of inserting. This is the same
+way that Picture mode insertion of other text is different from other
+modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
+the rectangle that was most recently killed, while `C-c C-x'
+(`picture-yank-rectangle-from-register') does for the rectangle found
+in a specified register.
+
+ Since most region commands in Picture mode operate on rectangles,
+when you select a region of text with the mouse in Picture mode, it is
+highlighted as a rectangle.
+
+\1f
+File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top
+
+Sending Mail
+************
+
+ To send a message in Emacs, start by typing the command (`C-x m') to
+select and initialize the `*mail*' buffer. You can then edit the text
+and headers of the message in the mail buffer, and type the command
+(`C-c C-c') to send the message.
+
+`C-x m'
+ Begin composing a message to send (`mail').
+
+`C-x 4 m'
+ Likewise, but display the message in another window
+ (`mail-other-window').
+
+`C-c C-c'
+ In Mail mode, send the message and switch to another buffer
+ (`mail-send-and-exit').
+
+ The command `C-x m' (`mail') selects a buffer named `*mail*' and
+initializes it with the skeleton of an outgoing message. `C-x 4 m'
+(`mail-other-window') selects the `*mail*' buffer in a different
+window, leaving the previous current buffer visible.
+
+ Because the buffer for mail composition is an ordinary Emacs buffer,
+you can switch to other buffers while in the middle of composing mail,
+and switch back later (or never). If you use the `C-x m' command again
+when you have been composing another message but have not sent it, a
+new mail buffer will be created; in this way, you can compose multiple
+messages at once. You can switch back to and complete an unsent
+message by using the normal buffer selection mechanisms.
+
+ `C-u C-x m' is another way to switch back to a message in progress:
+it will search for an existing, unsent mail message buffer and select
+it.
+
+* Menu:
+
+* Format: Mail Format. Format of the mail being composed.
+* Headers: Mail Headers. Details of allowed mail header fields.
+* Mode: Mail Mode. Special commands for editing mail being composed.
+
+\1f
+File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail
+
+The Format of the Mail Buffer
+=============================
+
+ In addition to the "text" or contents, a message has "header
+fields", which say who sent it, when, to whom, why, and so on. Some
+header fields, such as the date and sender, are created automatically
+after the message is sent. Others, such as the recipient names, must
+be specified by you in order to send the message properly.
+
+ Mail mode provides a few commands to help you edit some header
+fields, and some are preinitialized in the buffer automatically at
+times. You can insert or edit any header fields using ordinary editing
+commands.
+
+ The line in the buffer that says:
+
+ --text follows this line--
+
+is a special delimiter that separates the headers you have specified
+from the text. Whatever follows this line is the text of the message;
+the headers precede it. The delimiter line itself does not appear in
+the message actually sent. The text used for the delimiter line is
+controlled by the variable `mail-header-separator'.
+
+ Here is an example of what the headers and text in the `*mail*'
+buffer might look like.
+
+ To: rms@mc
+ CC: mly@mc, rg@oz
+ Subject: The XEmacs User's Manual
+ --Text follows this line--
+ Please ignore this message.
+
+\1f
+File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail
+
+Mail Header Fields
+==================
+
+ There are several header fields you can use in the `*mail*' buffer.
+Each header field starts with a field name at the beginning of a line,
+terminated by a colon. It does not matter whether you use upper or
+lower case in the field name. After the colon and optional whitespace
+comes the contents of the field.
+
+`To'
+ This field contains the mailing addresses of the message.
+
+`Subject'
+ The contents of the `Subject' field should be a piece of text that
+ says what the message is about. Subject fields are useful because
+ most mail-reading programs can provide a summary of messages,
+ listing the subject of each message but not its text.
+
+`CC'
+ This field contains additional mailing addresses to send the
+ message to, but whose readers should not regard the message as
+ addressed to them.
+
+`BCC'
+ This field contains additional mailing addresses to send the
+ message to, but which should not appear in the header of the
+ message actually sent.
+
+`FCC'
+ This field contains the name of one file (in Unix mail file
+ format) to which a copy of the message should be appended when the
+ message is sent.
+
+`From'
+ Use the `From' field to say who you are, when the account you are
+ using to send the mail is not your own. The contents of the
+ `From' field should be a valid mailing address, since replies will
+ normally go there.
+
+`Reply-To'
+ Use the `Reply-To' field to direct replies to a different address,
+ not your own. `From' and `Reply-To' have the same effect on where
+ replies go, but they convey a different meaning to the person who
+ reads the message.
+
+`In-Reply-To'
+ This field contains a piece of text describing a message you are
+ replying to. Some mail systems can use the information to
+ correlate related pieces of mail. This field is normally filled
+ in by your mail handling package when you are replying to a
+ message and you never need to think about it.
+
+The `To', `CC', `BCC' and `FCC' fields can appear any number of times,
+to specify many places to send the message.
+
+The `To', `CC', and `BCC', fields can have continuation lines. All the
+lines starting with whitespace, following the line on which the field
+starts, are considered part of the field. For example,
+
+ To: foo@here, this@there,
+ me@gnu.cambridge.mass.usa.earth.spiral3281
+
+If you have a `~/.mailrc' file, Emacs scans it for mail aliases the
+first time you try to send mail in an Emacs session. Emacs expands
+aliases found in the `To', `CC', and `BCC' fields where appropriate.
+You can set the variable `mail-abbrev-mailrc-file' to the name of the
+file with mail aliases. If `nil', `~/.mailrc' is used.
+
+ Your `.mailrc' file ensures that word-abbrevs are defined for each
+of your mail aliases when point is in a `To', `CC', `BCC', or `From'
+field. The aliases are defined in your `.mailrc' file or in a file
+specified by the MAILRC environment variable if it exists. Your mail
+aliases expand any time you type a word-delimiter at the end of an
+abbreviation.
+
+ In this version of Emacs, what you see is what you get: in contrast
+to some other versions, no abbreviations are expanded after you have
+sent the mail. This means you don't suffer the annoyance of having the
+system do things behind your back -- if the system rewrites an address
+you typed, you know it immediately, instead of after the mail has been
+sent and it's too late to do anything about it. For example, you will
+never again be in trouble because you forgot to delete an old alias
+from your `.mailrc' and a new local user is given a userid which
+conflicts with one of your aliases.
+
+ Your mail alias abbrevs are in effect only when point is in an
+appropriate header field. The mail aliases will not expand in the body
+of the message, or in other header fields. The default mode-specific
+abbrev table `mail-mode-abbrev-table' is used instead if defined. That
+means if you have been using mail-mode specific abbrevs, this code will
+not adversely affect you. You can control which header fields the
+abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'.
+
+ If auto-fill mode is on, abbrevs wrap at commas instead of at word
+boundaries, and header continuation lines will be properly indented.
+
+ You can also insert a mail alias with
+`mail-interactive-insert-alias'. This function, which is bound to `C-c
+C-a', prompts you for an alias (with completion) and inserts its
+expansion at point.
+
+ In this version of Emacs, it is possible to have lines like the
+following in your `.mailrc' file:
+
+ alias someone "John Doe <doe@quux.com>"
+
+ That is, if you want an address to have embedded spaces, simply
+surround it with double-quotes. The quotes are necessary because the
+format of the `.mailrc' file uses spaces as address delimiters.
+
+ Aliases in the `.mailrc' file may be nested. For example, assume you
+define aliases like:
+ alias group1 fred ethel
+ alias group2 larry curly moe
+ alias everybody group1 group2
+
+ When you now type `everybody' on the `To' line, it will expand to:
+ fred, ethyl, larry, curly, moe
+
+ Aliases may contain forward references; the alias of `everybody' in
+the example above can precede the aliases of `group1' and `group2'.
+
+ In this version of Emacs, you can use the `source' `.mailrc' command
+for reading aliases from some other file as well.
+
+ Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even
+though word-abbrevs normally cannot contain hyphens.
+
+ To read in the contents of another `.mailrc'-type file from Emacs,
+use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases'
+command is similar, but deletes existing aliases first.
+
+ If you want multiple addresses separated by a string other than `,'
+(a comma), then set the variable `mail-alias-seperator-string' to it.
+This has to be a comma bracketed by whitespace if you want any kind of
+reasonable behavior.
+
+ If the variable `mail-archive-file-name' is non-`nil', it should be
+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.
+
+\1f
+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').
+
+`<button3>'
+ 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'.
+
+\1f
+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.)
+
+\1f
+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.
+
+\1f
+File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary
+
+Movement in the Calendar
+------------------------
+
+ Calendar mode lets you move through the calendar in logical units of
+time such as days, weeks, months, and years. If you move outside the
+three months originally displayed, the calendar display "scrolls"
+automatically through time to make the selected date visible. Moving to
+a date lets you view its holidays or diary entries, or convert it to
+other calendars; moving longer time periods is also useful simply to
+scroll the calendar.
+
+* Menu:
+
+* Calendar Unit Motion:: Moving by days, weeks, months, and years.
+* Move to Beginning or End:: Moving to start/end of weeks, months, and years.
+* Specified Dates:: Moving to the current date or another
+ specific date.
+
+\1f
+File: xemacs.info, Node: Calendar Unit Motion, Next: Move to Beginning or End, Prev: Calendar Motion, Up: Calendar Motion
+
+Motion by Integral Days, Weeks, Months, Years
+.............................................
+
+ The commands for movement in the calendar buffer parallel the
+commands for movement in text. You can move forward and backward by
+days, weeks, months, and years.
+
+`C-f'
+ Move point one day forward (`calendar-forward-day').
+
+`C-b'
+ Move point one day backward (`calendar-backward-day').
+
+`C-n'
+ Move point one week forward (`calendar-forward-week').
+
+`C-p'
+ Move point one week backward (`calendar-backward-week').
+
+`M-}'
+ Move point one month forward (`calendar-forward-month').
+
+`M-{'
+ Move point one month backward (`calendar-backward-month').
+
+`C-x ]'
+ Move point one year forward (`calendar-forward-year').
+
+`C-x ['
+ Move point one year backward (`calendar-backward-year').
+
+ The day and week commands are natural analogues of the usual Emacs
+commands for moving by characters and by lines. Just as `C-n' usually
+moves to the same column in the following line, in Calendar mode it
+moves to the same day in the following week. And `C-p' moves to the
+same day in the previous week.
+
+ The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just
+as they normally are in other modes.
+
+ The commands for motion by months and years work like those for
+weeks, but move a larger distance. The month commands `M-}' and `M-{'
+move forward or backward by an entire month's time. The year commands
+`C-x ]' and `C-x [' move forward or backward a whole year.
+
+ The easiest way to remember these commands is to consider months and
+years analogous to paragraphs and pages of text, respectively. But the
+commands themselves are not quite analogous. The ordinary Emacs
+paragraph commands move to the beginning or end of a paragraph, whereas
+these month and year commands move by an entire month or an entire
+year, which usually involves skipping across the end of a month or year.
+
+ All these commands accept a numeric argument as a repeat count. For
+convenience, the digit keys and the minus sign specify numeric
+arguments in Calendar mode even without the Meta modifier. For example,
+`100 C-f' moves point 100 days forward from its present location.
+
+\1f
+File: xemacs.info, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion
+
+Beginning or End of Week, Month or Year
+.......................................
+
+ A week (or month, or year) is not just a quantity of days; we think
+of weeks (months, years) as starting on particular dates. So Calendar
+mode provides commands to move to the beginning or end of a week, month
+or year:
+
+`C-a'
+ Move point to start of week (`calendar-beginning-of-week').
+
+`C-e'
+ Move point to end of week (`calendar-end-of-week').
+
+`M-a'
+ Move point to start of month (`calendar-beginning-of-month').
+
+`M-e'
+ Move point to end of month (`calendar-end-of-month').
+
+`M-<'
+ Move point to start of year (`calendar-beginning-of-year').
+
+`M->'
+ Move point to end of year (`calendar-end-of-year').
+
+ These commands also take numeric arguments as repeat counts, with the
+repeat count indicating how many weeks, months, or years to move
+backward or forward.
+
+ By default, weeks begin on Sunday. To make them begin on Monday
+instead, set the variable `calendar-week-start-day' to 1.
+
+\1f
+File: xemacs.info, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion
+
+Particular Dates
+................
+
+ Calendar mode provides commands for moving to a particular date
+specified in various ways.
+
+`g d'
+ Move point to specified date (`calendar-goto-date').
+
+`o'
+ Center calendar around specified month (`calendar-other-month').
+
+`.'
+ Move point to today's date (`calendar-goto-today').
+
+ `g d' (`calendar-goto-date') prompts for a year, a month, and a day
+of the month, and then moves to that date. Because the calendar
+includes all dates from the beginning of the current era, you must type
+the year in its entirety; that is, type `1990', not `90'.
+
+ `o' (`calendar-other-month') prompts for a month and year, then
+centers the three-month calendar around that month.
+
+ You can return to today's date with `.' (`calendar-goto-today').
+
+\1f
+File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary
+
+Scrolling the Calendar through Time
+-----------------------------------
+
+ The calendar display scrolls automatically through time when you
+move out of the visible portion. You can also scroll it manually.
+Imagine that the calendar window contains a long strip of paper with
+the months on it. Scrolling it means moving the strip so that new
+months become visible in the window.
+
+`C-x <'
+ Scroll calendar one month forward (`scroll-calendar-left').
+
+`C-x >'
+ Scroll calendar one month backward (`scroll-calendar-right').
+
+`C-v'
+`<NEXT>'
+ Scroll calendar three months forward
+ (`scroll-calendar-left-three-months').
+
+`M-v'
+`<PRIOR>'
+ Scroll calendar three months backward
+ (`scroll-calendar-right-three-months').
+
+ The most basic calendar scroll commands scroll by one month at a
+time. This means that there are two months of overlap between the
+display before the command and the display after. `C-x <' scrolls the
+calendar contents one month to the left; that is, it moves the display
+forward in time. `C-x >' scrolls the contents to the right, which
+moves backwards in time.
+
+ The commands `C-v' and `M-v' scroll the calendar by an entire
+"screenful"--three months--in analogy with the usual meaning of these
+commands. `C-v' makes later dates visible and `M-v' makes earlier
+dates visible. These commands take a numeric argument as a repeat
+count; in particular, since `C-u' multiplies the next command by four,
+typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u
+M-v' scrolls the calendar backward by a year.
+
+ The function keys <NEXT> and <PRIOR> are equivalent to `C-v' and
+`M-v', just as they are in other modes.
+
+\1f
+File: xemacs.info, Node: Mark and Region, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary
+
+The Mark and the Region
+-----------------------
+
+ The concept of the mark applies to the calendar just as to any other
+buffer, but it marks a *date*, not a *position* in the buffer. The
+region consists of the days between the mark and point (including the
+starting and stopping dates).
+
+`C-SPC'
+ Set the mark to today's date (`calendar-set-mark').
+
+`C-@'
+ The same.
+
+`C-x C-x'
+ Interchange mark and point (`calendar-exchange-point-and-mark').
+
+`M-='
+ Display the number of days in the current region
+ (`calendar-count-days-region').
+
+ You set the mark in the calendar, as in any other buffer, by using
+`C-@' or `C-SPC' (`calendar-set-mark'). You return to the marked date
+with the command `C-x C-x' (`calendar-exchange-point-and-mark') which
+puts the mark where point was and point where mark was. The calendar
+is scrolled as necessary, if the marked date was not visible on the
+screen. This does not change the extent of the region.
+
+ To determine the number of days in the region, type `M-='
+(`calendar-count-days-region'). The numbers of days printed is
+*inclusive*; that is, it includes the days specified by mark and point.
+
+ The main use of the mark in the calendar is to remember dates that
+you may want to go back to. To make this feature more useful, the mark
+ring (*note Mark Ring::.) operates exactly as in other buffers: Emacs
+remembers 16 previous locations of the mark. To return to a marked
+date, type `C-u C-SPC' (or `C-u C-@'); this is the command
+`calendar-set-mark' given a numeric argument. It moves point to where
+the mark was, restores the mark from the ring of former marks, and
+stores the previous point at the end of the mark ring. So, repeated
+use of this command moves point through all the old marks on the ring,
+one by one.
+
+\1f
+File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary
+
+Miscellaneous Calendar Commands
+-------------------------------
+
+`p d'
+ Display day-in-year (`calendar-print-day-of-year').
+
+`?'
+ Briefly describe calendar commands (`describe-calendar-mode').
+
+`C-c C-l'
+ Regenerate the calendar window (`redraw-calendar').
+
+`SPC'
+ Scroll the next window (`scroll-other-window').
+
+`q'
+ Exit from calendar (`exit-calendar').
+
+ If you want to know how many days have elapsed since the start of
+the year, or the number of days remaining in the year, type the `p d'
+command (`calendar-print-day-of-year'). This displays both of those
+numbers in the echo area.
+
+ To display a brief description of the calendar commands, type `?'
+(`describe-calendar-mode'). For a fuller description, type `C-h m'.
+
+ You can use `SPC' (`scroll-other-window') to scroll the other
+window. This is handy when you display a list of holidays or diary
+entries in another window.
+
+ If the calendar window text gets corrupted, type `C-c C-l'
+(`redraw-calendar') to redraw it. (This can only happen if you use
+non-Calendar-mode editing commands.)
+
+ In Calendar mode, you can use `SPC' (`scroll-other-window') to
+scroll the other window. This is handy when you display a list of
+holidays or diary entries in another window.
+
+ To exit from the calendar, type `q' (`exit-calendar'). This buries
+all buffers related to the calendar, selecting other buffers. (If a
+frame contains a dedicated calendar window, exiting from the calendar
+iconifies that frame.)
+
+\1f
+File: xemacs.info, Node: LaTeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary
+
+LaTeX Calendar
+==============
+
+ The Calendar LaTeX commands produce a buffer of LaTeX code that
+prints as a calendar. Depending on the command you use, the printed
+calendar covers the day, week, month or year that point is in.
+
+`t m'
+ Generate a one-month calendar (`cal-tex-cursor-month').
+
+`t M'
+ Generate a sideways-printing one-month calendar
+ (`cal-tex-cursor-month-landscape').
+
+`t d'
+ Generate a one-day calendar (`cal-tex-cursor-day').
+
+`t w 1'
+ Generate a one-page calendar for one week (`cal-tex-cursor-week').
+
+`t w 2'
+ Generate a two-page calendar for one week (`cal-tex-cursor-week2').
+
+`t w 3'
+ Generate an ISO-style calendar for one week
+ (`cal-tex-cursor-week-iso').
+
+`t w 4'
+ Generate a calendar for one Monday-starting week
+ (`cal-tex-cursor-week-monday').
+
+`t f w'
+ Generate a Filofax-style two-weeks-at-a-glance calendar
+ (`cal-tex-cursor-filofax-2week').
+
+`t f W'
+ Generate a Filofax-style one-week-at-a-glance calendar
+ (`cal-tex-cursor-filofax-week').
+
+`t y'
+ Generate a calendar for one year (`cal-tex-cursor-year').
+
+`t Y'
+ Generate a sideways-printing calendar for one year
+ (`cal-tex-cursor-year-landscape').
+
+`t f y'
+ Generate a Filofax-style calendar for one year
+ (`cal-tex-cursor-filofax-year').
+
+ Some of these commands print the calendar sideways (in "landscape
+mode"), so it can be wider than it is long. Some of them use Filofax
+paper size (3.75in x 6.75in). All of these commands accept a prefix
+argument which specifies how many days, weeks, months or years to print
+(starting always with the selected one).
+
+ If the variable `cal-tex-holidays' is non-`nil' (the default), then
+the printed calendars show the holidays in `calendar-holidays'. If the
+variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary
+entries are included also (in weekly and monthly calendars only).
+
+\1f
+File: xemacs.info, Node: Holidays, Next: Sunrise/Sunset, Prev: LaTeX Calendar, Up: Calendar/Diary
+
+Holidays
+--------
+
+ The Emacs calendar knows about all major and many minor holidays,
+and can display them.
+
+`h'
+ Display holidays for the selected date
+ (`calendar-cursor-holidays').
+
+`Button2 Holidays'
+ Display any holidays for the date you click on.
+
+`x'
+ Mark holidays in the calendar window (`mark-calendar-holidays').
+
+`u'
+ Unmark calendar window (`calendar-unmark').
+
+`a'
+ List all holidays for the displayed three months in another window
+ (`list-calendar-holidays').
+
+`M-x holidays'
+ List all holidays for three months around today's date in another
+ window.
+
+`M-x list-holidays'
+ List holidays in another window for a specified range of years.
+
+ To see if any holidays fall on a given date, position point on that
+date in the calendar window and use the `h' command. Alternatively,
+click on that date with `Button2' and then choose `Holidays' from the
+menu that appears. Either way, this displays the holidays for that
+date, in the echo area if they fit there, otherwise in a separate
+window.
+
+ To view the distribution of holidays for all the dates shown in the
+calendar, use the `x' command. This displays the dates that are
+holidays in a different face (or places a `*' after these dates, if
+display with multiple faces is not available). The command applies both
+to the currently visible months and to other months that subsequently
+become visible by scrolling. To turn marking off and erase the current
+marks, type `u', which also erases any diary marks (*note Diary::.).
+
+ To get even more detailed information, use the `a' command, which
+displays a separate buffer containing a list of all holidays in the
+current three-month range. You can use <SPC> in the calendar window to
+scroll that list.
+
+ The command `M-x holidays' displays the list of holidays for the
+current month and the preceding and succeeding months; this works even
+if you don't have a calendar window. If you want the list of holidays
+centered around a different month, use `C-u M-x holidays', which
+prompts for the month and year.
+
+ The holidays known to Emacs include United States holidays and the
+major Christian, Jewish, and Islamic holidays; also the solstices and
+equinoxes.
+
+ The command `M-x list-holidays' displays the list of holidays for a
+range of years. This function asks you for the starting and stopping
+years, and allows you to choose all the holidays or one of several
+categories of holidays. You can use this command even if you don't have
+a calendar window.
+
+ The dates used by Emacs for holidays are based on *current
+practice*, not historical fact. Historically, for instance, the start
+of daylight savings time and even its existence have varied from year to
+year, but present United States law mandates that daylight savings time
+begins on the first Sunday in April. When the daylight savings rules
+are set up for the United States, Emacs always uses the present
+definition, even though it is wrong for some prior years.
+
+\1f
+File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary
+
+Times of Sunrise and Sunset
+---------------------------
+
+ Special calendar commands can tell you, to within a minute or two,
+the times of sunrise and sunset for any date.
+
+`S'
+ Display times of sunrise and sunset for the selected date
+ (`calendar-sunrise-sunset').
+
+`Button2 Sunrise/Sunset'
+ Display times of sunrise and sunset for the date you click on.
+
+`M-x sunrise-sunset'
+ Display times of sunrise and sunset for today's date.
+
+`C-u M-x sunrise-sunset'
+ Display times of sunrise and sunset for a specified date.
+
+ Within the calendar, to display the *local times* of sunrise and
+sunset in the echo area, move point to the date you want, and type `S'.
+Alternatively, click `Button2' on the date, then choose
+`Sunrise/Sunset' from the menu that appears. The command `M-x
+sunrise-sunset' is available outside the calendar to display this
+information for today's date or a specified date. To specify a date
+other than today, use `C-u M-x sunrise-sunset', which prompts for the
+year, month, and day.
+
+ You can display the times of sunrise and sunset for any location and
+any date with `C-u C-u M-x sunrise-sunset'. This asks you for a
+longitude, latitude, number of minutes difference from Coordinated
+Universal Time, and date, and then tells you the times of sunrise and
+sunset for that location on that date.
+
+ Because the times of sunrise and sunset depend on the location on
+earth, you need to tell Emacs your latitude, longitude, and location
+name before using these commands. Here is an example of what to set:
+
+ (setq calendar-latitude 40.1)
+ (setq calendar-longitude -88.2)
+ (setq calendar-location-name "Urbana, IL")
+
+Use one decimal place in the values of `calendar-latitude' and
+`calendar-longitude'.
+
+ Your time zone also affects the local time of sunrise and sunset.
+Emacs usually gets time zone information from the operating system, but
+if these values are not what you want (or if the operating system does
+not supply them), you must set them yourself. Here is an example:
+
+ (setq calendar-time-zone -360)
+ (setq calendar-standard-time-zone-name "CST")
+ (setq calendar-daylight-time-zone-name "CDT")
+
+The value of `calendar-time-zone' is the number of minutes difference
+between your local standard time and Coordinated Universal Time
+(Greenwich time). The values of `calendar-standard-time-zone-name' and
+`calendar-daylight-time-zone-name' are the abbreviations used in your
+time zone. Emacs displays the times of sunrise and sunset *corrected
+for daylight savings time*. *Note Daylight Savings::, for how daylight
+savings time is determined.
+
+ As a user, you might find it convenient to set the calendar location
+variables for your usual physical location in your `.emacs' file. And
+when you install Emacs on a machine, you can create a `default.el' file
+which sets them properly for the typical location of most users of that
+machine. *Note Init File::.
+
+\1f
+File: xemacs.info, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary
+
+Phases of the Moon
+------------------
+
+ These calendar commands display the dates and times of the phases of
+the moon (new moon, first quarter, full moon, last quarter). This
+feature is useful for debugging problems that "depend on the phase of
+the moon."
+
+`M'
+ Display the dates and times for all the quarters of the moon for
+ the three-month period shown (`calendar-phases-of-moon').
+
+`M-x phases-of-moon'
+ Display dates and times of the quarters of the moon for three
+ months around today's date.
+
+ Within the calendar, use the `M' command to display a separate
+buffer of the phases of the moon for the current three-month range. The
+dates and times listed are accurate to within a few minutes.
+
+ Outside the calendar, use the command `M-x phases-of-moon' to
+display the list of the phases of the moon for the current month and the
+preceding and succeeding months. For information about a different
+month, use `C-u M-x phases-of-moon', which prompts for the month and
+year.
+
+ The dates and times given for the phases of the moon are given in
+local time (corrected for daylight savings, when appropriate); but if
+the variable `calendar-time-zone' is void, Coordinated Universal Time
+(the Greenwich time zone) is used. *Note Daylight Savings::.
+
+\1f
+File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar Phases, Up: Calendar/Diary
+
+Conversion To and From Other Calendars
+--------------------------------------
+
+ The Emacs calendar displayed is *always* the Gregorian calendar,
+sometimes called the "new style" calendar, which is used in most of the
+world today. However, this calendar did not exist before the sixteenth
+century and was not widely used before the eighteenth century; it did
+not fully displace the Julian calendar and gain universal acceptance
+until the early twentieth century. The Emacs calendar can display any
+month since January, year 1 of the current era, but the calendar
+displayed is the Gregorian, even for a date at which the Gregorian
+calendar did not exist.
+
+ While Emacs cannot display other calendars, it can convert dates to
+and from several other calendars.
+
+* Menu:
+
+* Calendar Systems:: The calendars Emacs understands
+ (aside from Gregorian).
+* To Other Calendar:: Converting the selected date to various calendars.
+* From Other Calendar:: Moving to a date specified in another calendar.
+* Mayan Calendar:: Moving to a date specified in a Mayan calendar.
+
+ If you are interested in these calendars, you can convert dates one
+at a time. Put point on the desired date of the Gregorian calendar and
+press the appropriate keys. The `p' is a mnemonic for "print" since
+Emacs "prints' the equivalent date in the echo area.
+
+\1f
+File: xemacs.info, Node: Calendar Systems, Next: To Other Calendar, Prev: Other Calendars, Up: Other Calendars
+
+Supported Calendar Systems
+==========================
+
+ The ISO commercial calendar is used largely in Europe.
+
+ The Julian calendar, named after Julius Caesar, was the one used in
+Europe throughout medieval times, and in many countries up until the
+nineteenth century.
+
+ Astronomers use a simple counting of days elapsed since noon, Monday,
+January 1, 4713 B.C. on the Julian calendar. The number of days elapsed
+is called the *Julian day number* or the *Astronomical day number*.
+
+ The Hebrew calendar is used by tradition in the Jewish religion. The
+Emacs calendar program uses the Hebrew calendar to determine the dates
+of Jewish holidays. Hebrew calendar dates begin and end at sunset.
+
+ The Islamic calendar is used in many predominantly Islamic countries.
+Emacs uses it to determine the dates of Islamic holidays. There is no
+universal agreement in the Islamic world about the calendar; Emacs uses
+a widely accepted version, but the precise dates of Islamic holidays
+often depend on proclamation by religious authorities, not on
+calculations. As a consequence, the actual dates of observance can vary
+slightly from the dates computed by Emacs. Islamic calendar dates begin
+and end at sunset.
+
+ The French Revolutionary calendar was created by the Jacobins after
+the 1789 revolution, to represent a more secular and nature-based view
+of the annual cycle, and to install a 10-day week in a rationalization
+measure similar to the metric system. The French government officially
+abandoned this calendar at the end of 1805.
+
+ The Maya of Central America used three separate, overlapping calendar
+systems, the *long count*, the *tzolkin*, and the *haab*. Emacs knows
+about all three of these calendars. Experts dispute the exact
+correlation between the Mayan calendar and our calendar; Emacs uses the
+Goodman-Martinez-Thompson correlation in its calculations.
+
+ The Copts use a calendar based on the ancient Egyptian solar
+calendar. Their calendar consists of twelve 30-day months followed by
+an extra five-day period. Once every fourth year they add a leap day
+to this extra period to make it six days. The Ethiopic calendar is
+identical in structure, but has different year numbers and month names.
+
+ The Persians use a solar calendar based on a design of Omar Khayyam.
+Their calendar consists of twelve months of which the first six have 31
+days, the next five have 30 days, and the last has 29 in ordinary years
+and 30 in leap years. Leap years occur in a complicated pattern every
+four or five years.
+
+ The Chinese calendar is a complicated system of lunar months arranged
+into solar years. The years go in cycles of sixty, each year containing
+either twelve months in an ordinary year or thirteen months in a leap
+year; each month has either 29 or 30 days. Years, ordinary months, and
+days are named by combining one of ten "celestial stems" with one of
+twelve "terrestrial branches" for a total of sixty names that are
+repeated in a cycle of sixty.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars
+
+Converting To Other Calendars
+=============================
+
+ The following commands describe the selected date (the date at point)
+in various other calendar systems:
+
+`Button2 Other Calendars'
+ Display the date that you click on, expressed in various other
+ calendars.
+
+`p c'
+ Display ISO commercial calendar equivalent for selected day
+ (`calendar-print-iso-date').
+
+`p j'
+ Display Julian date for selected day
+ (`calendar-print-julian-date').
+
+`p a'
+ Display astronomical (Julian) day number for selected day
+ (`calendar-print-astro-day-number').
+
+`p h'
+ Display Hebrew date for selected day
+ (`calendar-print-hebrew-date').
+
+`p i'
+ Display Islamic date for selected day
+ (`calendar-print-islamic-date').
+
+`p f'
+ Display French Revolutionary date for selected day
+ (`calendar-print-french-date').
+
+`p C'
+ Display Chinese date for selected day
+ (`calendar-print-chinese-date').
+
+`p k'
+ Display Coptic date for selected day
+ (`calendar-print-coptic-date').
+
+`p e'
+ Display Ethiopic date for selected day
+ (`calendar-print-ethiopic-date').
+
+`p p'
+ Display Persian date for selected day
+ (`calendar-print-persian-date').
+
+`p m'
+ Display Mayan date for selected day (`calendar-print-mayan-date').
+
+ If you are using X, the easiest way to translate a date into other
+calendars is to click on it with `Button2', then choose `Other
+Calendars' from the menu that appears. This displays the equivalent
+forms of the date in all the calendars Emacs understands, in the form of
+a menu. (Choosing an alternative from this menu doesn't actually do
+anything--the menu is used only for display.)
+
+ Put point on the desired date of the Gregorian calendar, then type
+the appropriate keys. The `p' is a mnemonic for "print" since Emacs
+"prints" the equivalent date in the echo area.
+
+\1f
+File: xemacs.info, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars
+
+Converting From Other Calendars
+===============================
+
+ You can use the other supported calendars to specify a date to move
+to. This section describes the commands for doing this using calendars
+other than Mayan; for the Mayan calendar, see the following section.
+
+`g c'
+ Move to a date specified in the ISO commercial calendar
+ (`calendar-goto-iso-date').
+
+`g j'
+ Move to a date specified in the Julian calendar
+ (`calendar-goto-julian-date').
+
+`g a'
+ Move to a date specified in astronomical (Julian) day number
+ (`calendar-goto-astro-day-number').
+
+`g h'
+ Move to a date specified in the Hebrew calendar
+ (`calendar-goto-hebrew-date').
+
+`g i'
+ Move to a date specified in the Islamic calendar
+ (`calendar-goto-islamic-date').
+
+`g f'
+ Move to a date specified in the French Revolutionary calendar
+ (`calendar-goto-french-date').
+
+`g C'
+ Move to a date specified in the Chinese calendar
+ (`calendar-goto-chinese-date').
+
+`g p'
+ Move to a date specified in the Persian calendar
+ (`calendar-goto-persian-date').
+
+`g k'
+ Move to a date specified in the Coptic calendar
+ (`calendar-goto-coptic-date').
+
+`g e'
+ Move to a date specified in the Ethiopic calendar
+ (`calendar-goto-ethiopic-date').
+
+ These commands ask you for a date on the other calendar, move point
+to the Gregorian calendar date equivalent to that date, and display the
+other calendar's date in the echo area. Emacs uses strict completion
+(*note Completion::.) whenever it asks you to type a month name, so you
+don't have to worry about the spelling of Hebrew, Islamic, or French
+names.
+
+ One common question concerning the Hebrew calendar is the computation
+of the anniversary of a date of death, called a "yahrzeit." The Emacs
+calendar includes a facility for such calculations. If you are in the
+calendar, the command `M-x list-yahrzeit-dates' asks you for a range of
+years and then displays a list of the yahrzeit dates for those years
+for the date given by point. If you are not in the calendar, this
+command first asks you for the date of death and the range of years,
+and then displays the list of yahrzeit dates.
+
+\1f
+File: xemacs.info, Node: Mayan Calendar, Next: Diary, Prev: From Other Calendar, Up: Other Calendars
+
+Converting from the Mayan Calendar
+----------------------------------
+
+ Here are the commands to select dates based on the Mayan calendar:
+
+`g m l'
+ Move to a date specified by the long count calendar
+ (`calendar-goto-mayan-long-count-date').
+
+`g m n t'
+ Move to the next occurrence of a place in the tzolkin calendar
+ (`calendar-next-tzolkin-date').
+
+`g m p t'
+ Move to the previous occurrence of a place in the tzolkin calendar
+ (`calendar-previous-tzolkin-date').
+
+`g m n h'
+ Move to the next occurrence of a place in the haab calendar
+ (`calendar-next-haab-date').
+
+`g m p h'
+ Move to the previous occurrence of a place in the haab calendar
+ (`calendar-previous-haab-date').
+
+`g m n c'
+ Move to the next occurrence of a place in the calendar round
+ (`calendar-next-calendar-round-date').
+
+`g m p c'
+ Move to the previous occurrence of a place in the calendar round
+ (`calendar-previous-calendar-round-date').
+
+ To understand these commands, you need to understand the Mayan
+calendars. The "long count" is a counting of days with these units:
+
+ 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal
+ 1 katun = 20 tun 1 baktun = 20 katun
+
+Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11
+tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long
+count dates as early as 7.17.18.13.1, but no earlier. When you use the
+`g m l' command, type the Mayan long count date with the baktun, katun,
+tun, uinal, and kin separated by periods.
+
+ The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of
+independent cycles of 13 and 20 days. Since this cycle repeats
+endlessly, Emacs provides commands to move backward and forward to the
+previous or next point in the cycle. Type `g m p t' to go to the
+previous tzolkin date; Emacs asks you for a tzolkin date and moves point
+to the previous occurrence of that date. Similarly, type `g m n t' to
+go to the next occurrence of a tzolkin date.
+
+ The Mayan haab calendar is a cycle of 365 days arranged as 18 months
+of 20 days each, followed a 5-day monthless period. Like the tzolkin
+cycle, this cycle repeats endlessly, and there are commands to move
+backward and forward to the previous or next point in the cycle. Type
+`g m p h' to go to the previous haab date; Emacs asks you for a haab
+date and moves point to the previous occurrence of that date.
+Similarly, type `g m n h' to go to the next occurrence of a haab date.
+
+ The Maya also used the combination of the tzolkin date and the haab
+date. This combination is a cycle of about 52 years called a *calendar
+round*. If you type `g m p c', Emacs asks you for both a haab and a
+tzolkin date and then moves point to the previous occurrence of that
+combination. Use `g m n c' to move point to the next occurrence of a
+combination. These commands signal an error if the haab/tzolkin date
+combination you have typed is impossible.
+
+ Emacs uses strict completion (*note Completion::.) whenever it asks
+you to type a Mayan name, so you don't have to worry about spelling.
+
+\1f
+File: xemacs.info, Node: Diary, Next: Calendar Customization, Prev: Mayan Calendar, Up: Calendar/Diary
+
+The Diary
+---------
+
+ The Emacs diary keeps track of appointments or other events on a
+daily basis, in conjunction with the calendar. To use the diary
+feature, you must first create a "diary file" containing a list of
+events and their dates. Then Emacs can automatically pick out and
+display the events for today, for the immediate future, or for any
+specified date.
+
+ By default, Emacs uses `~/diary' as the diary file. This is the
+same file that the `calendar' utility uses. A sample `~/diary' file is:
+
+ 12/22/1988 Twentieth wedding anniversary!!
+ &1/1. Happy New Year!
+ 10/22 Ruth's birthday.
+ * 21, *: Payday
+ Tuesday--weekly meeting with grad students at 10am
+ Supowit, Shen, Bitner, and Kapoor to attend.
+ 1/13/89 Friday the thirteenth!!
+ &thu 4pm squash game with Lloyd.
+ mar 16 Dad's birthday
+ April 15, 1989 Income tax due.
+ &* 15 time cards due.
+
+This example uses extra spaces to align the event descriptions of most
+of the entries. Such formatting is purely a matter of taste.
+
+ Although you probably will start by creating a diary manually, Emacs
+provides a number of commands to let you view, add, and change diary
+entries. You can also share diary entries with other users (*note
+Included Diary Files::.).
+
+* Menu:
+
+* Diary Commands:: Viewing diary entries and associated calendar dates.
+* Format of Diary File:: Entering events in your diary.
+* Date Formats:: Various ways you can specify dates.
+* Adding to Diary:: Commands to create diary entries.
+* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.
+
+\1f
+File: xemacs.info, Node: Diary Commands, Next: Format of Diary File, Prev: Diary, Up: Diary
+
+Commands Displaying Diary Entries
+---------------------------------
+
+ Once you have created a `~/diary' file, you can use the calendar to
+view it. You can also view today's events outside of Calendar mode.
+
+`d'
+ Display all diary entries for the selected date
+ (`view-diary-entries').
+
+`Button2 Diary'
+ Display all diary entries for the date you click on.
+
+`s'
+ Display the entire diary file (`show-all-diary-entries').
+
+`m'
+ Mark all visible dates that have diary entries
+ (`mark-diary-entries').
+
+`u'
+ Unmark the calendar window (`calendar-unmark').
+
+`M-x print-diary-entries'
+ Print hard copy of the diary display as it appears.
+
+`M-x diary'
+ Display all diary entries for today's date.
+
+`M-x diary-mail-entries'
+ Mail yourself email reminders about upcoming diary entries.
+
+ Displaying the diary entries with `d' shows in a separate window the
+diary entries for the selected date in the calendar. The mode line of
+the new window shows the date of the diary entries and any holidays
+that fall on that date. If you specify a numeric argument with `d', it
+shows all the diary entries for that many successive days. Thus, `2 d'
+displays all the entries for the selected date and for the following
+day.
+
+ Another way to display the diary entries for a date is to click
+`Button2' on the date, and then choose `Diary' from the menu that
+appears.
+
+ To get a broader view of which days are mentioned in the diary, use
+the `m' command. This displays the dates that have diary entries in a
+different face (or places a `+' after these dates, if display with
+multiple faces is not available). The command applies both to the
+currently visible months and to other months that subsequently become
+visible by scrolling. To turn marking off and erase the current marks,
+type `u', which also turns off holiday marks (*note Holidays::.).
+
+ To see the full diary file, rather than just some of the entries, use
+the `s' command.
+
+ Display of selected diary entries uses the selective display feature
+to hide entries that don't apply.
+
+ The diary buffer as you see it is an illusion, so simply printing the
+buffer does not print what you see on your screen. There is a special
+command to print hard copy of the diary buffer *as it appears*; this
+command is `M-x print-diary-entries'. It sends the data directly to
+the printer. You can customize it like `lpr-region' (*note
+Hardcopy::.).
+
+ The command `M-x diary' displays the diary entries for the current
+date, independently of the calendar display, and optionally for the next
+few days as well; the variable `number-of-diary-entries' specifies how
+many days to include (*note Customization::.).
+
+ If you put `(diary)' in your `.emacs' file, this automatically
+displays a window with the day's diary entries, when you enter Emacs.
+The mode line of the displayed window shows the date and any holidays
+that fall on that date.
+
+ Many users like to receive notice of events in their diary as email.
+To send such mail to yourself, use the command `M-x
+diary-mail-entries'. A prefix argument specifies how many days
+(starting with today) to check; otherwise, the variable
+`diary-mail-days' says how many days.
+
+\1f
+File: xemacs.info, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary
+
+The Diary File
+--------------
+
+ Your "diary file" is a file that records events associated with
+particular dates. The name of the diary file is specified by the
+variable `diary-file'; `~/diary' is the default. The `calendar'
+utility program supports a subset of the format allowed by the Emacs
+diary facilities, so you can use that utility to view the diary file,
+with reasonable results aside from the entries it cannot understand.
+
+ Each entry in the diary file describes one event and consists of one
+or more lines. An entry always begins with a date specification at the
+left margin. The rest of the entry is simply text to describe the
+event. If the entry has more than one line, then the lines after the
+first must begin with whitespace to indicate they continue a previous
+entry. Lines that do not begin with valid dates and do not continue a
+preceding entry are ignored.
+
+ You can inhibit the marking of certain diary entries in the calendar
+window; to do this, insert an ampersand (`&') at the beginning of the
+entry, before the date. This has no effect on display of the entry in
+the diary window; it affects only marks on dates in the calendar
+window. Nonmarking entries are especially useful for generic entries
+that would otherwise mark many different dates.
+
+ If the first line of a diary entry consists only of the date or day
+name with no following blanks or punctuation, then the diary window
+display doesn't include that line; only the continuation lines appear.
+For example, this entry:
+
+ 02/11/1989
+ Bill B. visits Princeton today
+ 2pm Cognitive Studies Committee meeting
+ 2:30-5:30 Liz at Lawrenceville
+ 4:00pm Dentist appt
+ 7:30pm Dinner at George's
+ 8:00-10:00pm concert
+
+appears in the diary window without the date line at the beginning.
+This style of entry looks neater when you display just a single day's
+entries, but can cause confusion if you ask for more than one day's
+entries.
+
+ You can edit the diary entries as they appear in the window, but it
+is important to remember that the buffer displayed contains the *entire*
+diary file, with portions of it concealed from view. This means, for
+instance, that the `C-f' (`forward-char') command can put point at what
+appears to be the end of the line, but what is in reality the middle of
+some concealed line.
+
+ *Be careful when editing the diary entries!* Inserting additional
+lines or adding/deleting characters in the middle of a visible line
+cannot cause problems, but editing at the end of a line may not do what
+you expect. Deleting a line may delete other invisible entries that
+follow it. Before editing the diary, it is best to display the entire
+file with `s' (`show-all-diary-entries').
+
+\1f
+File: xemacs.info, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary
+
+Date Formats
+------------
+
+ Here are some sample diary entries, illustrating different ways of
+formatting a date. The examples all show dates in American order
+(month, day, year), but Calendar mode supports European order (day,
+month, year) as an option.
+
+ 4/20/93 Switch-over to new tabulation system
+ apr. 25 Start tabulating annual results
+ 4/30 Results for April are due
+ */25 Monthly cycle finishes
+ Friday Don't leave without backing up files
+
+ The first entry appears only once, on April 20, 1993. The second and
+third appear every year on the specified dates, and the fourth uses a
+wildcard (asterisk) for the month, so it appears on the 25th of every
+month. The final entry appears every week on Friday.
+
+ You can use just numbers to express a date, as in `MONTH/DAY' or
+`MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date
+itself, MONTH and DAY are numbers of one or two digits. The optional
+YEAR is also a number, and may be abbreviated to the last two digits;
+that is, you can use `11/12/1989' or `11/12/89'.
+
+ Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY,
+YEAR', where the month's name can be spelled in full or abbreviated to
+three characters (with or without a period). Case is not significant.
+
+ A date may be "generic"; that is, partially unspecified. Then the
+entry applies to all dates that match the specification. If the date
+does not contain a year, it is generic and applies to any year.
+Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any
+month, day, or year, respectively. Thus, a diary entry `3/*/*' matches
+any day in March of any year; so does `march *'.
+
+ If you prefer the European style of writing dates--in which the day
+comes before the month--type `M-x european-calendar' while in the
+calendar, or set the variable `european-calendar-style' to `t' *before*
+using any calendar or diary command. This mode interprets all dates in
+the diary in the European manner, and also uses European style for
+displaying diary dates. (Note that there is no comma after the
+MONTHNAME in the European style.) To go back to the (default) American
+style of writing dates, type `M-x american-calendar'.
+
+ You can use the name of a day of the week as a generic date which
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: xemacs.info, Node: Calendar Customization, Prev: Diary, Up: Calendar/Diary
+
+Customizing the Calendar and Diary
+----------------------------------
+
+ There are many customizations that you can use to make the calendar
+and diary suit your personal tastes.
+
+* Menu:
+
+* Calendar Customizing:: Defaults you can set.
+* Holiday Customizing:: Defining your own holidays.
+* Date Display Format:: Changing the format.
+* Time Display Format:: Changing the format.
+* Daylight Savings:: Changing the default.
+* Diary Customizing:: Defaults you can set.
+* Hebrew/Islamic Entries:: How to obtain them.
+* Fancy Diary Display:: Enhancing the diary display, sorting entries.
+* Included Diary Files:: Sharing a common diary file.
+* Sexp Diary Entries:: Fancy things you can do.
+* Appt Customizing:: Customizing appointment reminders.
+
+\1f
+File: xemacs.info, Node: Calendar Customizing, Next: Holiday Customizing, Up: Calendar Customization
+
+Customizing the Calendar
+........................
+
+ If you set the variable `view-diary-entries-initially' to `t',
+calling up the calendar automatically displays the diary entries for
+the current date as well. The diary dates appear only if the current
+date is visible. If you add both of the following lines to your
+`.emacs' file:
+
+ (setq view-diary-entries-initially t)
+ (calendar)
+
+this displays both the calendar and diary windows whenever you start
+Emacs.
+
+ Similarly, if you set the variable
+`view-calendar-holidays-initially' to `t', entering the calendar
+automatically displays a list of holidays for the current three-month
+period. The holiday list appears in a separate window.
+
+ You can set the variable `mark-diary-entries-in-calendar' to `t' in
+order to mark any dates with diary entries. This takes effect whenever
+the calendar window contents are recomputed. There are two ways of
+marking these dates: by changing the face (*note Faces::.), if the
+display supports that, or by placing a plus sign (`+') beside the date
+otherwise.
+
+ Similarly, setting the variable `mark-holidays-in-calendar' to `t'
+marks holiday dates, either with a change of face or with an asterisk
+(`*').
+
+ The variable `calendar-holiday-marker' specifies how to mark a date
+as being a holiday. Its value may be a character to insert next to the
+date, or a face name to use for displaying the date. Likewise, the
+variable `diary-entry-marker' specifies how to mark a date that has
+diary entries. The calendar creates faces named `holiday-face' and
+`diary-face' for these purposes; those symbols are the default values
+of these variables, when Emacs supports multiple faces on your terminal.
+
+ The variable `calendar-load-hook' is a normal hook run when the
+calendar package is first loaded (before actually starting to display
+the calendar).
+
+ Starting the calendar runs the normal hook
+`initial-calendar-window-hook'. Recomputation of the calendar display
+does not run this hook. But if you leave the calendar with the `q'
+command and reenter it, the hook runs again.
+
+ The variable `today-visible-calendar-hook' is a normal hook run
+after the calendar buffer has been prepared with the calendar when the
+current date is visible in the window. One use of this hook is to
+replace today's date with asterisks; to do that, use the hook function
+`calendar-star-date'.
+
+ (add-hook 'today-visible-calendar-hook 'calendar-star-date)
+
+Another standard hook function marks the current date, either by
+changing its face or by adding an asterisk. Here's how to use it:
+
+ (add-hook 'today-visible-calendar-hook 'calendar-mark-today)
+
+The variable `calendar-today-marker' specifies how to mark today's
+date. Its value should be a character to insert next to the date or a
+face name to use for displaying the date. A face named
+`calendar-today-face' is provided for this purpose; that symbol is the
+default for this variable when Emacs supports multiple faces on your
+terminal.
+
+A similar normal hook, `today-invisible-calendar-hook' is run if the
+current date is *not* visible in the window.
+
+\1f
+File: xemacs.info, Node: Holiday Customizing, Next: Date Display Format, Prev: Calendar Customizing, Up: Calendar Customization
+
+Customizing the Holidays
+........................
+
+ Emacs knows about holidays defined by entries on one of several
+lists. You can customize these lists of holidays to your own needs,
+adding or deleting holidays. The lists of holidays that Emacs uses are
+for general holidays (`general-holidays'), local holidays
+(`local-holidays'), Christian holidays (`christian-holidays'), Hebrew
+(Jewish) holidays (`hebrew-holidays'), Islamic (Moslem) holidays
+(`islamic-holidays'), and other holidays (`other-holidays').
+
+ The general holidays are, by default, holidays common throughout the
+United States. To eliminate these holidays, set `general-holidays' to
+`nil'.
+
+ There are no default local holidays (but sites may supply some). You
+can set the variable `local-holidays' to any list of holidays, as
+described below.
+
+ By default, Emacs does not include all the holidays of the religions
+that it knows, only those commonly found in secular calendars. For a
+more extensive collection of religious holidays, you can set any (or
+all) of the variables `all-christian-calendar-holidays',
+`all-hebrew-calendar-holidays', or `all-islamic-calendar-holidays' to
+`t'. If you want to eliminate the religious holidays, set any or all
+of the corresponding variables `christian-holidays', `hebrew-holidays',
+and `islamic-holidays' to `nil'.
+
+ You can set the variable `other-holidays' to any list of holidays.
+This list, normally empty, is intended for individual use.
+
+ Each of the lists (`general-holidays', `local-holidays',
+`christian-holidays', `hebrew-holidays', `islamic-holidays', and
+`other-holidays') is a list of "holiday forms", each holiday form
+describing a holiday (or sometimes a list of holidays).
+
+ Here is a table of the possible kinds of holiday form. Day numbers
+and month numbers count starting from 1, but "dayname" numbers count
+Sunday as 0. The element STRING is always the name of the holiday, as
+a string.
+
+`(holiday-fixed MONTH DAY STRING)'
+ A fixed date on the Gregorian calendar. MONTH and DAY are
+ numbers, STRING is the name of the holiday.
+
+`(holiday-float MONTH DAYNAME K STRING)'
+ The Kth DAYNAME in MONTH on the Gregorian calendar (DAYNAME=0 for
+ Sunday, and so on); negative K means count back from the end of
+ the month. STRING is the name of the holiday.
+
+`(holiday-hebrew MONTH DAY STRING)'
+ A fixed date on the Hebrew calendar. MONTH and DAY are numbers,
+ STRING is the name of the holiday.
+
+`(holiday-islamic MONTH DAY STRING)'
+ A fixed date on the Islamic calendar. MONTH and DAY are numbers,
+ STRING is the name of the holiday.
+
+`(holiday-julian MONTH DAY STRING)'
+ A fixed date on the Julian calendar. MONTH and DAY are numbers,
+ STRING is the name of the holiday.
+
+`(holiday-sexp SEXP STRING)'
+ A date calculated by the Lisp expression SEXP. The expression
+ should use the variable `year' to compute and return the date of a
+ holiday, or `nil' if the holiday doesn't happen this year. The
+ value of SEXP must represent the date as a list of the form
+ `(MONTH DAY YEAR)'. STRING is the name of the holiday.
+
+`(if CONDITION HOLIDAY-FORM &optional HOLIDAY-FORM)'
+ A holiday that happens only if CONDITION is true.
+
+`(FUNCTION [ARGS])'
+ A list of dates calculated by the function FUNCTION, called with
+ arguments ARGS.
+
+ For example, suppose you want to add Bastille Day, celebrated in
+France on July 14. You can do this by adding the following line to
+your `.emacs' file:
+
+ (setq other-holidays '((holiday-fixed 7 14 "Bastille Day")))
+
+The holiday form `(holiday-fixed 7 14 "Bastille Day")' specifies the
+fourteenth day of the seventh month (July).
+
+ Many holidays occur on a specific day of the week, at a specific time
+of month. Here is a holiday form describing Hurricane Supplication Day,
+celebrated in the Virgin Islands on the fourth Monday in August:
+
+ (holiday-float 8 1 4 "Hurricane Supplication Day")
+
+Here the 8 specifies August, the 1 specifies Monday (Sunday is 0,
+Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in
+the month (1 specifies the first occurrence, 2 the second occurrence,
+-1 the last occurrence, -2 the second-to-last occurrence, and so on).
+
+ You can specify holidays that occur on fixed days of the Hebrew,
+Islamic, and Julian calendars too. For example,
+
+ (setq other-holidays
+ '((holiday-hebrew 10 2 "Last day of Hanukkah")
+ (holiday-islamic 3 12 "Mohammed's Birthday")
+ (holiday-julian 4 2 "Jefferson's Birthday")))
+
+adds the last day of Hanukkah (since the Hebrew months are numbered with
+1 starting from Nisan), the Islamic feast celebrating Mohammed's
+birthday (since the Islamic months are numbered from 1 starting with
+Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the
+Julian calendar.
+
+ To include a holiday conditionally, use either Emacs Lisp's `if' or
+the `holiday-sexp' form. For example, American presidential elections
+occur on the first Tuesday after the first Monday in November of years
+divisible by 4:
+
+ (holiday-sexp (if (= 0 (% year 4))
+ (calendar-gregorian-from-absolute
+ (1+ (calendar-dayname-on-or-before
+ 1 (+ 6 (calendar-absolute-from-gregorian
+ (list 11 1 year))))))
+ "US Presidential Election"))
+
+or
+
+ (if (= 0 (% displayed-year 4))
+ (fixed 11
+ (extract-calendar-day
+ (calendar-gregorian-from-absolute
+ (1+ (calendar-dayname-on-or-before
+ 1 (+ 6 (calendar-absolute-from-gregorian
+ (list 11 1 displayed-year)))))))
+ "US Presidential Election"))
+
+ Some holidays just don't fit into any of these forms because special
+calculations are involved in their determination. In such cases you
+must write a Lisp function to do the calculation. To include eclipses,
+for example, add `(eclipses)' to `other-holidays' and write an Emacs
+Lisp function `eclipses' that returns a (possibly empty) list of the
+relevant Gregorian dates among the range visible in the calendar
+window, with descriptive strings, like this:
+
+ (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... )
+
+\1f
+File: xemacs.info, Node: Date Display Format, Next: Time Display Format, Prev: Holiday Customizing, Up: Calendar Customization
+
+Date Display Format
+...................
+
+ You can customize the manner of displaying dates in the diary, in
+mode lines, and in messages by setting `calendar-date-display-form'.
+This variable holds a list of expressions that can involve the variables
+`month', `day', and `year', which are all numbers in string form, and
+`monthname' and `dayname', which are both alphabetic strings. In the
+American style, the default value of this list is as follows:
+
+ ((if dayname (concat dayname ", ")) monthname " " day ", " year)
+
+while in the European style this value is the default:
+
+ ((if dayname (concat dayname ", ")) day " " monthname " " year)
+
+ + The ISO standard date representation is this:
+
+ (year "-" month "-" day)
+
+This specifies a typical American format:
+
+ (month "/" day "/" (substring year -2))
+
+\1f
+File: xemacs.info, Node: Time Display Format, Next: Daylight Savings, Prev: Date Display Format, Up: Calendar Customization
+
+Time Display Format
+...................
+
+ The calendar and diary by default display times of day in the
+conventional American style with the hours from 1 through 12, minutes,
+and either `am' or `pm'. If you prefer the European style, also known
+in the US as military, in which the hours go from 00 to 23, you can
+alter the variable `calendar-time-display-form'. This variable is a
+list of expressions that can involve the variables `12-hours',
+`24-hours', and `minutes', which are all numbers in string form, and
+`am-pm' and `time-zone', which are both alphabetic strings. The
+default value of `calendar-time-display-form' is as follows:
+
+ (12-hours ":" minutes am-pm
+ (if time-zone " (") time-zone (if time-zone ")"))
+
+Here is a value that provides European style times:
+
+ (24-hours ":" minutes
+ (if time-zone " (") time-zone (if time-zone ")"))
+
+gives military-style times like `21:07 (UT)' if time zone names are
+defined, and times like `21:07' if they are not.
+
+\1f
+File: xemacs.info, Node: Daylight Savings, Next: Diary Customizing, Prev: Time Display Format, Up: Calendar Customization
+
+Daylight Savings Time
+.....................
+
+ Emacs understands the difference between standard time and daylight
+savings time--the times given for sunrise, sunset, solstices,
+equinoxes, and the phases of the moon take that into account. The rules
+for daylight savings time vary from place to place and have also varied
+historically from year to year. To do the job properly, Emacs needs to
+know which rules to use.
+
+ Some operating systems keep track of the rules that apply to the
+place where you are; on these systems, Emacs gets the information it
+needs from the system automatically. If some or all of this
+information is missing, Emacs fills in the gaps with the rules
+currently used in Cambridge, Massachusetts. If the resulting rules are
+not what you want, you can tell Emacs the rules to use by setting
+certain variables.
+
+ If the default choice of rules is not appropriate for your location,
+you can tell Emacs the rules to use by setting the variables
+`calendar-daylight-savings-starts' and
+`calendar-daylight-savings-ends'. Their values should be Lisp
+expressions that refer to the variable `year', and evaluate to the
+Gregorian date on which daylight savings time starts or (respectively)
+ends, in the form of a list `(MONTH DAY YEAR)'. The values should be
+`nil' if your area does not use daylight savings time.
+
+ Emacs uses these expressions to determine the starting date of
+daylight savings time for the holiday list and for correcting times of
+day in the solar and lunar calculations.
+
+ The values for Cambridge, Massachusetts are as follows:
+
+ (calendar-nth-named-day 1 0 4 year)
+ (calendar-nth-named-day -1 0 10 year)
+
+That is, the first 0th day (Sunday) of the fourth month (April) in the
+year specified by `year', and the last Sunday of the tenth month
+(October) of that year. If daylight savings time were changed to start
+on October 1, you would set `calendar-daylight-savings-starts' to this:
+
+ (list 10 1 year)
+
+ For a more complex example, suppose daylight savings time begins on
+the first of Nisan on the Hebrew calendar. You should set
+`calendar-daylight-savings-starts' to this value:
+
+ (calendar-gregorian-from-absolute
+ (calendar-absolute-from-hebrew
+ (list 1 1 (+ year 3760))))
+
+because Nisan is the first month in the Hebrew calendar and the Hebrew
+year differs from the Gregorian year by 3760 at Nisan.
+
+ If there is no daylight savings time at your location, or if you want
+all times in standard time, set `calendar-daylight-savings-starts' and
+`calendar-daylight-savings-ends' to `nil'.
+
+ The variable `calendar-daylight-time-offset' specifies the
+difference between daylight savings time and standard time, measured in
+minutes. The value for Cambridge, Massachusetts is 60.
+
+ The two variables `calendar-daylight-savings-starts-time' and
+`calendar-daylight-savings-ends-time' specify the number of minutes
+after midnight local time when the transition to and from daylight
+savings time should occur. For Cambridge, Massachusetts both variables'
+values are 120.
+
+\1f
+File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization
+
+Customizing the Diary
+.....................
+
+ Ordinarily, the mode line of the diary buffer window indicates any
+holidays that fall on the date of the diary entries. The process of
+checking for holidays can take several seconds, so including holiday
+information delays the display of the diary buffer noticeably. If you'd
+prefer to have a faster display of the diary buffer but without the
+holiday information, set the variable `holidays-in-diary-buffer' to
+`nil'.
+
+ The variable `number-of-diary-entries' controls the number of days
+of diary entries to be displayed at one time. It affects the initial
+display when `view-diary-entries-initially' is `t', as well as the
+command `M-x diary'. For example, the default value is 1, which says
+to display only the current day's diary entries. If the value is 2,
+both the current day's and the next day's entries are displayed. The
+value can also be a vector of seven elements: for example, if the value
+is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the
+current date's and the next day's diary entries appear Monday through
+Thursday, Friday through Monday's entries appear on Friday, while on
+Saturday only that day's entries appear.
+
+ The variable `print-diary-entries-hook' is a normal hook run after
+preparation of a temporary buffer containing just the diary entries
+currently visible in the diary buffer. (The other, irrelevant diary
+entries are really absent from the temporary buffer; in the diary
+buffer, they are merely hidden.) The default value of this hook does
+the printing with the command `lpr-buffer'. If you want to use a
+different command to do the printing, just change the value of this
+hook. Other uses might include, for example, rearranging the lines into
+order by day and time.
+
+ You can customize the form of dates in your diary file, if neither
+the standard American nor European styles suits your needs, by setting
+the variable `diary-date-forms'. This variable is a list of patterns
+for recognizing a date. Each date pattern is a list whose elements may
+be regular expressions (*note Regexps::.) or the symbols `month',
+`day', `year', `monthname', and `dayname'. All these elements serve as
+patterns that match certain kinds of text in the diary file. In order
+for the date pattern, as a whole, to match, all of its elements must
+match consecutively.
+
+ A regular expression in a date pattern matches in its usual fashion,
+using the standard syntax table altered so that `*' is a word
+constituent.
+
+ The symbols `month', `day', `year', `monthname', and `dayname' match
+the month number, day number, year number, month name, and day name of
+the date being considered. The symbols that match numbers allow
+leading zeros; those that match names allow three-letter abbreviations
+and capitalization. All the symbols can match `*'; since `*' in a
+diary entry means "any day", "any month", and so on, it should match
+regardless of the date being considered.
+
+ The default value of `diary-date-forms' in the American style is
+this:
+
+ ((month "/" day "[^/0-9]")
+ (month "/" day "/" year "[^0-9]")
+ (monthname " *" day "[^,0-9]")
+ (monthname " *" day ", *" year "[^0-9]")
+ (dayname "\\W"))
+
+Emacs matches of the diary entries with the date forms is done with the
+standard syntax table from Fundamental mode (*note Syntax Tables:
+(lispref)Syntax Tables.), but with the `*' changed so that it is a word
+constituent.
+
+ The date patterns in the list must be *mutually exclusive* and must
+not match any portion of the diary entry itself, just the date and one
+character of whitespace. If, to be mutually exclusive, the pattern
+must match a portion of the diary entry text--beyond the whitespace
+that ends the date--then the first element of the date pattern *must*
+be `backup'. This causes the date recognizer to back up to the
+beginning of the current word of the diary entry, after finishing the
+match. Even if you use `backup', the date pattern must absolutely not
+match more than a portion of the first word of the diary entry. The
+default value of `diary-date-forms' in the European style is this list:
+
+ ((day "/" month "[^/0-9]")
+ (day "/" month "/" year "[^0-9]")
+ (backup day " *" monthname "\\W+\\<[^*0-9]")
+ (day " *" monthname " *" year "[^0-9]")
+ (dayname "\\W"))
+
+Notice the use of `backup' in the third pattern, because it needs to
+match part of a word beyond the date itself to distinguish it from the
+fourth pattern.
+
+\1f
+File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization
+
+Hebrew- and Islamic-Date Diary Entries
+......................................
+
+ Your diary file can have entries based on Hebrew or Islamic dates, as
+well as entries based on the world-standard Gregorian calendar.
+However, because recognition of such entries is time-consuming and most
+people don't use them, you must explicitly enable their use. If you
+want the diary to recognize Hebrew-date diary entries, for example, you
+must do this:
+
+ (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries)
+ (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries)
+
+If you want Islamic-date entries, do this:
+
+ (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries)
+ (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries)
+
+ Hebrew- and Islamic-date diary entries have the same formats as
+Gregorian-date diary entries, except that `H' precedes a Hebrew date
+and `I' precedes an Islamic date. Moreover, because the Hebrew and
+Islamic month names are not uniquely specified by the first three
+letters, you may not abbreviate them. For example, a diary entry for
+the Hebrew date Heshvan 25 could look like this:
+
+ HHeshvan 25 Happy Hebrew birthday!
+
+and would appear in the diary for any date that corresponds to Heshvan
+25 on the Hebrew calendar. And here is Islamic-date diary entry that
+matches Dhu al-Qada 25:
+
+ IDhu al-Qada 25 Happy Islamic birthday!
+
+and would appear in the diary for any date that corresponds to Dhu
+al-Qada 25 on the Islamic calendar.
+
+ As with Gregorian-date diary entries, Hebrew- and Islamic-date
+entries are nonmarking if they are preceded with an ampersand (`&').
+
+ Here is a table of commands used in the calendar to create diary
+entries that match the selected date and other dates that are similar
+in the Hebrew or Islamic calendar:
+
+`i h d'
+ Add a diary entry for the Hebrew date corresponding to the
+ selected date (`insert-hebrew-diary-entry').
+
+`i h m'
+ Add a diary entry for the day of the Hebrew month corresponding to
+ the selected date (`insert-monthly-hebrew-diary-entry'). This
+ diary entry matches any date that has the same Hebrew
+ day-within-month as the selected date.
+
+`i h y'
+ Add a diary entry for the day of the Hebrew year corresponding to
+ the selected date (`insert-yearly-hebrew-diary-entry'). This diary
+ entry matches any date which has the same Hebrew month and
+ day-within-month as the selected date.
+
+`i i d'
+ Add a diary entry for the Islamic date corresponding to the
+ selected date (`insert-islamic-diary-entry').
+
+`i i m'
+ Add a diary entry for the day of the Islamic month corresponding
+ to the selected date (`insert-monthly-islamic-diary-entry').
+
+`i i y'
+ Add a diary entry for the day of the Islamic year corresponding to
+ the selected date (`insert-yearly-islamic-diary-entry').
+
+ These commands work much like the corresponding commands for ordinary
+diary entries: they apply to the date that point is on in the calendar
+window, and what they do is insert just the date portion of a diary
+entry at the end of your diary file. You must then insert the rest of
+the diary entry.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization
+
+Fancy Diary Display
+...................
+
+ Diary display works by preparing the diary buffer and then running
+the hook `diary-display-hook'. The default value of this hook
+(`simple-diary-display') hides the irrelevant diary entries and then
+displays the buffer. However, if you specify the hook as follows,
+
+ (add-hook 'diary-display-hook 'fancy-diary-display)
+
+this enables fancy diary display. It displays diary entries and
+holidays by copying them into a special buffer that exists only for the
+sake of display. Copying to a separate buffer provides an opportunity
+to change the displayed text to make it prettier--for example, to sort
+the entries by the dates they apply to.
+
+ As with simple diary display, you can print a hard copy of the buffer
+with `print-diary-entries'. To print a hard copy of a day-by-day diary
+for a week by positioning point on Sunday of that week, type `7 d' and
+then do `M-x print-diary-entries'. As usual, the inclusion of the
+holidays slows down the display slightly; you can speed things up by
+setting the variable `holidays-in-diary-buffer' to `nil'.
+
+ Ordinarily, the fancy diary buffer does not show days for which
+there are no diary entries, even if that day is a holiday. If you want
+such days to be shown in the fancy diary buffer, set the variable
+`diary-list-include-blanks' to `t'.
+
+ If you use the fancy diary display, you can use the normal hook
+`list-diary-entries-hook' to sort each day's diary entries by their
+time of day. Add this line to your `.emacs' file:
+
+ (add-hook 'list-diary-entries-hook 'sort-diary-entries t)
+
+For each day, this sorts diary entries that begin with a recognizable
+time of day according to their times. Diary entries without times come
+first within each day.
+
+\1f
+File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization
+
+Included Diary Files
+....................
+
+ Fancy diary display also has the ability to process included diary
+files. This permits a group of people to share a diary file for events
+that apply to all of them. Lines in the diary file of this form:
+
+ #include "FILENAME"
+
+includes the diary entries from the file FILENAME in the fancy diary
+buffer. The include mechanism is recursive, so that included files can
+include other files, and so on; you must be careful not to have a cycle
+of inclusions, of course. Here is how to enable the include facility:
+
+ (add-hook 'list-diary-entries-hook 'include-other-diary-files)
+ (add-hook 'mark-diary-entries-hook 'mark-included-diary-files)
+
+ The include mechanism works only with the fancy diary display,
+because ordinary diary display shows the entries directly from your
+diary file.
+
+\1f
+File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization
+
+Sexp Entries and the Fancy Diary Display
+........................................
+
+ Sexp diary entries allow you to do more than just have complicated
+conditions under which a diary entry applies. If you use the fancy
+diary display, sexp entries can generate the text of the entry depending
+on the date itself. For example, an anniversary diary entry can insert
+the number of years since the anniversary date into the text of the
+diary entry. Thus the `%d' in this dairy entry:
+
+ %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
+
+gets replaced by the age, so on October 31, 1990 the entry appears in
+the fancy diary buffer like this:
+
+ Arthur's birthday (42 years old)
+
+If the diary file instead contains this entry:
+
+ %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
+
+the entry in the fancy diary buffer for October 31, 1990 appears like
+this:
+
+ Arthur's 42nd birthday
+
+ Similarly, cyclic diary entries can interpolate the number of
+repetitions that have occurred:
+
+ %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
+
+looks like this:
+
+ Renew medication (5th time)
+
+in the fancy diary display on September 8, 1990.
+
+ The generality of sexp diary entries lets you specify any diary entry
+that you can describe algorithmically. A sexp diary entry contains an
+expression that computes whether the entry applies to any given date.
+If its value is non-`nil', the entry applies to that date; otherwise,
+it does not. The expression can use the variable `date' to find the
+date being considered; its value is a list (MONTH DAY YEAR) that refers
+to the Gregorian calendar.
+
+ Suppose you get paid on the 21st of the month if it is a weekday, and
+on the Friday before if the 21st is on a weekend. Here is how to write
+a sexp diary entry that matches those dates:
+
+ &%%(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
+
+applies 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 expression is `t', the entry applies to
+that date. If the expression evaluates to `nil', the entry does *not*
+apply to that date.
+
+ The following sexp diary entries take advantage of the ability (in
+the fancy diary display) to concoct diary entries whose text varies
+based on the date:
+
+`%%(diary-sunrise-sunset)'
+ Make a diary entry for the local times of today's sunrise and
+ sunset.
+
+`%%(diary-phases-of-moon)'
+ Make a diary entry for the phases (quarters) of the moon.
+
+`%%(diary-day-of-year)'
+ Make a diary entry with today's day number in the current year and
+ the number of days remaining in the current year.
+
+`%%(diary-iso-date)'
+ Make a diary entry with today's equivalent ISO commercial date.
+
+`%%(diary-julian-date)'
+ Make a diary entry with today's equivalent date on the Julian
+ calendar.
+
+`%%(diary-astro-day-number)'
+ Make a diary entry with today's equivalent astronomical (Julian)
+ day number.
+
+`%%(diary-hebrew-date)'
+ Make a diary entry with today's equivalent date on the Hebrew
+ calendar.
+
+`%%(diary-islamic-date)'
+ Make a diary entry with today's equivalent date on the Islamic
+ calendar.
+
+`%%(diary-french-date)'
+ Make a diary entry with today's equivalent date on the French
+ Revolutionary calendar.
+
+`%%(diary-mayan-date)'
+ Make a diary entry with today's equivalent date on the Mayan
+ calendar.
+
+Thus including the diary entry
+
+ &%%(diary-hebrew-date)
+
+causes every day's diary display to contain the equivalent date on the
+Hebrew calendar, if you are using the fancy diary display. (With simple
+diary display, the line `&%%(diary-hebrew-date)' appears in the diary
+for any date, but does nothing particularly useful.)
+
+ These functions can be used to construct sexp diary entries based on
+the Hebrew calendar in certain standard ways:
+
+`%%(diary-rosh-hodesh)'
+ Make a diary entry that tells the occurrence and ritual
+ announcement of each new Hebrew month.
+
+`%%(diary-parasha)'
+ Make a Saturday diary entry that tells the weekly synagogue
+ scripture reading.
+
+`%%(diary-sabbath-candles)'
+ Make a Friday diary entry that tells the *local time* of Sabbath
+ candle lighting.
+
+`%%(diary-omer)'
+ Make a diary entry that gives the omer count, when appropriate.
+
+`%%(diary-yahrzeit MONTH DAY YEAR) NAME'
+ Make a diary entry marking the anniversary of a date of death.
+ The date is the *Gregorian* (civil) date of death. The diary
+ entry appears on the proper Hebrew calendar anniversary and on the
+ day before. (In the European style, the order of the parameters
+ is changed to DAY, MONTH, YEAR.)
+
+\1f
+File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization
+
+Customizing Appointment Reminders
+.................................
+
+ You can specify exactly how Emacs reminds you of an appointment, and
+how far in advance it begins doing so, by setting these variables:
+
+`appt-message-warning-time'
+ The time in minutes before an appointment that the reminder
+ begins. The default is 10 minutes.
+
+`appt-audible'
+ If this is `t' (the default), Emacs rings the terminal bell for
+ appointment reminders.
+
+`appt-visible'
+ If this is `t' (the default), Emacs displays the appointment
+ message in echo area.
+
+`appt-display-mode-line'
+ If this is `t' (the default), Emacs displays the number of minutes
+ to the appointment on the mode line.
+
+`appt-msg-window'
+ If this is `t' (the default), Emacs displays the appointment
+ message in another window.
+
+`appt-display-duration'
+ The number of seconds an appointment message is displayed. The
+ default is 5 seconds.
+
+\1f
+File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top
+
+Sorting Text
+============
+
+ XEmacs provides several commands for sorting text in a buffer. All
+operate on the contents of the region (the text between point and the
+mark). They divide the text of the region into many "sort records",
+identify a "sort key" for each record, and then reorder the records
+using the order determined by the sort keys. The records are ordered so
+that their keys are in alphabetical order, or, for numerical sorting, in
+numerical order. In alphabetical sorting, all upper-case letters `A'
+through `Z' come before lower-case `a', in accordance with the ASCII
+character sequence.
+
+ The sort commands differ in how they divide the text into sort
+records and in which part of each record they use as the sort key.
+Most of the commands make each line a separate sort record, but some
+commands use paragraphs or pages as sort records. Most of the sort
+commands use each entire sort record as its own sort key, but some use
+only a portion of the record as the sort key.
+
+`M-x sort-lines'
+ Divide the region into lines and sort by comparing the entire text
+ of a line. A prefix argument means sort in descending order.
+
+`M-x sort-paragraphs'
+ Divide the region into paragraphs and sort by comparing the entire
+ text of a paragraph (except for leading blank lines). A prefix
+ argument means sort in descending order.
+
+`M-x sort-pages'
+ Divide the region into pages and sort by comparing the entire text
+ of a page (except for leading blank lines). A prefix argument
+ means sort in descending order.
+
+`M-x sort-fields'
+ Divide the region into lines and sort by comparing the contents of
+ one field in each line. Fields are defined as separated by
+ whitespace, so the first run of consecutive non-whitespace
+ characters in a line constitutes field 1, the second such run
+ constitutes field 2, etc.
+
+ You specify which field to sort by with a numeric argument: 1 to
+ sort by field 1, etc. A negative argument means sort in descending
+ order. Thus, minus 2 means sort by field 2 in reverse-alphabetical
+ order.
+
+`M-x sort-numeric-fields'
+ Like `M-x sort-fields', except the specified field is converted to
+ a number for each line and the numbers are compared. `10' comes
+ before `2' when considered as text, but after it when considered
+ as a number.
+
+`M-x sort-columns'
+ Like `M-x sort-fields', except that the text within each line used
+ for comparison comes from a fixed range of columns. An explanation
+ is given below.
+
+ For example, if the buffer contains:
+
+ On systems where clash detection (locking of files being edited) is
+ implemented, XEmacs also checks the first time you modify a buffer
+ whether the file has changed on disk since it was last visited or
+ saved. If it has, you are asked to confirm that you want to change
+ the buffer.
+
+then if you apply `M-x sort-lines' to the entire buffer you get:
+
+ On systems where clash detection (locking of files being edited) is
+ implemented, XEmacs also checks the first time you modify a buffer
+ saved. If it has, you are asked to confirm that you want to change
+ the buffer.
+ whether the file has changed on disk since it was last visited or
+
+where the upper case `O' comes before all lower case letters. If you
+apply instead `C-u 2 M-x sort-fields' you get:
+
+ saved. If it has, you are asked to confirm that you want to change
+ implemented, XEmacs also checks the first time you modify a buffer
+ the buffer.
+ On systems where clash detection (locking of files being edited) is
+ whether the file has changed on disk since it was last visited or
+
+where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'.
+
+ `M-x sort-columns' requires more explanation. You specify the
+columns by putting point at one of the columns and the mark at the other
+column. Because this means you cannot put point or the mark at the
+beginning of the first line to sort, this command uses an unusual
+definition of `region': all of the line point is in is considered part
+of the region, and so is all of the line the mark is in.
+
+ For example, to sort a table by information found in columns 10 to
+15, you could put the mark on column 10 in the first line of the table,
+and point on column 15 in the last line of the table, and then use this
+command. Or you could put the mark on column 15 in the first line and
+point on column 10 in the last line.
+
+ This can be thought of as sorting the rectangle specified by point
+and the mark, except that the text on each line to the left or right of
+the rectangle moves along with the text inside the rectangle. *Note
+Rectangles::.
+
+\1f
+File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top
+
+Running Shell Commands from XEmacs
+==================================
+
+ XEmacs has commands for passing single command lines to inferior
+shell processes; it can also run a shell interactively with input and
+output to an XEmacs buffer `*shell*'.
+
+`M-!'
+ Run a specified shell command line and display the output
+ (`shell-command').
+
+`M-|'
+ Run a specified shell command line with region contents as input;
+ optionally replace the region with the output
+ (`shell-command-on-region').
+
+`M-x shell'
+ Run a subshell with input and output through an XEmacs buffer.
+ You can then give commands interactively.
+
+`M-x term'
+ Run a subshell with input and output through an XEmacs buffer.
+ You can then give commands interactively. Full terminal emulation
+ is available.
+
+* Menu:
+
+* Single Shell:: How to run one shell command and return.
+* Interactive Shell:: Permanent shell taking input via XEmacs.
+* Shell Mode:: Special XEmacs commands used with permanent shell.
+* Terminal emulator:: An XEmacs window as a terminal emulator.
+* Term Mode:: Special XEmacs commands used in Term mode.
+* Paging in Term:: Paging in the terminal emulator.
+
+\1f
+File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell
+
+Single Shell Commands
+---------------------
+
+ `M-!' (`shell-command') reads a line of text using the minibuffer
+and creates an inferior shell to execute the line as a command.
+Standard input from the command comes from the null device. If the
+shell command produces any output, the output goes to an XEmacs buffer
+named `*Shell Command Output*', which is displayed in another window
+but not selected. A numeric argument, as in `M-1 M-!', directs this
+command to insert any output into the current buffer. In that case,
+point is left before the output and the mark is set after the output.
+
+ `M-|' (`shell-command-on-region') is like `M-!' but passes the
+contents of the region as input to the shell command, instead of no
+input. If a numeric argument is used to direct output to the current
+buffer, then the old region is deleted first and the output replaces it
+as the contents of the region.
+
+ Both `M-!' and `M-|' use `shell-file-name' to specify the shell to
+use. This variable is initialized based on your `SHELL' environment
+variable when you start XEmacs. If the file name does not specify a
+directory, the directories in the list `exec-path' are searched; this
+list is initialized based on the `PATH' environment variable when you
+start XEmacs. You can override either or both of these default
+initializations in your `.emacs' file.
+
+ When you use `M-!' and `M-|', XEmacs has to wait until the shell
+command completes. You can quit with `C-g'; that terminates the shell
+command.
+
+\1f
+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
+<RET>.
+
+ 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 <M-p>, the previous shell input is inserted into the
+buffer before point. Immediately typing <M-p> again deletes that input
+and inserts the one before it. By repeating <M-p> you can move
+backward through your commands until you find one you want to repeat.
+You may then edit the command before typing <RET> if you wish. <M-n>
+moves forward through the command history, in case you moved backward
+past the one you wanted while using <M-p>. If you type the first few
+characters of a previous command and then type <M-p>, 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.
+
+\1f
+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:
+
+`<RET>'
+ 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
+ <RET>.
+
+`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
+ <M-p> quickly and go past the desired command
+ (`comint-next-input').
+
+`<TAB>'
+ Complete the file name preceding point (`comint-dynamic-complete').
+
+\1f
+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.
+
+\1f
+File: xemacs.info, Node: Term Mode, Next: Paging in Term, Prev: Terminal emulator, Up: Shell
+
+Term Mode
+---------
+
+ Term uses Term mode, which has two input modes: In line mode, Term
+basically acts like Shell mode. *Note Shell Mode::. In Char mode,
+each character is sent directly to the inferior subshell, except for
+the Term escape character, normally `C-c'.
+
+ To switch between line and char mode, use these commands:
+ findex term-char-mode
+
+`C-c C-k'
+ Switch to line mode. Do nothing if already in line mode.
+
+`C-c C-j'
+ Switch to char mode. Do nothing if already in char mode.
+
+ The following commands are only available in Char mode:
+`C-c C-c'
+ Send a literal <C-c> to the sub-shell.
+
+`C-c C-x'
+ A prefix command to conveniently access the global <C-x> commands.
+ For example, `C-c C-x o' invokes the global binding of `C-x o',
+ which is normally `other-window'.
+
+\1f
+File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell
+
+Paging in the terminal emulator
+-------------------------------
+
+ Term mode has a pager feature. When the pager is enabled, term mode
+will pause at the end of each screenful.
+
+`C-c C-q'
+ Toggles the pager feature: Disables the pager if it is enabled,
+ and vice versa. This works in both line and char modes. If the
+ pager enabled, the mode-line contains the word `page'.
+
+ If the pager is enabled, and Term receives more than a screenful of
+output since your last input, Term will enter More break mode. This is
+indicated by `**MORE**' in the mode-line. Type a `Space' to display
+the next screenful of output. Type `?' to see your other options. The
+interface is similar to the Unix `more' program.
+
+\1f
+File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top
+
+Narrowing
+=========
+
+ "Narrowing" means focusing in on some portion of the buffer, making
+the rest temporarily invisible and inaccessible. Cancelling the
+narrowing and making the entire buffer once again visible is called
+"widening". The amount of narrowing in effect in a buffer at any time
+is called the buffer's "restriction".
+
+`C-x n n'
+ Narrow down to between point and mark (`narrow-to-region').
+
+`C-x n w'
+ Widen to make the entire buffer visible again (`widen').
+
+ Narrowing sometimes makes it easier to concentrate on a single
+subroutine or paragraph by eliminating clutter. It can also be used to
+restrict the range of operation of a replace command or repeating
+keyboard macro. The word `Narrow' appears in the mode line whenever
+narrowing is in effect. When you have narrowed to a part of the
+buffer, that part appears to be all there is. You can't see the rest,
+can't move into it (motion commands won't go outside the visible part),
+and can't change it in any way. However, the invisible text is not
+gone; if you save the file, it will be saved.
+
+ The primary narrowing command is `C-x n n' (`narrow-to-region'). It
+sets the current buffer's restrictions so that the text in the current
+region remains visible but all text before the region or after the
+region is invisible. Point and mark do not change.
+
+ Because narrowing can easily confuse users who do not understand it,
+`narrow-to-region' is normally a disabled command. Attempting to use
+this command asks for confirmation and gives you the option of enabling
+it; once you enable the command, confirmation will no longer be
+required. *Note Disabling::.
+
+ To undo narrowing, use `C-x n w' (`widen'). This makes all text in
+the buffer accessible again.
+
+ Use the `C-x =' command to get information on what part of the
+buffer you narrowed down. *Note Position Info::.
+
+\1f
+File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top
+
+Hardcopy Output
+===============
+
+ The XEmacs commands for making hardcopy derive their names from the
+Unix commands `print' and `lpr'.
+
+`M-x print-buffer'
+ Print hardcopy of current buffer using Unix command `print'
+ (`lpr -p'). This command adds page headings containing the file
+ name and page number.
+
+`M-x lpr-buffer'
+ Print hardcopy of current buffer using Unix command `lpr'. This
+ command does not add page headings.
+
+`M-x print-region'
+ Like `print-buffer', but prints only the current region.
+
+`M-x lpr-region'
+ Like `lpr-buffer', but prints only the current region.
+
+ All the hardcopy commands pass extra switches to the `lpr' program
+based on the value of the variable `lpr-switches'. Its value should be
+a list of strings, each string a switch starting with `-'. For
+example, the value could be `("-Pfoo")' to print on printer `foo'.
+
+\1f
+File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
+
+Recursive Editing Levels
+========================
+
+ A "recursive edit" is a situation in which you are using XEmacs
+commands to perform arbitrary editing while in the middle of another
+XEmacs command. For example, when you type `C-r' inside a
+`query-replace', you enter a recursive edit in which you can change the
+current buffer. When you exit from the recursive edit, you go back to
+the `query-replace'.
+
+ "Exiting" a recursive edit means returning to the unfinished
+command, which continues execution. For example, exiting the recursive
+edit requested by `C-r' in `query-replace' causes query replacing to
+resume. Exiting is done with `C-M-c' (`exit-recursive-edit').
+
+ You can also "abort" a recursive edit. This is like exiting, but
+also quits the unfinished command immediately. Use the command `C-]'
+(`abort-recursive-edit') for this. *Note Quitting::.
+
+ The mode line shows you when you are in a recursive edit by
+displaying square brackets around the parentheses that always surround
+the major and minor mode names. Every window's mode line shows the
+square brackets, since XEmacs as a whole, rather than any particular
+buffer, is in a recursive edit.
+
+ It is possible to be in recursive edits within recursive edits. For
+example, after typing `C-r' in a `query-replace', you might type a
+command that entered the debugger. In such a case, two or more sets of
+square brackets appear in the mode line(s). Exiting the inner
+recursive edit (here with the debugger `c' command) resumes the
+query-replace command where it called the debugger. After the end of
+the query-replace command, you would be able to exit the first
+recursive edit. Aborting exits only one level of recursive edit; it
+returns to the command level of the previous recursive edit. You can
+then abort that one as well.
+
+ The command `M-x top-level' aborts all levels of recursive edits,
+returning immediately to the top level command reader.
+
+ The text you edit inside the recursive edit need not be the same text
+that you were editing at top level. If the command that invokes the
+recursive edit selects a different buffer first, that is the buffer you
+will edit recursively. You can switch buffers within the recursive edit
+in the normal manner (as long as the buffer-switching keys have not been
+rebound). While you could theoretically do the rest of your editing
+inside the recursive edit, including visiting files, this could have
+surprising effects (such as stack overflow) from time to time. It is
+best if you always exit or abort a recursive edit when you no longer
+need it.
+
+ In general, XEmacs tries to avoid using recursive edits. It is
+usually preferable to allow users to switch among the possible editing
+modes in any order they like. With recursive edits, the only way to get
+to another state is to go "back" to the state that the recursive edit
+was invoked from.
+
+\1f
+File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top
+
+Dissociated Press
+=================
+
+ `M-x dissociated-press' is a command for scrambling a file of text
+either word by word or character by character. Starting from a buffer
+of straight English, it produces extremely amusing output. The input
+comes from the current XEmacs buffer. Dissociated Press writes its
+output in a buffer named `*Dissociation*', and redisplays that buffer
+after every couple of lines (approximately) to facilitate reading it.
+
+ `dissociated-press' asks every so often whether to continue
+operating. Answer `n' to stop it. You can also stop at any time by
+typing `C-g'. The dissociation output remains in the `*Dissociation*'
+buffer for you to copy elsewhere if you wish.
+
+ Dissociated Press operates by jumping at random from one point in the
+buffer to another. In order to produce plausible output rather than
+gibberish, it insists on a certain amount of overlap between the end of
+one run of consecutive words or characters and the start of the next.
+That is, if it has just printed out `president' and then decides to
+jump to a different point in the file, it might spot the `ent' in
+`pentagon' and continue from there, producing `presidentagon'. Long
+sample texts produce the best results.
+
+ A positive argument to `M-x dissociated-press' tells it to operate
+character by character, and specifies the number of overlap characters.
+A negative argument tells it to operate word by word and specifies the
+number of overlap words. In this mode, whole words are treated as the
+elements to be permuted, rather than characters. No argument is
+equivalent to an argument of two. For your againformation, the output
+goes only into the buffer `*Dissociation*'. The buffer you start with
+is not changed.
+
+ Dissociated Press produces nearly the same results as a Markov chain
+based on a frequency table constructed from the sample text. It is,
+however, an independent, ignoriginal invention. Dissociated Press
+techniquitously copies several consecutive characters from the sample
+between random choices, whereas a Markov chain would choose randomly for
+each word or character. This makes for more plausible sounding results
+and runs faster.
+
+ It is a mustatement that too much use of Dissociated Press can be a
+developediment to your real work. Sometimes to the point of outragedy.
+And keep dissociwords out of your documentation, if you want it to be
+well userenced and properbose. Have fun. Your buggestions are welcome.
+
+\1f
+File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
+
+CONX
+====
+
+ Besides producing a file of scrambled text with Dissociated Press,
+you can generate random sentences by using CONX.
+
+`M-x conx'
+ Generate random sentences in the `*conx*' buffer.
+
+`M-x conx-buffer'
+ Absorb the text in the current buffer into the `conx' database.
+
+`M-x conx-init'
+ Forget the current word-frequency tree.
+
+`M-x conx-load'
+ Load a `conx' database that has been previously saved with `M-x
+ conx-save'.
+
+`M-x conx-region'
+ Absorb the text in the current buffer into the `conx' database.
+
+`M-x conx-save'
+ Save the current `conx' database to a file for future retrieval.
+
+ Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
+and then type `M-x conx'. Output is continuously generated until you
+type <^G>. You can save the `conx' database to a file with `M-x
+conx-save', which you can retrieve with `M-x conx-load'. To clear the
+database, use `M-x conx-init'.
+
+\1f
+File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
+
+Other Amusements
+================
+
+ If you are a little bit bored, you can try `M-x hanoi'. If you are
+considerably bored, give it a numeric argument. If you are very, very
+bored, try an argument of 9. Sit back and watch.
+
+ When you are frustrated, try the famous Eliza program. Just do `M-x
+doctor'. End each input by typing `RET' twice.
+
+ When you are feeling strange, type `M-x yow'.
+
+\1f
+File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
+
+Emulation
+=========
+
+ XEmacs can be programmed to emulate (more or less) most other
+editors. Standard facilities can emulate these:
+
+Viper (a vi emulator)
+ In XEmacs, Viper is the preferred emulation of vi within XEmacs.
+ Viper is designed to allow you to take advantage of the best
+ features of XEmacs while still doing your basic editing in a
+ familiar, vi-like fashion. Viper provides various different
+ levels of vi emulation, from a quite complete emulation that
+ allows almost no access to native XEmacs commands, to an "expert"
+ mode that combines the most useful vi commands with the most
+ useful XEmacs commands.
+
+ To start Viper, put the command
+
+ (viper-mode)
+
+ in your `.emacs' file.
+
+ Viper comes with a separate manual that is provided standard with
+ the XEmacs distribution.
+
+EDT (DEC VMS editor)
+ Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
+ edt-emulation-off' restores normal Emacs command bindings.
+
+ Most of the EDT emulation commands are keypad keys, and most
+ standard Emacs key bindings are still available. The EDT
+ emulation rebindings are done in the global keymap, so there is no
+ problem switching buffers or major modes while in EDT emulation.
+
+Gosling Emacs
+ Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
+ set-gosmacs-bindings'. This redefines many keys, mostly on the
+ `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x
+ set-gnu-bindings' returns to normal XEmacs by rebinding the same
+ keys to the definitions they had at the time `M-x
+ set-gosmacs-bindings' was done.
+
+ It is also possible to run Mocklisp code written for Gosling Emacs.
+ *Note Mocklisp::.
+
+\1f
+File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
+
+Customization
+*************
+
+ This chapter talks about various topics relevant to adapting the
+behavior of Emacs in minor ways.
+
+ All kinds of customization affect only the particular Emacs job that
+you do them in. They are completely lost when you kill the Emacs job,
+and have no effect on other Emacs jobs you may run at the same time or
+later. The only way an Emacs job can affect anything outside of it is
+by writing a file; in particular, the only way to make a customization
+`permanent' is to put something in your `.emacs' file or other
+appropriate file to do the customization in each session. *Note Init
+File::.
+
+* Menu:
+
+* Minor Modes:: Each minor mode is one feature you can turn on
+ independently of any others.
+* Variables:: Many Emacs commands examine Emacs variables
+ to decide what to do; by setting variables,
+ you can control their functioning.
+* Keyboard Macros:: A keyboard macro records a sequence of keystrokes
+ to be replayed with a single command.
+* Key Bindings:: The keymaps say what command each key runs.
+ By changing them, you can "redefine keys".
+* Syntax:: The syntax table controls how words and expressions
+ are parsed.
+* Init File:: How to write common customizations in the `.emacs'
+ file.
+* Audible Bell:: Changing how Emacs sounds the bell.
+* Faces:: Changing the fonts and colors of a region of text.
+* X Resources:: X resources controlling various aspects of the
+ behavior of XEmacs.
+
+\1f
+File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
+
+Minor Modes
+===========
+
+ Minor modes are options which you can use or not. For example, Auto
+Fill mode is a minor mode in which <SPC> breaks lines between words as
+you type. All the minor modes are independent of each other and of the
+selected major mode. Most minor modes inform you in the mode line when
+they are on; for example, `Fill' in the mode line means that Auto Fill
+mode is on.
+
+ Append `-mode' to the name of a minor mode to get the name of a
+command function that turns the mode on or off. Thus, the command to
+enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These
+commands are usually invoked with `M-x', but you can bind keys to them
+if you wish. With no argument, the function turns the mode on if it was
+off and off if it was on. This is known as "toggling". A positive
+argument always turns the mode on, and an explicit zero argument or a
+negative argument always turns it off.
+
+ Auto Fill mode allows you to enter filled text without breaking lines
+explicitly. Emacs inserts newlines as necessary to prevent lines from
+becoming too long. *Note Filling::.
+
+ Overwrite mode causes ordinary printing characters to replace
+existing text instead of moving it to the right. For example, if point
+is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
+mode, it changes to `FOOGAR', instead of `FOOGBAR'.
+
+ Abbrev mode allows you to define abbreviations that automatically
+expand as you type them. For example, `amd' might expand to `abbrev
+mode'. *Note Abbrevs::, for full information.
+
+\1f
+File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization
+
+Variables
+=========
+
+ A "variable" is a Lisp symbol which has a value. Variable names can
+contain any characters, but by convention they are words separated by
+hyphens. A variable can also have a documentation string, which
+describes what kind of value it should have and how the value will be
+used.
+
+ Lisp allows any variable to have any kind of value, but most
+variables that Emacs uses require a value of a certain type. Often the
+value has to be a string or a number. Sometimes we say that a certain
+feature is turned on if a variable is "non-`nil'," meaning that if the
+variable's value is `nil', the feature is off, but the feature is on
+for any other value. The conventional value to turn on the
+feature--since you have to pick one particular value when you set the
+variable--is `t'.
+
+ Emacs uses many Lisp variables for internal recordkeeping, as any
+Lisp program must, but the most interesting variables for you are the
+ones that exist for the sake of customization. Emacs does not
+(usually) change the values of these variables; instead, you set the
+values, and thereby alter and control the behavior of certain Emacs
+commands. These variables are called "options". Most options are
+documented in this manual and appear in the Variable Index (*note
+Variable Index::.).
+
+ One example of a variable which is an option is `fill-column', which
+specifies the position of the right margin (as a number of characters
+from the left margin) to be used by the fill commands (*note
+Filling::.).
+
+* Menu:
+
+* Examining:: Examining or setting one variable's value.
+* Easy Customization:: Convenient and easy customization of variables.
+* Edit Options:: Examining or editing list of all variables' values.
+* Locals:: Per-buffer values of variables.
+* File Variables:: How files can specify variable values.
+
+\1f
+File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
+
+Examining and Setting Variables
+-------------------------------
+
+`C-h v'
+`M-x describe-variable'
+ Print the value and documentation of a variable.
+
+`M-x set-variable'
+ Change the value of a variable.
+
+ To examine the value of a single variable, use `C-h v'
+(`describe-variable'), which reads a variable name using the
+minibuffer, with completion. It prints both the value and the
+documentation of the variable.
+
+ C-h v fill-column <RET>
+
+prints something like:
+
+ fill-column's value is 75
+
+ Documentation:
+ *Column beyond which automatic line-wrapping should happen.
+ Automatically becomes local when set in any fashion.
+
+The star at the beginning of the documentation indicates that this
+variable is an option. `C-h v' is not restricted to options; it allows
+any variable name.
+
+ If you know which option you want to set, you can use `M-x
+set-variable' to set it. This prompts for the variable name in the
+minibuffer (with completion), and then prompts for a Lisp expression
+for the new value using the minibuffer a second time. For example,
+
+ M-x set-variable <RET> fill-column <RET> 75 <RET>
+
+sets `fill-column' to 75, as if you had executed the Lisp expression
+`(setq fill-column 75)'.
+
+ Setting variables in this way, like all means of customizing Emacs
+except where explicitly stated, affects only the current Emacs session.
+
+\1f
+File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
+
+Easy Customization Interface
+----------------------------
+
+ A convenient way to find the user option variables that you want to
+change, and then change them, is with `M-x customize'. This command
+creates a "customization buffer" with which you can browse through the
+Emacs user options in a logically organized structure, then edit and
+set their values. You can also use the customization buffer to save
+settings permanently. (Not all Emacs user options are included in this
+structure as of yet, but we are adding the rest.)
+
+* Menu:
+
+* Groups: Customization Groups.
+ How options are classified in a structure.
+* Changing an Option:: How to edit a value and set an option.
+* Face Customization:: How to edit the attributes of a face.
+* Specific Customization:: Making a customization buffer for specific
+ options, faces, or groups.
+
+\1f
+File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization
+
+Customization Groups
+....................
+
+ For customization purposes, user options are organized into "groups"
+to help you find them. Groups are collected into bigger groups, all
+the way up to a master group called `Emacs'.
+
+ `M-x customize' creates a customization buffer that shows the
+top-level `Emacs' group and the second-level groups immediately under
+it. It looks like this, in part:
+
+ /- Emacs group: ---------------------------------------------------\
+ [State]: visible group members are all at standard settings.
+ Customization of the One True Editor.
+ See also [Manual].
+
+ [Open] Editing group
+ Basic text editing facilities.
+
+ [Open] External group
+ Interfacing to external utilities.
+
+ MORE SECOND-LEVEL GROUPS
+
+ \- Emacs group end ------------------------------------------------/
+
+This says that the buffer displays the contents of the `Emacs' group.
+The other groups are listed because they are its contents. But they
+are listed differently, without indentation and dashes, because *their*
+contents are not included. Each group has a single-line documentation
+string; the `Emacs' group also has a `[State]' line.
+
+ Most of the text in the customization buffer is read-only, but it
+typically includes some "editable fields" that you can edit. There are
+also "active fields"; this means a field that does something when you
+"invoke" it. To invoke an active field, either click on it with
+`Mouse-1', or move point to it and type <RET>.
+
+ For example, the phrase `[Open]' that appears in a second-level
+group is an active field. Invoking the `[Open]' field for a group
+opens up a new customization buffer, which shows that group and its
+contents. This field is a kind of hypertext link to another group.
+
+ The `Emacs' group does not include any user options itself, but
+other groups do. By examining various groups, you will eventually find
+the options and faces that belong to the feature you are interested in
+customizing. Then you can use the customization buffer to set them.
+
+ You can view the structure of customization groups on a larger scale
+with `M-x customize-browse'. This command creates a special kind of
+customization buffer which shows only the names of the groups (and
+options and faces), and their structure.
+
+ In this buffer, you can show the contents of a group by invoking
+`[+]'. When the group contents are visible, this button changes to
+`[-]'; invoking that hides the group contents.
+
+ Each group, option or face name in this buffer has an active field
+which says `[Group]', `[Option]' or `[Face]'. Invoking that active
+field creates an ordinary customization buffer showing just that group
+and its contents, just that option, or just that face. This is the way
+to set values in it.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
+
+Changing an Option
+..................
+
+ Here is an example of what a user option looks like in the
+customization buffer:
+
+ Kill Ring Max: [Hide] 30
+ [State]: this option is unchanged from its standard setting.
+ Maximum length of kill ring before oldest elements are thrown away.
+
+ The text following `[Hide]', `30' in this case, indicates the
+current value of the option. If you see `[Show]' instead of `[Hide]',
+it means that the value is hidden; the customization buffer initially
+hides values that take up several lines. Invoke `[Show]' to show the
+value.
+
+ The line after the option name indicates the "customization state"
+of the option: in the example above, it says you have not changed the
+option yet. The word `[State]' at the beginning of this line is
+active; you can get a menu of various operations by invoking it with
+`Mouse-1' or <RET>. These operations are essential for customizing the
+variable.
+
+ The line after the `[State]' line displays the beginning of the
+option's documentation string. If there are more lines of
+documentation, this line ends with `[More]'; invoke this to show the
+full documentation string.
+
+ To enter a new value for `Kill Ring Max', move point to the value
+and edit it textually. For example, you can type `M-d', then insert
+another number.
+
+ When you begin to alter the text, you will see the `[State]' line
+change to say that you have edited the value:
+
+ [State]: you have edited the value as text, but not set the option.
+
+ Editing the value does not actually set the option variable. To do
+that, you must "set" the option. To do this, invoke the word `[State]'
+and choose `Set for Current Session'.
+
+ The state of the option changes visibly when you set it:
+
+ [State]: you have set this option, but not saved it for future sessions.
+
+ You don't have to worry about specifying a value that is not valid;
+setting the option checks for validity and will not really install an
+unacceptable value.
+
+ While editing a value or field that is a file name, directory name,
+command name, or anything else for which completion is defined, you can
+type `M-<TAB>' (`widget-complete') to do completion.
+
+ Some options have a small fixed set of possible legitimate values.
+These options don't let you edit the value textually. Instead, an
+active field `[Value Menu]' appears before the value; invoke this field
+to edit the value. For a boolean "on or off" value, the active field
+says `[Toggle]', and it changes to the other value. `[Value Menu]' and
+`[Toggle]' edit the buffer; the changes take effect when you use the
+`Set for Current Session' operation.
+
+ Some options have values with complex structure. For example, the
+value of `load-path' is a list of directories. Here is how it appears
+in the customization buffer:
+
+ Load Path:
+ [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
+ [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
+ [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
+ [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
+ [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
+ [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
+ [INS]
+ [State]: this item has been changed outside the customization buffer.
+ List of directories to search for files to load....
+
+Each directory in the list appears on a separate line, and each line has
+several editable or active fields.
+
+ You can edit any of the directory names. To delete a directory from
+the list, invoke `[DEL]' on that line. To insert a new directory in
+the list, invoke `[INS]' at the point where you want to insert it.
+
+ You can also invoke `[Current dir?]' to switch between including a
+specific named directory in the path, and including `nil' in the path.
+(`nil' in a search path means "try the current directory.")
+
+ Two special commands, <TAB> and `S-<TAB>', are useful for moving
+through the customization buffer. <TAB> (`widget-forward') moves
+forward to the next active or editable field; `S-<TAB>'
+(`widget-backward') moves backward to the previous active or editable
+field.
+
+ Typing <RET> on an editable field also moves forward, just like
+<TAB>. The reason for this is that people have a tendency to type
+<RET> when they are finished editing a field. If you have occasion to
+insert a newline in an editable field, use `C-o' or `C-q C-j',
+
+ Setting the option changes its value in the current Emacs session;
+"saving" the value changes it for future sessions as well. This works
+by writing code into your `~/.emacs' file so as to set the option
+variable again each time you start Emacs. To save the option, invoke
+`[State]' and select the `Save for Future Sessions' operation.
+
+ You can also restore the option to its standard value by invoking
+`[State]' and selecting the `Reset' operation. There are actually
+three reset operations:
+
+`Reset to Current'
+ If you have made some modifications and not yet set the option,
+ this restores the text in the customization buffer to match the
+ actual value.
+
+`Reset to Saved'
+ This restores the value of the option to the last saved value, and
+ updates the text accordingly.
+
+`Reset to Standard Settings'
+ This sets the option to its standard value, and updates the text
+ accordingly. This also eliminates any saved value for the option,
+ so that you will get the standard value in future Emacs sessions.
+
+ The state of a group indicates whether anything in that group has
+been edited, set or saved. You can select `Set for Current Session',
+`Save for Future Sessions' and the various kinds of `Reset' operation
+for the group; these operations on the group apply to all options in
+the group and its subgroups.
+
+ Near the top of the customization buffer there are two lines
+containing several active fields:
+
+ [Set] [Save] [Reset] [Done]
+
+Invoking `[Done]' buries this customization buffer. Each of the other
+fields performs an operation--set, save or reset--on each of the items
+in the buffer that could meaningfully be set, saved or reset.
+
+\1f
+File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
+
+Customizing Faces
+.................
+
+ In addition to user options, some customization groups also include
+faces. When you show the contents of a group, both the user options and
+the faces in the group appear in the customization buffer. Here is an
+example of how a face looks:
+
+ Custom Changed Face: (sample)
+ [State]: this face is unchanged from its standard setting.
+ Face used when the customize item has been changed.
+ Parent groups: [Custom Magic Faces]
+ Attributes: [ ] Bold: [Toggle] off (nil)
+ [ ] Italic: [Toggle] off (nil)
+ [ ] Underline: [Toggle] off (nil)
+ [ ] Foreground: white (sample)
+ [ ] Background: blue (sample)
+ [ ] Inverse: [Toggle] off (nil)
+ [ ] Stipple:
+ [ ] Font Family:
+ [ ] Size:
+ [ ] Strikethru: off
+
+ Each face attribute has its own line. The `[X]' field before the
+attribute name indicates whether the attribute is "enabled"; `X' means
+that it is. You can enable or disable the attribute by invoking that
+field. When the attribute is enabled, you can change the attribute
+value in the usual ways.
+
+ Setting, saving and resetting a face work like the same operations
+for options (*note Changing an Option::.).
+
+ A face can specify different appearances for different types of
+display. For example, a face can make text red on a color display, but
+use a bold font on a monochrome display. To specify multiple
+appearances for a face, select `Show Display Types' in the menu you get
+from invoking `[State]'.
+
+\1f
+File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
+
+Customizing Specific Items
+..........................
+
+ Instead of finding the options you want to change by moving down
+through the structure of groups, you can specify the particular option,
+face or group that you want to customize.
+
+`M-x customize-option <RET> OPTION <RET>'
+ Set up a customization buffer with just one option, OPTION.
+
+`M-x customize-face <RET> FACE <RET>'
+ Set up a customization buffer with just one face, FACE.
+
+`M-x customize-group <RET> GROUP <RET>'
+ Set up a customization buffer with just one group, GROUP.
+
+`M-x customize-apropos <RET> REGEXP <RET>'
+ Set up a customization buffer with all the options, faces and
+ groups that match REGEXP.
+
+`M-x customize-saved'
+ Set up a customization buffer containing all options and faces
+ that you have saved with customization buffers.
+
+`M-x customize-customized'
+ Set up a customization buffer containing all options and faces
+ that you have customized but not saved.
+
+ If you want to alter a particular user option variable with the
+customization buffer, and you know its name, you can use the command
+`M-x customize-option' and specify the option name. This sets up the
+customization buffer with just one option--the one that you asked for.
+Editing, setting and saving the value work as described above, but only
+for the specified option.
+
+ Likewise, you can modify a specific face, chosen by name, using `M-x
+customize-face'.
+
+ You can also set up the customization buffer with a specific group,
+using `M-x customize-group'. The immediate contents of the chosen
+group, including option variables, faces, and other groups, all appear
+as well. However, these subgroups' own contents start out hidden. You
+can show their contents in the usual way, by invoking `[Show]'.
+
+ To control more precisely what to customize, you can use `M-x
+customize-apropos'. You specify a regular expression as argument; then
+all options, faces and groups whose names match this regular expression
+are set up in the customization buffer. If you specify an empty regular
+expression, this includes *all* groups, options and faces in the
+customization buffer (but that takes a long time).
+
+ If you change option values and then decide the change was a mistake,
+you can use two special commands to revisit your previous changes. Use
+`customize-saved' to look at the options and faces that you have saved.
+Use `M-x customize-customized' to look at the options and faces that
+you have set but not saved.
+
+\1f
+File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
+
+Editing Variable Values
+-----------------------
+
+`M-x list-options'
+ Display a buffer listing names, values, and documentation of all
+ options.
+
+`M-x edit-options'
+ Change option values by editing a list of options.
+
+ `M-x list-options' displays a list of all Emacs option variables in
+an Emacs buffer named `*List Options*'. Each option is shown with its
+documentation and its current value. Here is what a portion of it might
+look like:
+
+ ;; exec-path:
+ ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
+ *List of directories to search programs to run in subprocesses.
+ Each element is a string (directory name)
+ or nil (try the default directory).
+ ;;
+ ;; fill-column:
+ 75
+ *Column beyond which automatic line-wrapping should happen.
+ Automatically becomes local when set in any fashion.
+ ;;
+
+ `M-x edit-options' goes one step further and immediately selects the
+`*List Options*' buffer; this buffer uses the major mode Options mode,
+which provides commands that allow you to point at an option and change
+its value:
+
+`s'
+ Set the variable point is in or near to a new value read using the
+ minibuffer.
+
+`x'
+ Toggle the variable point is in or near: if the value was `nil',
+ it becomes `t'; otherwise it becomes `nil'.
+
+`1'
+ Set the variable point is in or near to `t'.
+
+`0'
+ Set the variable point is in or near to `nil'.
+
+`n'
+`p'
+ Move to the next or previous variable.
+
+\1f
+File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
+
+Local Variables
+---------------
+
+`M-x make-local-variable'
+ Make a variable have a local value in the current buffer.
+
+`M-x kill-local-variable'
+ Make a variable use its global value in the current buffer.
+
+`M-x make-variable-buffer-local'
+ Mark a variable so that setting it will make it local to the
+ buffer that is current at that time.
+
+ You can make any variable "local" to a specific Emacs buffer. This
+means that the variable's value in that buffer is independent of its
+value in other buffers. A few variables are always local in every
+buffer. All other Emacs variables have a "global" value which is in
+effect in all buffers that have not made the variable local.
+
+ Major modes always make the variables they set local to the buffer.
+This is why changing major modes in one buffer has no effect on other
+buffers.
+
+ `M-x make-local-variable' reads the name of a variable and makes it
+local to the current buffer. Further changes in this buffer will not
+affect others, and changes in the global value will not affect this
+buffer.
+
+ `M-x make-variable-buffer-local' reads the name of a variable and
+changes the future behavior of the variable so that it automatically
+becomes local when it is set. More precisely, once you have marked a
+variable in this way, the usual ways of setting the variable will
+automatically invoke `make-local-variable' first. We call such
+variables "per-buffer" variables.
+
+ Some important variables have been marked per-buffer already. They
+include `abbrev-mode', `auto-fill-function', `case-fold-search',
+`comment-column', `ctl-arrow', `fill-column', `fill-prefix',
+`indent-tabs-mode', `left-margin',
+`mode-line-format', `overwrite-mode', `selective-display-ellipses',
+`selective-display', `tab-width', and `truncate-lines'. Some other
+variables are always local in every buffer, but they are used for
+internal purposes.
+
+ Note: the variable `auto-fill-function' was formerly named
+`auto-fill-hook'.
+
+ If you want a variable to cease to be local to the current buffer,
+call `M-x kill-local-variable' and provide the name of a variable to
+the prompt. The global value of the variable is again in effect in
+this buffer. Setting the major mode kills all the local variables of
+the buffer.
+
+ To set the global value of a variable, regardless of whether the
+variable has a local value in the current buffer, you can use the Lisp
+function `setq-default'. It works like `setq'. If there is a local
+value in the current buffer, the local value is not affected by
+`setq-default'; thus, the new global value may not be visible until you
+switch to another buffer, as in the case of:
+
+ (setq-default fill-column 75)
+
+`setq-default' is the only way to set the global value of a variable
+that has been marked with `make-variable-buffer-local'.
+
+ Programs can look at a variable's default value with `default-value'.
+This function takes a symbol as an argument and returns its default
+value. The argument is evaluated; usually you must quote it
+explicitly, as in the case of:
+
+ (default-value 'fill-column)
+
+\1f
+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
+`.emacs' 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: xemacs.info, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros
+
+Naming and Saving Keyboard Macros
+---------------------------------
+
+ To save a keyboard macro for longer than until you define the next
+one, you must give it a name using `M-x name-last-kbd-macro'. This
+reads a name as an argument using the minibuffer and defines that name
+to execute the macro. The macro name is a Lisp symbol, and defining it
+in this way makes it a valid command name for calling with `M-x' or for
+binding a key to with `global-set-key' (*note Keymaps::.). If you
+specify a name that has a prior definition other than another keyboard
+macro, Emacs prints an error message and nothing is changed.
+
+ Once a macro has a command name, you can save its definition in a
+file. You can then use it in another editing session. First visit the
+file you want to save the definition in. Then use the command:
+
+ M-x insert-kbd-macro <RET> MACRONAME <RET>
+
+This inserts some Lisp code that, when executed later, will define the
+same macro with the same definition it has now. You need not
+understand Lisp code to do this, because `insert-kbd-macro' writes the
+Lisp code for you. Then save the file. You can load the file with
+`load-file' (*note Lisp Libraries::.). If the file you save in is your
+initialization file `~/.emacs' (*note Init File::.), then the macro
+will be defined each time you run Emacs.
+
+ If you give `insert-kbd-macro' a prefix argument, it creates
+additional Lisp code to record the keys (if any) that you have bound to
+the keyboard macro, so that the macro is reassigned the same keys when
+you load the file.
+
+\1f
+File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
+
+Executing Macros With Variations
+--------------------------------
+
+ You can use `C-x q' (`kbd-macro-query'), to get an effect similar to
+that of `query-replace'. The macro asks you each time whether to make
+a change. When you are defining the macro, type `C-x q' at the point
+where you want the query to occur. During macro definition, the `C-x
+q' does nothing, but when you invoke the macro, `C-x q' reads a
+character from the terminal to decide whether to continue.
+
+ The special answers to a `C-x q' query are <SPC>, <DEL>, `C-d',
+`C-l', and `C-r'. Any other character terminates execution of the
+keyboard macro and is then read as a command. <SPC> means to continue.
+<DEL> means to skip the remainder of this repetition of the macro,
+starting again from the beginning in the next repetition. `C-d' means
+to skip the remainder of this repetition and cancel further repetition.
+`C-l' redraws the frame and asks you again for a character to specify
+what to do. `C-r' enters a recursive editing level, in which you can
+perform editing that is not part of the macro. When you exit the
+recursive edit using `C-M-c', you are asked again how to continue with
+the keyboard macro. If you type a <SPC> at this time, the rest of the
+macro definition is executed. It is up to you to leave point and the
+text in a state such that the rest of the macro will do what you want.
+
+ `C-u C-x q', which is `C-x q' with a numeric argument, performs a
+different function. It enters a recursive edit reading input from the
+keyboard, both when you type it during the definition of the macro and
+when it is executed from the macro. During definition, the editing you
+do inside the recursive edit does not become part of the macro. During
+macro execution, the recursive edit gives you a chance to do some
+particularized editing. *Note Recursive Edit::.
+
+\1f
+File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
+
+Customizing Key Bindings
+========================
+
+ This section deals with the "keymaps" that define the bindings
+between keys and functions, and shows how you can customize these
+bindings.
+
+ A command is a Lisp function whose definition provides for
+interactive use. Like every Lisp function, a command has a function
+name, which is a Lisp symbol whose name usually consists of lower case
+letters and hyphens.
+
+* Menu:
+
+* Keymaps:: Definition of the keymap data structure.
+ Names of Emacs's standard keymaps.
+* Rebinding:: How to redefine one key's meaning conveniently.
+* Disabling:: Disabling a command means confirmation is required
+ before it can be executed. This is done to protect
+ beginners from surprises.
+
+\1f
+File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
+
+Keymaps
+-------
+
+ The bindings between characters and command functions are recorded in
+data structures called "keymaps". Emacs has many of these. One, the
+"global" keymap, defines the meanings of the single-character keys that
+are defined regardless of major mode. It is the value of the variable
+`global-map'.
+
+ Each major mode has another keymap, its "local keymap", which
+contains overriding definitions for the single-character keys that are
+redefined in that mode. Each buffer records which local keymap is
+installed for it at any time, and the current buffer's local keymap is
+the only one that directly affects command execution. The local keymaps
+for Lisp mode, C mode, and many other major modes always exist even when
+not in use. They are the values of the variables `lisp-mode-map',
+`c-mode-map', and so on. For less frequently used major modes, the
+local keymap is sometimes constructed only when the mode is used for the
+first time in a session, to save space.
+
+ There are local keymaps for the minibuffer, too; they contain various
+completion and exit commands.
+
+ * `minibuffer-local-map' is used for ordinary input (no completion).
+
+ * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
+ like <RET>. This is used mainly for Mocklisp compatibility.
+
+ * `minibuffer-local-completion-map' is for permissive completion.
+
+ * `minibuffer-local-must-match-map' is for strict completion and for
+ cautious completion.
+
+ * `repeat-complex-command-map' is for use in `C-x <ESC>'.
+
+ * `isearch-mode-map' contains the bindings of the special keys which
+ are bound in the pseudo-mode entered with `C-s' and `C-r'.
+
+ Finally, each prefix key has a keymap which defines the key sequences
+that start with it. For example, `ctl-x-map' is the keymap used for
+characters following a `C-x'.
+
+ * `ctl-x-map' is the variable name for the map used for characters
+ that follow `C-x'.
+
+ * `help-map' is used for characters that follow `C-h'.
+
+ * `esc-map' is for characters that follow <ESC>. All Meta characters
+ are actually defined by this map.
+
+ * `ctl-x-4-map' is for characters that follow `C-x 4'.
+
+ * `mode-specific-map' is for characters that follow `C-c'.
+
+ The definition of a prefix key is the keymap to use for looking up
+the following character. Sometimes the definition is actually a Lisp
+symbol whose function definition is the following character keymap. The
+effect is the same, but it provides a command name for the prefix key
+that you can use as a description of what the prefix key is for. Thus
+the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
+definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
+
+ Prefix key definitions can appear in either the global map or a
+local map. The definitions of `C-c', `C-x', `C-h', and <ESC> as prefix
+keys appear in the global map, so these prefix keys are always
+available. Major modes can locally redefine a key as a prefix by
+putting a prefix key definition for it in the local map.
+
+ A mode can also put a prefix definition of a global prefix character
+such as `C-x' into its local map. This is how major modes override the
+definitions of certain keys that start with `C-x'. This case is
+special, because the local definition does not entirely replace the
+global one. When both the global and local definitions of a key are
+other keymaps, the next character is looked up in both keymaps, with
+the local definition overriding the global one. The character after the
+`C-x' is looked up in both the major mode's own keymap for redefined
+`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
+`C-x' commands contains `nil', the definition from the global keymap
+for `C-x' commands is used.
+
+\1f
+File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
+
+Changing Key Bindings
+---------------------
+
+ You can redefine an Emacs key by changing its entry in a keymap.
+You can change the global keymap, in which case the change is effective
+in all major modes except those that have their own overriding local
+definitions for the same key. Or you can change the current buffer's
+local map, which affects all buffers using the same major mode.
+
+* Menu:
+
+* Interactive Rebinding:: Changing Key Bindings Interactively
+* Programmatic Rebinding:: Changing Key Bindings Programmatically
+* Key Bindings Using Strings::Using Strings for Changing Key Bindings
+
+\1f
+File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
+
+Changing Key Bindings Interactively
+...................................
+
+`M-x global-set-key <RET> KEY CMD <RET>'
+ Defines KEY globally to run CMD.
+
+`M-x local-set-key <RET> KEYS CMD <RET>'
+ Defines KEY locally (in the major mode now in effect) to run CMD.
+
+`M-x local-unset-key <RET> KEYS <RET>'
+ Removes the local binding of KEY.
+
+ CMD is a symbol naming an interactively-callable function.
+
+ When called interactively, KEY is the next complete key sequence
+that you type. When called as a function, KEY is a string, a vector of
+events, or a vector of key-description lists as described in the
+`define-key' function description. The binding goes in the current
+buffer's local map, which is shared with other buffers in the same
+major mode.
+
+ The following example:
+
+ M-x global-set-key <RET> C-f next-line <RET>
+
+redefines `C-f' to move down a line. The fact that CMD is read second
+makes it serve as a kind of confirmation for KEY.
+
+ These functions offer no way to specify a particular prefix keymap as
+the one to redefine in, but that is not necessary, as you can include
+prefixes in KEY. KEY is read by reading characters one by one until
+they amount to a complete key (that is, not a prefix key). Thus, if
+you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
+CMD. But if you type `C-x', another character is read; if that
+character is `4', another character is read, and so on. For example,
+
+ M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
+
+redefines `C-x 4 $' to run the (fictitious) command
+`spell-other-window'.
+
+ The most general way to modify a keymap is the function
+`define-key', used in Lisp code (such as your `.emacs' file).
+`define-key' takes three arguments: the keymap, the key to modify in
+it, and the new definition. *Note Init File::, for an example.
+`substitute-key-definition' is used similarly; it takes three
+arguments, an old definition, a new definition, and a keymap, and
+redefines in that keymap all keys that were previously defined with the
+old definition to have the new definition instead.
+
+\1f
+File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
+
+Changing Key Bindings Programmatically
+......................................
+
+ You can use the functions `global-set-key' and `define-key' to
+rebind keys under program control.
+
+``(global-set-key KEYS CMD)''
+ Defines KEYS globally to run CMD.
+
+``(define-key KEYMAP KEYS DEF)''
+ Defines KEYS to run DEF in the keymap KEYMAP.
+
+ KEYMAP is a keymap object.
+
+ KEYS is the sequence of keystrokes to bind.
+
+ DEF is anything that can be a key's definition:
+
+ * `nil', meaning key is undefined in this keymap
+
+ * A command, that is, a Lisp function suitable for interactive
+ calling
+
+ * A string or key sequence vector, which is treated as a keyboard
+ macro
+
+ * A keymap to define a prefix key
+
+ * A symbol so that when the key is looked up, the symbol stands for
+ its function definition, which should at that time be one of the
+ above, or another symbol whose function definition is used, and so
+ on
+
+ * A cons, `(string . defn)', meaning that DEFN is the definition
+ (DEFN should be a valid definition in its own right)
+
+ * A cons, `(keymap . char)', meaning use the definition of CHAR in
+ map KEYMAP
+
+ For backward compatibility, XEmacs allows you to specify key
+sequences as strings. However, the preferred method is to use the
+representations of key sequences as vectors of keystrokes. *Note
+Keystrokes::, for more information about the rules for constructing key
+sequences.
+
+ Emacs allows you to abbreviate representations for key sequences in
+most places where there is no ambiguity. Here are some rules for
+abbreviation:
+
+ * The keysym by itself is equivalent to a list of just that keysym,
+ i.e., `f1' is equivalent to `(f1)'.
+
+ * A keystroke by itself is equivalent to a vector containing just
+ that keystroke, i.e., `(control a)' is equivalent to `[(control
+ a)]'.
+
+ * You can use ASCII codes for keysyms that have them. i.e., `65' is
+ equivalent to `A'. (This is not so much an abbreviation as an
+ alternate representation.)
+
+ Here are some examples of programmatically binding keys:
+
+
+ ;;; Bind `my-command' to <f1>
+ (global-set-key 'f1 'my-command)
+
+ ;;; Bind `my-command' to Shift-f1
+ (global-set-key '(shift f1) 'my-command)
+
+ ;;; Bind `my-command' to C-c Shift-f1
+ (global-set-key '[(control c) (shift f1)] 'my-command)
+
+ ;;; Bind `my-command' to the middle mouse button.
+ (global-set-key 'button2 'my-command)
+
+ ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
+ ;;; in the keymap that is in force when you are running `dired'.
+ (define-key dired-mode-map '(meta control button3) 'my-command)
+
+\1f
+File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
+
+Using Strings for Changing Key Bindings
+.......................................
+
+ For backward compatibility, you can still use strings to represent
+key sequences. Thus you can use commands like the following:
+
+ ;;; Bind `end-of-line' to C-f
+ (global-set-key "\C-f" 'end-of-line)
+
+ Note, however, that in some cases you may be binding more than one
+key sequence by using a single command. This situation can arise
+because in ASCII, `C-i' and <TAB> have the same representation.
+Therefore, when Emacs sees:
+
+ (global-set-key "\C-i" 'end-of-line)
+
+ it is unclear whether the user intended to bind `C-i' or <TAB>. The
+solution XEmacs adopts is to bind both of these key sequences.
+
+ After binding a command to two key sequences with a form like:
+
+ (define-key global-map "\^X\^I" 'command-1)
+
+ it is possible to redefine only one of those sequences like so:
+
+ (define-key global-map [(control x) (control i)] 'command-2)
+ (define-key global-map [(control x) tab] 'command-3)
+
+ This applies only when running under a window system. If you are
+talking to Emacs through an ASCII-only channel, you do not get any of
+these features.
+
+ Here is a table of pairs of key sequences that behave in a similar
+fashion:
+
+ control h backspace
+ control l clear
+ control i tab
+ control m return
+ control j linefeed
+ control [ escape
+ control @ control space
+
+\1f
+File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
+
+Disabling Commands
+------------------
+
+ Disabling a command marks it as requiring confirmation before it can
+be executed. The purpose of disabling a command is to prevent
+beginning users from executing it by accident and being confused.
+
+ The direct mechanism for disabling a command is to have a non-`nil'
+`disabled' property on the Lisp symbol for the command. These
+properties are normally set by the user's `.emacs' file with Lisp
+expressions such as:
+
+ (put 'delete-region 'disabled t)
+
+ If the value of the `disabled' property is a string, that string is
+included in the message printed when the command is used:
+
+ (put 'delete-region 'disabled
+ "Text deleted this way cannot be yanked back!\n")
+
+ You can disable a command either by editing the `.emacs' file
+directly or with the command `M-x disable-command', which edits the
+`.emacs' file for you. *Note Init File::.
+
+ When you attempt to invoke a disabled command interactively in Emacs,
+a window is displayed containing the command's name, its documentation,
+and some instructions on what to do next; then Emacs asks for input
+saying whether to execute the command as requested, enable it and
+execute, or cancel it. If you decide to enable the command, you are
+asked whether to do this permanently or just for the current session.
+Enabling permanently works by automatically editing your `.emacs' file.
+You can use `M-x enable-command' at any time to enable any command
+permanently.
+
+ Whether a command is disabled is independent of what key is used to
+invoke it; it also applies if the command is invoked using `M-x'.
+Disabling a command has no effect on calling it as a function from Lisp
+programs.
+
+\1f
+File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization
+
+The Syntax Table
+================
+
+ All the Emacs commands which parse words or balance parentheses are
+controlled by the "syntax table". The syntax table specifies which
+characters are opening delimiters, which are parts of words, which are
+string quotes, and so on. Actually, each major mode has its own syntax
+table (though sometimes related major modes use the same one) which it
+installs in each buffer that uses that major mode. The syntax table
+installed in the current buffer is the one that all commands use, so we
+call it "the" syntax table. A syntax table is a Lisp object, a vector
+of length 256 whose elements are numbers.
+
+* Menu:
+
+* Entry: Syntax Entry. What the syntax table records for each character.
+* Change: Syntax Change. How to change the information.
+
+\1f
+File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax
+
+Information About Each Character
+--------------------------------
+
+ The syntax table entry for a character is a number that encodes six
+pieces of information:
+
+ * The syntactic class of the character, represented as a small
+ integer
+
+ * The matching delimiter, for delimiter characters only (the
+ matching delimiter of `(' is `)', and vice versa)
+
+ * A flag saying whether the character is the first character of a
+ two-character comment starting sequence
+
+ * A flag saying whether the character is the second character of a
+ two-character comment starting sequence
+
+ * A flag saying whether the character is the first character of a
+ two-character comment ending sequence
+
+ * A flag saying whether the character is the second character of a
+ two-character comment ending sequence
+
+ The syntactic classes are stored internally as small integers, but
+are usually described to or by the user with characters. For example,
+`(' is used to specify the syntactic class of opening delimiters. Here
+is a table of syntactic classes, with the characters that specify them.
+
+` '
+ The class of whitespace characters.
+
+`w'
+ The class of word-constituent characters.
+
+`_'
+ The class of characters that are part of symbol names but not
+ words. This class is represented by `_' because the character `_'
+ has this class in both C and Lisp.
+
+`.'
+ The class of punctuation characters that do not fit into any other
+ special class.
+
+`('
+ The class of opening delimiters.
+
+`)'
+ The class of closing delimiters.
+
+`''
+ The class of expression-adhering characters. These characters are
+ part of a symbol if found within or adjacent to one, and are part
+ of a following expression if immediately preceding one, but are
+ like whitespace if surrounded by whitespace.
+
+`"'
+ The class of string-quote characters. They match each other in
+ pairs, and the characters within the pair all lose their syntactic
+ significance except for the `\' and `/' classes of escape
+ characters, which can be used to include a string-quote inside the
+ string.
+
+`$'
+ The class of self-matching delimiters. This is intended for TeX's
+ `$', which is used both to enter and leave math mode. Thus, a
+ pair of matching `$' characters surround each piece of math mode
+ TeX input. A pair of adjacent `$' characters act like a single
+ one for purposes of matching.
+
+`/'
+ The class of escape characters that always just deny the following
+ character its special syntactic significance. The character after
+ one of these escapes is always treated as alphabetic.
+
+`\'
+ The class of C-style escape characters. In practice, these are
+ treated just like `/'-class characters, because the extra
+ possibilities for C escapes (such as being followed by digits)
+ have no effect on where the containing expression ends.
+
+`<'
+ The class of comment-starting characters. Only single-character
+ comment starters (such as `;' in Lisp mode) are represented this
+ way.
+
+`>'
+ The class of comment-ending characters. Newline has this syntax in
+ Lisp mode.
+
+ The characters flagged as part of two-character comment delimiters
+can have other syntactic functions most of the time. For example, `/'
+and `*' in C code, when found separately, have nothing to do with
+comments. The comment-delimiter significance overrides when the pair of
+characters occur together in the proper order. Only the list and sexp
+commands use the syntax table to find comments; the commands
+specifically for comments have other variables that tell them where to
+find comments. Moreover, the list and sexp commands notice comments
+only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set
+to `nil' in modes where comment-terminator sequences are liable to
+appear where there is no comment, for example, in Lisp mode where the
+comment terminator is a newline but not every newline ends a comment.
+
+\1f
+File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax
+
+Altering Syntax Information
+---------------------------
+
+ It is possible to alter a character's syntax table entry by storing
+a new number in the appropriate element of the syntax table, but it
+would be hard to determine what number to use. Emacs therefore
+provides a command that allows you to specify the syntactic properties
+of a character in a convenient way.
+
+ `M-x modify-syntax-entry' is the command to change a character's
+syntax. It can be used interactively and is also used by major modes
+to initialize their own syntax tables. Its first argument is the
+character to change. The second argument is a string that specifies the
+new syntax. When called from Lisp code, there is a third, optional
+argument, which specifies the syntax table in which to make the change.
+If not supplied, or if this command is called interactively, the third
+argument defaults to the current buffer's syntax table.
+
+ 1. The first character in the string specifies the syntactic class.
+ It is one of the characters in the previous table (*note Syntax
+ Entry::.).
+
+ 2. The second character is the matching delimiter. For a character
+ that is not an opening or closing delimiter, this should be a
+ space, and may be omitted if no following characters are needed.
+
+ 3. The remaining characters are flags. The flag characters allowed
+ are:
+
+ `1'
+ Flag this character as the first of a two-character comment
+ starting sequence.
+
+ `2'
+ Flag this character as the second of a two-character comment
+ starting sequence.
+
+ `3'
+ Flag this character as the first of a two-character comment
+ ending sequence.
+
+ `4'
+ Flag this character as the second of a two-character comment
+ ending sequence.
+
+ Use `C-h s' (`describe-syntax') to display a description of the
+contents of the current syntax table. The description of each
+character includes both the string you have to pass to
+`modify-syntax-entry' to set up that character's current syntax, and
+some English to explain that string if necessary.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization
+
+The Init File, .emacs
+=====================
+
+ When you start Emacs, it normally loads the file `.emacs' in your
+home directory. This file, if it exists, should contain Lisp code. It
+is called your initialization file or "init file". Use the command
+line switch `-q' to tell Emacs whether to load an init file (*note
+Entering Emacs::.). Use the command line switch `-user-init-file'
+(*note Command Switches::.) to tell Emacs to load a different file
+instead of `~/.emacs'.
+
+ When the `.emacs' file is read, the variable `user-init-file' says
+which init file was loaded.
+
+ At some sites there is a "default init file", which is the library
+named `default.el', found via the standard search path for libraries.
+The Emacs distribution contains no such library; your site may create
+one for local customizations. If this library exists, it is loaded
+whenever you start Emacs. But your init file, if any, is loaded first;
+if it sets `inhibit-default-init' non-`nil', then `default' is not
+loaded.
+
+ If you have a large amount of code in your `.emacs' file, you should
+move it into another file named `SOMETHING.el', byte-compile it (*note
+Lisp Libraries::.), and load that file from your `.emacs' file using
+`load'.
+
+* Menu:
+
+* Init Syntax:: Syntax of constants in Emacs Lisp.
+* Init Examples:: How to do some things with an init file.
+* Terminal Init:: Each terminal type can have an init file.
+
+\1f
+File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File
+
+Init File Syntax
+----------------
+
+ The `.emacs' file contains one or more Lisp function call
+expressions. Each consists of a function name followed by arguments,
+all surrounded by parentheses. For example, `(setq fill-column 60)'
+represents a call to the function `setq' which is used to set the
+variable `fill-column' (*note Filling::.) to 60.
+
+ The second argument to `setq' is an expression for the new value of
+the variable. This can be a constant, a variable, or a function call
+expression. In `.emacs', constants are used most of the time. They
+can be:
+
+Numbers
+ Integers are written in decimal, with an optional initial minus
+ sign.
+
+ If a sequence of digits is followed by a period and another
+ sequence of digits, it is interpreted as a floating point number.
+
+ The number prefixes `#b', `#o', and `#x' are supported to
+ represent numbers in binary, octal, and hexadecimal notation (or
+ radix).
+
+Strings
+ Lisp string syntax is the same as C string syntax with a few extra
+ features. Use a double-quote character to begin and end a string
+ constant.
+
+ Newlines and special characters may be present literally in
+ strings. They can also be represented as backslash sequences:
+ `\n' for newline, `\b' for backspace, `\r' for return, `\t' for
+ tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a
+ backslash, `\"' for a double-quote, or `\OOO' for the character
+ whose octal code is OOO. Backslash and double-quote are the only
+ characters for which backslash sequences are mandatory.
+
+ You can use `\C-' as a prefix for a control character, as in
+ `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta
+ character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A.
+
+Characters
+ Lisp character constant syntax consists of a `?' followed by
+ either a character or an escape sequence starting with `\'.
+ Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and
+ characters are not interchangeable in Lisp; some contexts require
+ one and some contexts require the other.
+
+True
+ `t' stands for `true'.
+
+False
+ `nil' stands for `false'.
+
+Other Lisp objects
+ Write a single-quote (') followed by the Lisp object you want.
+
+\1f
+File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File
+
+Init File Examples
+------------------
+
+ Here are some examples of doing certain commonly desired things with
+Lisp expressions:
+
+ * Make <TAB> in C mode just insert a tab if point is in the middle
+ of a line.
+
+ (setq c-tab-always-indent nil)
+
+ Here we have a variable whose value is normally `t' for `true' and
+ the alternative is `nil' for `false'.
+
+ * Make searches case sensitive by default (in all buffers that do not
+ override this).
+
+ (setq-default case-fold-search nil)
+
+ This sets the default value, which is effective in all buffers
+ that do not have local values for the variable. Setting
+ `case-fold-search' with `setq' affects only the current buffer's
+ local value, which is probably not what you want to do in an init
+ file.
+
+ * Make Text mode the default mode for new buffers.
+
+ (setq default-major-mode 'text-mode)
+
+ Note that `text-mode' is used because it is the command for
+ entering the mode we want. A single-quote is written before it to
+ make a symbol constant; otherwise, `text-mode' would be treated as
+ a variable name.
+
+ * Turn on Auto Fill mode automatically in Text mode and related
+ modes.
+
+ (setq text-mode-hook
+ '(lambda () (auto-fill-mode 1)))
+
+ Here we have a variable whose value should be a Lisp function. The
+ function we supply is a list starting with `lambda', and a single
+ quote is written in front of it to make it (for the purpose of this
+ `setq') a list constant rather than an expression. Lisp functions
+ are not explained here; for mode hooks it is enough to know that
+ `(auto-fill-mode 1)' is an expression that will be executed when
+ Text mode is entered. You could replace it with any other
+ expression that you like, or with several expressions in a row.
+
+ (setq text-mode-hook 'turn-on-auto-fill)
+
+ This is another way to accomplish the same result.
+ `turn-on-auto-fill' is a symbol whose function definition is
+ `(lambda () (auto-fill-mode 1))'.
+
+ * Load the installed Lisp library named `foo' (actually a file
+ `foo.elc' or `foo.el' in a standard Emacs directory).
+
+ (load "foo")
+
+ When the argument to `load' is a relative pathname, not starting
+ with `/' or `~', `load' searches the directories in `load-path'
+ (*note Loading::.).
+
+ * Load the compiled Lisp file `foo.elc' from your home directory.
+
+ (load "~/foo.elc")
+
+ Here an absolute file name is used, so no searching is done.
+
+ * Rebind the key `C-x l' to run the function `make-symbolic-link'.
+
+ (global-set-key "\C-xl" 'make-symbolic-link)
+
+ or
+
+ (define-key global-map "\C-xl" 'make-symbolic-link)
+
+ Note once again the single-quote used to refer to the symbol
+ `make-symbolic-link' instead of its value as a variable.
+
+ * Do the same thing for C mode only.
+
+ (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+
+ * Bind the function key <F1> to a command in C mode. Note that the
+ names of function keys must be lower case.
+
+ (define-key c-mode-map 'f1 'make-symbolic-link)
+
+ * Bind the shifted version of <F1> to a command.
+
+ (define-key c-mode-map '(shift f1) 'make-symbolic-link)
+
+ * Redefine all keys which now run `next-line' in Fundamental mode to
+ run `forward-line' instead.
+
+ (substitute-key-definition 'next-line 'forward-line
+ global-map)
+
+ * Make `C-x C-v' undefined.
+
+ (global-unset-key "\C-x\C-v")
+
+ One reason to undefine a key is so that you can make it a prefix.
+ Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix,
+ but `C-x C-v' must be freed of any non-prefix definition first.
+
+ * Make `$' have the syntax of punctuation in Text mode. Note the
+ use of a character constant for `$'.
+
+ (modify-syntax-entry ?\$ "." text-mode-syntax-table)
+
+ * Enable the use of the command `eval-expression' without
+ confirmation.
+
+ (put 'eval-expression 'disabled nil)
+
+\1f
+File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File
+
+Terminal-Specific Initialization
+--------------------------------
+
+ Each terminal type can have a Lisp library to be loaded into Emacs
+when it is run on that type of terminal. For a terminal type named
+TERMTYPE, the library is called `term/TERMTYPE' and it is found by
+searching the directories `load-path' as usual and trying the suffixes
+`.elc' and `.el'. Normally it appears in the subdirectory `term' of
+the directory where most Emacs libraries are kept.
+
+ The usual purpose of the terminal-specific library is to define the
+escape sequences used by the terminal's function keys using the library
+`keypad.el'. See the file `term/vt100.el' for an example of how this
+is done.
+
+ When the terminal type contains a hyphen, only the part of the name
+before the first hyphen is significant in choosing the library name.
+Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library
+`term/aaa'. The code in the library can use `(getenv "TERM")' to find
+the full terminal type name.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Your `.emacs' file
+can prevent the loading of the terminal-specific library by setting
+`term-file-prefix' to `nil'.
+
+ The value of the variable `term-setup-hook', if not `nil', is called
+as a function of no arguments at the end of Emacs initialization, after
+both your `.emacs' file and any terminal-specific library have been
+read. You can set the value in the `.emacs' file to override part of
+any of the terminal-specific libraries and to define initializations
+for terminals that do not have a library.
+
+\1f
+File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization
+
+Changing the Bell Sound
+=======================
+
+ You can now change how the audible bell sounds using the variable
+`sound-alist'.
+
+ `sound-alist''s value is an list associating symbols with, among
+other things, strings of audio-data. When `ding' is called with one of
+the symbols, the associated sound data is played instead of the
+standard beep. This only works if you are logged in on the console of a
+machine with audio hardware. To listen to a sound of the provided type,
+call the function `play-sound' with the argument SOUND. You can also
+set the volume of the sound with the optional argument VOLUME.
+
+ 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 of the form:
+
+ ( SOUND-NAME . <SOUND> )
+ ( SOUND-NAME <VOLUME> <SOUND> )
+
+ You should probably add things to this list by calling the function
+`load-sound-file'.
+
+ Note that you can only play audio data if running on the console
+screen of a machine with audio hardware which emacs understands, which
+at this time means a Sun SparcStation, SGI, or HP9000s700.
+
+ Also note that the pitch, duration, and volume options are available
+everywhere, but most X servers ignore the `pitch' option.
+
+ The variable `bell-volume' should be an integer from 0 to 100, with
+100 being loudest, which controls how loud the sounds emacs makes
+should be. Elements of the `sound-alist' may override this value.
+This variable applies to the standard X bell sound as well as sound
+files.
+
+ If the symbol `t' is in place of a sound-string, Emacs uses the
+default X beep. This allows you to define beep-types of different
+volumes even when not running on the console.
+
+ You can add things to this list by calling the function
+`load-sound-file', which reads in an audio-file and adds its data to
+the sound-alist. You can specify the sound with the SOUND-NAME argument
+and the file into which the sounds are loaded with the FILENAME
+argument. The optional VOLUME argument sets the volume.
+
+ `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)'
+
+ To load and install some sound files as beep-types, use the function
+`load-default-sounds' (note that this only works if you are on display
+0 of a machine with audio hardware).
+
+ The following beep-types are used by Emacs itself. Other Lisp
+packages may use other beep types, but these are the ones that the C
+kernel of Emacs uses.
+
+`auto-save-error'
+ An auto-save does not succeed
+
+`command-error'
+ The Emacs command loop catches an error
+
+`undefined-key'
+ You type a key that is undefined
+
+`undefined-click'
+ You use an undefined mouse-click combination
+
+`no-completion'
+ Completion was not possible
+
+`y-or-n-p'
+ You type something other than the required `y' or `n'
+
+`yes-or-no-p'
+ You type something other than `yes' or `no'
+
+\1f
+File: xemacs.info, Node: Faces, Next: X Resources, 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.
+
+\1f
+File: xemacs.info, Node: X Resources, Prev: Faces, 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
+compatability. 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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+File: xemacs.info, Node: Resource List, Next: Face Resources, Prev: Iconic Resources, Up: X Resources
+
+Resource List
+-------------
+
+ Emacs frames accept the following resources:
+
+`geometry' (class `Geometry'): string
+ Initial geometry for the frame. *Note Geometry Resources::, for a
+ complete discussion of how this works.
+
+`iconic' (class `Iconic'): boolean
+ Whether this frame should appear in the iconified state.
+
+`internalBorderWidth' (class `InternalBorderWidth'): int
+ How many blank pixels to leave between the text and the edge of the
+ window.
+
+`interline' (class `Interline'): int
+ How many pixels to leave between each line (may not be
+ implemented).
+
+`menubar' (class `Menubar'): boolean
+ Whether newly-created frames should initially have a menubar. Set
+ to true by default.
+
+`initiallyUnmapped' (class `InitiallyUnmapped'): boolean
+ Whether XEmacs should leave the initial frame unmapped when it
+ starts up. This is useful if you are starting XEmacs as a server
+ (e.g. in conjunction with gnuserv or the external client widget).
+ You can also control this with the `-unmapped' command-line option.
+
+`barCursor' (class `BarColor'): boolean
+ Whether the cursor should be displayed as a bar, or the
+ traditional box.
+
+`cursorColor' (class `CursorColor'): color-name
+ The color of the text cursor.
+
+`scrollBarWidth' (class `ScrollBarWidth'): integer
+ How wide the vertical scrollbars should be, in pixels; 0 means no
+ vertical scrollbars. You can also use a resource specification of
+ the form `*scrollbar.width', or the usual toolkit scrollbar
+ resources: `*XmScrollBar.width' (Motif), `*XlwScrollBar.width'
+ (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
+ that you use the toolkit resources, though, because they're
+ dependent on how exactly your particular build of XEmacs was
+ configured.
+
+`scrollBarHeight' (class `ScrollBarHeight'): integer
+ How high the horizontal scrollbars should be, in pixels; 0 means no
+ horizontal scrollbars. You can also use a resource specification
+ of the form `*scrollbar.height', or the usual toolkit scrollbar
+ resources: `*XmScrollBar.height' (Motif), `*XlwScrollBar.height'
+ (Lucid), or `*Scrollbar.thickness' (Athena). We don't recommend
+ that you use the toolkit resources, though, because they're
+ dependent on how exactly your particular build of XEmacs was
+ configured.
+
+`scrollBarPlacement' (class `ScrollBarPlacement'): string
+ Where the horizontal and vertical scrollbars should be positioned.
+ This should be one of the four strings `BOTTOM_LEFT',
+ `BOTTOM_RIGHT', `TOP_LEFT', and `TOP_RIGHT'. Default is
+ `BOTTOM_RIGHT' for the Motif and Lucid scrollbars and
+ `BOTTOM_LEFT' for the Athena scrollbars.
+
+`topToolBarHeight' (class `TopToolBarHeight'): integer
+`bottomToolBarHeight' (class `BottomToolBarHeight'): integer
+`leftToolBarWidth' (class `LeftToolBarWidth'): integer
+`rightToolBarWidth' (class `RightToolBarWidth'): integer
+ Height and width of the four possible toolbars.
+
+`topToolBarShadowColor' (class `TopToolBarShadowColor'): color-name
+`bottomToolBarShadowColor' (class `BottomToolBarShadowColor'): color-name
+ Color of the top and bottom shadows for the toolbars. NOTE: These
+ resources do *not* have anything to do with the top and bottom
+ toolbars (i.e. the toolbars at the top and bottom of the frame)!
+ Rather, they affect the top and bottom shadows around the edges of
+ all four kinds of toolbars.
+
+`topToolBarShadowPixmap' (class `TopToolBarShadowPixmap'): pixmap-name
+`bottomToolBarShadowPixmap' (class `BottomToolBarShadowPixmap'): pixmap-name
+ Pixmap of the top and bottom shadows for the toolbars. If set,
+ these resources override the corresponding color resources. NOTE:
+ These resources do *not* have anything to do with the top and
+ bottom toolbars (i.e. the toolbars at the top and bottom of the
+ frame)! Rather, they affect the top and bottom shadows around the
+ edges of all four kinds of toolbars.
+
+`toolBarShadowThickness' (class `ToolBarShadowThickness'): integer
+ Thickness of the shadows around the toolbars, in pixels.
+
+`visualBell' (class `VisualBell'): boolean
+ Whether XEmacs should flash the screen rather than making an
+ audible beep.
+
+`bellVolume' (class `BellVolume'): integer
+ Volume of the audible beep.
+
+`useBackingStore' (class `UseBackingStore'): boolean
+ Whether XEmacs should set the backing-store attribute of the X
+ windows it creates. This increases the memory usage of the X
+ server but decreases the amount of X traffic necessary to update
+ the screen, and is useful when the connection to the X server goes
+ over a low-bandwidth line such as a modem connection.
+
+ Emacs devices accept the following resources:
+
+`textPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over text. This resource is
+ used to initialize the variable `x-pointer-shape'.
+
+`selectionPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a selectable text region
+ (an extent with the `highlight' property; for example, an Info
+ cross-reference). This resource is used to initialize the variable
+ `x-selection-pointer-shape'.
+
+`spacePointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a blank space in a buffer
+ (that is, after the end of a line or after the end-of-file). This
+ resource is used to initialize the variable
+ `x-nontext-pointer-shape'.
+
+`modeLinePointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over a modeline. This
+ resource is used to initialize the variable `x-mode-pointer-shape'.
+
+`gcPointer' (class `Cursor'): cursor-name
+ The cursor to display when a garbage-collection is in progress.
+ This resource is used to initialize the variable
+ `x-gc-pointer-shape'.
+
+`scrollbarPointer' (class `Cursor'): cursor-name
+ The cursor to use when the mouse is over the scrollbar. This
+ resource is used to initialize the variable
+ `x-scrollbar-pointer-shape'.
+
+`pointerColor' (class `Foreground'): color-name
+`pointerBackground' (class `Background'): color-name
+ The foreground and background colors of the mouse cursor. These
+ resources are used to initialize the variables
+ `x-pointer-foreground-color' and `x-pointer-background-color'.
+
+\1f
+File: xemacs.info, Node: Face Resources, Next: Widgets, Prev: Resource List, Up: X Resources
+
+Face Resources
+--------------
+
+ The attributes of faces are also per-frame. They can be specified as:
+
+ Emacs.FACE_NAME.parameter: value
+
+or
+
+ Emacs*FRAME_NAME.FACE_NAME.parameter: value
+
+Faces accept the following resources:
+
+`attributeFont' (class `AttributeFont'): font-name
+ The font of this face.
+
+`attributeForeground' (class `AttributeForeground'): color-name
+`attributeBackground' (class `AttributeBackground'): color-name
+ The foreground and background colors of this face.
+
+`attributeBackgroundPixmap' (class `AttributeBackgroundPixmap'): file-name
+ The name of an XBM file (or XPM file, if your version of Emacs
+ supports XPM), to use as a background stipple.
+
+`attributeUnderline' (class `AttributeUnderline'): boolean
+ Whether text in this face should be underlined.
+
+ All text is displayed in some face, defaulting to the face named
+`default'. To set the font of normal text, use
+`Emacs*default.attributeFont'. To set it in the frame named `fred', use
+`Emacs*fred.default.attributeFont'.
+
+ These are the names of the predefined faces:
+
+`default'
+ Everything inherits from this.
+
+`bold'
+ If this is not specified in the resource database, Emacs tries to
+ find a bold version of the font of the default face.
+
+`italic'
+ If this is not specified in the resource database, Emacs tries to
+ find an italic version of the font of the default face.
+
+`bold-italic'
+ If this is not specified in the resource database, Emacs tries to
+ find a bold-italic version of the font of the default face.
+
+`modeline'
+ This is the face that the modeline is displayed in. If not
+ specified in the resource database, it is determined from the
+ default face by reversing the foreground and background colors.
+
+`highlight'
+ This is the face that highlighted extents (for example, Info
+ cross-references and possible completions, when the mouse passes
+ over them) are displayed in.
+
+`left-margin'
+`right-margin'
+ These are the faces that the left and right annotation margins are
+ displayed in.
+
+`zmacs-region'
+ This is the face that mouse selections are displayed in.
+
+`isearch'
+ This is the face that the matched text being searched for is
+ displayed in.
+
+`info-node'
+ This is the face of info menu items. If unspecified, it is copied
+ from `bold-italic'.
+
+`info-xref'
+ This is the face of info cross-references. If unspecified, it is
+ copied from `bold'. (Note that, when the mouse passes over a
+ cross-reference, the cross-reference's face is determined from a
+ combination of the `info-xref' and `highlight' faces.)
+
+ Other packages might define their own faces; to see a list of all
+faces, use any of the interactive face-manipulation commands such as
+`set-face-font' and type `?' when you are prompted for the name of a
+face.
+
+ If the `bold', `italic', and `bold-italic' faces are not specified
+in the resource database, then XEmacs attempts to derive them from the
+font of the default face. It can only succeed at this if you have
+specified the default font using the XLFD (X Logical Font Description)
+format, which looks like
+
+ *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+If you use any of the other, less strict font name formats, some of
+which look like
+
+ lucidasanstypewriter-12
+ fixed
+ 9x13
+
+ then XEmacs won't be able to guess the names of the bold and italic
+versions. All X fonts can be referred to via XLFD-style names, so you
+should use those forms. See the man pages for `X(1)', `xlsfonts(1)',
+and `xfontsel(1)'.
+
+\1f
+File: xemacs.info, Node: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
+
+Widgets
+-------
+
+ There are several structural widgets between the terminal EmacsFrame
+widget and the top level ApplicationShell; the exact names and types of
+these widgets change from release to release (for example, they changed
+between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
+subject to further change in the future, so you should avoid mentioning
+them in your resource database. The above-mentioned syntaxes should be
+forward- compatible. As of 19.13, the exact widget hierarchy is as
+follows:
+
+ INVOCATION-NAME "shell" "container" FRAME-NAME
+ x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
+
+ where INVOCATION-NAME is the terminal component of the name of the
+XEmacs executable (usually `xemacs'), and `x-emacs-application-class'
+is generally `Emacs'.
+
+\1f
+File: xemacs.info, Node: Menubar Resources, Prev: Widgets, Up: X Resources
+
+Menubar Resources
+-----------------
+
+ As the menubar is implemented as a widget which is not a part of
+XEmacs proper, it does not use the fac" mechanism for specifying fonts
+and colors: It uses whatever resources are appropriate to the type of
+widget which is used to implement it.
+
+ If Emacs was compiled to use only the Motif-lookalike menu widgets,
+then one way to specify the font of the menubar would be
+
+ Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+ If the Motif library is being used, then one would have to use
+
+ Emacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+
+ because the Motif library uses the `fontList' resource name instead
+of `font', which has subtly different semantics.
+
+ The same is true of the scrollbars: They accept whichever resources
+are appropriate for the toolkit in use.
+
+\1f
+File: xemacs.info, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top
+
+Quitting and Aborting
+=====================
+
+`C-g'
+ Quit. Cancel running or partially typed command.
+
+`C-]'
+ Abort innermost recursive editing level and cancel the command
+ which invoked it (`abort-recursive-edit').
+
+`M-x top-level'
+ Abort all recursive editing levels that are currently executing.
+
+`C-x u'
+ Cancel an already-executed command, usually (`undo').
+
+ There are two ways of cancelling commands which are not finished
+executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
+top-level'. Quitting is cancelling a partially typed command or one
+which is already running. Aborting is getting out of a recursive
+editing level and cancelling the command that invoked the recursive
+edit.
+
+ Quitting with `C-g' is used for getting rid of a partially typed
+command or a numeric argument that you don't want. It also stops a
+running command in the middle in a relatively safe way, so you can use
+it if you accidentally start executing a command that takes a long
+time. In particular, it is safe to quit out of killing; either your
+text will ALL still be there, or it will ALL be in the kill ring (or
+maybe both). Quitting an incremental search does special things
+documented under searching; in general, it may take two successive
+`C-g' characters to get out of a search. `C-g' works by setting the
+variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
+checks this variable frequently and quits if it is non-`nil'. `C-g' is
+only actually executed as a command if it is typed while Emacs is
+waiting for input.
+
+ If you quit twice in a row before the first `C-g' is recognized, you
+activate the "emergency escape" feature and return to the shell. *Note
+Emergency Escape::.
+
+ You can use `C-]' (`abort-recursive-edit') to get out of a recursive
+editing level and cancel the command which invoked it. Quitting with
+`C-g' does not do this, and could not do this because it is used to
+cancel a partially typed command within the recursive editing level.
+Both operations are useful. For example, if you are in the Emacs
+debugger (*note Lisp Debug::.) and have typed `C-u 8' to enter a
+numeric argument, you can cancel that argument with `C-g' and remain in
+the debugger.
+
+ The command `M-x top-level' is equivalent to "enough" `C-]' commands
+to get you out of all the levels of recursive edits that you are in.
+`C-]' only gets you out one level at a time, but `M-x top-level' goes
+out all levels at once. Both `C-]' and `M-x top-level' are like all
+other commands and unlike `C-g' in that they are effective only when
+Emacs is ready for a command. `C-]' is an ordinary key and has its
+meaning only because of its binding in the keymap. *Note Recursive
+Edit::.
+
+ `C-x u' (`undo') is not strictly speaking a way of cancelling a
+command, but you can think of it as cancelling a command already
+finished executing. *Note Undo::.
+
+\1f
+File: xemacs.info, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top
+
+Dealing With Emacs Trouble
+==========================
+
+ This section describes various conditions in which Emacs fails to
+work, and how to recognize them and correct them.
+
+* Menu:
+
+* Stuck Recursive:: `[...]' in mode line around the parentheses.
+* Screen Garbled:: Garbage on the screen.
+* Text Garbled:: Garbage in the text.
+* Unasked-for Search:: Spontaneous entry to incremental search.
+* Emergency Escape:: Emergency escape--
+ What to do if Emacs stops responding.
+* Total Frustration:: When you are at your wits' end.
+
+\1f
+File: xemacs.info, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
+
+Recursive Editing Levels
+------------------------
+
+ Recursive editing levels are important and useful features of Emacs,
+but they can seem like malfunctions to the user who does not understand
+them.
+
+ If the mode line has square brackets `[...]' around the parentheses
+that contain the names of the major and minor modes, you have entered a
+recursive editing level. If you did not do this on purpose, or if you
+don't understand what that means, you should just get out of the
+recursive editing level. To do so, type `M-x top-level'. This is
+called getting back to top level. *Note Recursive Edit::.
+
+\1f
+File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage
+
+Garbage on the Screen
+---------------------
+
+ If the data on the screen looks wrong, the first thing to do is see
+whether the text is actually wrong. Type `C-l', to redisplay the
+entire screen. If the text appears correct after this, the problem was
+entirely in the previous screen update.
+
+ Display updating problems often result from an incorrect termcap
+entry for the terminal you are using. The file `etc/TERMS' in the Emacs
+distribution gives the fixes for known problems of this sort.
+`INSTALL' contains general advice for these problems in one of its
+sections. Very likely there is simply insufficient padding for certain
+display operations. To investigate the possibility that you have this
+sort of problem, try Emacs on another terminal made by a different
+manufacturer. If problems happen frequently on one kind of terminal but
+not another kind, the real problem is likely to be a bad termcap entry,
+though it could also be due to a bug in Emacs that appears for terminals
+that have or lack specific features.
+
+\1f
+File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage
+
+Garbage in the Text
+-------------------
+
+ If `C-l' shows that the text is wrong, try undoing the changes to it
+using `C-x u' until it gets back to a state you consider correct. Also
+try `C-h l' to find out what command you typed to produce the observed
+results.
+
+ If a large portion of text appears to be missing at the beginning or
+end of the buffer, check for the word `Narrow' in the mode line. If it
+appears, the text is still present, but marked off-limits. To make it
+visible again, type `C-x n w'. *Note Narrowing::.
+
+\1f
+File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage
+
+Spontaneous Entry to Incremental Search
+---------------------------------------
+
+ If Emacs spontaneously displays `I-search:' at the bottom of the
+screen, it means that the terminal is sending `C-s' and `C-q' according
+to the poorly designed xon/xoff "flow control" protocol. You should
+try to prevent this by putting the terminal in a mode where it will not
+use flow control, or by giving it enough padding that it will never
+send a `C-s'. If that cannot be done, you must tell Emacs to expect
+flow control to be used, until you can get a properly designed terminal.
+
+ Information on how to do these things can be found in the file
+`INSTALL' in the Emacs distribution.
+
+\1f
+File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage
+
+Emergency Escape
+----------------
+
+ Because at times there have been bugs causing Emacs to loop without
+checking `quit-flag', a special feature causes Emacs to be suspended
+immediately if you type a second `C-g' while the flag is already set,
+so you can always get out of XEmacs. Normally Emacs recognizes and
+clears `quit-flag' (and quits!) quickly enough to prevent this from
+happening.
+
+ When you resume Emacs after a suspension caused by multiple `C-g', it
+asks two questions before going back to what it had been doing:
+
+ Auto-save? (y or n)
+ Abort (and dump core)? (y or n)
+
+Answer each one with `y' or `n' followed by <RET>.
+
+ Saying `y' to `Auto-save?' causes immediate auto-saving of all
+modified buffers in which auto-saving is enabled.
+
+ Saying `y' to `Abort (and dump core)?' causes an illegal instruction
+to be executed, dumping core. This is to enable a wizard to figure out
+why Emacs was failing to quit in the first place. Execution does not
+continue after a core dump. If you answer `n', execution does
+continue. With luck, Emacs will ultimately check `quit-flag' and quit
+normally. If not, and you type another `C-g', it is suspended again.
+
+ If Emacs is not really hung, but is just being slow, you may invoke
+the double `C-g' feature without really meaning to. In that case,
+simply resume and answer `n' to both questions, and you will arrive at
+your former state. Presumably the quit you requested will happen soon.
+
+ The double-`C-g' feature may be turned off when Emacs is running
+under a window system, since the window system always enables you to
+kill Emacs or to create another window and run another program.
+
+\1f
+File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage
+
+Help for Total Frustration
+--------------------------
+
+ If using Emacs (or something else) becomes terribly frustrating and
+none of the techniques described above solve the problem, Emacs can
+still help you.
+
+ First, if the Emacs you are using is not responding to commands, type
+`C-g C-g' to get out of it and then start a new one.
+
+ Second, type `M-x doctor <RET>'.
+
+ The doctor will make you feel better. Each time you say something to
+the doctor, you must end it by typing <RET> <RET>. This lets the
+doctor know you are finished.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top
+
+Reporting Bugs
+==============
+
+ Sometimes you will encounter a bug in Emacs. Although we cannot
+promise we can or will fix the bug, and we might not even agree that it
+is a bug, we want to hear about bugs you encounter in case we do want
+to fix them.
+
+ To make it possible for us to fix a bug, you must report it. In
+order to do so effectively, you must know when and how to do it.
+
+When Is There a Bug
+-------------------
+
+ If Emacs executes an illegal instruction, or dies with an operating
+system error message that indicates a problem in the program (as
+opposed to something like "disk full"), then it is certainly a bug.
+
+ If Emacs updates the display in a way that does not correspond to
+what is in the buffer, then it is certainly a bug. If a command seems
+to do the wrong thing but the problem corrects itself if you type
+`C-l', it is a case of incorrect display updating.
+
+ Taking forever to complete a command can be a bug, but you must make
+certain that it was really Emacs's fault. Some commands simply take a
+long time. Type `C-g' and then `C-h l' to see whether the input Emacs
+received was what you intended to type; if the input was such that you
+KNOW it should have been processed quickly, report a bug. If you don't
+know whether the command should take a long time, find out by looking
+in the manual or by asking for assistance.
+
+ If a command you are familiar with causes an Emacs error message in a
+case where its usual definition ought to be reasonable, it is probably a
+bug.
+
+ If a command does the wrong thing, that is a bug. But be sure you
+know for certain what it ought to have done. If you aren't familiar
+with the command, or don't know for certain how the command is supposed
+to work, then it might actually be working right. Rather than jumping
+to conclusions, show the problem to someone who knows for certain.
+
+ Finally, a command's intended definition may not be best for editing
+with. This is a very important sort of problem, but it is also a
+matter of judgment. Also, it is easy to come to such a conclusion out
+of ignorance of some of the existing features. It is probably best not
+to complain about such a problem until you have checked the
+documentation in the usual ways, feel confident that you understand it,
+and know for certain that what you want is not available. If you are
+not sure what the command is supposed to do after a careful reading of
+the manual, check the index and glossary for any terms that may be
+unclear. If you still do not understand, this indicates a bug in the
+manual. The manual's job is to make everything clear. It is just as
+important to report documentation bugs as program bugs.
+
+ If the online documentation string of a function or variable
+disagrees with the manual, one of them must be wrong, so report the bug.
+
+How to Report a Bug
+-------------------
+
+ When you decide that there is a bug, it is important to report it
+and to report it in a way which is useful. What is most useful is an
+exact description of what commands you type, starting with the shell
+command to run Emacs, until the problem happens. Always include the
+version number of Emacs that you are using; type `M-x emacs-version' to
+print this.
+
+ The most important principle in reporting a bug is to report FACTS,
+not hypotheses or categorizations. It is always easier to report the
+facts, but people seem to prefer to strain to posit explanations and
+report them instead. If the explanations are based on guesses about
+how Emacs is implemented, they will be useless; we will have to try to
+figure out what the facts must have been to lead to such speculations.
+Sometimes this is impossible. But in any case, it is unnecessary work
+for us.
+
+ For example, suppose that you type `C-x C-f /glorp/baz.ugh <RET>',
+visiting a file which (you know) happens to be rather large, and Emacs
+prints out `I feel pretty today'. The best way to report the bug is
+with a sentence like the preceding one, because it gives all the facts
+and nothing but the facts.
+
+ Do not assume that the problem is due to the size of the file and
+say, "When I visit a large file, Emacs prints out `I feel pretty
+today'." This is what we mean by "guessing explanations". The problem
+is just as likely to be due to the fact that there is a `z' in the file
+name. If this is so, then when we got your report, we would try out
+the problem with some "large file", probably with no `z' in its name,
+and not find anything wrong. There is no way in the world that we
+could guess that we should try visiting a file with a `z' in its name.
+
+ Alternatively, the problem might be due to the fact that the file
+starts with exactly 25 spaces. For this reason, you should make sure
+that you inform us of the exact contents of any file that is needed to
+reproduce the bug. What if the problem only occurs when you have typed
+the `C-x a l' command previously? This is why we ask you to give the
+exact sequence of characters you typed since starting to use Emacs.
+
+ You should not even say "visit a file" instead of `C-x C-f' unless
+you know that it makes no difference which visiting command is used.
+Similarly, rather than saying "if I have three characters on the line,"
+say "after I type `<RET> A B C <RET> C-p'," if that is the way you
+entered the text.
+
+ If you are not in Fundamental mode when the problem occurs, you
+should say what mode you are in.
+
+ If the manifestation of the bug is an Emacs error message, it is
+important to report not just the text of the error message but a
+backtrace showing how the Lisp program in Emacs arrived at the error.
+To make the backtrace, you must execute the Lisp expression `(setq
+debug-on-error t)' before the error happens (that is to say, you must
+execute that expression and then make the bug happen). This causes the
+Lisp debugger to run (*note Lisp Debug::.). The debugger's backtrace
+can be copied as text into the bug report. This use of the debugger is
+possible only if you know how to make the bug happen again. Do note
+the error message the first time the bug happens, so if you can't make
+it happen again, you can report at least that.
+
+ Check whether any programs you have loaded into the Lisp world,
+including your `.emacs' file, set any variables that may affect the
+functioning of Emacs. Also, see whether the problem happens in a
+freshly started Emacs without loading your `.emacs' file (start Emacs
+with the `-q' switch to prevent loading the init file). If the problem
+does NOT occur then, it is essential that we know the contents of any
+programs that you must load into the Lisp world in order to cause the
+problem to occur.
+
+ If the problem does depend on an init file or other Lisp programs
+that are not part of the standard Emacs system, then you should make
+sure it is not a bug in those programs by complaining to their
+maintainers first. After they verify that they are using Emacs in a
+way that is supposed to work, they should report the bug.
+
+ If you can tell us a way to cause the problem without visiting any
+files, please do so. This makes it much easier to debug. If you do
+need files, make sure you arrange for us to see their exact contents.
+For example, it can often matter whether there are spaces at the ends
+of lines, or a newline after the last line in the buffer (nothing ought
+to care whether the last line is terminated, but tell that to the bugs).
+
+ The easy way to record the input to Emacs precisely is to write a
+dribble file; execute the Lisp expression:
+
+ (open-dribble-file "~/dribble")
+
+using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
+Emacs. From then on, all Emacs input will be written in the specified
+dribble file until the Emacs process is killed.
+
+ For possible display bugs, it is important to report the terminal
+type (the value of environment variable `TERM'), the complete termcap
+entry for the terminal from `/etc/termcap' (since that file is not
+identical on all machines), and the output that Emacs actually sent to
+the terminal. The way to collect this output is to execute the Lisp
+expression:
+
+ (open-termscript "~/termscript")
+
+using `Meta-<ESC>' or from the `*scratch*' buffer just after starting
+Emacs. From then on, all output from Emacs to the terminal will be
+written in the specified termscript file as well, until the Emacs
+process is killed. If the problem happens when Emacs starts up, put
+this expression into your `.emacs' file so that the termscript file will
+be open when Emacs displays the screen for the first time. Be warned:
+it is often difficult, and sometimes impossible, to fix a
+terminal-dependent bug without access to a terminal of the type that
+stimulates the bug.
+
+ The newsgroup `comp.emacs.xemacs' may be used for bug reports, other
+discussions and requests for assistance.
+
+ If you don't have access to this newgroup, you can subscribe to the
+mailing list version: the newsgroup is bidirectionally gatewayed into
+the mailing list `xemacs@xemacs.org'.
+
+ To be added or removed from this mailing list, send mail to
+`xemacs-request@xemacs.org'. Do not send requests for addition to the
+mailing list itself.
+
+ The mailing lists and newsgroups are archived on our anonymous FTP
+server, `ftp.xemacs.org', and at various other archive sites around the
+net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous
+FTP server. It provides some introductory information and help for
+initial configuration problems.
+
+\1f
+File: xemacs.info, Node: Glossary, Next: Manifesto, Prev: Intro, Up: Top
+
+Glossary
+********
+
+Abbrev
+ An abbrev is a text string which expands into a different text
+ string when present in the buffer. For example, you might define
+ a short word as an abbrev for a long phrase that you want to insert
+ frequently. *Note Abbrevs::.
+
+Aborting
+ Aborting means getting out of a recursive edit (q.v.). You can use
+ the commands `C-]' and `M-x top-level' for this. *Note Quitting::.
+
+Auto Fill mode
+ Auto Fill mode is a minor mode in which text you insert is
+ automatically broken into lines of fixed width. *Note Filling::.
+
+Auto Saving
+ Auto saving means that Emacs automatically stores the contents of
+ an Emacs buffer in a specially-named file so the information will
+ not be lost if the buffer is lost due to a system error or user
+ error. *Note Auto Save::.
+
+Backup File
+ A backup file records the contents that a file had before the
+ current editing session. Emacs creates backup files automatically
+ to help you track down or cancel changes you later regret. *Note
+ Backup::.
+
+Balance Parentheses
+ Emacs can balance parentheses manually or automatically. Manual
+ balancing is done by the commands to move over balanced expressions
+ (*note Lists::.). Automatic balancing is done by blinking the
+ parenthesis that matches one just inserted (*note Matching Parens:
+ Matching.).
+
+Bind
+ To bind a key is to change its binding (q.v.). *Note Rebinding::.
+
+Binding
+ A key gets its meaning in Emacs by having a binding which is a
+ command (q.v.), a Lisp function that is run when the key is typed.
+ *Note Binding: Commands. Customization often involves rebinding a
+ character to a different command function. The bindings of all
+ keys are recorded in the keymaps (q.v.). *Note Keymaps::.
+
+Blank Lines
+ Blank lines are lines that contain only whitespace. Emacs has
+ several commands for operating on the blank lines in a buffer.
+
+Buffer
+ The buffer is the basic editing unit; one buffer corresponds to one
+ piece of text being edited. You can have several buffers, but at
+ any time you are editing only one, the `selected' buffer, though
+ several buffers can be visible when you are using multiple
+ windows. *Note Buffers::.
+
+Buffer Selection History
+ Emacs keeps a buffer selection history which records how recently
+ each Emacs buffer was selected. Emacs uses this list when
+ choosing a buffer to select. *Note Buffers::.
+
+C-
+ `C' in the name of a character is an abbreviation for Control.
+ *Note C-: Keystrokes.
+
+C-M-
+ `C-M-' in the name of a character is an abbreviation for
+ Control-Meta. *Note C-M-: Keystrokes.
+
+Case Conversion
+ Case conversion means changing text from upper case to lower case
+ or vice versa. *Note Case::, for the commands for case conversion.
+
+Characters
+ Characters form the contents of an Emacs buffer; also, Emacs
+ commands are invoked by keys (q.v.), which are sequences of one or
+ more characters. *Note Keystrokes::.
+
+Command
+ A command is a Lisp function specially defined to be able to serve
+ as a key binding in Emacs. When you type a key (q.v.), Emacs
+ looks up its binding (q.v.) in the relevant keymaps (q.v.) to find
+ the command to run. *Note Commands::.
+
+Command Name
+ A command name is the name of a Lisp symbol which is a command
+ (*note Commands::.). You can invoke any command by its name using
+ `M-x' (*note M-x::.).
+
+Comments
+ A comment is text in a program which is intended only for the
+ people reading the program, and is marked specially so that it
+ will be ignored when the program is loaded or compiled. Emacs
+ offers special commands for creating, aligning, and killing
+ comments. *Note Comments::.
+
+Compilation
+ Compilation is the process of creating an executable program from
+ source code. Emacs has commands for compiling files of Emacs Lisp
+ code (*note Lisp Libraries::.) and programs in C and other
+ languages (*note Compilation::.).
+
+Complete Key
+ A complete key is a character or sequence of characters which,
+ when typed by the user, fully specifies one action to be performed
+ by Emacs. For example, `X' and `Control-f' and `Control-x m' are
+ keys. Keys derive their meanings from being bound (q.v.) to
+ commands (q.v.). Thus, `X' is conventionally bound to a command
+ to insert `X' in the buffer; `C-x m' is conventionally bound to a
+ command to begin composing a mail message. *Note Keystrokes::.
+
+Completion
+ When Emacs automatically fills an abbreviation for a name into the
+ entire name, that process is called completion. Completion is
+ done for minibuffer (q.v.) arguments when the set of possible
+ valid inputs is known; for example, on command names, buffer
+ names, and file names. Completion occurs when you type <TAB>,
+ <SPC>, or <RET>. *Note Completion::.
+
+Continuation Line
+ When a line of text is longer than the width of the frame, it
+ takes up more than one screen line when displayed. We say that the
+ text line is continued, and all screen lines used for it after the
+ first are called continuation lines. *Note Continuation: Basic.
+
+Control-Character
+ ASCII characters with octal codes 0 through 037, and also code
+ 0177, do not have graphic images assigned to them. These are the
+ control characters. Any control character can be typed by holding
+ down the <CTRL> key and typing some other character; some have
+ special keys on the keyboard. <RET>, <TAB>, <ESC>, <LFD>, and
+ <DEL> are all control characters. *Note Keystrokes::.
+
+Copyleft
+ A copyleft is a notice giving the public legal permission to
+ redistribute a program or other work of art. Copylefts are used
+ by leftists to enrich the public just as copyrights are used by
+ rightists to gain power over the public.
+
+Current Buffer
+ The current buffer in Emacs is the Emacs buffer on which most
+ editing commands operate. You can select any Emacs buffer as the
+ current one. *Note Buffers::.
+
+Current Line
+ The line point is on (*note Point::.).
+
+Current Paragraph
+ The paragraph that point is in. If point is between paragraphs,
+ the current paragraph is the one that follows point. *Note
+ Paragraphs::.
+
+Current Defun
+ The defun (q.v.) that point is in. If point is between defuns, the
+ current defun is the one that follows point. *Note Defuns::.
+
+Cursor
+ The cursor is the rectangle on the screen which indicates the
+ position called point (q.v.) at which insertion and deletion takes
+ place. The cursor is on or under the character that follows
+ point. Often people speak of `the cursor' when, strictly
+ speaking, they mean `point'. *Note Cursor: Basic.
+
+Customization
+ Customization is making minor changes in the way Emacs works. It
+ is often done by setting variables (*note Variables::.) or by
+ rebinding keys (*note Keymaps::.).
+
+Default Argument
+ The default for an argument is the value that is used if you do not
+ specify one. When Emacs prompts you in the minibuffer for an
+ argument, the default argument is used if you just type <RET>.
+ *Note Minibuffer::.
+
+Default Directory
+ When you specify a file name that does not start with `/' or `~',
+ it is interpreted relative to the current buffer's default
+ directory. *Note Default Directory: Minibuffer File.
+
+Defun
+ A defun is a list at the top level of parenthesis or bracket
+ structure in a program. It is so named because most such lists in
+ Lisp programs are calls to the Lisp function `defun'. *Note
+ Defuns::.
+
+<DEL>
+ The <DEL> character runs the command that deletes one character of
+ text. *Note DEL: Basic.
+
+Deletion
+ Deleting text means erasing it without saving it. Emacs deletes
+ text only when it is expected not to be worth saving (all
+ whitespace, or only one character). The alternative is killing
+ (q.v.). *Note Deletion: Killing.
+
+Deletion of Files
+ Deleting a file means removing it from the file system. *Note
+ Misc File Ops::.
+
+Deletion of Messages
+ Deleting a message means flagging it to be eliminated from your
+ mail file. Until the mail file is expunged, you can undo this by
+ undeleting the message.
+
+Deletion of Frames
+ When working under the multi-frame X-based version of XEmacs, you
+ can delete individual frames using the Close menu item from the
+ File menu.
+
+Deletion of Windows
+ When you delete a subwindow of an Emacs frame, you eliminate it
+ from the frame. Other windows expand to use up the space. The
+ deleted window can never come back, but no actual text is lost.
+ *Note Windows::.
+
+Directory
+ Files in the Unix file system are grouped into file directories.
+ *Note Directories: ListDir.
+
+Dired
+ Dired is the Emacs facility that displays the contents of a file
+ directory and allows you to "edit the directory", performing
+ operations on the files in the directory. *Note Dired::.
+
+Disabled Command
+ A disabled command is one that you may not run without special
+ confirmation. Commands are usually disabled because they are
+ confusing for beginning users. *Note Disabling::.
+
+Dribble File
+ A file into which Emacs writes all the characters that the user
+ types on the keyboard. Dribble files are used to make a record for
+ debugging Emacs bugs. Emacs does not make a dribble file unless
+ you tell it to. *Note Bugs::.
+
+Echo Area
+ The area at the bottom of the Emacs frame which is used for
+ echoing the arguments to commands, for asking questions, and for
+ printing brief messages (including error messages). *Note Echo
+ Area::.
+
+Echoing
+ Echoing refers to acknowledging the receipt of commands by
+ displaying them (in the echo area). Emacs never echoes
+ single-character keys; longer keys echo only if you pause while
+ typing them.
+
+Error
+ An error occurs when an Emacs command cannot execute in the current
+ circumstances. When an error occurs, execution of the command
+ stops (unless the command has been programmed to do otherwise) and
+ Emacs reports the error by printing an error message (q.v.).
+ Type-ahead is discarded. Then Emacs is ready to read another
+ editing command.
+
+Error Messages
+ Error messages are single lines of output printed by Emacs when the
+ user asks for something impossible to do (such as killing text
+ forward when point is at the end of the buffer). They appear in
+ the echo area, accompanied by a beep.
+
+<ESC>
+ <ESC> is a character used as a prefix for typing Meta characters on
+ keyboards lacking a <META> key. Unlike the <META> key (which,
+ like the <SHIFT> key, is held down while another character is
+ typed), the <ESC> key is pressed and released, and applies to the
+ next character typed.
+
+Fill Prefix
+ The fill prefix is a string that Emacs enters at the beginning of
+ each line when it performs filling. It is not regarded as part of
+ the text to be filled. *Note Filling::.
+
+Filling
+ Filling text means moving text from line to line so that all the
+ lines are approximately the same length. *Note Filling::.
+
+Frame
+ When running Emacs on a TTY terminal, "frame" means the terminal's
+ screen. When running Emacs under X, you can have multiple frames,
+ each corresponding to a top-level X window and each looking like
+ the screen on a TTY. Each frame contains one or more
+ non-overlapping Emacs windows (possibly with associated
+ scrollbars, under X), an echo area, and (under X) possibly a
+ menubar.
+
+Global
+ Global means `independent of the current environment; in effect
+ throughout Emacs'. It is the opposite of local (q.v.). Examples
+ of the use of `global' appear below.
+
+Global Abbrev
+ A global definition of an abbrev (q.v.) is effective in all major
+ modes that do not have local (q.v.) definitions for the same
+ abbrev. *Note Abbrevs::.
+
+Global Keymap
+ The global keymap (q.v.) contains key bindings that are in effect
+ unless local key bindings in a major mode's local keymap (q.v.)
+ override them.*Note Keymaps::.
+
+Global Substitution
+ Global substitution means replacing each occurrence of one string
+ by another string through a large amount of text. *Note Replace::.
+
+Global Variable
+ The global value of a variable (q.v.) takes effect in all buffers
+ that do not have their own local (q.v.) values for the variable.
+ *Note Variables::.
+
+Graphic Character
+ Graphic characters are those assigned pictorial images rather than
+ just names. All the non-Meta (q.v.) characters except for the
+ Control (q.v.) character are graphic characters. These include
+ letters, digits, punctuation, and spaces; they do not include
+ <RET> or <ESC>. In Emacs, typing a graphic character inserts that
+ character (in ordinary editing modes). *Note Basic Editing: Basic.
+
+Grinding
+ Grinding means adjusting the indentation in a program to fit the
+ nesting structure. *Note Grinding: Indentation.
+
+Hardcopy
+ Hardcopy means printed output. Emacs has commands for making
+ printed listings of text in Emacs buffers. *Note Hardcopy::.
+
+<HELP>
+ You can type <HELP> at any time to ask what options you have, or
+ to ask what any command does. <HELP> is really `Control-h'.
+ *Note Help::.
+
+Inbox
+ An inbox is a file in which mail is delivered by the operating
+ system. Some mail handlers transfers mail from inboxes to mail
+ files (q.v.) in which the mail is then stored permanently or until
+ explicitly deleted.
+
+Indentation
+ Indentation means blank space at the beginning of a line. Most
+ programming languages have conventions for using indentation to
+ illuminate the structure of the program, and Emacs has special
+ features to help you set up the correct indentation. *Note
+ Indentation::.
+
+Insertion
+ Insertion means copying text into the buffer, either from the
+ keyboard or from some other place in Emacs.
+
+Justification
+ Justification means adding extra spaces to lines of text to make
+ them come exactly to a specified width. *Note Justification:
+ Filling.
+
+Keyboard Macros
+ Keyboard macros are a way of defining new Emacs commands from
+ sequences of existing ones, with no need to write a Lisp program.
+ *Note Keyboard Macros::.
+
+Key
+ A key is a sequence of characters that, when input to Emacs,
+ specify or begin to specify a single action for Emacs to perform.
+ That is, the sequence is considered a single unit. If the key is
+ enough to specify one action, it is a complete key (q.v.); if it
+ is less than enough, it is a prefix key (q.v.). *Note
+ Keystrokes::.
+
+Keymap
+ The keymap is the data structure that records the bindings (q.v.)
+ of keys to the commands that they run. For example, the keymap
+ binds the character `C-n' to the command function `next-line'.
+ *Note Keymaps::.
+
+Kill Ring
+ The kill ring is the place where all text you have killed recently
+ is saved. You can re-insert any of the killed text still in the
+ ring; this is called yanking (q.v.). *Note Yanking::.
+
+Killing
+ Killing means erasing text and saving it on the kill ring so it
+ can be yanked (q.v.) later. Some other systems call this
+ "cutting." Most Emacs commands to erase text do killing, as
+ opposed to deletion (q.v.). *Note Killing::.
+
+Killing Jobs
+ Killing a job (such as, an invocation of Emacs) means making it
+ cease to exist. Any data within it, if not saved in a file, is
+ lost. *Note Exiting::.
+
+List
+ A list is, approximately, a text string beginning with an open
+ parenthesis and ending with the matching close parenthesis. In C
+ mode and other non-Lisp modes, groupings surrounded by other kinds
+ of matched delimiters appropriate to the language, such as braces,
+ are also considered lists. Emacs has special commands for many
+ operations on lists. *Note Lists::.
+
+Local
+ Local means `in effect only in a particular context'; the relevant
+ kind of context is a particular function execution, a particular
+ buffer, or a particular major mode. Local is the opposite of
+ `global' (q.v.). Specific uses of `local' in Emacs terminology
+ appear below.
+
+Local Abbrev
+ A local abbrev definition is effective only if a particular major
+ mode is selected. In that major mode, it overrides any global
+ definition for the same abbrev. *Note Abbrevs::.
+
+Local Keymap
+ A local keymap is used in a particular major mode; the key bindings
+ (q.v.) in the current local keymap override global bindings of the
+ same keys. *Note Keymaps::.
+
+Local Variable
+ A local value of a variable (q.v.) applies to only one buffer.
+ *Note Locals::.
+
+M-
+ `M-' in the name of a character is an abbreviation for <META>, one
+ of the modifier keys that can accompany any character. *Note
+ Keystrokes::.
+
+M-C-
+ `M-C-' in the name of a character is an abbreviation for
+ Control-Meta; it means the same thing as `C-M-'. If your terminal
+ lacks a real <META> key, you type a Control-Meta character by
+ typing <ESC> and then typing the corresponding Control character.
+ *Note C-M-: Keystrokes.
+
+M-x
+ `M-x' is the key which is used to call an Emacs command by name.
+ You use it to call commands that are not bound to keys. *Note
+ M-x::.
+
+Mail
+ Mail means messages sent from one user to another through the
+ computer system, to be read at the recipient's convenience. Emacs
+ has commands for composing and sending mail, and for reading and
+ editing the mail you have received. *Note Sending Mail::.
+
+Major Mode
+ The major modes are a mutually exclusive set of options each of
+ which configures Emacs for editing a certain sort of text.
+ Ideally, each programming language has its own major mode. *Note
+ Major Modes::.
+
+Mark
+ The mark points to a position in the text. It specifies one end
+ of the region (q.v.), point being the other end. Many commands
+ operate on the whole region, that is, all the text from point to
+ the mark. *Note Mark::.
+
+Mark Ring
+ The mark ring is used to hold several recent previous locations of
+ the mark, just in case you want to move back to them. *Note Mark
+ Ring::.
+
+Message
+ See `mail'.
+
+Meta
+ Meta is the name of a modifier bit which a command character may
+ have. It is present in a character if the character is typed with
+ the <META> key held down. Such characters are given names that
+ start with `Meta-'. For example, `Meta-<' is typed by holding down
+ <META> and at the same time typing `<' (which itself is done, on
+ most terminals, by holding down <SHIFT> and typing `,'). *Note
+ Meta: Keystrokes.
+
+Meta Character
+ A Meta character is one whose character code includes the Meta bit.
+
+Minibuffer
+ The minibuffer is the window that Emacs displays inside the echo
+ area (q.v.) when it prompts you for arguments to commands. *Note
+ Minibuffer::.
+
+Minor Mode
+ A minor mode is an optional feature of Emacs which can be switched
+ on or off independent of the major mode. Each minor mode has a
+ command to turn it on or off. *Note Minor Modes::.
+
+Mode Line
+ The mode line is the line at the bottom of each text window (q.v.),
+ which gives status information on the buffer displayed in that
+ window. *Note Mode Line::.
+
+Modified Buffer
+ A buffer (q.v.) is modified if its text has been changed since the
+ last time the buffer was saved (or since it was created, if it has
+ never been saved). *Note Saving::.
+
+Moving Text
+ Moving text means erasing it from one place and inserting it in
+ another. This is done by killing (q.v.) and then yanking (q.v.).
+ *Note Killing::.
+
+Named Mark
+ A named mark is a register (q.v.) in its role of recording a
+ location in text so that you can move point to that location.
+ *Note Registers::.
+
+Narrowing
+ Narrowing means creating a restriction (q.v.) that limits editing
+ in the current buffer to only a part of the text in the buffer.
+ Text outside that part is inaccessible to the user until the
+ boundaries are widened again, but it is still there, and saving
+ the file saves the invisible text. *Note Narrowing::.
+
+Newline
+ <LFD> characters in the buffer terminate lines of text and are
+ called newlines. *Note Newline: Keystrokes.
+
+Numeric Argument
+ A numeric argument is a number, specified before a command, to
+ change the effect of the command. Often the numeric argument
+ serves as a repeat count. *Note Arguments::.
+
+Option
+ An option is a variable (q.v.) that allows you to customize Emacs
+ by giving it a new value. *Note Variables::.
+
+Overwrite Mode
+ Overwrite mode is a minor mode. When it is enabled, ordinary text
+ characters replace the existing text after point rather than
+ pushing it to the right. *Note Minor Modes::.
+
+Page
+ A page is a unit of text, delimited by formfeed characters (ASCII
+ Control-L, code 014) coming at the beginning of a line. Some Emacs
+ commands are provided for moving over and operating on pages.
+ *Note Pages::.
+
+Paragraphs
+ Paragraphs are the medium-size unit of English text. There are
+ special Emacs commands for moving over and operating on paragraphs.
+ *Note Paragraphs::.
+
+Parsing
+ We say that Emacs parses words or expressions in the text being
+ edited. Really, all it knows how to do is find the other end of a
+ word or expression. *Note Syntax::.
+
+Point
+ Point is the place in the buffer at which insertion and deletion
+ occur. Point is considered to be between two characters, not at
+ one character. The terminal's cursor (q.v.) indicates the
+ location of point. *Note Point: Basic.
+
+Prefix Key
+ A prefix key is a key (q.v.) whose sole function is to introduce a
+ set of multi-character keys. `Control-x' is an example of a prefix
+ key; any two-character sequence starting with `C-x' is also a
+ legitimate key. *Note Keystrokes::.
+
+Prompt
+ A prompt is text printed to ask the user for input. Printing a
+ prompt is called prompting. Emacs prompts always appear in the
+ echo area (q.v.). One kind of prompting happens when the
+ minibuffer is used to read an argument (*note Minibuffer::.); the
+ echoing which happens when you pause in the middle of typing a
+ multi-character key is also a kind of prompting (*note Echo
+ Area::.).
+
+Quitting
+ Quitting means cancelling a partially typed command or a running
+ command, using `C-g'. *Note Quitting::.
+
+Quoting
+ Quoting means depriving a character of its usual special
+ significance. In Emacs this is usually done with `Control-q'.
+ What constitutes special significance depends on the context and
+ on convention. For example, an "ordinary" character as an Emacs
+ command inserts itself; so in this context, a special character is
+ any character that does not normally insert itself (such as <DEL>,
+ for example), and quoting it makes it insert itself as if it were
+ not special. Not all contexts allow quoting. *Note Quoting:
+ Basic.
+
+Read-only Buffer
+ A read-only buffer is one whose text you are not allowed to change.
+ Normally Emacs makes buffers read-only when they contain text which
+ has a special significance to Emacs, such asDired buffers.
+ Visiting a file that is write-protected also makes a read-only
+ buffer. *Note Buffers::.
+
+Recursive Editing Level
+ A recursive editing level is a state in which part of the
+ execution of a command involves asking the user to edit some text.
+ This text may or may not be the same as the text to which the
+ command was applied. The mode line indicates recursive editing
+ levels with square brackets (`[' and `]'). *Note Recursive Edit::.
+
+Redisplay
+ Redisplay is the process of correcting the image on the screen to
+ correspond to changes that have been made in the text being edited.
+ *Note Redisplay: Frame.
+
+Regexp
+ See `regular expression'.
+
+Region
+ The region is the text between point (q.v.) and the mark (q.v.).
+ Many commands operate on the text of the region. *Note Region:
+ Mark.
+
+Registers
+ Registers are named slots in which text or buffer positions or
+ rectangles can be saved for later use. *Note Registers::.
+
+Regular Expression
+ A regular expression is a pattern that can match various text
+ strings; for example, `l[0-9]+' matches `l' followed by one or more
+ digits. *Note Regexps::.
+
+Replacement
+ See `global substitution'.
+
+Restriction
+ A buffer's restriction is the amount of text, at the beginning or
+ the end of the buffer, that is temporarily invisible and
+ inaccessible. Giving a buffer a nonzero amount of restriction is
+ called narrowing (q.v.). *Note Narrowing::.
+
+<RET>
+ <RET> is the character than runs the command to insert a newline
+ into the text. It is also used to terminate most arguments read
+ in the minibuffer (q.v.). *Note Return: Keystrokes.
+
+Saving
+ Saving a buffer means copying its text into the file that was
+ visited (q.v.) in that buffer. To actually change a file you have
+ edited in Emacs, you have to save it. *Note Saving::.
+
+Scrolling
+ Scrolling means shifting the text in the Emacs window to make a
+ different part ot the buffer visible. *Note Scrolling: Display.
+
+Searching
+ Searching means moving point to the next occurrence of a specified
+ string. *Note Search::.
+
+Selecting
+ Selecting a buffer means making it the current (q.v.) buffer.
+ *Note Selecting: Buffers.
+
+Self-documentation
+ Self-documentation is the feature of Emacs which can tell you what
+ any command does, or can give you a list of all commands related
+ to a topic you specify. You ask for self-documentation with the
+ help character, `C-h'. *Note Help::.
+
+Sentences
+ Emacs has commands for moving by or killing by sentences. *Note
+ Sentences::.
+
+Sexp
+ An sexp (short for `s-expression,' itself short for `symbolic
+ expression') is the basic syntactic unit of Lisp in its textual
+ form: either a list, or Lisp atom. Many Emacs commands operate on
+ sexps. The term `sexp' is generalized to languages other than
+ Lisp to mean a syntactically recognizable expression. *Note
+ Sexps: Lists.
+
+Simultaneous Editing
+ Simultaneous editing means two users modifying the same file at
+ once. If simultaneous editing is not detected, you may lose your
+ work. Emacs detects all cases of simultaneous editing and warns
+ the user to investigate them. *Note Simultaneous Editing:
+ Interlocking.
+
+String
+ A string is a kind of Lisp data object which contains a sequence of
+ characters. Many Emacs variables are intended to have strings as
+ values. The Lisp syntax for a string consists of the characters in
+ the string with a `"' before and another `"' after. Write a `"'
+ that is part of the string as `\"' and a `\' that is part of the
+ string as `\\'. You can include all other characters, including
+ newline, just by writing them inside the string. You can also
+ include escape sequences as in C, such as `\n' for newline or
+ `\241' using an octal character code.
+
+String Substitution
+ See `global substitution'.
+
+Syntax Table
+ The syntax table tells Emacs which characters are part of a word,
+ which characters balance each other like parentheses, etc. *Note
+ Syntax::.
+
+Tag Table
+ A tag table is a file that serves as an index to the function
+ definitions in one or more other files. *Note Tags::.
+
+Termscript File
+ A termscript file contains a record of all characters Emacs sent to
+ the terminal. It is used for tracking down bugs in Emacs
+ redisplay. Emacs does not make a termscript file unless
+ explicitly instructed to do so. *Note Bugs::.
+
+Text
+ Text has two meanings (*note Text::.):
+
+ * Data consisting of a sequence of characters, as opposed to
+ binary numbers, images, graphics commands, executable
+ programs, and the like. The contents of an Emacs buffer are
+ always text in this sense.
+
+ * Data consisting of written human language, as opposed to
+ programs, or something that follows the stylistic conventions
+ of human language.
+
+Top Level
+ Top level is the normal state of Emacs, in which you are editing
+ the text of the file you have visited. You are at top level
+ whenever you are not in a recursive editing level (q.v.) or the
+ minibuffer (q.v.), and not in the middle of a command. You can
+ get back to top level by aborting (q.v.) and quitting (q.v.).
+ *Note Quitting::.
+
+Transposition
+ Transposing two units of text means putting each one into the place
+ formerly occupied by the other. There are Emacs commands to
+ transpose two adjacent characters, words, sexps (q.v.), or lines
+ (*note Transpose::.).
+
+Truncation
+ Truncating text lines in the display means leaving out any text on
+ a line that does not fit within the right margin of the window
+ displaying it. See also `continuation line'. *Note Truncation:
+ Basic.
+
+Undoing
+ Undoing means making your previous editing go in reverse, bringing
+ back the text that existed earlier in the editing session. *Note
+ Undo::.
+
+Variable
+ A variable is Lisp object that can store an arbitrary value.
+ Emacs uses some variables for internal purposes, and has others
+ (known as `options' (q.v.)) you can set to control the behavior of
+ Emacs. The variables used in Emacs that you are likely to be
+ interested in are listed in the Variables Index of this manual.
+ *Note Variables::, for information on variables.
+
+Visiting
+ Visiting a file means loading its contents into a buffer (q.v.)
+ where they can be edited. *Note Visiting::.
+
+Whitespace
+ Whitespace is any run of consecutive formatting characters (spaces,
+ tabs, newlines, and backspaces).
+
+Widening
+ Widening is removing any restriction (q.v.) on the current buffer;
+ it is the opposite of narrowing (q.v.). *Note Narrowing::.
+
+Window
+ Emacs divides the frame into one or more windows, each of which can
+ display the contents of one buffer (q.v.) at any time. *Note
+ Frame::, for basic information on how Emacs uses the frame. *Note
+ Windows::, for commands to control the use of windows. Note that if
+ you are running Emacs under X, terminology can be confusing: Each
+ Emacs frame occupies a separate X window and can, in turn, be
+ divided into different subwindows.
+
+Word Abbrev
+ Synonymous with `abbrev'.
+
+Word Search
+ Word search is searching for a sequence of words, considering the
+ punctuation between them as insignificant. *Note Word Search::.
+
+Yanking
+ Yanking means reinserting text previously killed. It can be used
+ to undo a mistaken kill, or for copying or moving text. Some other
+ systems call this "pasting". *Note Yanking::.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Manifesto, Next: Key Index, Prev: Glossary, Up: Top
+
+The GNU Manifesto
+*****************
+
+What's GNU? GNU's Not Unix!
+============================
+
+ GNU, which stands for GNU's Not Unix, is the name for the complete
+Unix-compatible software system which I am writing so that I can give it
+away free to everyone who can use it. Several other volunteers are
+helping me. Contributions of time, money, programs, and equipment are
+greatly needed.
+
+ So far we have an Emacs text editor with Lisp for writing editor
+commands, a source level debugger, a yacc-compatible parser generator,
+a linker, and around 35 utilities. A shell (command interpreter) is
+nearly completed. A new portable optimizing C compiler has compiled
+itself and may be released this year. An initial kernel exists, but
+many more features are needed to emulate Unix. When the kernel and
+compiler are finished, it will be possible to distribute a GNU system
+suitable for program development. We will use TeX as our text
+formatter, but an nroff is being worked on. We will use the free,
+portable X window system as well. After this we will add a portable
+Common Lisp, an Empire game, a spreadsheet, and hundreds of other
+things, plus online documentation. We hope to supply, eventually,
+everything useful that normally comes with a Unix system, and more.
+
+ GNU will be able to run Unix programs, but will not be identical to
+Unix. We will make all improvements that are convenient, based on our
+experience with other operating systems. In particular, we plan to
+have longer filenames, file version numbers, a crashproof file system,
+filename completion perhaps, terminal-independent display support, and
+perhaps eventually a Lisp-based window system through which several
+Lisp programs and ordinary Unix programs can share a screen. Both C
+and Lisp will be available as system programming languages. We will
+try to support UUCP, MIT Chaosnet, and Internet protocols for
+communication.
+
+ GNU is aimed initially at machines in the 68000/16000 class with
+virtual memory, because they are the easiest machines to make it run
+on. The extra effort to make it run on smaller machines will be left
+to someone who wants to use it on them.
+
+ To avoid horrible confusion, please pronounce the `G' in the word
+`GNU' when it is the name of this project.
+
+Why I Must Write GNU
+====================
+
+ I consider that the golden rule requires that if I like a program I
+must share it with other people who like it. Software sellers want to
+divide the users and conquer them, making each user agree not to share
+with others. I refuse to break solidarity with other users in this
+way. I cannot in good conscience sign a nondisclosure agreement or a
+software license agreement. For years I worked within the Artificial
+Intelligence Lab to resist such tendencies and other inhospitalities,
+but eventually they had gone too far: I could not remain in an
+institution where such things are done for me against my will.
+
+ So that I can continue to use computers without dishonor, I have
+decided to put together a sufficient body of free software so that I
+will be able to get along without any software that is not free. I
+have resigned from the AI lab to deny MIT any legal excuse to prevent
+me from giving GNU away.
+
+Why GNU Will Be Compatible With Unix
+====================================
+
+ Unix is not my ideal system, but it is not too bad. The essential
+features of Unix seem to be good ones, and I think I can fill in what
+Unix lacks without spoiling them. And a system compatible with Unix
+would be convenient for many other people to adopt.
+
+How GNU Will Be Available
+=========================
+
+ GNU is not in the public domain. Everyone will be permitted to
+modify and redistribute GNU, but no distributor will be allowed to
+restrict its further redistribution. That is to say, proprietary
+modifications will not be allowed. I want to make sure that all
+versions of GNU remain free.
+
+Why Many Other Programmers Want to Help
+=======================================
+
+ I have found many other programmers who are excited about GNU and
+want to help.
+
+ Many programmers are unhappy about the commercialization of system
+software. It may enable them to make more money, but it requires them
+to feel in conflict with other programmers in general rather than feel
+as comrades. The fundamental act of friendship among programmers is the
+sharing of programs; marketing arrangements now typically used
+essentially forbid programmers to treat others as friends. The
+purchaser of software must choose between friendship and obeying the
+law. Naturally, many decide that friendship is more important. But
+those who believe in law often do not feel at ease with either choice.
+They become cynical and think that programming is just a way of making
+money.
+
+ By working on and using GNU rather than proprietary programs, we can
+be hospitable to everyone and obey the law. In addition, GNU serves as
+an example to inspire and a banner to rally others to join us in
+sharing. This can give us a feeling of harmony which is impossible if
+we use software that is not free. For about half the programmers I
+talk to, this is an important happiness that money cannot replace.
+
+How You Can Contribute
+======================
+
+ I am asking computer manufacturers for donations of machines and
+money. I'm asking individuals for donations of programs and work.
+
+ One consequence you can expect if you donate machines is that GNU
+will run on them at an early date. The machines should be complete,
+ready-to-use systems, approved for use in a residential area, and not
+in need of sophisticated cooling or power.
+
+ I have found very many programmers eager to contribute part-time
+work for GNU. For most projects, such part-time distributed work would
+be very hard to coordinate; the independently-written parts would not
+work together. But for the particular task of replacing Unix, this
+problem is absent. A complete Unix system contains hundreds of utility
+programs, each of which is documented separately. Most interface
+specifications are fixed by Unix compatibility. If each contributor
+can write a compatible replacement for a single Unix utility, and make
+it work properly in place of the original on a Unix system, then these
+utilities will work right when put together. Even allowing for Murphy
+to create a few unexpected problems, assembling these components will
+be a feasible task. (The kernel will require closer communication and
+will be worked on by a small, tight group.)
+
+ If I get donations of money, I may be able to hire a few people full
+or part time. The salary won't be high by programmers' standards, but
+I'm looking for people for whom building community spirit is as
+important as making money. I view this as a way of enabling dedicated
+people to devote their full energies to working on GNU by sparing them
+the need to make a living in another way.
+
+Why All Computer Users Will Benefit
+===================================
+
+ Once GNU is written, everyone will be able to obtain good system
+software free, just like air.
+
+ This means much more than just saving everyone the price of a Unix
+license. It means that much wasteful duplication of system programming
+effort will be avoided. This effort can go instead into advancing the
+state of the art.
+
+ Complete system sources will be available to everyone. As a result,
+a user who needs changes in the system will always be free to make them
+himself, or hire any available programmer or company to make them for
+him. Users will no longer be at the mercy of one programmer or company
+which owns the sources and is in sole position to make changes.
+
+ Schools will be able to provide a much more educational environment
+by encouraging all students to study and improve the system code.
+Harvard's computer lab used to have the policy that no program could be
+installed on the system if its sources were not on public display, and
+upheld it by actually refusing to install certain programs. I was very
+much inspired by this.
+
+ Finally, the overhead of considering who owns the system software
+and what one is or is not entitled to do with it will be lifted.
+
+ Arrangements to make people pay for using a program, including
+licensing of copies, always incur a tremendous cost to society through
+the cumbersome mechanisms necessary to figure out how much (that is,
+which programs) a person must pay for. And only a police state can
+force everyone to obey them. Consider a space station where air must
+be manufactured at great cost: charging each breather per liter of air
+may be fair, but wearing the metered gas mask all day and all night is
+intolerable even if everyone can afford to pay the air bill. And the
+TV cameras everywhere to see if you ever take the mask off are
+outrageous. It's better to support the air plant with a head tax and
+chuck the masks.
+
+ Copying all or parts of a program is as natural to a programmer as
+breathing, and as productive. It ought to be as free.
+
+Some Easily Rebutted Objections to GNU's Goals
+==============================================
+
+ "Nobody will use it if it is free, because that means they can't
+ rely on any support."
+
+ "You have to charge for the program to pay for providing the
+ support."
+
+ If people would rather pay for GNU plus service than get GNU free
+without service, a company to provide just service to people who have
+obtained GNU free ought to be profitable.
+
+ We must distinguish between support in the form of real programming
+work and mere handholding. The former is something one cannot rely on
+from a software vendor. If your problem is not shared by enough
+people, the vendor will tell you to get lost.
+
+ If your business needs to be able to rely on support, the only way
+is to have all the necessary sources and tools. Then you can hire any
+available person to fix your problem; you are not at the mercy of any
+individual. With Unix, the price of sources puts this out of
+consideration for most businesses. With GNU this will be easy. It is
+still possible for there to be no available competent person, but this
+problem cannot be blamed on distibution arrangements. GNU does not
+eliminate all the world's problems, only some of them.
+
+ Meanwhile, the users who know nothing about computers need
+handholding: doing things for them which they could easily do
+themselves but don't know how.
+
+ Such services could be provided by companies that sell just
+hand-holding and repair service. If it is true that users would rather
+spend money and get a product with service, they will also be willing
+to buy the service having got the product free. The service companies
+will compete in quality and price; users will not be tied to any
+particular one. Meanwhile, those of us who don't need the service
+should be able to use the program without paying for the service.
+
+ "You cannot reach many people without advertising, and you must
+ charge for the program to support that."
+
+ "It's no use advertising a program people can get free."
+
+ There are various forms of free or very cheap publicity that can be
+used to inform numbers of computer users about something like GNU. But
+it may be true that one can reach more microcomputer users with
+advertising. If this is really so, a business which advertises the
+service of copying and mailing GNU for a fee ought to be successful
+enough to pay for its advertising and more. This way, only the users
+who benefit from the advertising pay for it.
+
+ On the other hand, if many people get GNU from their friends, and
+such companies don't succeed, this will show that advertising was not
+really necessary to spread GNU. Why is it that free market advocates
+don't want to let the free market decide this?
+
+ "My company needs a proprietary operating system to get a
+ competitive edge."
+
+ GNU will remove operating system software from the realm of
+competition. You will not be able to get an edge in this area, but
+neither will your competitors be able to get an edge over you. You and
+they will compete in other areas, while benefitting mutually in this
+one. If your business is selling an operating system, you will not
+like GNU, but that's tough on you. If your business is something else,
+GNU can save you from being pushed into the expensive business of
+selling operating systems.
+
+ I would like to see GNU development supported by gifts from many
+manufacturers and users, reducing the cost to each.
+
+ "Don't programmers deserve a reward for their creativity?"
+
+ If anything deserves a reward, it is social contribution.
+Creativity can be a social contribution, but only in so far as society
+is free to use the results. If programmers deserve to be rewarded for
+creating innovative programs, by the same token they deserve to be
+punished if they restrict the use of these programs.
+
+ "Shouldn't a programmer be able to ask for a reward for his
+ creativity?"
+
+ There is nothing wrong with wanting pay for work, or seeking to
+maximize one's income, as long as one does not use means that are
+destructive. But the means customary in the field of software today
+are based on destruction.
+
+ Extracting money from users of a program by restricting their use of
+it is destructive because the restrictions reduce the amount and the
+ways that the program can be used. This reduces the amount of wealth
+that humanity derives from the program. When there is a deliberate
+choice to restrict, the harmful consequences are deliberate destruction.
+
+ The reason a good citizen does not use such destructive means to
+become wealthier is that, if everyone did so, we would all become
+poorer from the mutual destructiveness. This is Kantian ethics; or,
+the Golden Rule. Since I do not like the consequences that result if
+everyone hoards information, I am required to consider it wrong for one
+to do so. Specifically, the desire to be rewarded for one's creativity
+does not justify depriving the world in general of all or part of that
+creativity.
+
+ "Won't programmers starve?"
+
+ I could answer that nobody is forced to be a programmer. Most of us
+cannot manage to get any money for standing on the street and making
+faces. But we are not, as a result, condemned to spend our lives
+standing on the street making faces, and starving. We do something
+else.
+
+ But that is the wrong answer because it accepts the questioner's
+implicit assumption: that without ownership of software, programmers
+cannot possibly be paid a cent. Supposedly it is all or nothing.
+
+ The real reason programmers will not starve is that it will still be
+possible for them to get paid for programming; just not paid as much as
+now.
+
+ Restricting copying is not the only basis for business in software.
+It is the most common basis because it brings in the most money. If it
+were prohibited, or rejected by the customer, software business would
+move to other bases of organization which are now used less often.
+There are always numerous ways to organize any kind of business.
+
+ Probably programming will not be as lucrative on the new basis as it
+is now. But that is not an argument against the change. It is not
+considered an injustice that sales clerks make the salaries that they
+now do. If programmers made the same, that would not be an injustice
+either. (In practice they would still make considerably more than
+that.)
+
+ "Don't people have a right to control how their creativity is
+ used?"
+
+ "Control over the use of one's ideas" really constitutes control over
+other people's lives; and it is usually used to make their lives more
+difficult.
+
+ People who have studied the issue of intellectual property rights
+carefully (such as lawyers) say that there is no intrinsic right to
+intellectual property. The kinds of supposed intellectual property
+rights that the government recognizes were created by specific acts of
+legislation for specific purposes.
+
+ For example, the patent system was established to encourage
+inventors to disclose the details of their inventions. Its purpose was
+to help society rather than to help inventors. At the time, the life
+span of 17 years for a patent was short compared with the rate of
+advance of the state of the art. Since patents are an issue only among
+manufacturers, for whom the cost and effort of a license agreement are
+small compared with setting up production, the patents often do not do
+much harm. They do not obstruct most individuals who use patented
+products.
+
+ The idea of copyright did not exist in ancient times, when authors
+frequently copied other authors at length in works of non-fiction. This
+practice was useful, and is the only way many authors' works have
+survived even in part. The copyright system was created expressly for
+the purpose of encouraging authorship. In the domain for which it was
+invented--books, which could be copied economically only on a printing
+press--it did little harm, and did not obstruct most of the individuals
+who read the books.
+
+ All intellectual property rights are just licenses granted by society
+because it was thought, rightly or wrongly, that society as a whole
+would benefit by granting them. But in any particular situation, we
+have to ask: are we really better off granting such license? What kind
+of act are we licensing a person to do?
+
+ The case of programs today is very different from that of books a
+hundred years ago. The fact that the easiest way to copy a program is
+from one neighbor to another, the fact that a program has both source
+code and object code which are distinct, and the fact that a program is
+used rather than read and enjoyed, combine to create a situation in
+which a person who enforces a copyright is harming society as a whole
+both materially and spiritually; in which a person should not do so
+regardless of whether the law enables him to.
+
+ "Competition makes things get done better."
+
+ The paradigm of competition is a race: by rewarding the winner, we
+encourage everyone to run faster. When capitalism really works this
+way, it does a good job; but its defenders are wrong in assuming it
+always works this way. If the runners forget why the reward is offered
+and become intent on winning, no matter how, they may find other
+strategies--such as, attacking other runners. If the runners get into
+a fist fight, they will all finish late.
+
+ Proprietary and secret software is the moral equivalent of runners
+in a fist fight. Sad to say, the only referee we've got does not seem
+to object to fights; he just regulates them ("For every ten yards you
+run, you can fire one shot"). He really ought to break them up, and
+penalize runners for even trying to fight.
+
+ "Won't everyone stop programming without a monetary incentive?"
+
+ Actually, many people will program with absolutely no monetary
+incentive. Programming has an irresistible fascination for some
+people, usually the people who are best at it. There is no shortage of
+professional musicians who keep at it even though they have no hope of
+making a living that way.
+
+ But really this question, though commonly asked, is not appropriate
+to the situation. Pay for programmers will not disappear, only become
+less. So the right question is, will anyone program with a reduced
+monetary incentive? My experience shows that they will.
+
+ For more than ten years, many of the world's best programmers worked
+at the Artificial Intelligence Lab for far less money than they could
+have had anywhere else. They got many kinds of non-monetary rewards:
+fame and appreciation, for example. And creativity is also fun, a
+reward in itself.
+
+ Then most of them left when offered a chance to do the same
+interesting work for a lot of money.
+
+ What the facts show is that people will program for reasons other
+than riches; but if given a chance to make a lot of money as well, they
+will come to expect and demand it. Low-paying organizations do poorly
+in competition with high-paying ones, but they do not have to do badly
+if the high-paying ones are banned.
+
+ "We need the programmers desperately. If they demand that we stop
+ helping our neighbors, we have to obey."
+
+ You're never so desperate that you have to obey this sort of demand.
+Remember: millions for defense, but not a cent for tribute!
+
+ "Programmers need to make a living somehow."
+
+ In the short run, this is true. However, there are plenty of ways
+that programmers could make a living without selling the right to use a
+program. This way is customary now because it brings programmers and
+businessmen the most money, not because it is the only way to make a
+living. It is easy to find other ways if you want to find them. Here
+are a number of examples.
+
+ A manufacturer introducing a new computer will pay for the porting of
+operating systems onto the new hardware.
+
+ The sale of teaching, hand-holding, and maintenance services could
+also employ programmers.
+
+ People with new ideas could distribute programs as freeware and ask
+for donations from satisfied users or sell hand-holding services. I
+have met people who are already working this way successfully.
+
+ Users with related needs can form users' groups and pay dues. A
+group would contract with programming companies to write programs that
+the group's members would like to use.
+
+ All sorts of development can be funded with a Software Tax:
+
+ Suppose everyone who buys a computer has to pay a certain percent
+ of the price as a software tax. The government gives this to an
+ agency like the NSF to spend on software development.
+
+ But if the computer buyer makes a donation to software development
+ himself, he can take a credit against the tax. He can donate to
+ the project of his own choosing--often, chosen because he hopes to
+ use the results when
+
+ it is done. He can take a credit for any amount of donation up to
+ the total tax he had to pay.
+
+ The total tax rate could be decided by a vote of the payers of the
+ tax, weighted according to the amount they will be taxed on.
+
+ The consequences:
+
+ * The computer-using community supports software development.
+
+ * This community decides what level of support is needed.
+
+ * Users who care which projects their share is spent on can
+ choose this for themselves.
+
+ In the long run, making programs free is a step toward the
+post-scarcity world, where nobody will have to work very hard just to
+make a living. People will be free to devote themselves to activities
+that are fun, such as programming, after spending the necessary ten
+hours a week on required tasks such as legislation, family counseling,
+robot repair, and asteroid prospecting. There will be no need to be
+able to make a living from programming.
+
+ We have already greatly reduced the amount of work that the whole
+society must do for its actual productivity, but only a little of this
+has translated itself into leisure for workers because much
+nonproductive activity is required to accompany productive activity.
+The main causes of this are bureaucracy and isometric struggles against
+competition. Free software will greatly reduce these drains in the
+area of software production. We must do this, in order for technical
+gains in productivity to translate into less work for us.
+
+\1f
+File: xemacs.info, Node: Key Index, Next: Command Index, Prev: Manifesto, Up: Top
+
+Key (Character) Index
+*********************
+
+* Menu:
+
+* ! (query-replace): Query Replace.
+* " (TeX mode): TeX Editing.
+* , (query-replace): Query Replace.
+* . (Calendar mode): Specified Dates.
+* . (query-replace): Query Replace.
+* ? (Calendar mode): General Calendar.
+* ^ (query-replace): Query Replace.
+* a (Calendar mode): Holidays.
+* button1: Intro to Keystrokes.
+* button1up: Intro to Keystrokes.
+* button2: Intro to Keystrokes.
+* button2up: Intro to Keystrokes.
+* button3: Intro to Keystrokes.
+* button3up: Intro to Keystrokes.
+* C-<: Setting Mark.
+* C->: Setting Mark.
+* C-@ (Calendar mode): Mark and Region.
+* C-\: Select Input Method.
+* C-] <1>: Recursive Edit.
+* C-]: Quitting.
+* C-_: Undo.
+* C-a: Basic.
+* C-a (Calendar mode): Move to Beginning or End.
+* C-b: Basic.
+* C-b (Calendar mode): Calendar Unit Motion.
+* C-c: Key Sequences.
+* C-c ' (Picture mode): Insert in Picture.
+* C-c . (Picture mode): Insert in Picture.
+* C-c / (Picture mode): Insert in Picture.
+* C-c ; (Fortran mode): Fortran Comments.
+* C-c < (Picture mode): Insert in Picture.
+* C-c > (Picture mode): Insert in Picture.
+* C-c \ (Picture mode): Insert in Picture.
+* C-c ^ (Picture mode): Insert in Picture.
+* C-c ` (Picture mode): Insert in Picture.
+* C-c C-\ (Shell mode): Shell Mode.
+* C-c C-b (Outline mode): Outline Motion.
+* C-c C-b (Picture mode): Insert in Picture.
+* C-c C-b (TeX mode): TeX Print.
+* C-c C-c (Edit Abbrevs): Editing Abbrevs.
+* C-c C-c (Edit Tab Stops): Tab Stops.
+* C-c C-c (Mail mode): Mail Mode.
+* C-c C-c (Occur mode): Other Repeating Search.
+* C-c C-c (Shell mode): Shell Mode.
+* C-c C-d (Picture mode): Basic Picture.
+* C-c C-d (Shell mode): Shell Mode.
+* C-c C-f (LaTeX mode): TeX Editing.
+* C-c C-f (Outline mode): Outline Motion.
+* C-c C-f (Picture mode): Insert in Picture.
+* C-c C-f C-c (Mail mode): Mail Mode.
+* C-c C-f C-s (Mail mode): Mail Mode.
+* C-c C-f C-t (Mail mode): Mail Mode.
+* C-c C-h (Outline mode): Outline Visibility.
+* C-c C-i (Outline mode): Outline Visibility.
+* C-c C-j (Term mode): Term Mode.
+* C-c C-k (Picture mode): Rectangles in Picture.
+* C-c C-k (Term mode): Term Mode.
+* C-c C-k (TeX mode): TeX Print.
+* C-c C-l (Calendar mode): General Calendar.
+* C-c C-l (TeX mode): TeX Print.
+* C-c C-n (Fortran mode): Fortran Motion.
+* C-c C-n (Outline mode): Outline Motion.
+* C-c C-o (Shell mode): Shell Mode.
+* C-c C-p (Fortran mode): Fortran Motion.
+* C-c C-p (Outline mode): Outline Motion.
+* C-c C-p (TeX mode): TeX Print.
+* C-c C-q (Mail mode): Mail Mode.
+* C-c C-q (Term mode): Paging in Term.
+* C-c C-q (TeX mode): TeX Print.
+* C-c C-r (Fortran mode): Fortran Columns.
+* C-c C-r (Shell mode): Shell Mode.
+* C-c C-r (TeX mode): TeX Print.
+* C-c C-s (Mail mode): Mail Mode.
+* C-c C-s (Outline mode): Outline Visibility.
+* C-c C-u (Outline mode): Outline Motion.
+* C-c C-u (Shell mode): Shell Mode.
+* C-c C-w (Fortran mode): Fortran Columns.
+* C-c C-w (Mail mode): Mail Mode.
+* C-c C-w (Picture mode): Rectangles in Picture.
+* C-c C-w (Shell mode): Shell Mode.
+* C-c C-x (Picture mode): Rectangles in Picture.
+* C-c C-y (Mail mode): Mail Mode.
+* C-c C-y (Picture mode): Rectangles in Picture.
+* C-c C-y (Shell mode): Shell Mode.
+* C-c C-z (Shell mode): Shell Mode.
+* C-c TAB (Picture mode): Tabs in Picture.
+* C-c { (TeX mode): TeX Editing.
+* C-c } (TeX mode): TeX Editing.
+* C-d: Killing.
+* C-d (Shell mode): Shell Mode.
+* C-e: Basic.
+* C-e (Calendar mode): Move to Beginning or End.
+* C-END: Basic.
+* C-f: Basic.
+* C-f (Calendar mode): Calendar Unit Motion.
+* C-g <1>: Quitting.
+* C-g: Minibuffer.
+* C-g (isearch-mode): Incremental Search.
+* C-h: Key Sequences.
+* C-h a: Help.
+* C-h b: Help.
+* C-h C: Coding Systems.
+* C-h c: Help.
+* C-h C-\: Select Input Method.
+* C-h C-c: Help.
+* C-h C-d: Help.
+* C-h C-w: Help.
+* C-h f <1>: Help.
+* C-h f: Documentation.
+* C-h h: Mule Intro.
+* C-h I: Select Input Method.
+* C-h i: Help.
+* C-h k: Help.
+* C-h L: Language Environments.
+* C-h l: Help.
+* C-h m: Help.
+* C-h n: Help.
+* C-h s: Syntax Change.
+* C-h t <1>: Help.
+* C-h t: Basic.
+* C-h v <1>: Help.
+* C-h v <2>: Examining.
+* C-h v: Documentation.
+* C-h w: Help.
+* C-HOME: Basic.
+* C-k: Killing.
+* C-l <1>: Basic.
+* C-l: Scrolling.
+* C-l (query-replace): Query Replace.
+* C-LEFT: Basic.
+* C-M-@ <1>: Marking Objects.
+* C-M-@: Lists.
+* C-M-\ <1>: Indentation Commands.
+* C-M-\: Multi-line Indent.
+* C-M-a: Defuns.
+* C-M-a (Fortran mode): Fortran Motion.
+* C-M-b: Lists.
+* C-M-c: Recursive Edit.
+* C-M-d: Lists.
+* C-M-e: Defuns.
+* C-M-e (Fortran mode): Fortran Motion.
+* C-M-f: Lists.
+* C-M-h <1>: Marking Objects.
+* C-M-h: Defuns.
+* C-M-h (Fortran mode): Fortran Motion.
+* C-M-k <1>: Killing.
+* C-M-k: Lists.
+* C-M-n: Lists.
+* C-M-o: Indentation Commands.
+* C-M-p: Lists.
+* C-M-q: Multi-line Indent.
+* C-M-q (Fortran mode): ForIndent Commands.
+* C-M-t <1>: Transpose.
+* C-M-t: Lists.
+* C-M-u: Lists.
+* C-M-v <1>: Other Window.
+* C-M-v: Minibuffer Edit.
+* C-M-w: Appending Kills.
+* C-M-x <1>: External Lisp.
+* C-M-x: Lisp Eval.
+* C-n: Basic.
+* C-n (Calendar mode): Calendar Unit Motion.
+* C-o: Blank Lines.
+* C-p: Basic.
+* C-p (Calendar mode): Calendar Unit Motion.
+* C-q: Basic.
+* C-q (isearch-mode): Incremental Search.
+* C-r: Incremental Search.
+* C-r (isearch-mode): Incremental Search.
+* C-r (query-replace): Query Replace.
+* C-RIGHT: Basic.
+* C-s: Incremental Search.
+* C-s (isearch-mode): Incremental Search.
+* C-SPC: Setting Mark.
+* C-SPC (Calendar mode): Mark and Region.
+* C-t <1>: Transpose.
+* C-t: Basic.
+* C-u: Arguments.
+* C-u - C-x ;: Comments.
+* C-u C-@: Mark Ring.
+* C-u C-SPC: Mark Ring.
+* C-u C-x v v: Editing with VC.
+* C-u TAB: Multi-line Indent.
+* C-v <1>: Scrolling.
+* C-v: Basic.
+* C-v (Calendar mode): Scroll Calendar.
+* C-w: Killing.
+* C-w (isearch-mode): Incremental Search.
+* C-w (query-replace): Query Replace.
+* C-x: Key Sequences.
+* C-x $: Selective Display.
+* C-x (: Basic Kbd Macro.
+* C-x ): Basic Kbd Macro.
+* C-x .: Fill Prefix.
+* C-x 0: Change Window.
+* C-x 1: Change Window.
+* C-x 2: Split Window.
+* C-x 3: Split Window.
+* C-x 4: Pop Up Window.
+* C-x 4 .: Find Tag.
+* C-x 4 b: Select Buffer.
+* C-x 4 d: Dired Enter.
+* C-x 4 f: Visiting.
+* C-x 4 m: Sending Mail.
+* C-x 5 b: Select Buffer.
+* C-x 5 C-f: Visiting.
+* C-x ;: Comments.
+* C-x <: Horizontal Scrolling.
+* C-x < (Calendar mode): Scroll Calendar.
+* C-x =: Position Info.
+* C-x >: Horizontal Scrolling.
+* C-x > (Calendar mode): Scroll Calendar.
+* C-x [: Pages.
+* C-x [ (Calendar mode): Calendar Unit Motion.
+* C-x ]: Pages.
+* C-x ] (Calendar mode): Calendar Unit Motion.
+* C-x ^: Change Window.
+* C-x `: Compilation.
+* C-x a g: Defining Abbrevs.
+* C-x a i g: Defining Abbrevs.
+* C-x a i l: Defining Abbrevs.
+* C-x a l: Defining Abbrevs.
+* C-x b: Select Buffer.
+* C-x C-b: List Buffers.
+* C-x C-c: Exiting.
+* C-x C-d: ListDir.
+* C-x C-e: Lisp Eval.
+* C-x C-l: Case.
+* C-x C-o <1>: Killing.
+* C-x C-o: Blank Lines.
+* C-x C-p <1>: Marking Objects.
+* C-x C-p: Pages.
+* C-x C-q: Misc Buffer.
+* C-x C-q (version control): Editing with VC.
+* C-x C-s: Saving.
+* C-x C-t: Transpose.
+* C-x C-u: Case.
+* C-x C-v: Visiting.
+* C-x C-w: Saving.
+* C-x C-x: Setting Mark.
+* C-x C-x (Calendar mode): Mark and Region.
+* C-x d: Dired Enter.
+* C-x DEL <1>: Sentences.
+* C-x DEL <2>: Kill Errors.
+* C-x DEL: Killing.
+* C-x e: Basic Kbd Macro.
+* C-x ESC: Repetition.
+* C-x f: Fill Commands.
+* C-x h: Marking Objects.
+* C-x k: Kill Buffer.
+* C-x l: Pages.
+* C-x m: Sending Mail.
+* C-x n n: Narrowing.
+* C-x n w: Narrowing.
+* C-x o: Other Window.
+* C-x q: Kbd Macro Query.
+* C-x r g: RegText.
+* C-x r j: RegPos.
+* C-x r s: RegText.
+* C-x r SPC: RegPos.
+* C-x RET: Mule Intro.
+* C-x RET c: Specify Coding.
+* C-x RET C-\: Select Input Method.
+* C-x RET f: Specify Coding.
+* C-x RET k: Specify Coding.
+* C-x RET p: Specify Coding.
+* C-x RET t: Specify Coding.
+* C-x s: Saving.
+* C-x TAB: Indentation Commands.
+* C-x u: Undo.
+* C-x v =: Old Versions.
+* C-x v a: Change Logs and VC.
+* C-x v c: Editing with VC.
+* C-x v d: VC Status.
+* C-x v h: Version Headers.
+* C-x v i: Editing with VC.
+* C-x v l: VC Status.
+* C-x v r: Making Snapshots.
+* C-x v s: Making Snapshots.
+* C-x v u: Editing with VC.
+* C-x v ~: Old Versions.
+* C-x }: Change Window.
+* C-y: Kill Ring.
+* C-y (isearch-mode): Incremental Search.
+* C-z: Exiting.
+* control key: Intro to Keystrokes.
+* d (Calendar mode): Diary Commands.
+* DEL <1>: Basic.
+* DEL <2>: Killing.
+* DEL <3>: Kill Errors.
+* DEL <4>: Program Modes.
+* DEL: Major Modes.
+* DEL (isearch-mode): Incremental Search.
+* DEL (query-replace): Query Replace.
+* DOWN: Basic.
+* END: Basic.
+* ESC <1>: Key Sequences.
+* ESC: Meta Key.
+* ESC (query-replace): Query Replace.
+* g CHAR (Calendar mode): From Other Calendar.
+* g d (Calendar mode): Specified Dates.
+* g m l (Calendar mode): Mayan Calendar.
+* h (Calendar mode): Holidays.
+* HOME: Basic.
+* hyper key <1>: Intro to Keystrokes.
+* hyper key <2>: Representing Keystrokes.
+* hyper key: Super and Hyper Keys.
+* i a (Calendar mode): Special Diary Entries.
+* i b (Calendar mode): Special Diary Entries.
+* i c (Calendar mode): Special Diary Entries.
+* i d (Calendar mode): Adding to Diary.
+* i m (Calendar mode): Adding to Diary.
+* i w (Calendar mode): Adding to Diary.
+* i y (Calendar mode): Adding to Diary.
+* LEFT: Basic.
+* LFD <1>: Basic Indent.
+* LFD <2>: String Key Sequences.
+* LFD: Major Modes.
+* LFD (TeX mode): TeX Editing.
+* M (Calendar mode): Lunar Phases.
+* m (Calendar mode): Diary Commands.
+* M-!: Single Shell.
+* M-$: Spelling.
+* M-%: Query Replace.
+* M-': Expanding Abbrevs.
+* M-(: Balanced Editing.
+* M-): Balanced Editing.
+* M-,: Tags Search.
+* M--: Arguments.
+* M-- M-c: Fixing Case.
+* M-- M-l: Fixing Case.
+* M-- M-u: Fixing Case.
+* M-.: Find Tag.
+* M-/: Dynamic Abbrevs.
+* M-1: Arguments.
+* M-;: Comments.
+* M-<: Basic.
+* M-< (Calendar mode): Move to Beginning or End.
+* M-=: Position Info.
+* M-= (Calendar mode): Mark and Region.
+* M->: Basic.
+* M-> (Calendar mode): Move to Beginning or End.
+* M-?: Nroff Mode.
+* M-@ <1>: Words.
+* M-@: Marking Objects.
+* M-[: Paragraphs.
+* M-\ <1>: Indentation Commands.
+* M-\: Killing.
+* M-]: Paragraphs.
+* M-^ <1>: Killing.
+* M-^: Indentation Commands.
+* M-a: Sentences.
+* M-a (Calendar mode): Move to Beginning or End.
+* M-b: Words.
+* M-c: Case.
+* M-C-s: Regexp Search.
+* M-d <1>: Words.
+* M-d: Killing.
+* M-DEL <1>: Killing.
+* M-DEL <2>: Kill Errors.
+* M-DEL: Words.
+* M-e: Sentences.
+* M-e (Calendar mode): Move to Beginning or End.
+* M-ESC: Lisp Eval.
+* M-f: Words.
+* M-g: Fill Commands.
+* M-h <1>: Paragraphs.
+* M-h: Marking Objects.
+* M-i: Tab Stops.
+* M-k <1>: Killing.
+* M-k: Sentences.
+* M-l: Case.
+* M-LFD: Comments.
+* M-LFD (Fortran mode): ForIndent Commands.
+* M-m: Indentation Commands.
+* M-n <1>: Nroff Mode.
+* M-n: Repetition.
+* M-n (isearch-mode): Incremental Search.
+* M-n (Shell mode): Shell Mode.
+* M-p <1>: Repetition.
+* M-p: Nroff Mode.
+* M-p (isearch-mode): Incremental Search.
+* M-p (Shell mode): Shell Mode.
+* M-q: Fill Commands.
+* M-r: Basic.
+* M-s: Fill Commands.
+* M-SPC: Killing.
+* M-t <1>: Transpose.
+* M-t: Words.
+* M-TAB <1>: Tabs in Picture.
+* M-TAB: Lisp Completion.
+* M-TAB (customization buffer): Changing an Option.
+* M-TAB (isearch-mode): Incremental Search.
+* M-u: Case.
+* M-v <1>: Basic.
+* M-v: Scrolling.
+* M-v (Calendar mode): Scroll Calendar.
+* M-w: Kill Ring.
+* M-x: M-x.
+* M-y: Earlier Kills.
+* M-z: Killing.
+* M-{ (Calendar mode): Calendar Unit Motion.
+* M-|: Single Shell.
+* M-} (Calendar mode): Calendar Unit Motion.
+* M-~: Saving.
+* META: Meta Key.
+* meta key: Intro to Keystrokes.
+* next: Scrolling.
+* o (Calendar mode): Specified Dates.
+* p (Calendar mode): To Other Calendar.
+* p d (Calendar mode): General Calendar.
+* PGDN: Basic.
+* pgdn: Scrolling.
+* PGUP: Basic.
+* pgup: Scrolling.
+* prior: Scrolling.
+* q (Calendar mode): General Calendar.
+* RET: Basic.
+* RET (isearch-mode): Incremental Search.
+* RET (Shell mode): Shell Mode.
+* RIGHT: Basic.
+* s (Calendar mode): Diary Commands.
+* S (Calendar mode): Sunrise/Sunset.
+* S-TAB (customization buffer): Changing an Option.
+* shift key: Intro to Keystrokes.
+* SPC: Completion.
+* SPC (Calendar mode): General Calendar.
+* SPC (query-replace): Query Replace.
+* super key <1>: Intro to Keystrokes.
+* super key <2>: Super and Hyper Keys.
+* super key: Representing Keystrokes.
+* t (Calendar mode): LaTeX Calendar.
+* TAB <1>: String Key Sequences.
+* TAB <2>: Major Modes.
+* TAB <3>: Basic Indent.
+* TAB <4>: Text Mode.
+* TAB <5>: Completion.
+* TAB: Indentation.
+* TAB (customization buffer): Changing an Option.
+* TAB (Shell mode): Shell Mode.
+* u (Calendar mode) <1>: Diary Commands.
+* u (Calendar mode): Holidays.
+* UP: Basic.
+* x (Calendar mode): Holidays.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Mode Line, Next: XEmacs under X, Prev: Echo Area, Up: Frame
+
+The Mode Line
+=============
+
+ Each text window's last line is a "mode line" which describes what is
+going on in that window. When there is only one text window, the mode
+line appears right above the echo area. The mode line is in inverse
+video if the terminal supports that, starts and ends with dashes, and
+contains text like `XEmacs: SOMETHING'.
+
+ If a mode line has something else in place of `XEmacs: SOMETHING',
+the window above it is in a special subsystem such as Dired. The mode
+line then indicates the status of the subsystem.
+
+ Normally, the mode line has the following appearance:
+
+ --CH-XEmacs: BUF (MAJOR MINOR)----POS------
+
+This gives information about the buffer being displayed in the window:
+the buffer's name, what major and minor modes are in use, whether the
+buffer's text has been changed, and how far down the buffer you are
+currently looking.
+
+ CH contains two stars (`**') if the text in the buffer has been
+edited (the buffer is "modified"), or two dashes (`--') if the buffer
+has not been edited. Exception: for a read-only buffer, it is `%%'.
+
+ BUF is the name of the window's chosen "buffer". The chosen buffer
+in the selected window (the window that the cursor is in) is also
+XEmacs's selected buffer, the buffer in which editing takes place. When
+we speak of what some command does to "the buffer", we mean the
+currently selected buffer. *Note Buffers::.
+
+ POS tells you whether there is additional text above the top of the
+screen or below the bottom. If your file is small and it is completely
+visible on the screen, POS is `All'. Otherwise, POS is `Top' if you
+are looking at the beginning of the file, `Bot' if you are looking at
+the end of the file, or `NN%', where NN is the percentage of the file
+above the top of the screen.
+
+ MAJOR is the name of the "major mode" in effect in the buffer. At
+any time, each buffer is in one and only one major mode. The available
+major modes include Fundamental mode (the least specialized), Text
+mode, Lisp mode, and C mode. *Note Major Modes::, for details on how
+the modes differ and how you select one.
+
+ MINOR is a list of some of the "minor modes" that are turned on in
+the window's chosen buffer. For example, `Fill' means that Auto Fill
+mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means
+that Overwrite mode is on. *Note Minor Modes::, for more information.
+`Narrow' means that the buffer being displayed has editing restricted
+to only a portion of its text. This is not really a minor mode, but is
+like one. *Note Narrowing::. `Def' means that a keyboard macro is
+being defined. *Note Keyboard Macros::.
+
+ Some buffers display additional information after the minor modes.
+For example, Rmail buffers display the current message number and the
+total number of messages. Compilation buffers and Shell mode display
+the status of the subprocess.
+
+ If XEmacs is currently inside a recursive editing level, square
+brackets (`[...]') appear around the parentheses that surround the
+modes. If XEmacs is in one recursive editing level within another,
+double square brackets appear, and so on. Since information on
+recursive editing applies to XEmacs in general and not to any one
+buffer, the square brackets appear in every mode line on the screen or
+not in any of them. *Note Recursive Edit::.
+
+ XEmacs can optionally display the time and system load in all mode
+lines. To enable this feature, type `M-x display-time'. The
+information added to the mode line usually appears after the file name,
+before the mode names and their parentheses. It looks like this:
+
+ HH:MMpm L.LL [D]
+
+(Some fields may be missing if your operating system cannot support
+them.) HH and MM are the hour and minute, followed always by `am' or
+`pm'. L.LL is the average number of running processes in the whole
+system recently. D is an approximate index of the ratio of disk
+activity to CPU activity for all users.
+
+ The word `Mail' appears after the load level if there is mail for
+you that you have not read yet.
+
+ Customization note: the variable `mode-line-inverse-video' controls
+whether the mode line is displayed in inverse video (assuming the
+terminal supports it); `nil' means no inverse video. The default is
+`t'. For X frames, simply set the foreground and background colors
+appropriately.
+
+\1f
+File: xemacs.info, Node: XEmacs under X, Prev: Mode Line, Up: Frame
+
+Using XEmacs Under the X Window System
+======================================
+
+ XEmacs can be used with the X Window System and a window manager like
+MWM or TWM. In that case, the X window manager opens, closes, and
+resizes XEmacs frames. You use the window manager's mouse gestures to
+perform the operations. Consult your window manager guide or reference
+manual for information on manipulating X windows.
+
+ When you are working under X, each X window (that is, each XEmacs
+frame) has a menu bar for mouse-controlled operations (*note Pull-down
+Menus::.).
+
+ XEmacs under X is also a multi-frame XEmacs. You can use the New
+Frame menu item from the File menu to create a new XEmacs frame in a
+new X window from the same process. The different frames will share the
+same buffer list, but you can look at different buffers in the different
+frames.
+
+ The function `find-file-other-frame' is just like `find-file', but
+creates a new frame to display the buffer in first. This is normally
+bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
+does.
+
+ The function `switch-to-buffer-other-frame' is just like
+`switch-to-buffer', but creates a new frame to display the buffer in
+first. This is normally bound to `C-x 5 b'.
+
+ You can specify a different default frame size other than the one
+provided. Use the variable `default-frame-alist', which is an alist of
+default values for frame creation other than the first one. These may
+be set in your init file, like this:
+
+ (setq default-frame-alist '((width . 80) (height . 55)))
+
+ For values specific to the first XEmacs frame, you must use X
+resources. The variable `x-frame-defaults' takes an alist of default
+frame creation parameters for X window frames. These override what is
+specified in `~/.Xdefaults' but are overridden by the arguments to the
+particular call to `x-create-frame'.
+
+ When you create a new frame, the variable `create-frame-hook' is
+called with one argument, the frame just created.
+
+ If you want to close one or more of the X windows you created using
+New Frame, use the Delete Frame menu item from the File menu.
+
+ If you are working with multiple frames, some special information
+applies:
+ * Two variables, `frame-title-format' and `frame-icon-title-format'
+ determine the title of the frame and the title of the icon that
+ results if you shrink the frame.
+
+ * The variables `auto-lower-frame' and `auto-raise-frame' position a
+ frame. If true, `auto-lower-frame' lowers a frame to the bottom
+ when it is no longer selected. If true, `auto-raise-frame' raises
+ a frame to the top when it is selected. Under X, most
+ ICCCM-compliant window managers will have options to do this for
+ you, but these variables are provided in case you are using a
+ broken window manager.
+
+ * There is a new frame/modeline format directive, %S, which expands
+ to the name of the current frame (a frame's name is distinct from
+ its title; the name is used for resource lookup, among other
+ things, and the title is simply what appears above the window.)
+
+\1f
+File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
+
+Keystrokes, Key Sequences, and Key Bindings
+*******************************************
+
+* Menu:
+
+* Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
+* Representing Keystrokes:: Using lists of modifiers and keysyms to
+ represent keystrokes.
+* Key Sequences:: Combine key strokes into key sequences you can
+ bind to commands.
+* String Key Sequences:: Available for upward compatibility.
+* Meta Key:: Using <ESC> to represent <Meta>
+* Super and Hyper Keys:: Adding modifier keys on certain keyboards.
+* Character Representation:: How characters appear in Emacs buffers.
+* Commands:: How commands are bound to key sequences.
+
+\1f
+File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
+
+Keystrokes as Building Blocks of Key Sequences
+==============================================
+
+ Earlier versions of Emacs used only the ASCII character set, which
+defines 128 different character codes. Some of these codes are
+assigned graphic symbols like `a' and `='; the rest are control
+characters, such as `Control-a' (also called `C-a'). `C-a' means you
+hold down the <CTRL> key and then press `a'.
+
+ Keybindings in XEmacs are not restricted to the set of keystrokes
+that can be represented in ASCII. XEmacs can tell the difference
+between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
+
+ A keystroke is like a piano chord: you get it by simultaneously
+striking several keys. To be more precise, a keystroke consists of a
+possibly empty set of modifiers followed by a single "keysym". The set
+of modifiers is small; it consists of `Control', `Meta', `Super',
+`Hyper', and `Shift'.
+
+ The rest of the keys on your keyboard, along with the mouse buttons,
+make up the set of keysyms. A keysym is usually what is printed on the
+keys on your keyboard. Here is a table of some of the symbolic names
+for keysyms:
+`a,b,c...'
+ alphabetic keys
+
+`f1,f2...'
+ function keys
+
+`button1'
+ left mouse button
+
+`button2'
+ middle mouse button
+
+`button3'
+ right mouse button
+
+`button1up'
+ upstroke on the left mouse button
+
+`button2up'
+ upstroke on the middle mouse button
+
+`button3up'
+ upstroke on the right mouse button
+
+`return'
+ Return key
+
+ Use the variable `keyboard-translate-table' only if you are on a
+dumb tty, as it cannot handle input that cannot be represented as ASCII.
+The value of this variable is a string used as a translate table for
+keyboard input or `nil'. Each character is looked up in this string
+and the contents used instead. If the string is of length `n',
+character codes `N' and up are untranslated. If you are running Emacs
+under X, you should do the translations with the `xmodmap' program
+instead.
+
+\1f
+File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
+
+Representing Keystrokes
+-----------------------
+
+ XEmacs represents keystrokes as lists. Each list consists of an
+arbitrary combination of modifiers followed by a single keysym at the
+end of the list. If the keysym corresponds to an ASCII character, you
+can use its character code. (A keystroke may also be represented by an
+event object, as returned by the `read-key-sequence' function;
+non-programmers need not worry about this.)
+
+ The following table gives some examples of how to list
+representations for keystrokes. Each list consists of sets of
+modifiers followed by keysyms:
+
+`(control a)'
+ Pressing <CTRL> and `a' simultaneously.
+
+`(control ?a)'
+ Another way of writing the keystroke `C-a'.
+
+`(control 65)'
+ Yet another way of writing the keystroke `C-a'.
+
+`(break)'
+ Pressing the <BREAK> key.
+
+`(control meta button2up)'
+ Release the middle mouse button, while pressing <CTRL> and <META>.
+ Note: As you define keystrokes, you can use the `shift' key only as a
+modifier with characters that do not have a second keysym on the same
+key, such as `backspace' and `tab'. It is an error to define a
+keystroke using the <shift> modifier with keysyms such as `a' and `='.
+The correct forms are `A' and `+'.
+
+\1f
+File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
+
+Representing Key Sequences
+--------------------------
+
+ A "complete key sequence" is a sequence of keystrokes that Emacs
+understands as a unit. Key sequences are significant because you can
+bind them to commands. Note that not all sequences of keystrokes are
+possible key sequences. In particular, the initial keystrokes in a key
+sequence must make up a "prefix key sequence".
+
+ Emacs represents a key sequence as a vector of keystrokes. Thus, the
+schematic representation of a complete key sequence is as follows:
+
+ [(modifier .. modifer keysym) ... (modifier .. modifier keysym)]
+
+ Here are some examples of complete key sequences:
+
+`[(control c) (control a)]'
+ Typing `C-c' followed by `C-a'
+
+`[(control c) (control 65)]'
+ Typing `C-c' followed by `C-a'. (Using the ASCII code for the
+ character `a')
+
+`[(control c) (break)]'
+ Typing `C-c' followed by the `break' character.
+
+ A "prefix key sequence" is the beginning of a series of longer
+sequences that are valid key sequences; adding any single keystroke to
+the end of a prefix results in a valid key sequence. For example,
+`control-x' is standardly defined as a prefix. Thus there is a
+two-character key sequence starting with `C-x' for each valid
+keystroke, giving numerous possibilities. Here are some samples:
+
+ * `[(control x) (c)]'
+
+ * `[(control x) (control c)]'
+
+ Adding one character to a prefix key does not have to form a complete
+key. It could make another, longer prefix. For example, `[(control x)
+(\4)]' is itself a prefix that leads to any number of different
+three-character keys, including `[(control x) (\4) (f)]', `[(control x)
+(\4) (b)]' and so on. It would be possible to define one of those
+three-character sequences as a prefix, creating a series of
+four-character keys, but we did not define any of them this way.
+
+ By contrast, the two-character sequence `[(control f) (control k)]'
+is not a key, because the `(control f)' is a complete key sequence in
+itself. You cannot give `[(control f (control k)]' an independent
+meaning as a command while `(control f)' is a complete sequence,
+because Emacs would understand <C-f C-k> as two commands.
+
+ The predefined prefix key sequences in Emacs are `(control c)',
+`(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
+can customize Emacs and could make new prefix keys or eliminate the
+default key sequences. *Note Key Bindings::. For example, if you
+redefine `(control f)' as a prefix, `[(control f) (control k)]'
+automatically becomes a valid key sequence (complete, unless you define
+it as a prefix as well). Conversely, if you remove the prefix
+definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
+`[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
+
+ Note that the above paragraphs uses \4 instead of simply 4, because
+\4 is the symbol whose name is "4", and plain 4 is the integer 4, which
+would have been interpreted as the ASCII value. Another way of
+representing the symbol whose name is "4" is to write ?4, which would be
+interpreted as the number 52, which is the ASCII code for the character
+"4". We could therefore actually have written 52 directly, but that is
+far less clear.
+
+\1f
+File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
+
+String Key Sequences
+--------------------
+
+ For backward compatibility, you may also represent a key sequence
+using strings. For example, we have the following equivalent
+representations:
+
+`"\C-c\C-c"'
+ `[(control c) (control c)]'
+
+`"\e\C-c"'
+ `[(meta control c)]'
+
+\1f
+File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
+
+Assignment of the <META> Key
+----------------------------
+
+ Not all terminals have the complete set of modifiers. Terminals
+that have a <Meta> key allow you to type Meta characters by just
+holding that key down. To type `Meta-a', hold down <META> and press
+`a'. On those terminals, the <META> key works like the <SHIFT> key.
+Such a key is not always labeled <META>, however, as this function is
+often a special option for a key with some other primary purpose.
+
+ If there is no <META> key, you can still type Meta characters using
+two-character sequences starting with <ESC>. To enter `M-a', you could
+type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
+allowed on terminals with Meta keys, too, in case you have formed a
+habit of using it.
+
+ If you are running under X and do not have a <META> key, it is
+possible to reconfigure some other key to be a <META> key. *Note Super
+and Hyper Keys::.
+
+ Emacs believes the terminal has a <META> key if the variable
+`meta-flag' is non-`nil'. Normally this is set automatically according
+to the termcap entry for your terminal type. However, sometimes the
+termcap entry is wrong, and then it is useful to set this variable
+yourself. *Note Variables::, for how to do this.
+
+ Note: If you are running under the X window system, the setting of
+the `meta-flag' variable is irrelevant.
+
+\1f
+File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
+
+Assignment of the <SUPER> and <HYPER> Keys
+------------------------------------------
+
+ Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
+keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
+to bind keys to sequences using `super' and `hyper'. You can use the
+`xmodmap' program to do this.
+
+ For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
+following:
+
+ Create a file called `~/.xmodmap'. In this file, place the lines
+
+ remove Lock = Caps_Lock
+ keysym Caps_Lock = Super_L
+ add Mod2 = Super_L
+
+ The first line says that the key that is currently called `Caps_Lock'
+should no longer behave as a "lock" key. The second line says that
+this should now be called `Super_L' instead. The third line says that
+the key called `Super_L' should be a modifier key, which produces the
+`Mod2' modifier.
+
+ To create a <META> or <HYPER> key instead of a <SUPER> key, replace
+the word `Super' above with `Meta' or `Hyper'.
+
+ Just after you start up X, execute the command `xmodmap /.xmodmap'.
+You can add this command to the appropriate initialization file to have
+the command executed automatically.
+
+ If you have problems, see the documentation for the `xmodmap'
+program. The X keyboard model is quite complicated, and explaining it
+is beyond the scope of this manual. However, we reprint the following
+description from the X Protocol document for your convenience:
+
+ A list of keysyms is associated with each keycode. If that list
+(ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
+list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
+the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
+`K1 K2', then the list is treated as if it were the list ```K1 K2 K1
+K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
+of keysyms `K1 K2 K3', then the list is treated as if it were the list
+```K1 K2 K3 NoSymbol'''.
+
+ The first four elements of the list are split into two groups of
+keysyms. Group 1 contains the first and second keysyms; Group 2 contains
+third and fourth keysyms. Within each group, if the second element of
+the group is NoSymbol, then the group should be treated as if the second
+element were the same as the first element, except when the first
+element is an alphabetic keysym `K' for which both lowercase and
+uppercase forms are defined. In that case, the group should be treated
+as if the first element were the lowercase form of `K' and the second
+element were the uppercase form of `K'.
+
+ The standard rules for obtaining a keysym from a KeyPress event make
+use of only the Group 1 and Group 2 keysyms; no interpretation of other
+keysyms in the list is given here. (That is, the last four keysyms are
+unused.)
+
+ Which group to use is determined by modifier state. Switching between
+groups is controlled by the keysym named `Mode_switch'. Attach that
+keysym to some keycode and attach that keycode to any one of the
+modifiers Mod1 through Mod5. This modifier is called the "group
+modifier". For any keycode, Group 1 is used when the group modifier is
+off, and Group 2 is used when the group modifier is on.
+
+ Within a group, which keysym to use is also determined by modifier
+state. The first keysym is used when the `Shift' and `Lock' modifiers
+are off. The second keysym is used when the `Shift' modifier is on, or
+when the `Lock' modifier is on and the second keysym is uppercase
+alphabetic, or when the `Lock' modifier is on and is interpreted as
+`ShiftLock'. Otherwise, when the `Lock' modifier is on and is
+interpreted as `CapsLock', the state of the `Shift' modifier is applied
+first to select a keysym, but if that keysym is lower-case alphabetic,
+then the corresponding upper-case keysym is used instead.
+
+ In addition to the above information on keysyms, we also provide the
+following description of modifier mapping from the InterClient
+Communications Conventions Manual:
+
+ X11 supports 8 modifier bits, of which 3 are pre-assigned to
+`Shift', `Lock', and `Control'. Each modifier bit is controlled by the
+state of a set of keys, and these sets are specified in a table
+accessed by `GetModifierMapping()' and `SetModifierMapping()'.
+
+ A client needing to use one of the pre-assigned modifiers should
+assume that the modifier table has been set up correctly to control
+these modifiers. The `Lock' modifier should be interpreted as `Caps
+Lock' or `Shift Lock' according to whether the keycodes in its
+controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
+
+ Clients should determine the meaning of a modifier bit from the
+keysyms being used to control it.
+
+ A client needing to use an extra modifier, for example `Meta',
+should:
+
+ 1. Scan the existing modifier mappings.
+
+ 1. If it finds a modifier that contains a keycode whose set of
+ keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
+ that modifier bit.
+
+ 2. If there is no existing modifier controlled by `XK_Meta_L' or
+ `XK_Meta_R', it should select an unused modifier bit (one with
+ an empty controlling set) and:
+
+ 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
+ that keycode to the set for the chosen modifier, and then:
+
+ 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
+ add that keycode to the set for the chosen modifier, and then:
+
+ 2. If the controlling set is still empty, interact with the user
+ to select one or more keys to be `Meta'.
+
+ 3. If there are no unused modifier bits, ask the user to take
+ corrective action.
+
+ This means that the `Mod1' modifier does not necessarily mean
+`Meta', although some applications (such as twm and emacs 18) assume
+that. Any of the five unassigned modifier bits could mean `Meta'; what
+matters is that a modifier bit is generated by a keycode which is bound
+to the keysym `Meta_L' or `Meta_R'.
+
+ Therefore, if you want to make a <META> key, the right way is to
+make the keycode in question generate both a `Meta' keysym and some
+previously-unassigned modifier bit.
+
+\1f
+File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
+
+Representation of Characters
+============================
+
+ This section briefly discusses how characters are represented in
+Emacs buffers. *Note Key Sequences::, for information on representing
+key sequences to create key bindings.
+
+ ASCII graphic characters in Emacs buffers are displayed with their
+graphics. <LFD> is the same as a newline character; it is displayed by
+starting a new line. <TAB> is displayed by moving to the next tab stop
+column (usually every 8 spaces). Other control characters are
+displayed as a caret (`^') followed by the non-control version of the
+character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
+and up are displayed with octal escape sequences; thus, character code
+243 (octal), also called `M-#' when used as an input character, is
+displayed as `\243'.
+
+ The variable `ctl-arrow' may be used to alter this behavior. *Note
+Display Vars::.
+
+\1f
+File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
+
+Keys and Commands
+=================
+
+ This manual is full of passages that tell you what particular keys
+do. But Emacs does not assign meanings to keys directly. Instead,
+Emacs assigns meanings to "functions", and then gives keys their
+meanings by "binding" them to functions.
+
+ A function is a Lisp object that can be executed as a program.
+Usually it is a Lisp symbol that has been given a function definition;
+every symbol has a name, usually made of a few English words separated
+by dashes, such as `next-line' or `forward-word'. It also has a
+"definition", which is a Lisp program. Only some functions can be the
+bindings of keys; these are functions whose definitions use
+`interactive' to specify how to call them interactively. Such
+functions are called "commands", and their names are "command names".
+More information on this subject will appear in the XEmacs Lisp
+Reference Manual.
+
+ The bindings between keys and functions are recorded in various
+tables called "keymaps". *Note Key Bindings::, for more information on
+key sequences you can bind commands to. *Note Keymaps::, for
+information on creating keymaps.
+
+ When we say "`C-n' moves down vertically one line" we are glossing
+over a distinction that is irrelevant in ordinary use but is vital in
+understanding how to customize Emacs. The function `next-line' is
+programmed to move down vertically. `C-n' has this effect because it
+is bound to that function. If you rebind `C-n' to the function
+`forward-word' then `C-n' will move forward by words instead.
+Rebinding keys is a common method of customization.
+
+ The rest of this manual usually ignores this subtlety to keep things
+simple. To give the customizer the information needed, we often state
+the name of the command that really does the work in parentheses after
+mentioning the key that runs it. For example, we will say that "The
+command `C-n' (`next-line') moves point vertically down," meaning that
+`next-line' is a command that moves vertically down and `C-n' is a key
+that is standardly bound to it.
+
+ While we are on the subject of information for customization only,
+it's a good time to tell you about "variables". Often the description
+of a command will say, "To change this, set the variable `mumble-foo'."
+A variable is a name used to remember a value. Most of the variables
+documented in this manual exist just to facilitate customization: some
+command or other part of Emacs uses the variable and behaves
+differently depending on its setting. Until you are interested in
+customizing, you can ignore the information about variables. When you
+are ready to be interested, read the basic information on variables, and
+then the information on individual variables will make sense. *Note
+Variables::.
+
+\1f
+File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
+
+XEmacs Pull-down Menus
+======================
+
+ If you are running XEmacs under X, a menu bar on top of the Emacs
+frame provides access to pull-down menus of file, edit, and
+help-related commands. The menus provide convenient shortcuts and an
+easy interface for novice users. They do not provide additions to the
+functionality available via key commands; you can still invoke commands
+from the keyboard as in previous versions of Emacs.
+
+File
+ Perform file and buffer-related operations, such as opening and
+ closing files, saving and printing buffers, as well as exiting
+ Emacs.
+
+Edit
+ Perform standard editing operations, such as cutting, copying,
+ pasting, and killing selected text.
+
+Apps
+ Access to sub-applications implemented within XEmacs, such as the
+ mail reader, the World Wide Web browser, the spell-checker, and
+ the calendar program.
+
+Options
+ Control various options regarding the way XEmacs works, such as
+ controlling which elements of the frame are visible, selecting the
+ fonts to be used for text, specifying whether searches are
+ case-sensitive, etc.
+
+Buffers
+ Present a menu of buffers for selection as well as the option to
+ display a buffer list.
+
+Tools
+ Perform various actions designed to automate software development
+ and similar technical work, such as searching through many files,
+ compiling a program, and comparing or merging two or three files.
+
+Help
+ Access to Emacs Info.
+
+ There are two ways of selecting an item from a pull-down menu:
+
+ * Select an item in the menu bar by moving the cursor over it and
+ click the left mouse-button. Then move the cursor over the menu
+ item you want to choose and click left again.
+
+ * Select an item in the menu bar by moving the cursor over it and
+ click and hold the left mouse-button. With the mouse-button
+ depressed, move the cursor over the menu item you want, then
+ release it to make your selection.
+
+ If a command in the pull-down menu is not applicable in a given
+situation, the command is disabled and its name appears faded. You
+cannot invoke items that are faded. For example, many commands on the
+Edit menu appear faded until you select text on which they are to
+operate; after you select a block of text, edit commands are enabled.
+*Note Mouse Selection::, for information on using the mouse to select
+text. *Note Using X Selections::, for related information.
+
+ There are also `M-x' equivalents for each menu item. To find the
+equivalent for any left-button menu item, do the following:
+
+ 1. Type `C-h k' to get the `Describe Key' prompt.
+
+ 2. Select the menu item and click.
+
+ Emacs displays the function associated with the menu item in a
+separate window, usually together with some documentation.
+
+* Menu:
+
+* File Menu:: Items on the File menu.
+* Edit Menu:: Items on the Edit menu.
+* Apps Menu:: Items on the Apps menu.
+* Options Menu:: Items on the Options menu.
+* Buffers Menu:: Information about the Buffers menu.
+* Tools Menu:: Items on the Tools menu.
+* Help Menu:: Items on the Help menu.
+* Menu Customization:: Adding and removing menu items and related
+ operations.
+
+\1f
+File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
+
+The File Menu
+-------------
+
+ The File menu bar item contains the items New Frame, Open File...,
+Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
+Frame, Kill Buffer and Exit Emacs on the pull-down menu. If you select
+a menu item, Emacs executes the equivalent command.
+
+Open File, New Frame...
+ Prompts you for a filename and loads that file into a new buffer
+ in a new Emacs frame, that is, a new X window running under the
+ same Emacs process. You can remove the frame using the Delete
+ Frame menu item. When you remove the last frame, you exit Emacs
+ and are prompted for confirmation.
+
+Open File...
+ Prompts you for a filename and loads that file into a new buffer.
+ Open File... is equivalent to the Emacs command `find-file' (`C-x
+ C-f').
+
+Insert File...
+ Prompts you for a filename and inserts the contents of that file
+ into the current buffer. The file associated with the current
+ buffer is not changed by this command. This is equivalent to the
+ Emacs command `insert-file' (`C-x i').
+
+Save Buffer
+ Writes and saves the current Emacs buffer as the latest version of
+ the current visited file. Save Buffer is equivalent to the Emacs
+ command `save-buffer' (`C-x C-s').
+
+Save Buffer As...
+ Writes and saves the current Emacs buffer to the filename you
+ specify. Save Buffer As... is equivalent to the Emacs command
+ `write-file' (`C-x C-w').
+
+Revert Buffer
+ Restores the last saved version of the file to the current buffer.
+ When you edit a buffer containing a text file, you must save the
+ buffer before your changes become effective. Use Revert Buffer if
+ you do not want to keep the changes you have made in the buffer.
+ Revert Buffer is equivalent to the Emacs command `revert-file'
+ (`M-x revert-buffer').
+
+Kill Buffer
+ Kills the current buffer, prompting you first if there are unsaved
+ changes. This is roughly equivalent to the Emacs command
+ `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
+ name of a buffer to kill.
+
+Print Buffer
+ Prints a hardcopy of the current buffer. Equivalent to the Emacs
+ command `print-buffer' (`M-x print-buffer').
+
+New Frame
+ Creates a new Emacs frame displaying the `*scratch*' buffer. This
+ is like the Open File, New Frame... menu item, except that it does
+ not prompt for or load a file.
+
+Delete Frame
+ Allows you to close all but one of the frames created by New Frame.
+ If you created several Emacs frames belonging to the same Emacs
+ process, you can close all but one of them. When you attempt to
+ close the last frame, Emacs informs you that you are attempting to
+ delete the last frame. You have to choose Exit Emacs for that.
+
+Split Frame
+ Divides the current window on the current frame into two
+ equal-sized windows, both displaying the same buffer. Equivalent
+ to the Emacs command `split-window-vertically' (`C-x 2').
+
+Un-split (Keep This)
+ If the frame is divided into multiple windows, this removes all
+ windows other than the selected one. Equivalent to the Emacs
+ command `delete-other-windows' (`C-x 1').
+
+Un-split (Keep Others)
+ If the frame is divided into multiple windows, this removes the
+ selected window from the frame, giving the space back to one of the
+ other windows. Equivalent to the Emacs command `delete-window'
+ (`C-x 0').
+
+Exit Emacs
+ Shuts down (kills) the Emacs process. Equivalent to the Emacs
+ command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
+ Emacs process, the system asks which unsaved buffers to save by
+ going through the list of all buffers in that Emacs process.
+
+\1f
+File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
+
+The Edit Menu
+-------------
+
+ The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
+Clear menu items. When you select a menu item, Emacs executes the
+equivalent command. Most commands on the Edit menu work on a block of
+text, the X selection. They appear faded until you select a block of
+text (activate a region) with the mouse. *Note Using X Selections::,
+*note Killing::., and *note Yanking::. for more information.
+
+Undo
+ Undoes the previous command. Undo is equivalent to the Emacs
+ command `undo' (`C-x u').
+
+Cut
+ Removes the selected text block from the current buffer, makes it
+ the X clipboard selection, and places it in the kill ring. Before
+ executing this command, you have to select a region using Emacs
+ region selection commands or with the mouse.
+
+Copy
+ Makes a selected text block the X clipboard selection, and places
+ it in the kill ring. You can select text using one of the Emacs
+ region selection commands or by selecting a text region with the
+ mouse.
+
+Paste
+ Inserts the current value of the X clipboard selection in the
+ current buffer. Note that this is not necessarily the same as the
+ Emacs `yank' command, because the Emacs kill ring and the X
+ clipboard selection are not the same thing. You can paste in text
+ you have placed in the clipboard using Copy or Cut. You can also
+ use Paste to insert text that was pasted into the clipboard from
+ other applications.
+
+Clear
+ Removes the selected text block from the current buffer but does
+ not place it in the kill ring or the X clipboard selection.
+
+Start Macro Recording
+ After selecting this, Emacs will remember every keystroke you type
+ until End Macro Recording is selected. This is the same as the
+ Emacs command `start-kbd-macro' (`C-x (').
+
+End Macro Recording
+ Selecting this tells emacs to stop remembering your keystrokes.
+ This is the same as the Emacs command `end-kbd-macro' (`C-x )').
+
+Execute Last Macro
+ Selecting this item will cause emacs to re-interpret all of the
+ keystrokes which were saved between selections of the Start Macro
+ Recording and End Macro Recording menu items. This is the same as
+ the Emacs command `call-last-kbd-macro' (`C-x e').
+
+\1f
+File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
+
+The Apps Menu
+-------------
+
+ The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
+(MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
+Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
+When you select a menu item, Emacs executes the equivalent command.
+For some of the menu items, there are sub-menus which you will need to
+select.
+
+\1f
+File: xemacs.info, Node: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
+
+The Options Menu
+----------------
+
+ The Options pull-down menu contains the Read Only, Case Sensitive
+Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
+Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
+Menu Length..., Buffers Sub-Menus and Save Options menu items. When
+you select a menu item, Emacs executes the equivalent command. For
+some of the menu items, there are sub-menus which you will need to
+select.
+
+Read Only
+ Selecting this item will cause the buffer to visit the file in a
+ read-only mode. Changes to the file will not be allowed. This is
+ equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
+
+Case Sensitive Search
+ Selecting this item will cause searches to be case-sensitive. If
+ its not selected then searches will ignore case. This option is
+ local to the buffer.
+
+Overstrike
+ After selecting this item, when you type letters they will replace
+ existing text on a one-to-one basis, rather than pushing it to the
+ right. At the end of a line, such characters extend the line.
+ Before a tab, such characters insert until the tab is filled in.
+ This is the same as Emacs command `quoted-insert' (`C-q').
+
+Auto Delete Selection
+ Selecting this item will cause automatic deletion of the selected
+ region. The typed text will replace the selection if the selection
+ is active (i.e. if its highlighted). If the option is not selected
+ then the typed text is just inserted at the point.
+
+Teach Extended Commands
+ After you select this item, any time you execute a command with
+ `M-x'which has a shorter keybinding, you will be shown the
+ alternate binding before the command executes.
+
+Syntax Highlighting
+ You can customize your `.emacs' file to include the font-lock mode
+ so that when you select this item, the comments will be displayed
+ in one face, strings in another, reserved words in another, and so
+ on. When Fonts is selected, different parts of the program will
+ appear in different Fonts. When Colors is selected, then the
+ program will be displayed in different colors. Selecting None
+ causes the program to appear in just one Font and Color. Selecting
+ Less resets the Fonts and Colors to a fast, minimal set of
+ decorations. Selecting More resets the Fonts and Colors to a larger
+ set of decorations. For example, if Less is selected (which is the
+ default setting) then you might have all comments in green color.
+ Whereas, if More is selected then a function name in the comments
+ themselves might appear in a different Color or Font.
+
+Paren Highlighting
+ After selecting Blink from this item, if you place the cursor on a
+ parenthesis, the matching parenthesis will blink. If you select
+ Highlight and place the cursor on a parenthesis, the whole
+ expression of the parenthesis under the cursor will be highlighted.
+ Selecting None will turn off the options (regarding Paren
+ Highlighting) which you had selected earlier.
+
+Font
+ You can select any Font for your program by choosing from one of
+ the available Fonts.
+
+Size
+ You can select any size ranging from 2 to 24 by selecting the
+ appropriate option.
+
+Weight
+ You can choose either Bold or Medium for the weight.
+
+Buffers Menu Length...
+ Prompts you for the number of buffers to display. Then it will
+ display that number of most recently selected buffers.
+
+Buffers Sub-Menus
+ After selection of this item the Buffers menu will contain several
+ commands, as submenus of each buffer line. If this item is
+ unselected, then there are no submenus for each buffer line, the
+ only command available will be selecting that buffer.
+
+Save Options
+ Selecting this item will save the current settings of your Options
+ menu to your `.emacs' file.
+
+\1f
+File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
+
+The Buffers Menu
+----------------
+
+ The Buffers menu provides a selection of up to ten buffers and the
+item List All Buffers, which provides a Buffer List. *Note List
+Buffers::, for more information.
+
+\1f
+File: xemacs.info, Node: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
+
+The Tools Menu
+--------------
+
+ The Tools pull-down menu contains the Grep..., Compile..., Shell
+Command..., Shell Command on Region..., Debug(GDB)... and
+Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
+sub-menus. When you select a menu item, Emacs executes the equivalent
+command. For some of the menu items, there are sub-menus which you
+will need to select.
+
+\1f
+File: xemacs.info, Node: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
+
+The Help Menu
+-------------
+
+ The Help Menu gives you access to Emacs Info and provides a menu
+equivalent for each of the choices you have when using `C-h'. *Note
+Help::, for more information.
+
+ The Help menu also gives access to UNIX online manual pages via the
+UNIX Manual Page option.
+
+\1f
+File: xemacs.info, Node: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
+
+Customizing XEmacs Menus
+------------------------
+
+ You can customize any of the pull-down menus by adding or removing
+menu items and disabling or enabling existing menu items.
+
+ The following functions are available:
+`add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &OPTIONAL BEFORE)'
+ Add a menu to the menu bar or one of its submenus.
+
+`add-menu-item: (MENU-PATH ITEM-NAME FUNCTION ENABLED-P
+ &optional before)' Add a menu item to a menu, creating the menu
+ first if necessary.
+
+`delete-menu-item: (PATH)'
+ Remove the menu item defined by PATH from the menu hierarchy.
+
+`disable-menu-item: (PATH)'
+ Disable the specified menu item.
+
+`enable-menu-item: (PATH)'
+ Enable the specified previously disabled menu item.
+
+`relabel-menu-item: (PATH NEW-NAME)'
+ Change the string of the menu item specified by PATH to NEW-NAME.
+
+ Use the function `add-menu' to add a new menu or submenu. If a menu
+or submenu of the given name exists already, it is changed.
+
+ MENU-PATH identifies the menu under which the new menu should be
+inserted. It is a list of strings; for example, `("File")' names the
+top-level File menu. `("File" "Foo")' names a hypothetical submenu of
+File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
+
+ MENU-NAME is the string naming the menu to be added.
+
+ MENU-ITEMS is a list of menu item descriptions. Each menu item
+should be a vector of three elements:
+
+ * A string, which is the name of the menu item
+
+ * A symbol naming a command, or a form to evaluate
+
+ * `t' or `nil' to indicate whether the item is selectable
+
+ The optional argument BEFORE is the name of the menu before which
+the new menu or submenu should be added. If the menu is already
+present, it is not moved.
+
+ The function `add-menu-item' adds a menu item to the specified menu,
+creating the menu first if necessary. If the named item already
+exists, the menu remains unchanged.
+
+ MENU-PATH identifies the menu into which the new menu item should be
+inserted. It is a list of strings; for example, `("File")' names the
+top-level File menu. `("File" "Foo")' names a hypothetical submenu of
+File.
+
+ ITEM-NAME is the string naming the menu item to add.
+
+ FUNCTION is the command to invoke when this menu item is selected.
+If it is a symbol, it is invoked with `call-interactively', in the same
+way that functions bound to keys are invoked. If it is a list, the
+list is simply evaluated.
+
+ ENABLED-P controls whether the item is selectable or not. It should
+be `t', `nil', or a form to evaluate to decide. This form will be
+evaluated just before the menu is displayed, and the menu item will be
+selectable if that form returns non-`nil'.
+
+ For example, to make the `rename-file' command available from the
+File menu, use the following code:
+
+ (add-menu-item '("File") "Rename File" 'rename-file t)
+
+ To add a submenu of file management commands using a File Management
+item, use the following code:
+
+ (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
+ (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
+ (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
+
+ The optional BEFORE argument is the name of a menu item before which
+the new item should be added. If the item is already present, it is
+not moved.
+
+ To remove a specified menu item from the menu hierarchy, use
+`delete-menu-item'.
+
+ PATH is a list of strings that identify the position of the menu
+item in the menu hierarchy. `("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.
+
+ To disable a menu item, use `disable-menu-item'. The disabled menu
+item is grayed and can no longer be selected. To make the item
+selectable again, use `enable-menu-item'. `disable-menu-item' and
+`enable-menu-item' both have the argument PATH.
+
+ To change the string of the specified menu item, use
+`relabel-menu-item'. This function also takes the argument PATH.
+
+ NEW-NAME is the string to which the menu item will be changed.
+
+\1f
+File: xemacs.info, Node: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
+
+Entering and Exiting Emacs
+**************************
+
+ The usual way to invoke Emacs is to type `emacs <RET>' at the shell
+(for XEmacs, type `xemacs <RET>'). Emacs clears the screen and then
+displays an initial advisory message and copyright notice. You can
+begin typing Emacs commands immediately afterward.
+
+ Some operating systems insist on discarding all type-ahead when Emacs
+starts up; they give Emacs no way to prevent this. Therefore, it is
+wise to wait until Emacs clears the screen before typing the first
+editing command.
+
+ Before Emacs reads the first command, you have not had a chance to
+give a command to specify a file to edit. Since Emacs must always have
+a current buffer for editing, it presents a buffer, by default, a
+buffer named `*scratch*'. The buffer is in Lisp Interaction mode; you
+can use it to type Lisp expressions and evaluate them, or you can
+ignore that capability and simply doodle. You can specify a different
+major mode for this buffer by setting the variable `initial-major-mode'
+in your init file. *Note Init File::.
+
+ It is possible to give Emacs arguments in the shell command line to
+specify files to visit, Lisp files to load, and functions to call.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Command Index, Next: Variable Index, Prev: Key Index, Up: Top
+
+Command and Function Index
+**************************
+
+* Menu:
+
+* abbrev-mode <1>: Abbrevs.
+* abbrev-mode: Minor Modes.
+* abbrev-prefix-mark: Expanding Abbrevs.
+* abort-recursive-edit <1>: Recursive Edit.
+* abort-recursive-edit: Quitting.
+* add-change-log-entry: Change Log.
+* add-global-abbrev: Defining Abbrevs.
+* add-menu: Menu Customization.
+* add-menu-item: Menu Customization.
+* add-mode-abbrev: Defining Abbrevs.
+* add-name-to-file: Misc File Ops.
+* american-calendar: Date Formats.
+* append-next-kill: Appending Kills.
+* append-to-buffer: Accumulating Text.
+* append-to-file <1>: Misc File Ops.
+* append-to-file: Accumulating Text.
+* apropos: Help.
+* ask-user-about-lock: Interlocking.
+* auto-fill-mode <1>: Minor Modes.
+* auto-fill-mode: Auto Fill.
+* auto-save-mode: Auto Save Control.
+* back-to-indentation: Indentation Commands.
+* backward-char: Basic.
+* backward-delete-char-untabify: Program Modes.
+* backward-kill-sentence <1>: Kill Errors.
+* backward-kill-sentence <2>: Sentences.
+* backward-kill-sentence: Killing.
+* backward-kill-word <1>: Kill Errors.
+* backward-kill-word <2>: Words.
+* backward-kill-word: Killing.
+* backward-list: Lists.
+* backward-page: Pages.
+* backward-paragraph: Paragraphs.
+* backward-sentence: Sentences.
+* backward-sexp: Lists.
+* backward-text-line: Nroff Mode.
+* backward-up-list: Lists.
+* backward-word: Words.
+* batch-byte-compile: Compiling Libraries.
+* beginning-of-buffer: Basic.
+* beginning-of-defun: Defuns.
+* beginning-of-fortran-subprogram: Fortran Motion.
+* beginning-of-line: Basic.
+* buffer-menu: Several Buffers.
+* byte-compile-and-load-file: Compiling Libraries.
+* byte-compile-buffer: Compiling Libraries.
+* byte-compile-file: Compiling Libraries.
+* byte-recompile-directory: Compiling Libraries.
+* c-indent-line: Basic Indent.
+* calendar: Calendar/Diary.
+* calendar-backward-day: Calendar Unit Motion.
+* calendar-backward-month: Calendar Unit Motion.
+* calendar-backward-week: Calendar Unit Motion.
+* calendar-beginning-of-month: Move to Beginning or End.
+* calendar-beginning-of-week: Move to Beginning or End.
+* calendar-beginning-of-year: Move to Beginning or End.
+* calendar-count-days-region: Mark and Region.
+* calendar-cursor-holidays: Holidays.
+* calendar-end-of-month: Move to Beginning or End.
+* calendar-end-of-week: Move to Beginning or End.
+* calendar-end-of-year: Move to Beginning or End.
+* calendar-exchange-point-and-mark: Mark and Region.
+* calendar-forward-day: Calendar Unit Motion.
+* calendar-forward-month: Calendar Unit Motion.
+* calendar-forward-week: Calendar Unit Motion.
+* calendar-forward-year: Calendar Unit Motion.
+* calendar-goto-astro-day-number: From Other Calendar.
+* calendar-goto-chinese-date: From Other Calendar.
+* calendar-goto-coptic-date: From Other Calendar.
+* calendar-goto-date: Specified Dates.
+* calendar-goto-ethiopic-date: From Other Calendar.
+* calendar-goto-french-date: From Other Calendar.
+* calendar-goto-hebrew-date: From Other Calendar.
+* calendar-goto-islamic-date: From Other Calendar.
+* calendar-goto-iso-date: From Other Calendar.
+* calendar-goto-julian-date: From Other Calendar.
+* calendar-goto-mayan-long-count-date: Mayan Calendar.
+* calendar-goto-persian-date: From Other Calendar.
+* calendar-goto-today: Specified Dates.
+* calendar-mark-today: Calendar Customizing.
+* calendar-next-calendar-round-date: Mayan Calendar.
+* calendar-next-haab-date: Mayan Calendar.
+* calendar-next-tzolkin-date: Mayan Calendar.
+* calendar-other-month: Specified Dates.
+* calendar-phases-of-moon: Lunar Phases.
+* calendar-previous-haab-date: Mayan Calendar.
+* calendar-previous-tzolkin-date: Mayan Calendar.
+* calendar-print-astro-day-number: To Other Calendar.
+* calendar-print-chinese-date: To Other Calendar.
+* calendar-print-coptic-date: To Other Calendar.
+* calendar-print-day-of-year: General Calendar.
+* calendar-print-ethiopic-date: To Other Calendar.
+* calendar-print-french-date: To Other Calendar.
+* calendar-print-hebrew-date: To Other Calendar.
+* calendar-print-islamic-date: To Other Calendar.
+* calendar-print-iso-date: To Other Calendar.
+* calendar-print-julian-date: To Other Calendar.
+* calendar-print-mayan-date: To Other Calendar.
+* calendar-print-persian-date: To Other Calendar.
+* calendar-set-mark: Mark and Region.
+* calendar-star-date: Calendar Customizing.
+* calendar-sunrise-sunset: Sunrise/Sunset.
+* calendar-unmark <1>: Diary Commands.
+* calendar-unmark: Holidays.
+* call-last-kbd-macro: Basic Kbd Macro.
+* cancel-debug-on-entry: Lisp Debug.
+* capitalize-word <1>: Fixing Case.
+* capitalize-word: Case.
+* center-line: Fill Commands.
+* clear-rectangle: Rectangles.
+* comint-delchar-or-maybe-eof: Shell Mode.
+* comint-dynamic-complete: Shell Mode.
+* comint-next-input: Shell Mode.
+* comint-previous-input: Shell Mode.
+* command-apropos: Help.
+* compare-windows <1>: Other Window.
+* compare-windows: Comparing Files.
+* compile: Compilation.
+* compile-defun: Defuns.
+* convert-mocklisp-buffer: Mocklisp.
+* conx: CONX.
+* conx-buffer: CONX.
+* conx-init: CONX.
+* conx-load: CONX.
+* conx-region: CONX.
+* conx-save: CONX.
+* copy-file: Misc File Ops.
+* copy-last-shell-input: Shell Mode.
+* copy-region-as-kill: Kill Ring.
+* copy-region-to-rectangle: RegRect.
+* copy-to-buffer: Accumulating Text.
+* copy-to-register: RegText.
+* count-lines-page: Pages.
+* count-lines-region: Position Info.
+* count-matches: Other Repeating Search.
+* count-text-lines: Nroff Mode.
+* customize: Easy Customization.
+* customize-apropos: Specific Customization.
+* customize-browse: Customization Groups.
+* customize-customized: Specific Customization.
+* customize-face: Specific Customization.
+* customize-group: Specific Customization.
+* customize-option: Specific Customization.
+* customize-saved: Specific Customization.
+* dabbrev-expand: Dynamic Abbrevs.
+* debug: Lisp Debug.
+* debug-on-entry: Lisp Debug.
+* default-value: Locals.
+* define-abbrevs: Saving Abbrevs.
+* define-key <1>: Programmatic Rebinding.
+* define-key: Interactive Rebinding.
+* delete-backward-char <1>: Basic.
+* delete-backward-char <2>: Killing.
+* delete-backward-char: Kill Errors.
+* delete-blank-lines <1>: Killing.
+* delete-blank-lines: Blank Lines.
+* delete-char <1>: Basic Picture.
+* delete-char: Killing.
+* delete-file: Misc File Ops.
+* delete-horizontal-space <1>: Indentation Commands.
+* delete-horizontal-space: Killing.
+* delete-indentation <1>: Indentation Commands.
+* delete-indentation: Killing.
+* delete-matching-lines: Other Repeating Search.
+* delete-menu-item: Menu Customization.
+* delete-non-matching-lines: Other Repeating Search.
+* delete-other-windows: Change Window.
+* delete-rectangle: Rectangles.
+* delete-window: Change Window.
+* describe-bindings: Help.
+* describe-calendar-mode: General Calendar.
+* describe-coding-system: Coding Systems.
+* describe-copying: Help.
+* describe-distribution: Help.
+* describe-function <1>: Help.
+* describe-function: Documentation.
+* describe-input-method: Select Input Method.
+* describe-key: Help.
+* describe-key-briefly: Help.
+* describe-language-environment: Language Environments.
+* describe-mode: Help.
+* describe-no-warranty: Help.
+* describe-syntax: Syntax Change.
+* describe-variable <1>: Documentation.
+* describe-variable <2>: Examining.
+* describe-variable: Help.
+* diary: Diary Commands.
+* diary-anniversary <1>: Special Diary Entries.
+* diary-anniversary: Sexp Diary Entries.
+* diary-astro-day-number: Sexp Diary Entries.
+* diary-block: Special Diary Entries.
+* diary-cyclic <1>: Special Diary Entries.
+* diary-cyclic: Sexp Diary Entries.
+* diary-day-of-year: Sexp Diary Entries.
+* diary-float: Special Diary Entries.
+* diary-french-date: Sexp Diary Entries.
+* diary-hebrew-date: Sexp Diary Entries.
+* diary-islamic-date: Sexp Diary Entries.
+* diary-iso-date: Sexp Diary Entries.
+* diary-julian-date: Sexp Diary Entries.
+* diary-mail-entries: Diary Commands.
+* diary-mayan-date: Sexp Diary Entries.
+* diary-omer: Sexp Diary Entries.
+* diary-parasha: Sexp Diary Entries.
+* diary-phases-of-moon: Sexp Diary Entries.
+* diary-rosh-hodesh: Sexp Diary Entries.
+* diary-sabbath-candles: Sexp Diary Entries.
+* diary-sunrise-sunset: Sexp Diary Entries.
+* diary-yahrzeit: Sexp Diary Entries.
+* diff: Comparing Files.
+* diff-backup: Comparing Files.
+* digit-argument: Arguments.
+* dired: Dired Enter.
+* dired-other-window <1>: Pop Up Window.
+* dired-other-window: Dired Enter.
+* disable-command: Disabling.
+* disable-menu-item: Menu Customization.
+* disassemble: Compiling Libraries.
+* display-time: Mode Line.
+* dissociated-press: Dissociated Press.
+* do-auto-save: Auto Save Control.
+* doctor: Total Frustration.
+* down-list: Lists.
+* downcase-region: Case.
+* downcase-word <1>: Case.
+* downcase-word: Fixing Case.
+* edit-abbrevs: Editing Abbrevs.
+* edit-abbrevs-redefine: Editing Abbrevs.
+* edit-options: Edit Options.
+* edit-picture: Picture.
+* edit-tab-stops <1>: Text Mode.
+* edit-tab-stops: Tab Stops.
+* edit-tab-stops-note-changes: Tab Stops.
+* edt-emulation-off: Emulation.
+* edt-emulation-on: Emulation.
+* electric-nroff-mode: Nroff Mode.
+* emacs-lisp-mode: Lisp Eval.
+* emacs-version: Bugs.
+* enable-command: Disabling.
+* enable-menu-item: Menu Customization.
+* end-kbd-macro: Basic Kbd Macro.
+* end-of-buffer: Basic.
+* end-of-defun: Defuns.
+* end-of-fortran-subprogram: Fortran Motion.
+* end-of-line: Basic.
+* enlarge-window: Change Window.
+* enlarge-window-horizontally: Change Window.
+* european-calendar: Date Formats.
+* eval-current-buffer: Lisp Eval.
+* eval-defun: Lisp Eval.
+* eval-expression: Lisp Eval.
+* eval-last-sexp: Lisp Eval.
+* eval-region: Lisp Eval.
+* exchange-point-and-mark: Setting Mark.
+* execute-extended-command: M-x.
+* exit-calendar: General Calendar.
+* exit-recursive-edit: Recursive Edit.
+* expand-abbrev: Expanding Abbrevs.
+* expand-region-abbrevs: Expanding Abbrevs.
+* fancy-diary-display: Fancy Diary Display.
+* fill-individual-paragraphs: Fill Prefix.
+* fill-paragraph: Fill Commands.
+* fill-region: Fill Commands.
+* fill-region-as-paragraph: Fill Commands.
+* find-alternate-file: Visiting.
+* find-file: Visiting.
+* find-file-other-frame <1>: XEmacs under X.
+* find-file-other-frame: Visiting.
+* find-file-other-window <1>: Pop Up Window.
+* find-file-other-window: Visiting.
+* find-tag: Find Tag.
+* find-tag-other-window <1>: Find Tag.
+* find-tag-other-window: Pop Up Window.
+* find-this-file: Visiting.
+* find-this-file-other-window: Visiting.
+* fortran-column-ruler: Fortran Columns.
+* fortran-comment-region: Fortran Comments.
+* fortran-indent-line: ForIndent Commands.
+* fortran-indent-subprogram: ForIndent Commands.
+* fortran-mode: Fortran.
+* fortran-next-statement: Fortran Motion.
+* fortran-previous-statement: Fortran Motion.
+* fortran-split-line: ForIndent Commands.
+* fortran-window-create: Fortran Columns.
+* forward-char: Basic.
+* forward-list: Lists.
+* forward-page: Pages.
+* forward-paragraph: Paragraphs.
+* forward-sentence: Sentences.
+* forward-sexp: Lists.
+* forward-text-line: Nroff Mode.
+* forward-word: Words.
+* global-set-key <1>: Interactive Rebinding.
+* global-set-key: Programmatic Rebinding.
+* goto-char: Basic.
+* goto-line: Basic.
+* hanoi: Amusements.
+* help-with-tutorial <1>: Help.
+* help-with-tutorial: Basic.
+* hide-body: Outline Visibility.
+* hide-entry: Outline Visibility.
+* hide-leaves: Outline Visibility.
+* hide-subtree: Outline Visibility.
+* holidays: Holidays.
+* include-other-diary-files: Included Diary Files.
+* indent-c-exp: Multi-line Indent.
+* indent-for-comment: Comments.
+* indent-new-comment-line: Comments.
+* indent-region <1>: Multi-line Indent.
+* indent-region: Indentation Commands.
+* indent-relative: Indentation Commands.
+* indent-rigidly: Indentation Commands.
+* indent-sexp: Multi-line Indent.
+* indented-text-mode: Text Mode.
+* info: Help.
+* insert-abbrevs: Saving Abbrevs.
+* insert-anniversary-diary-entry: Special Diary Entries.
+* insert-block-diary-entry: Special Diary Entries.
+* insert-cyclic-diary-entry: Special Diary Entries.
+* insert-diary-entry: Adding to Diary.
+* insert-file: Misc File Ops.
+* insert-hebrew-diary-entry: Hebrew/Islamic Entries.
+* insert-islamic-diary-entry: Hebrew/Islamic Entries.
+* insert-kbd-macro: Save Kbd Macro.
+* insert-monthly-diary-entry: Adding to Diary.
+* insert-monthly-hebrew-diary-entry: Hebrew/Islamic Entries.
+* insert-monthly-islamic-diary-entry: Hebrew/Islamic Entries.
+* insert-parentheses: Balanced Editing.
+* insert-register: RegText.
+* insert-weekly-diary-entry: Adding to Diary.
+* insert-yearly-diary-entry: Adding to Diary.
+* insert-yearly-hebrew-diary-entry: Hebrew/Islamic Entries.
+* insert-yearly-islamic-diary-entry: Hebrew/Islamic Entries.
+* interactive: M-x.
+* interrupt-shell-subjob: Shell Mode.
+* inverse-add-global-abbrev: Defining Abbrevs.
+* inverse-add-mode-abbrev: Defining Abbrevs.
+* invert-face: Faces.
+* isearch-abort: Incremental Search.
+* isearch-backward: Incremental Search.
+* isearch-backward-regexp: Regexp Search.
+* isearch-complete: Incremental Search.
+* isearch-delete-char: Incremental Search.
+* isearch-exit: Incremental Search.
+* isearch-forward: Incremental Search.
+* isearch-forward-regexp: Regexp Search.
+* isearch-quote-char: Incremental Search.
+* isearch-repeat-backward: Incremental Search.
+* isearch-repeat-forward: Incremental Search.
+* isearch-ring-advance: Incremental Search.
+* isearch-ring-retreat: Incremental Search.
+* isearch-yank-line: Incremental Search.
+* isearch-yank-word: Incremental Search.
+* jump-to-register: Split Window.
+* just-one-space: Killing.
+* kbd-macro-query: Kbd Macro Query.
+* kill-all-abbrevs: Defining Abbrevs.
+* kill-buffer: Kill Buffer.
+* kill-comment: Comments.
+* kill-compilation: Compilation.
+* kill-line: Killing.
+* kill-local-variable: Locals.
+* kill-output-from-shell: Shell Mode.
+* kill-rectangle: Rectangles.
+* kill-region: Killing.
+* kill-sentence <1>: Killing.
+* kill-sentence: Sentences.
+* kill-sexp <1>: Lists.
+* kill-sexp: Killing.
+* kill-some-buffers: Kill Buffer.
+* kill-word <1>: Words.
+* kill-word: Killing.
+* latex-mode: TeX Mode.
+* LaTeX-mode: TeX Mode.
+* lisp-complete-symbol: Lisp Completion.
+* lisp-indent-line: Basic Indent.
+* lisp-interaction-mode: Lisp Interaction.
+* lisp-mode: External Lisp.
+* lisp-send-defun: External Lisp.
+* list-abbrevs: Editing Abbrevs.
+* list-buffers: List Buffers.
+* list-calendar-holidays: Holidays.
+* list-coding-systems: Coding Systems.
+* list-command-history: Repetition.
+* list-directory: ListDir.
+* list-hebrew-diary-entries: Hebrew/Islamic Entries.
+* list-holidays: Holidays.
+* list-input-methods: Select Input Method.
+* list-islamic-diary-entries: Hebrew/Islamic Entries.
+* list-matching-lines: Other Repeating Search.
+* list-options: Edit Options.
+* list-tags: List Tags.
+* list-yahrzeit-dates: From Other Calendar.
+* load: Loading.
+* load-default-sounds: Audible Bell.
+* load-file: Loading.
+* load-library <1>: Startup Paths.
+* load-library: Loading.
+* load-sound-file: Audible Bell.
+* local-set-key: Interactive Rebinding.
+* local-unset-key: Interactive Rebinding.
+* locate-library: Loading.
+* lpr-buffer: Hardcopy.
+* lpr-region: Hardcopy.
+* mail: Sending Mail.
+* mail-cc: Mail Mode.
+* mail-fill-yanked-message: Mail Mode.
+* mail-interactive-insert-alias: Mail Headers.
+* mail-other-window <1>: Pop Up Window.
+* mail-other-window: Sending Mail.
+* mail-send: Mail Mode.
+* mail-send-and-exit: Mail Mode.
+* mail-signature: Mail Mode.
+* mail-subject: Mail Mode.
+* mail-to: Mail Mode.
+* mail-yank-original: Mail Mode.
+* make-directory: File Names.
+* make-face-bold: Faces.
+* make-face-bold-italic: Faces.
+* make-face-italic: Faces.
+* make-face-larger: Faces.
+* make-face-smaller: Faces.
+* make-face-unbold: Faces.
+* make-face-unitalic: Faces.
+* make-frame: XEmacs under X.
+* make-local-variable: Locals.
+* make-obsolete: Compiling Libraries.
+* make-symbolic-link: Misc File Ops.
+* make-variable-buffer-local: Locals.
+* manual-entry: Documentation.
+* mark-beginning-of-buffer: Setting Mark.
+* mark-calendar-holidays: Holidays.
+* mark-defun <1>: Defuns.
+* mark-defun: Marking Objects.
+* mark-diary-entries: Diary Commands.
+* mark-end-of-buffer: Setting Mark.
+* mark-fortran-subprogram: Fortran Motion.
+* mark-hebrew-diary-entries: Hebrew/Islamic Entries.
+* mark-included-diary-files: Included Diary Files.
+* mark-islamic-diary-entries: Hebrew/Islamic Entries.
+* mark-page <1>: Pages.
+* mark-page: Marking Objects.
+* mark-paragraph <1>: Paragraphs.
+* mark-paragraph: Marking Objects.
+* mark-sexp <1>: Marking Objects.
+* mark-sexp: Lists.
+* mark-whole-buffer: Marking Objects.
+* mark-word <1>: Words.
+* mark-word: Marking Objects.
+* minibuffer-complete: Completion.
+* minibuffer-complete-word: Completion.
+* modify-syntax-entry: Syntax Change.
+* mouse-del-char: Additional Mouse Operations.
+* mouse-delete-window: Additional Mouse Operations.
+* mouse-keep-one-window: Additional Mouse Operations.
+* mouse-kill-line: Additional Mouse Operations.
+* mouse-line-length: Additional Mouse Operations.
+* mouse-scroll: Additional Mouse Operations.
+* mouse-select: Additional Mouse Operations.
+* mouse-select-and-split: Additional Mouse Operations.
+* mouse-set-mark: Additional Mouse Operations.
+* mouse-set-point: Additional Mouse Operations.
+* mouse-track: Additional Mouse Operations.
+* mouse-track-adjust: Additional Mouse Operations.
+* mouse-track-and-copy-to-cutbuffer: Additional Mouse Operations.
+* mouse-track-delete-and-insert: Additional Mouse Operations.
+* move-over-close-and-reindent: Balanced Editing.
+* move-to-window-line: Basic.
+* name-last-kbd-macro: Save Kbd Macro.
+* narrow-to-region: Narrowing.
+* negative-argument: Arguments.
+* newline: Basic.
+* newline-and-indent: Basic Indent.
+* next-complex-command: Repetition.
+* next-error: Compilation.
+* next-line: Basic.
+* not-modified: Saving.
+* nroff-mode: Nroff Mode.
+* occur: Other Repeating Search.
+* open-dribble-file: Bugs.
+* open-line: Blank Lines.
+* open-rectangle: Rectangles.
+* open-termscript: Bugs.
+* other-window: Other Window.
+* other-window-any-frame: Other Window.
+* outline-backward-same-level: Outline Motion.
+* outline-forward-same-level: Outline Motion.
+* outline-next-visible-heading: Outline Motion.
+* outline-previous-visible-heading: Outline Motion.
+* outline-up-heading: Outline Motion.
+* overwrite-mode: Minor Modes.
+* phases-of-moon: Lunar Phases.
+* picture-backward-clear-column: Basic Picture.
+* picture-backward-column: Basic Picture.
+* picture-clear-column: Basic Picture.
+* picture-clear-line: Basic Picture.
+* picture-clear-rectangle: Rectangles in Picture.
+* picture-clear-rectangle-to-register: Rectangles in Picture.
+* picture-forward-column: Basic Picture.
+* picture-motion: Insert in Picture.
+* picture-motion-reverse: Insert in Picture.
+* picture-move-down: Basic Picture.
+* picture-move-up: Basic Picture.
+* picture-movement-down: Insert in Picture.
+* picture-movement-left: Insert in Picture.
+* picture-movement-ne: Insert in Picture.
+* picture-movement-nw: Insert in Picture.
+* picture-movement-right: Insert in Picture.
+* picture-movement-se: Insert in Picture.
+* picture-movement-sw: Insert in Picture.
+* picture-movement-up: Insert in Picture.
+* picture-newline: Basic Picture.
+* picture-open-line: Basic Picture.
+* picture-set-tab-stops: Tabs in Picture.
+* picture-tab: Tabs in Picture.
+* picture-tab-search: Tabs in Picture.
+* picture-yank-rectangle: Rectangles in Picture.
+* picture-yank-rectangle-from-register: Rectangles in Picture.
+* plain-tex-mode: TeX Mode.
+* plain-TeX-mode: TeX Mode.
+* play-sound: Audible Bell.
+* point-to-register: RegPos.
+* prefer-coding-system: Recognize Coding.
+* prepend-to-buffer: Accumulating Text.
+* previous-complex-command: Repetition.
+* previous-line: Basic.
+* print-buffer: Hardcopy.
+* print-diary-entries <1>: Diary Customizing.
+* print-diary-entries: Diary Commands.
+* print-region: Hardcopy.
+* quail-set-keyboard-layout: Select Input Method.
+* query-replace: Query Replace.
+* query-replace-regexp: Query Replace.
+* quietly-read-abbrev-file: Saving Abbrevs.
+* quit-shell-subjob: Shell Mode.
+* quoted-insert: Basic.
+* re-search-backward: Regexp Search.
+* re-search-forward: Regexp Search.
+* read-abbrev-file: Saving Abbrevs.
+* read-key-sequence: Representing Keystrokes.
+* recenter <1>: Scrolling.
+* recenter: Basic.
+* recover-file: Recover.
+* redraw-calendar: General Calendar.
+* register-to-point: RegPos.
+* relabel-menu-item: Menu Customization.
+* remove-directory: File Names.
+* rename-buffer: Misc Buffer.
+* rename-file: Misc File Ops.
+* repeat-complex-command: Repetition.
+* replace-regexp: Unconditional Replace.
+* replace-string: Unconditional Replace.
+* revert-buffer: Reverting.
+* run-lisp: External Lisp.
+* save-buffer: Saving.
+* save-buffers-kill-emacs: Exiting.
+* save-some-buffers: Saving.
+* scroll-calendar-left: Scroll Calendar.
+* scroll-calendar-left-three-months: Scroll Calendar.
+* scroll-calendar-right: Scroll Calendar.
+* scroll-calendar-right-three-months: Scroll Calendar.
+* scroll-down: Scrolling.
+* scroll-left: Horizontal Scrolling.
+* scroll-other-window <1>: Other Window.
+* scroll-other-window: General Calendar.
+* scroll-right: Horizontal Scrolling.
+* scroll-up: Scrolling.
+* search-backward: Non-Incremental Search.
+* search-forward: Non-Incremental Search.
+* select-input-method: Select Input Method.
+* self-insert: Basic.
+* send-shell-input: Shell Mode.
+* set-buffer-file-coding-system: Specify Coding.
+* set-buffer-process-coding-system: Specify Coding.
+* set-comment-column: Comments.
+* set-default-file-modes: Interlocking.
+* set-face-background: Faces.
+* set-face-background-pixmap: Faces.
+* set-face-font: Faces.
+* set-face-foreground: Faces.
+* set-face-underline-p: Faces.
+* set-fill-column: Fill Commands.
+* set-fill-prefix: Fill Prefix.
+* set-gnu-bindings: Emulation.
+* set-goal-column: Basic.
+* set-gosmacs-bindings: Emulation.
+* set-keyboard-coding-system: Specify Coding.
+* set-language-environment: Language Environments.
+* set-mark-command: Setting Mark.
+* set-selective-display: Selective Display.
+* set-terminal-coding-system: Specify Coding.
+* set-variable: Examining.
+* set-visited-file-name: Saving.
+* setq-default: Locals.
+* shell: Interactive Shell.
+* shell-command: Single Shell.
+* shell-command-on-region: Single Shell.
+* shell-send-eof: Shell Mode.
+* show-all: Outline Visibility.
+* show-all-diary-entries: Diary Commands.
+* show-branches: Outline Visibility.
+* show-children: Outline Visibility.
+* show-entry: Outline Visibility.
+* show-output-from-shell: Shell Mode.
+* show-subtree: Outline Visibility.
+* simple-diary-display: Fancy Diary Display.
+* sort-columns: Sorting.
+* sort-diary-entries: Fancy Diary Display.
+* sort-fields: Sorting.
+* sort-lines: Sorting.
+* sort-numeric-fields: Sorting.
+* sort-pages: Sorting.
+* sort-paragraphs: Sorting.
+* spell-buffer: Spelling.
+* spell-region: Spelling.
+* spell-string: Spelling.
+* spell-word: Spelling.
+* split-line: Indentation Commands.
+* split-window-horizontally: Split Window.
+* split-window-vertically: Split Window.
+* start-kbd-macro: Basic Kbd Macro.
+* stop-shell-subjob: Shell Mode.
+* substitute-key-definition: Interactive Rebinding.
+* sunrise-sunset: Sunrise/Sunset.
+* suspend-emacs: Exiting.
+* switch-to-buffer: Select Buffer.
+* switch-to-buffer-other-frame <1>: XEmacs under X.
+* switch-to-buffer-other-frame: Select Buffer.
+* switch-to-buffer-other-window <1>: Select Buffer.
+* switch-to-buffer-other-window: Pop Up Window.
+* switch-to-other-buffer: Select Buffer.
+* tab-to-tab-stop <1>: Tab Stops.
+* tab-to-tab-stop: Text Mode.
+* tabify: Just Spaces.
+* tags-apropos: List Tags.
+* tags-loop-continue: Tags Search.
+* tags-query-replace: Tags Search.
+* tags-search: Tags Search.
+* term: Terminal emulator.
+* term-line-mode: Term Mode.
+* term-pager-toggle: Paging in Term.
+* tex-buffer: TeX Print.
+* tex-close-latex-block: TeX Editing.
+* tex-insert-braces: TeX Editing.
+* tex-insert-quote: TeX Editing.
+* tex-kill-job: TeX Print.
+* TeX-mode: TeX Mode.
+* tex-mode: TeX Mode.
+* tex-print: TeX Print.
+* tex-recenter-output-buffer: TeX Print.
+* tex-region: TeX Print.
+* tex-show-print-queue: TeX Print.
+* tex-terminate-paragraph: TeX Editing.
+* text-mode: Text Mode.
+* toggle-input-method: Select Input Method.
+* toggle-read-only: Misc Buffer.
+* top-level <1>: Recursive Edit.
+* top-level: Quitting.
+* transpose-chars <1>: Basic.
+* transpose-chars: Transpose.
+* transpose-lines: Transpose.
+* transpose-sexps <1>: Lists.
+* transpose-sexps: Transpose.
+* transpose-words <1>: Transpose.
+* transpose-words: Words.
+* undo: Undo.
+* unexpand-abbrev: Expanding Abbrevs.
+* universal-argument: Arguments.
+* universal-coding-system-argument: Specify Coding.
+* untabify: Just Spaces.
+* up-list: TeX Editing.
+* upcase-region: Case.
+* upcase-word <1>: Fixing Case.
+* upcase-word: Case.
+* validate-tex-buffer: TeX Editing.
+* vc-cancel-version: Editing with VC.
+* vc-create-snapshot: Making Snapshots.
+* vc-diff: Old Versions.
+* vc-directory: VC Status.
+* vc-insert-headers: Version Headers.
+* vc-next-action: Editing with VC.
+* vc-print-log: VC Status.
+* vc-register: Editing with VC.
+* vc-rename-file: Renaming and VC.
+* vc-retrieve-snapshot: Making Snapshots.
+* vc-revert-buffer: Editing with VC.
+* vc-update-change-log: Change Logs and VC.
+* vc-version-other-window: Old Versions.
+* view-buffer: Misc Buffer.
+* view-diary-entries: Diary Commands.
+* view-emacs-news: Help.
+* view-file: Misc File Ops.
+* view-hello-file: Mule Intro.
+* view-lossage: Help.
+* view-register: Registers.
+* visit-tags-table: Select Tags Table.
+* what-cursor-position: Position Info.
+* what-line: Position Info.
+* what-page: Position Info.
+* where-is: Help.
+* widen: Narrowing.
+* widget-backward: Changing an Option.
+* widget-complete: Changing an Option.
+* widget-forward: Changing an Option.
+* window-configuration-to-register: Split Window.
+* word-search-backward: Word Search.
+* word-search-forward: Word Search.
+* write-abbrev-file: Saving Abbrevs.
+* write-file: Saving.
+* x-copy-primary-selection: X Selection Commands.
+* x-create-frame: X Resources.
+* x-delete-primary-selection: X Selection Commands.
+* x-insert-selection: X Selection Commands.
+* x-kill-primary-selection: X Selection Commands.
+* x-mouse-kill: X Selection Commands.
+* x-own-secondary-selection: X Selection Commands.
+* x-own-selection: X Selection Commands.
+* x-set-point-and-insert-selection: X Selection Commands.
+* Yank: Kill Ring.
+* yank-pop: Earlier Kills.
+* yank-rectangle: Rectangles.
+* yow: Amusements.
+* zap-to-char: Killing.
+* zmacs-activate-region: Active Regions.
+* zmacs-deactivate-region: Active Regions.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Variable Index, Next: Concept Index, Prev: Command Index, Up: Top
+
+Variable Index
+**************
+
+* Menu:
+
+* abbrev-all-caps: Expanding Abbrevs.
+* abbrev-file-name: Saving Abbrevs.
+* abbrev-mode: Abbrevs.
+* after-load-alist: Loading.
+* after-save-hook: Saving.
+* all-christian-calendar-holidays: Holiday Customizing.
+* all-hebrew-calendar-holidays: Holiday Customizing.
+* all-islamic-calendar-holidays: Holiday Customizing.
+* appt-audible: Appt Customizing.
+* appt-display-duration: Appt Customizing.
+* appt-display-mode-line: Appt Customizing.
+* appt-message-warning-time: Appt Customizing.
+* appt-msg-window: Appt Customizing.
+* appt-visible: Appt Customizing.
+* auto-fill-inhibit-regexp: Fill Commands.
+* auto-lower-frame: XEmacs under X.
+* auto-mode-alist: Choosing Modes.
+* auto-raise-frame: XEmacs under X.
+* auto-save-default: Auto Save Control.
+* auto-save-interval: Auto Save Control.
+* auto-save-timeout: Auto Save Control.
+* auto-save-visited-file-name: Auto Save Files.
+* backup-by-copying: Backup Copying.
+* backup-by-copying-when-linked: Backup Copying.
+* backup-by-copying-when-mismatch: Backup Copying.
+* bell-volume: Audible Bell.
+* blink-matching-paren: Matching.
+* blink-matching-paren-distance: Matching.
+* buffer-file-coding-system: Recognize Coding.
+* buffer-file-name: Visiting.
+* buffer-file-truename: Visiting.
+* buffer-read-only: Misc Buffer.
+* buffer-tag-table: Find Tag.
+* c-argdecl-indent: C Indent.
+* c-auto-newline: C Indent.
+* c-brace-imaginary-offset: C Indent.
+* c-brace-offset: C Indent.
+* c-continued-statement-offset: C Indent.
+* c-indent-level: C Indent.
+* c-label-offset: C Indent.
+* c-mode-hook: Program Modes.
+* c-mode-map: Keymaps.
+* c-tab-always-indent: C Indent.
+* calendar-date-display-form: Date Display Format.
+* calendar-daylight-savings-ends: Daylight Savings.
+* calendar-daylight-savings-ends-time: Daylight Savings.
+* calendar-daylight-savings-starts: Daylight Savings.
+* calendar-daylight-time-offset: Daylight Savings.
+* calendar-daylight-time-zone-name: Sunrise/Sunset.
+* calendar-holiday-marker: Calendar Customizing.
+* calendar-holidays: Holiday Customizing.
+* calendar-latitude: Sunrise/Sunset.
+* calendar-load-hook: Calendar Customizing.
+* calendar-location-name: Sunrise/Sunset.
+* calendar-longitude: Sunrise/Sunset.
+* calendar-standard-time-zone-name: Sunrise/Sunset.
+* calendar-time-display-form: Time Display Format.
+* calendar-time-zone: Sunrise/Sunset.
+* calendar-today-marker: Calendar Customizing.
+* calendar-week-start-day: Move to Beginning or End.
+* case-fold-search <1>: Search Case.
+* case-fold-search: Replacement and Case.
+* case-replace: Replacement and Case.
+* christian-holidays: Holiday Customizing.
+* coding: Recognize Coding.
+* command-history: Repetition.
+* command-line-args: Command Switches.
+* comment-column: Comments.
+* comment-end: Comments.
+* comment-indent-hook: Comments.
+* comment-line-start: Fortran Comments.
+* comment-line-start-skip: Fortran Comments.
+* comment-multi-line: Comments.
+* comment-start: Comments.
+* comment-start-skip: Comments.
+* compare-ignore-case: Comparing Files.
+* compile-command: Compilation.
+* completion-auto-help: Completion.
+* completion-ignored-extensions: Completion.
+* create-frame-hook: XEmacs under X.
+* ctl-arrow: Display Vars.
+* ctl-x-map: Keymaps.
+* current-input-method: Select Input Method.
+* data-directory: Startup Paths.
+* data-directory-list: Startup Paths.
+* debug-on-error: Lisp Debug.
+* debug-on-quit: Lisp Debug.
+* default-buffer-file-coding-system: Specify Coding.
+* default-directory: File Names.
+* default-directory-alist: File Names.
+* default-frame-alist: XEmacs under X.
+* default-input-method: Select Input Method.
+* default-major-mode: Choosing Modes.
+* delete-auto-save-files: Auto Save Files.
+* describe-function-show-arglist: Help.
+* diary-date-forms: Diary Customizing.
+* diary-display-hook: Fancy Diary Display.
+* diary-entry-marker: Calendar Customizing.
+* diary-file: Format of Diary File.
+* diary-list-include-blanks: Fancy Diary Display.
+* diary-mail-days: Diary Commands.
+* diff-switches: Comparing Files.
+* dired-kept-versions: Dired Deletion.
+* dired-listing-switches: Dired Enter.
+* display-buffer-function: Pop Up Window.
+* doc-directory: Startup Paths.
+* echo-keystrokes: Display Vars.
+* emacs-lisp-mode-hook: Program Modes.
+* emacs-roots: Startup Paths.
+* EMACSDATA: Startup Paths.
+* EMACSLOADPATH: Startup Paths.
+* EMACSLOCKDIR: Startup Paths.
+* EMACSPATH: Startup Paths.
+* enable-local-variables: File Variables.
+* enable-recursive-minibuffers: Minibuffer Edit.
+* esc-map: Keymaps.
+* european-calendar-style: Date Formats.
+* exec-directory: Startup Paths.
+* exec-path: Startup Paths.
+* explicit-shell-file-name: Interactive Shell.
+* file-coding-system-alist: Recognize Coding.
+* file-name-coding-system: Specify Coding.
+* fill-column: Fill Commands.
+* fill-prefix: Fill Prefix.
+* find-file-compare-truenames: Visiting.
+* find-file-hooks: Visiting.
+* find-file-not-found-hooks: Visiting.
+* find-file-run-dired: Visiting.
+* find-file-use-truenames: Visiting.
+* fortran-check-all-num-for-matching-do: ForIndent Vars.
+* fortran-comment-indent-char: Fortran Comments.
+* fortran-comment-indent-style: Fortran Comments.
+* fortran-comment-line-column: Fortran Comments.
+* fortran-comment-region: Fortran Comments.
+* fortran-continuation-char: ForIndent Conv.
+* fortran-continuation-indent: ForIndent Vars.
+* fortran-do-indent: ForIndent Vars.
+* fortran-electric-line-number: ForIndent Num.
+* fortran-if-indent: ForIndent Vars.
+* fortran-line-number-indent: ForIndent Num.
+* fortran-minimum-statement-indent: ForIndent Vars.
+* frame-icon-title-format <1>: XEmacs under X.
+* frame-icon-title-format: Command Switches.
+* frame-title-format <1>: Command Switches.
+* frame-title-format: XEmacs under X.
+* general-holidays: Holiday Customizing.
+* global-map: Keymaps.
+* hebrew-holidays: Holiday Customizing.
+* help-map: Keymaps.
+* holidays-in-diary-buffer: Diary Customizing.
+* indent-tabs-mode: Just Spaces.
+* Info-directory-list: Startup Paths.
+* INFOPATH: Startup Paths.
+* initial-calendar-window-hook: Calendar Customizing.
+* initial-major-mode: Entering Emacs.
+* input-method-highlight-flag: Input Methods.
+* input-method-verbose-flag: Input Methods.
+* input-ring-size: Interactive Shell.
+* insert-default-directory <1>: Minibuffer File.
+* insert-default-directory: File Names.
+* isearch-mode-map: Keymaps.
+* islamic-holidays: Holiday Customizing.
+* kept-new-versions: Backup Deletion.
+* kept-old-versions: Backup Deletion.
+* keyboard-translate-table: Intro to Keystrokes.
+* kill-ring-max: Earlier Kills.
+* LaTeX-mode-hook: TeX Print.
+* lisp-body-indention: Lisp Indent.
+* lisp-directory: Startup Paths.
+* lisp-indent-offset: Lisp Indent.
+* lisp-interaction-mode-hook: Program Modes.
+* lisp-mode-hook: Program Modes.
+* lisp-mode-map: Keymaps.
+* list-diary-entries-hook: Included Diary Files.
+* list-directory-brief-switches: ListDir.
+* list-directory-verbose-switches: ListDir.
+* load-path <1>: Loading.
+* load-path: Startup Paths.
+* local-holidays: Holiday Customizing.
+* lock-directory: Startup Paths.
+* lpr-switches: Hardcopy.
+* mail-abbrev-mailrc-file: Mail Headers.
+* mail-abbrev-mode-regexp: Mail Headers.
+* mail-alias-seperator-string: Mail Headers.
+* mail-archive-file-name: Mail Headers.
+* mail-header-separator: Mail Format.
+* mail-mode-hook: Mail Mode.
+* make-backup-files: Backup.
+* make-tags-files-invisible: Find Tag.
+* mark-diary-entries-hook: Included Diary Files.
+* mark-diary-entries-in-calendar: Calendar Customizing.
+* mark-holidays-in-calendar: Calendar Customizing.
+* mark-ring: Mark Ring.
+* mark-ring-max: Mark Ring.
+* meta-flag: Meta Key.
+* minibuffer-confirm-incomplete: Completion.
+* minibuffer-local-completion-map: Keymaps.
+* minibuffer-local-map: Keymaps.
+* minibuffer-local-must-match-map: Keymaps.
+* minibuffer-local-ns-map: Keymaps.
+* mode-line-inverse-video: Mode Line.
+* modeline-pointer-glyph: Mouse Selection.
+* muddle-mode-hook: Program Modes.
+* next-screen-context-lines: Scrolling.
+* no-redraw-on-reenter: Display Vars.
+* nongregorian-diary-listing-hook: Hebrew/Islamic Entries.
+* nongregorian-diary-marking-hook: Hebrew/Islamic Entries.
+* nontext-pointer-glyph: Mouse Selection.
+* nroff-mode-hook: Nroff Mode.
+* number-of-diary-entries: Diary Customizing.
+* other-holidays: Holiday Customizing.
+* outline-mode-hook: Outline Mode.
+* outline-regexp: Outline Format.
+* page-delimiter: Pages.
+* paragraph-separate: Paragraphs.
+* paragraph-start: Paragraphs.
+* parse-sexp-ignore-comments: Syntax Entry.
+* PATH: Startup Paths.
+* picture-mode-hook: Picture.
+* picture-tab-chars: Tabs in Picture.
+* plain-TeX-mode-hook: TeX Print.
+* print-diary-entries-hook: Diary Customizing.
+* repeat-complex-command-map: Keymaps.
+* require-final-newline: Saving.
+* save-abbrevs: Saving Abbrevs.
+* scheme-mode-hook: Program Modes.
+* scroll-conservatively: Scrolling.
+* scroll-step: Scrolling.
+* search-slow-speed: Incremental Search.
+* search-slow-window-lines: Incremental Search.
+* selective-display-ellipses <1>: Display Vars.
+* selective-display-ellipses: Outline Visibility.
+* sentence-end: Sentences.
+* shell-cd-regexp: Interactive Shell.
+* shell-file-name: Single Shell.
+* shell-popd-regexp: Interactive Shell.
+* shell-prompt-pattern: Shell Mode.
+* shell-pushd-regexp: Interactive Shell.
+* sound-alist: Audible Bell.
+* superlock-file: Startup Paths.
+* tab-stop-list: Tab Stops.
+* tab-width: Display Vars.
+* tag-mark-stack-max: Find Tag.
+* tag-table-alist <1>: Find Tag.
+* tag-table-alist: Select Tags Table.
+* tags-always-build-completion-table: Select Tags Table.
+* tags-build-completion-table: Find Tag.
+* tags-file-name <1>: Find Tag.
+* tags-file-name: Select Tags Table.
+* term-file-prefix: Terminal Init.
+* term-setup-hook: Terminal Init.
+* TeX-mode-hook: TeX Print.
+* text-mode-hook: Text Mode.
+* text-pointer-glyph: Mouse Selection.
+* today-invisible-calendar-hook: Calendar Customizing.
+* today-visible-calendar-hook: Calendar Customizing.
+* track-eol: Basic.
+* trim-versions-without-asking: Backup Deletion.
+* truncate-lines: Continuation Lines.
+* truncate-partial-width-windows: Split Window.
+* vc-command-messages: Variables for Check-in/out.
+* vc-comment-alist: Version Headers.
+* vc-default-back-end: Editing with VC.
+* vc-header-alist: Version Headers.
+* vc-initial-comment: Editing with VC.
+* vc-keep-workfiles: Editing with VC.
+* vc-log-mode-hook: Log Entries.
+* vc-make-backup-files: Editing with VC.
+* vc-mistrust-permissions: Variables for Check-in/out.
+* vc-path: Variables for Check-in/out.
+* vc-static-header-alist: Version Headers.
+* vc-suppress-confirm: Variables for Check-in/out.
+* version-control: Backup Names.
+* view-calendar-holidays-initially: Calendar Customizing.
+* view-diary-entries-initially: Calendar Customizing.
+* window-min-height: Change Window.
+* window-min-width: Change Window.
+* write-file-hooks: Saving.
+* x-frame-defaults: XEmacs under X.
+* zmacs-region-stays: Active Regions.
+* zmacs-regions: Active Regions.
+
+\1f
+File: xemacs.info, Node: Concept Index, Next: Frame, Prev: Variable Index, Up: Top
+
+Concept Index
+*************
+
+* Menu:
+
+* .mailrc file: Mail Headers.
+* Abbrev mode: Minor Modes.
+* abbrevs: Abbrevs.
+* aborting: Quitting.
+* accumulating text: Accumulating Text.
+* active fields (customization buffer): Customization Groups.
+* active regions: Active Regions.
+* adding menu items: Menu Customization.
+* adding menus: Menu Customization.
+* againformation: Dissociated Press.
+* Apps menu <1>: Pull-down Menus.
+* Apps menu: Apps Menu.
+* apropos: Help.
+* architecture-specific directories: Startup Paths.
+* arguments (from shell): Command Switches.
+* ASCII: Intro to Keystrokes.
+* Asm mode: Asm Mode.
+* astronomical day numbers: Calendar Systems.
+* audible bell, changing: Audible Bell.
+* Auto Delete Selection menu item: Options Menu.
+* Auto Fill mode <1>: Comments.
+* Auto Fill mode <2>: Auto Fill.
+* Auto Fill mode: Minor Modes.
+* Auto-Save mode: Auto Save.
+* autoload: Loading.
+* backup file: Backup.
+* batch mode: Command Switches.
+* bell, changing: Audible Bell.
+* binary packages: Package Terminology.
+* binding: Commands.
+* blank lines <1>: Comments.
+* blank lines: Blank Lines.
+* body lines (Outline mode): Outline Format.
+* bold font: Face Customization.
+* boredom: Amusements.
+* buffer: Frame.
+* buffer menu: Several Buffers.
+* buffers: Buffers.
+* Buffers menu <1>: Buffers Menu.
+* Buffers menu: Pull-down Menus.
+* Buffers Menu Length... menu item: Options Menu.
+* Buffers Sub-Menus menu item: Options Menu.
+* buggestion: Dissociated Press.
+* bugs: Bugs.
+* byte code: Compiling Libraries.
+* C: Programs.
+* C mode: Program Modes.
+* calendar: Calendar/Diary.
+* calendar and LaTeX: LaTeX Calendar.
+* calendar, first day of week: Move to Beginning or End.
+* candle lighting times: Sexp Diary Entries.
+* case conversion <1>: Fixing Case.
+* case conversion: Case.
+* Case Sensitive Search menu item: Options Menu.
+* centering: Fill Commands.
+* change log: Change Log.
+* changing buffers: Select Buffer.
+* changing menu items: Menu Customization.
+* character set: Intro to Keystrokes.
+* checking in files: Concepts of VC.
+* checking out files: Concepts of VC.
+* Chinese: Mule.
+* Chinese calendar: Calendar Systems.
+* Clear menu item: Edit Menu.
+* clipboard selections: X Clipboard Selection.
+* coding systems: Coding Systems.
+* command <1>: Commands.
+* command: Key Bindings.
+* command history: Repetition.
+* command line arguments: Command Switches.
+* command name: Key Bindings.
+* comments: Comments.
+* comparing files: Comparing Files.
+* compilation errors: Compilation.
+* compiling files: Compilation.
+* completion: Completion.
+* completion (symbol names): Lisp Completion.
+* continuation line: Continuation Lines.
+* Control-Meta: Lists.
+* Coptic calendar: Calendar Systems.
+* Copy menu item: Edit Menu.
+* copying files: Misc File Ops.
+* copying text <1>: Yanking.
+* copying text: Accumulating Text.
+* core distribution: Using Packages.
+* crashes: Auto Save.
+* creating directories: File Names.
+* creating files: Visiting.
+* current buffer: Buffers.
+* current stack frame: Lisp Debug.
+* cursor <1>: Point.
+* cursor: Basic.
+* customization <1>: Customization.
+* customization <2>: Commands.
+* customization: Lisp Indent.
+* customization buffer: Easy Customization.
+* customization groups: Customization Groups.
+* customizing faces: Face Customization.
+* cut buffers: X Selection Commands.
+* Cut menu item: Edit Menu.
+* cutting: Killing.
+* day of year: General Calendar.
+* daylight savings time: Daylight Savings.
+* debugger: Lisp Debug.
+* default argument: Minibuffer.
+* defuns: Defuns.
+* Delete Frame menu item: File Menu.
+* deleting menu items: Menu Customization.
+* deletion <1>: Killing.
+* deletion: Basic.
+* deletion (of files) <1>: Misc File Ops.
+* deletion (of files): Dired.
+* diary: Diary.
+* diary buffer: Fancy Diary Display.
+* diary file: Format of Diary File.
+* ding: Audible Bell.
+* directories: Startup Paths.
+* directory hierarchies: Startup Paths.
+* directory listing: ListDir.
+* Dired: Dired.
+* disabled command: Disabling.
+* disabling menu items: Menu Customization.
+* Distribution: License.
+* doctor: Total Frustration.
+* drastic changes: Reverting.
+* dribble file: Bugs.
+* early package hierarchies: Startup Paths.
+* echo area: Echo Area.
+* Edit menu <1>: Pull-down Menus.
+* Edit menu: Edit Menu.
+* editable fields (customization buffer): Customization Groups.
+* editing level, recursive <1>: Recursive Edit.
+* editing level, recursive: Quitting.
+* EDT: Emulation.
+* Eliza: Total Frustration.
+* Emacs initialization file: Init File.
+* Emacs-Lisp mode: Lisp Eval.
+* enabling menu items: Menu Customization.
+* encoding of characters: Mule.
+* End Macro Recording menu item: Edit Menu.
+* entering Emacs: Entering Emacs.
+* entering XEmacs: Entering Emacs.
+* environment: Single Shell.
+* error log: Compilation.
+* etags program: Create Tags Table.
+* Ethiopic calendar: Calendar Systems.
+* Execute Last Macro menu item: Edit Menu.
+* Exit Emacs menu item: File Menu.
+* exiting <1>: Recursive Edit.
+* exiting: Exiting.
+* expansion (of abbrevs): Abbrevs.
+* expression: Lists.
+* file dates: Interlocking.
+* file directory: ListDir.
+* File menu <1>: Pull-down Menus.
+* File menu: File Menu.
+* file names: File Names.
+* file protection: Interlocking.
+* files <1>: Files.
+* files <2>: Visiting.
+* files: Basic.
+* fill prefix: Fill Prefix.
+* filling: Filling.
+* Font menu item: Options Menu.
+* fonts and faces: Face Customization.
+* formfeed: Pages.
+* Fortran mode: Fortran.
+* frame: Frame.
+* French Revolutionary calendar: Calendar Systems.
+* function <1>: Key Bindings.
+* function: Commands.
+* General Public License: License.
+* global keymap: Keymaps.
+* global substitution: Replace.
+* graphic characters: Basic.
+* Greek: Mule.
+* Gregorian calendar: Other Calendars.
+* grinding: Grinding.
+* hardcopy: Hardcopy.
+* header (TeX mode): TeX Print.
+* headers (of mail message): Mail Headers.
+* heading lines (Outline mode): Outline Format.
+* Hebrew calendar: Calendar Systems.
+* help: Help.
+* Help menu <1>: Help Menu.
+* Help menu: Pull-down Menus.
+* hierarchies: Startup Paths.
+* history of commands: Repetition.
+* holiday forms: Holiday Customizing.
+* holidays: Holidays.
+* horizontal scrolling: Horizontal Scrolling.
+* ignoriginal: Dissociated Press.
+* indentation <1>: Grinding.
+* indentation <2>: Indentation.
+* indentation: Comments.
+* inferior process: Compilation.
+* init file: Init File.
+* input methods: Input Methods.
+* Insert File... menu item: File Menu.
+* insertion: Basic.
+* international scripts: Mule.
+* interval operator (in regexps): Create Tags Table.
+* invisible lines: Outline Mode.
+* IPA: Mule.
+* Islamic calendar: Calendar Systems.
+* ISO commercial calendar: Calendar Systems.
+* italic font: Face Customization.
+* Japanese: Mule.
+* Julian calendar: Calendar Systems.
+* Julian day numbers: Calendar Systems.
+* justification: Fill Commands.
+* key rebinding, permanent: Init File.
+* key rebinding, this session: Rebinding.
+* keyboard macros: Keyboard Macros.
+* keycode: Super and Hyper Keys.
+* keymap <1>: Commands.
+* keymap: Keymaps.
+* keystroke: Intro to Keystrokes.
+* keysym: Intro to Keystrokes.
+* keysyms: Super and Hyper Keys.
+* Kill Buffer menu item: File Menu.
+* kill ring: Yanking.
+* killing: Killing.
+* killing Emacs: Exiting.
+* Korean: Mule.
+* language environments: Language Environments.
+* last package hierarchies: Startup Paths.
+* late package hierarchies: Startup Paths.
+* LaTeX: TeX Mode.
+* libraries: Lisp Libraries.
+* license to copy XEmacs: License.
+* line number: Position Info.
+* Lisp: Programs.
+* Lisp mode: Program Modes.
+* list: Lists.
+* loading libraries: Loading.
+* loading Lisp code: Lisp Libraries.
+* local keymap: Keymaps.
+* local variables: Locals.
+* local variables in files: File Variables.
+* locking and version control: Concepts of VC.
+* log entry: Editing with VC.
+* mail <1>: Reading Mail.
+* mail: Sending Mail.
+* major modes: Major Modes.
+* make: Compilation.
+* mark: Mark.
+* mark ring <1>: Mark and Region.
+* mark ring: Mark Ring.
+* Markov chain: Dissociated Press.
+* master file: Concepts of VC.
+* matching parentheses: Matching.
+* Mayan calendar: Calendar Systems.
+* Mayan calendar round: Mayan Calendar.
+* Mayan haab calendar: Mayan Calendar.
+* Mayan long count: Mayan Calendar.
+* Mayan tzolkin calendar: Mayan Calendar.
+* menus <1>: Change Window.
+* menus: Pull-down Menus.
+* message <1>: Sending Mail.
+* message: Reading Mail.
+* Meta: Words.
+* minibuffer <1>: M-x.
+* minibuffer <2>: Keymaps.
+* minibuffer: Minibuffer.
+* minor modes: Minor Modes.
+* mistakes, correcting <1>: Fixit.
+* mistakes, correcting: Undo.
+* mocklisp: Mocklisp.
+* mode hook: Program Modes.
+* mode line <1>: Mode Line.
+* mode line: Minor Modes.
+* mode, Term: Term Mode.
+* modified (buffer): Visiting.
+* modifier key: Intro to Keystrokes.
+* modifier mapping: Super and Hyper Keys.
+* moon, phases of: Lunar Phases.
+* mouse operations: Additional Mouse Operations.
+* mouse selection: Mouse Selection.
+* moving inside the calendar: Calendar Motion.
+* moving text: Yanking.
+* MULE: Mule.
+* multi-frame XEmacs: XEmacs under X.
+* multibyte characters: Mule.
+* named configurations (RCS): Snapshot Caveats.
+* narrowing: Narrowing.
+* New Frame menu item: File Menu.
+* newline: Basic.
+* non-incremental search: Non-Incremental Search.
+* nroff: Nroff Mode.
+* numeric arguments: Arguments.
+* omer count: Sexp Diary Entries.
+* Open File, New Frame... menu item: File Menu.
+* Open File... menu item: File Menu.
+* option <1>: Variables.
+* option: Examining.
+* Options menu <1>: Pull-down Menus.
+* Options menu: Options Menu.
+* other editors: Emulation.
+* outlines: Outline Mode.
+* outragedy: Dissociated Press.
+* Overstrike menu item: Options Menu.
+* Overwrite mode: Minor Modes.
+* package hierarchies: Startup Paths.
+* package path: Startup Paths.
+* packages: Packages.
+* page number: Position Info.
+* pages: Pages.
+* paragraphs: Paragraphs.
+* parasha, weekly: Sexp Diary Entries.
+* Paren Highlighting menu item: Options Menu.
+* parentheses: Matching.
+* Paste menu item: Edit Menu.
+* pasting: Yanking.
+* path: Startup Paths.
+* paths: Startup Paths.
+* per-buffer variables: Locals.
+* Persian calendar: Calendar Systems.
+* phases of the moon: Lunar Phases.
+* pictures: Picture.
+* point <1>: Basic.
+* point: Point.
+* pointer face: Mouse Selection.
+* pointer shapes: Mouse Selection.
+* prefix key sequence: Key Sequences.
+* presidentagon: Dissociated Press.
+* primary selections: X Selection Commands.
+* Print Buffer menu item: File Menu.
+* prompt: Minibuffer.
+* properbose: Dissociated Press.
+* Pull-down Menus <1>: Change Window.
+* Pull-down Menus: Pull-down Menus.
+* query replace: Query Replace.
+* quitting: Quitting.
+* quitting (in search): Incremental Search.
+* quoting: Basic.
+* random sentences: CONX.
+* RCS: Concepts of VC.
+* Read Only menu item: Options Menu.
+* read-only buffer: Misc Buffer.
+* rebinding keys, permanently: Init File.
+* rebinding keys, this session: Rebinding.
+* rectangle <1>: RegRect.
+* rectangle: Rectangles in Picture.
+* rectangles: Rectangles.
+* recursive editing level <1>: Quitting.
+* recursive editing level: Recursive Edit.
+* redefining keys: Key Bindings Using Strings.
+* regexp: Regexp Search.
+* region <1>: Case.
+* region: Mark.
+* registered file: Concepts of VC.
+* registers: Registers.
+* regular expression: Regexp Search.
+* regular packages: Package Terminology.
+* removing directories: File Names.
+* replacement: Replace.
+* restriction: Narrowing.
+* Revert Buffer menu item: File Menu.
+* root of a hierarchy: Startup Paths.
+* rosh hodesh: Sexp Diary Entries.
+* Russian: Mule.
+* Save Buffer As ... menu item: File Menu.
+* Save Buffer menu item: File Menu.
+* Save Options: Options Menu.
+* saving: Visiting.
+* saving option value: Changing an Option.
+* SCCS: Concepts of VC.
+* Scheme mode: Program Modes.
+* scrolling: Scrolling.
+* scrolling in the calendar: Scroll Calendar.
+* searching: Search.
+* selected buffer: Buffers.
+* selected window: Basic Window.
+* selective display: Outline Mode.
+* self-documentation: Help.
+* sentences: Sentences.
+* setting option value: Changing an Option.
+* setting variables: Examining.
+* sexp: Lists.
+* sexp diary entries: Sexp Diary Entries.
+* shell commands: Shell.
+* Shell mode: Shell Mode.
+* shift modifer: Representing Keystrokes.
+* shrinking XEmacs frame: Exiting.
+* simultaneous editing: Interlocking.
+* single-file packages: Package Terminology.
+* site-specific directories: Startup Paths.
+* Size menu item: Options Menu.
+* snapshots and version control: Snapshots.
+* sorting: Sorting.
+* sorting diary entries: Fancy Diary Display.
+* source packages: Package Terminology.
+* spelling: Spelling.
+* Split Frame: File Menu.
+* Start Macro Recording menu item: Edit Menu.
+* startup paths: Startup Paths.
+* string substitution: Replace.
+* subshell: Shell.
+* subtree (Outline mode): Outline Visibility.
+* sunrise and sunset: Sunrise/Sunset.
+* suspending: Exiting.
+* switching buffers: Select Buffer.
+* Syntax Highlighting menu item: Options Menu.
+* syntax table <1>: Syntax.
+* syntax table: Words.
+* tags table: Tags.
+* Teach Extended Commands menu item: Options Menu.
+* techniquitous: Dissociated Press.
+* television: Appending Kills.
+* Term mode: Term Mode.
+* termscript file: Bugs.
+* TeX: TeX Mode.
+* text: Text.
+* Text mode: Text Mode.
+* Tools menu <1>: Pull-down Menus.
+* Tools menu: Tools Menu.
+* top level: Mode Line.
+* transposition <1>: Words.
+* transposition <2>: Lists.
+* transposition: Transpose.
+* truncation: Continuation Lines.
+* typos: Fixit.
+* Un-split (Keep Others): File Menu.
+* Un-split (Keep This): File Menu.
+* undo: Undo.
+* Undo menu item: Edit Menu.
+* variable: Variables.
+* variables: Commands.
+* version control: Version Control.
+* version-specific directories: Startup Paths.
+* vi: Emulation.
+* viewing: Misc File Ops.
+* Viper: Emulation.
+* visiting: Visiting.
+* visiting files: Visiting.
+* weeks, which day they start on: Move to Beginning or End.
+* Weight menu item: Options Menu.
+* widening: Narrowing.
+* window: Frame.
+* windows: Windows.
+* Windows menu: Change Window.
+* word search: Word Search.
+* words <1>: Case.
+* words <2>: Fixing Case.
+* words: Words.
+* work file: Concepts of VC.
+* X resources: X Resources.
+* yahrzeits <1>: From Other Calendar.
+* yahrzeits: Sexp Diary Entries.
+* yanking: Yanking.
+
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Exiting, Next: Command Switches, Prev: Entering Emacs, Up: Top
+
+Exiting Emacs
+=============
+
+ There are two commands for exiting Emacs because there are two kinds
+of exiting: "suspending" Emacs and "killing" Emacs. "Suspending" means
+stopping Emacs temporarily and returning control to its superior
+(usually the shell), allowing you to resume editing later in the same
+Emacs job, with the same files, same kill ring, same undo history, and
+so on. This is the usual way to exit. "Killing" Emacs means
+destroying the Emacs job. You can run Emacs again later, but you will
+get a fresh Emacs; there is no way to resume the same editing session
+after it has been killed.
+
+`C-z'
+ Suspend Emacs (`suspend-emacs'). If used under the X window
+ system, shrink the X window containing the Emacs frame to an icon
+ (see below).
+
+`C-x C-c'
+ Kill Emacs (`save-buffers-kill-emacs').
+
+ If you use XEmacs under the X window system, `C-z' shrinks the X
+window containing the Emacs frame to an icon. The Emacs process is
+stopped temporarily, and control is returned to the window manager. If
+more than one frame is associated with the Emacs process, only the
+frame from which you used `C-z' is retained. The X windows containing
+the other Emacs frames are closed.
+
+ To activate the "suspended" Emacs, use the appropriate window manager
+mouse gestures. Usually left-clicking on the icon reactivates and
+reopens the X window containing the Emacs frame, but the window manager
+you use determines what exactly happens. To actually kill the Emacs
+process, use `C-x C-c' or the Exit Emacs item on the File menu.
+
+ On systems that do not permit programs to be suspended, `C-z' runs
+an inferior shell that communicates directly with the terminal, and
+Emacs waits until you exit the subshell. On these systems, the only way
+to return to the shell from which Emacs was started (to log out, for
+example) is to kill Emacs. `C-d' or `exit' are typical commands to
+exit a subshell.
+
+ To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A
+two-character key is used for this to make it harder to type. In
+XEmacs, selecting the Exit Emacs option of the File menu is an
+alternate way of issuing the command.
+
+ Unless a numeric argument is used, this command first offers to save
+any modified buffers. If you do not save all buffers, you are asked for
+reconfirmation with `yes' before killing Emacs, since any changes not
+saved will be lost. If any subprocesses are still running, `C-x C-c'
+asks you to confirm killing them, since killing Emacs kills the
+subprocesses simultaneously.
+
+ In most programs running on Unix, certain characters may instantly
+suspend or kill the program. (In Berkeley Unix these characters are
+normally `C-z' and `C-c'.) This Unix feature is turned off while you
+are in Emacs. The meanings of `C-z' and `C-x C-c' as keys in Emacs were
+inspired by the standard Berkeley Unix meanings of `C-z' and `C-c', but
+that is their only relationship with Unix. You could customize these
+keys to do anything (*note Keymaps::.).
+
+\1f
+File: xemacs.info, Node: Command Switches, Next: Startup Paths, Prev: Exiting, Up: Top
+
+Command Line Switches and Arguments
+===================================
+
+ XEmacs supports command line arguments you can use to request
+various actions when invoking Emacs. The commands are for compatibility
+with other editors and for sophisticated activities. If you are using
+XEmacs under the X window system, you can also use a number of standard
+Xt command line arguments. Command line arguments are not usually
+needed for editing with Emacs; new users can skip this section.
+
+ Many editors are designed to be started afresh each time you want to
+edit. You start the editor to edit one file; then exit the editor. The
+next time you want to edit either another file or the same one, you
+start the editor again. Under these circumstances, it makes sense to
+use a command line argument to say which file to edit.
+
+ The recommended way to use XEmacs is to start it only once, just
+after you log in, and do all your editing in the same Emacs process.
+Each time you want to edit a file, you visit it using the existing
+Emacs. Emacs creates a new buffer for each file, and (unless you kill
+some of the buffers) Emacs eventually has many files in it ready for
+editing. Usually you do not kill the Emacs process until you are about
+to log out. Since you usually read files by typing commands to Emacs,
+command line arguments for specifying a file when Emacs is started are
+seldom needed.
+
+ Emacs accepts command-line arguments that specify files to visit,
+functions to call, and other activities and operating modes. If you are
+running XEmacs under the X window system, a number of standard Xt
+command line arguments are available as well.
+
+ The following subsections list:
+ * Command line arguments that you can always use
+
+ * Command line arguments that have to appear at the beginning of the
+ argument list
+
+ * Command line arguments that are only relevant if you are running
+ XEmacs under X
+
+Command Line Arguments for Any Position
+---------------------------------------
+
+ Command line arguments are processed in the order they appear on the
+command line; however, certain arguments (the ones in the second table)
+must be at the front of the list if they are used.
+
+ Here are the arguments allowed:
+
+`FILE'
+ Visit FILE using `find-file'. *Note Visiting::.
+
+`+LINENUM FILE'
+ Visit FILE using `find-file', then go to line number LINENUM in it.
+
+`-load FILE'
+`-l FILE'
+ Load a file FILE of Lisp code with the function `load'. *Note
+ Lisp Libraries::.
+
+`-funcall FUNCTION'
+`-f FUNCTION'
+ Call Lisp function FUNCTION with no arguments.
+
+`-eval FUNCTION'
+ Interpret the next argument as a Lisp expression, and evaluate it.
+ You must be very careful of the shell quoting here.
+
+`-insert FILE'
+`-i FILE'
+ Insert the contents of FILE into the current buffer. This is like
+ what `M-x insert-buffer' does; *Note Misc File Ops::.
+
+`-kill'
+ Exit from Emacs without asking for confirmation.
+
+`-version'
+`-V'
+ Prints version information. This implies `-batch'.
+
+ % xemacs -version
+ XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs]
+
+`-help'
+ Prints a summary of command-line options and then exits.
+
+Command Line Arguments (Beginning of Line Only)
+-----------------------------------------------
+
+ The following arguments are recognized only at the beginning of the
+command line. If more than one of them appears, they must appear in the
+order in which they appear in this table.
+
+`-t FILE'
+ Use FILE instead of the terminal for input and output. This
+ implies the `-nw' option, documented below.
+
+`-batch'
+ Run Emacs in "batch mode", which means that the text being edited
+ is not displayed and the standard Unix interrupt characters such as
+ `C-z' and `C-c' continue to have their normal effect. Emacs in
+ batch mode outputs to `stderr' only what would normally be printed
+ in the echo area under program control.
+
+ Batch mode is used for running programs written in Emacs Lisp from
+ shell scripts, makefiles, and so on. Normally the `-l' switch or
+ `-f' switch will be used as well, to invoke a Lisp program to do
+ the batch processing.
+
+ `-batch' implies `-q' (do not load an init file). It also causes
+ Emacs to kill itself after all command switches have been
+ processed. In addition, auto-saving is not done except in buffers
+ for which it has been explicitly requested.
+
+`-nw'
+ Start up XEmacs in TTY mode (using the TTY XEmacs was started
+ from), rather than trying to connect to an X display. Note that
+ this happens automatically if the `DISPLAY' environment variable
+ is not set.
+
+`-debug-init'
+ Enter the debugger if an error in the init file occurs.
+
+`-debug-paths'
+ Displays information on how XEmacs constructs the various paths
+ into its hierarchy on startup. (See also *note Startup Paths::..)
+
+`-unmapped'
+ Do not map the initial frame. This is useful if you want to start
+ up XEmacs as a server (e.g. for gnuserv screens or external client
+ widgets).
+
+`-no-init-file'
+`-q'
+ Do not load your Emacs init file `~/.emacs'.
+
+`-no-site-file'
+ Do not load the site-specific init file `lisp/site-start.el'.
+
+`-no-autoloads'
+ Do not load global symbol files (`auto-autoloads') at startup.
+ This implies `-vanilla'.
+
+`-no-early-packages'
+ Do not process early packages. (For more information on startup
+ issues concerning the package system, *Note Startup Paths::.)
+
+`-vanilla'
+ This is equivalent to `-q -no-site-file -no-early-packages'.
+
+`-user-init-file FILE'
+ Load FILE as your Emacs init file instead of `~/.emacs'.
+
+`-user-init-directory DIRECTORY'
+ Use DIRECTORY as the location of your early package hierarchies
+ and the various user-specific initialization files.
+
+`-user USER'
+`-u USER'
+ Equivalent to `-user-init-file ~USER/.emacs -user-init-directory
+ ~USER/.xemacs'.
+
+ Note that the init file can get access to the command line argument
+values as the elements of a list in the variable `command-line-args'.
+(The arguments in the second table above will already have been
+processed and will not be in the list.) The init file can override the
+normal processing of the other arguments by setting this variable.
+
+ One way to use command switches is to visit many files automatically:
+
+ xemacs *.c
+
+passes each `.c' file as a separate argument to Emacs, so that Emacs
+visits each file (*note Visiting::.).
+
+ Here is an advanced example that assumes you have a Lisp program file
+called `hack-c-program.el' which, when loaded, performs some useful
+operation on the current buffer, expected to be a C program.
+
+ xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
+
+Here Emacs is told to visit `foo.c', load `hack-c-program.el' (which
+makes changes in the visited file), save `foo.c' (note that
+`save-buffer' is the function that `C-x C-s' is bound to), and then
+exit to the shell from which the command was executed. `-batch'
+guarantees there will be no problem redirecting output to `log',
+because Emacs will not assume that it has a display terminal to work
+with.
+
+Command Line Arguments (for XEmacs Under X)
+-------------------------------------------
+
+ If you are running XEmacs under X, a number of options are available
+to control color, border, and window title and icon name:
+
+`-title TITLE'
+`-wn TITLE'
+`-T TITLE'
+ Use TITLE as the window title. This sets the `frame-title-format'
+ variable, which controls the title of the X window corresponding
+ to the selected frame. This is the same format as
+ `mode-line-format'.
+
+`-iconname TITLE'
+`-in TITLE'
+ Use TITLE as the icon name. This sets the
+ `frame-icon-title-format' variable, which controls the title of
+ the icon corresponding to the selected frame.
+
+`-mc COLOR'
+ Use COLOR as the mouse color.
+
+`-cr COLOR'
+ Use COLOR as the text-cursor foreground color.
+
+`-private'
+ Install a private colormap for XEmacs.
+
+ In addition, XEmacs allows you to use a number of standard Xt
+command line arguments.
+
+`-background COLOR'
+`-bg COLOR'
+ Use COLOR as the background color.
+
+`-bordercolor COLOR'
+`-bd COLOR'
+ Use COLOR as the border color.
+
+`-borderwidth WIDTH'
+`-bw WIDTH'
+ Use WIDTH as the border width.
+
+`-display DISPLAY'
+`-d DISPLAY'
+ When running under the X window system, create the window
+ containing the Emacs frame on the display named DISPLAY.
+
+`-foreground COLOR'
+`-fg COLOR'
+ Use COLOR as the foreground color.
+
+`-font NAME'
+`-fn NAME'
+ Use NAME as the default font.
+
+`-geometry SPEC'
+`-geom SPEC'
+`-g SPEC'
+ Use the geometry (window size and/or position) specified by SPEC.
+
+`-iconic'
+ Start up iconified.
+
+`-rv'
+ Bring up Emacs in reverse video.
+
+`-name NAME'
+ Use the resource manager resources specified by NAME. The default
+ is to use the name of the program (`argv[0]') as the resource
+ manager name.
+
+`-xrm'
+ Read something into the resource database for this invocation of
+ Emacs only.
+
+\1f
+File: xemacs.info, Node: Startup Paths, Next: Basic, Prev: Command Switches, Up: Top
+
+How XEmacs finds Directories and Files
+======================================
+
+ XEmacs deals with a multitude of files during operation. These files
+are spread over many directories, and XEmacs determines the location of
+most of these directories at startup and organizes them into various
+paths. (A "path", for the purposes of this section, is simply a list
+of directories which XEmacs searches successively in order to locate a
+file.)
+
+XEmacs Directory Hierarchies
+----------------------------
+
+ Many of the files XEmacs looks for are located within the XEmacs
+installation itself. However, there are several views of what actually
+constitutes the "XEmacs installation": XEmacs may be run from the
+compilation directory, it may be installed into arbitrary directories,
+spread over several directories unrelated to each other. Moreover, it
+may subsequently be moved to a different place. (This last case is not
+as uncommon as it sounds. Binary kits work this way.) Consequently,
+XEmacs has quite complex procedures in place to find directories, no
+matter where they may be hidden.
+
+ XEmacs will always respect directory options passed to `configure'.
+However, if it cannot locate a directory at the configured place, it
+will initiate a search for the directory in any of a number of
+"hierarchies" rooted under a directory which XEmacs assumes contain
+parts of the XEmacs installation; it may locate several such hierarchies
+and search across them. (Typically, there are just one or two
+hierarchies: the hierarchy where XEmacs was or will be installed, and
+the one where it is being built.) Such a directory containing a
+hierarchy is called a "root". Whenever this section refers to a
+directory using the shorthand `<root>', it means that XEmacs searches
+for it under all hierarchies under all hierarchies XEmacs was able to
+scrounge up. In a running XEmacs, the hierarchy roots are stored in
+the variable `emacs-roots'.
+
+Package Hierarchies
+-------------------
+
+ Many relevant directories and files XEmacs uses are actually not
+part of the core installation. They are part of any of the many
+packages usually installed on top of an XEmacs installation. (*Note
+Packages::.) Hence, they play a prominent role in the various paths
+XEmacs sets up.
+
+ XEmacs locates packages in any of a number of package hierarchies.
+Package hierarchies fall into three groups: "early", "late", and "last",
+according to the relative location at which they show up in the various
+XEmacs paths. Early package hierarchies are at the very front, late
+ones somewhere in the middle, and last hierarchies are (you guessed it)
+last.
+
+ By default, XEmacs expects an early package hierarchy in the a
+subdirectory `.xemacs' of the user's home directory.
+
+ Moreover, XEmacs expects late hierarchies in the subdirectories
+`site-packages', `mule-packages', and `xemacs-packages' (in that order)
+of the `<root>/lib/xemacs' subdirectory of one of the installation
+hierarchies. (If you run in-place, these are direct subdirectories of
+the build directory.) Furthermore, XEmacs will also search these
+subdirectories in the `<root>/lib/xemacs-<VERSION>' subdirectory and
+prefer directories found there.
+
+ By default, XEmacs does not have a pre-configured last package
+hierarchy. Last hierarchies are primarily for using package hierarchies
+of outdated versions of XEmacs as a fallback option. For example, it is
+possible to run XEmacs 21.0 with the 20.4 package hierarchy as a last
+hierarchy.
+
+ It is possible to specify at configure-time the location of the
+various package hierarchies with the `--package-path' option to
+configure. The early, late, and last components of the package path
+are separated by double instead of single colons. If three components
+are present, they are locate the early, late, and last package
+hierarchies respectively. If two components are present, they locate
+the early and late hierarchies. If only one component is present, it
+locates the late hierarchy. At run time, the package path may also be
+specified via the `PACKAGEPATH' environment variable.
+
+ An XEmacs package is laid out just like a normal installed XEmacs
+lisp directory. It may have `lisp', `etc', `info', and `lib-src'
+subdirectories. XEmacs adds these at appropriate places within the
+various system-wide paths.
+
+ There may be any number of package hierarchy directories.
+
+Directories and Paths
+---------------------
+
+ Here is a list of the various directories and paths XEmacs tries to
+locate during startup. XEmacs distinguishes between directories and
+paths specific to "version", "site", and "architecture" when looking
+for them.
+
+`version-specific'
+ directories are specific to the version of XEmacs they belong to
+ and typically reside under `<root>/lib/xemacs-<VERSION>'.
+
+`site-specific'
+ directories are independent of the version of XEmacs they belong
+ to and typically reside under `<root>/lib/xemacs'
+
+`architecture-specific'
+ directories are specific both to the version of XEmacs and the
+ architecture it runs on and typically reside under
+ `<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>'.
+
+ During installation, all of these directories may also reside
+directly under `<root>', because that is where they are in the XEmacs
+tarball.
+
+ If XEmacs runs with the `-debug-paths' option (*note Command
+Switches::.), it will print the values of these variables, hopefully
+aiding in debugging any problems which come up.
+
+`lisp-directory'
+ Contains the version-specific location of the Lisp files that come
+ with the core distribution of XEmacs. XEmacs will search it
+ recursively to a depth of 1 when setting up `load-path'.
+
+`load-path'
+ Is where XEmacs searches for XEmacs Lisp files with commands like
+ `load-library'. It contains the package lisp directories (see
+ further down) and the version-specific core Lisp directories. If
+ the environment variable `EMACSLOADPATH' is set at startup, its
+ directories are prepended to `load-path'.
+
+`Info-directory-list'
+ Contains the location of info files. (See *Note (info)::.) It
+ contains the package info directories and the version-specific core
+ documentation. Moreover, XEmacs will add `/usr/info',
+ `/usr/local/info' as well as the directories of the environment
+ variable `INFOPATH' to `Info-directory-list'.
+
+`lock-directory'
+`superlock-file'
+ Are the site-specific locations of the lock directory and the
+ superlock file, respectively. The `lock-directory' variable may
+ also be initialized from the `EMACSLOCKDIR' environment variable.
+
+`exec-directory'
+ Is the directory of architecture-dependent files that come with
+ XEmacs, especially executable programs intended for XEmacs to
+ invoke.
+
+`exec-path'
+ Is the path for executables which XEmacs may want to start. It
+ contains the package executable paths as well as `exec-directory',
+ and the directories of the environment variables `PATH' and
+ `EMACSPATH'.
+
+`doc-directory'
+ Is the directory containing the architecture-specific `DOC' file
+ that contains documentation for XEmacs' commands.
+
+`data-directory'
+ Is the version-specific directory that contains core data files
+ XEmacs uses. It may be initialized from the `EMACSDATA'
+ environment variable.
+
+`data-directory-list'
+ Is the path where XEmacs looks for data files. It contains
+ package data directories as well as `data-directory'.
+
+\1f
+File: xemacs.info, Node: Basic, Next: Undo, Prev: Startup Paths, Up: Top
+
+Basic Editing Commands
+**********************
+
+ We now give the basics of how to enter text, make corrections, and
+save the text in a file. If this material is new to you, you might
+learn it more easily by running the Emacs learn-by-doing tutorial. To
+do this, type `Control-h t' (`help-with-tutorial').
+
+Inserting Text
+==============
+
+ To insert printing characters into the text you are editing, just
+type them. This inserts the characters into the buffer at the cursor
+(that is, at "point"; *note Point::.). The cursor moves forward. Any
+characters after the cursor move forward too. If the text in the buffer
+is `FOOBAR', with the cursor before the `B', and you type `XX', the
+result is `FOOXXBAR', with the cursor still before the `B'.
+
+ To "delete" text you have just inserted, use <DEL>. <DEL> deletes
+the character BEFORE the cursor (not the one that the cursor is on top
+of or under; that is the character AFTER the cursor). The cursor and
+all characters after it move backwards. Therefore, if you type a
+printing character and then type <DEL>, they cancel out.
+
+ To end a line and start typing a new one, type <RET>. This inserts
+a newline character in the buffer. If point is in the middle of a
+line, <RET> splits the line. Typing <DEL> when the cursor is at the
+beginning of a line rubs out the newline before the line, thus joining
+the line with the preceding line.
+
+ Emacs automatically splits lines when they become too long, if you
+turn on a special mode called "Auto Fill" mode. *Note Filling::, for
+information on using Auto Fill mode.
+
+ Customization information: <DEL>, in most modes, runs the command
+`delete-backward-char'; <RET> runs the command `newline', and
+self-inserting printing characters run the command `self-insert', which
+inserts whatever character was typed to invoke it. Some major modes
+rebind <DEL> to other commands.
+
+ Direct insertion works for printing characters and <SPC>, but other
+characters act as editing commands and do not insert themselves. If
+you need to insert a control character or a character whose code is
+above 200 octal, you must "quote" it by typing the character
+`control-q' (`quoted-insert') first. There are two ways to use `C-q':
+
+ * `Control-q' followed by any non-graphic character (even `C-g')
+ inserts that character.
+
+ * `Control-q' followed by three octal digits inserts the character
+ with the specified character code.
+
+A numeric argument to `C-q' specifies how many copies of the quoted
+character should be inserted (*note Arguments::.).
+
+ If you prefer to have text characters replace (overwrite) existing
+text instead of moving it to the right, you can enable Overwrite mode, a
+minor mode. *Note Minor Modes::.
+
+Changing the Location of Point
+==============================
+
+ To do more than insert characters, you have to know how to move point
+(*note Point::.). Here are a few of the available commands.
+
+ NOTE: Many of the following commands have two versions, one that uses
+the function keys (e.g. <LEFT> or <END>) and one that doesn't. The
+former versions may only be available on X terminals (i.e. not on
+TTY's), but the latter are available on all terminals.
+
+`C-a'
+`HOME'
+ Move to the beginning of the line (`beginning-of-line').
+
+`C-e'
+`END'
+ Move to the end of the line (`end-of-line').
+
+`C-f'
+`RIGHT'
+ Move forward one character (`forward-char').
+
+`C-b'
+`LEFT'
+ Move backward one character (`backward-char').
+
+`M-f'
+`C-RIGHT'
+ Move forward one word (`forward-word').
+
+`M-b'
+`C-LEFT'
+ Move backward one word (`backward-word').
+
+`C-n'
+`DOWN'
+ Move down one line, vertically (`next-line'). This command
+ attempts to keep the horizontal position unchanged, so if you
+ start in the middle of one line, you end in the middle of the
+ next. When on the last line of text, `C-n' creates a new line and
+ moves onto it.
+
+`C-p'
+`UP'
+ Move up one line, vertically (`previous-line').
+
+`C-v'
+`PGDN'
+ Move down one page, vertically (`scroll-up').
+
+`M-v'
+`PGUP'
+ Move up one page, vertically (`scroll-down').
+
+`C-l'
+ Clear the frame and reprint everything (`recenter'). Text moves
+ on the frame to bring point to the center of the window.
+
+`M-r'
+ Move point to left margin on the line halfway down the frame or
+ window (`move-to-window-line'). Text does not move on the frame.
+ A numeric argument says how many screen lines down from the top of
+ the window (zero for the top). A negative argument counts from
+ the bottom (-1 for the bottom).
+
+`C-t'
+ Transpose two characters, the ones before and after the cursor
+ (`transpose-chars').
+
+`M-<'
+`C-HOME'
+ Move to the top of the buffer (`beginning-of-buffer'). With
+ numeric argument N, move to N/10 of the way from the top. *Note
+ Arguments::, for more information on numeric arguments.
+
+`M->'
+`C-END'
+ Move to the end of the buffer (`end-of-buffer').
+
+`M-x goto-char'
+ Read a number N and move the cursor to character number N.
+ Position 1 is the beginning of the buffer.
+
+`M-g'
+ Read a number N and move cursor to line number N (`goto-line').
+ Line 1 is the beginning of the buffer.
+
+`C-x C-n'
+ Use the current column of point as the "semi-permanent goal
+ column" for `C-n' and `C-p' (`set-goal-column'). Henceforth, those
+ commands always move to this column in each line moved into, or as
+ close as possible given the contents of the line. This goal
+ column remains in effect until canceled.
+
+`C-u C-x C-n'
+ Cancel the goal column. Henceforth, `C-n' and `C-p' once again
+ try to avoid changing the horizontal position, as usual.
+
+ If you set the variable `track-eol' to a non-`nil' value, `C-n' and
+`C-p' move to the end of the line when at the end of the starting line.
+By default, `track-eol' is `nil'.
+
+Erasing Text
+============
+
+`<DEL>'
+ Delete the character before the cursor (`delete-backward-char').
+
+`C-d'
+ Delete the character after the cursor (`delete-char').
+
+`C-k'
+ Kill to the end of the line (`kill-line').
+
+`M-d'
+ Kill forward to the end of the next word (`kill-word').
+
+`M-<DEL>'
+ Kill back to the beginning of the previous word
+ (`backward-kill-word').
+
+ In contrast to the <DEL> key, which deletes the character before the
+cursor, `Control-d' deletes the character after the cursor, causing the
+rest of the text on the line to shift left. If `Control-d' is typed at
+the end of a line, that line and the next line are joined.
+
+ To erase a larger amount of text, use `Control-k', which kills a
+line at a time. If you use `C-k' at the beginning or in the middle of
+a line, it kills all the text up to the end of the line. If you use
+`C-k' at the end of a line, it joins that line and the next line.
+
+ *Note Killing::, for more flexible ways of killing text.
+
+Files
+=====
+
+ The commands above are sufficient for creating and altering text in
+an Emacs buffer. More advanced Emacs commands just make things easier.
+But to keep any text permanently you must put it in a "file". Files
+are named units of text which are stored by the operating system and
+which you can retrieve by name. To look at or use the contents of a
+file in any way, including editing the file with Emacs, you must
+specify the file name.
+
+ Consider a file named `/usr/rms/foo.c'. To begin editing this file
+from Emacs, type:
+
+ C-x C-f /usr/rms/foo.c <RET>
+
+The file name is given as an "argument" to the command `C-x C-f'
+(`find-file'). The command uses the "minibuffer" to read the argument.
+You have to type <RET> to terminate the argument (*note Minibuffer::.).
+
+ You can also use the Open... menu item from the File menu, then type
+the name of the file to the prompt.
+
+ Emacs obeys the command by "visiting" the file: it creates a buffer,
+copies the contents of the file into the buffer, and then displays the
+buffer for you to edit. You can make changes in the buffer, and then
+"save" the file by typing `C-x C-s' (`save-buffer') or choosing Save
+Buffer from the File menu. This makes the changes permanent by copying
+the altered contents of the buffer back into the file `/usr/rms/foo.c'.
+Until then, the changes are only inside your Emacs buffer, and the
+file `foo.c' is not changed.
+
+ To create a file, visit the file with `C-x C-f' as if it already
+existed or choose Open... from the File menu and provide the name for
+the new file in the minibuffer. Emacs will create an empty buffer in
+which you can insert the text you want to put in the file. When you
+save the buffer with `C-x C-s', or by choosing Save Buffer from the
+File menu, the file is created.
+
+ To learn more about using files, *note Files::..
+
+Help
+====
+
+ If you forget what a key does, you can use the Help character
+(`C-h') to find out: Type `C-h k' followed by the key you want to know
+about. For example, `C-h k C-n' tells you what `C-n' does. `C-h' is a
+prefix key; `C-h k' is just one of its subcommands (the command
+`describe-key'). The other subcommands of `C-h' provide different
+kinds of help. Type `C-h' three times to get a description of all the
+help facilities. *Note Help::.
+
+* Menu:
+
+* Blank Lines:: Commands to make or delete blank lines.
+* Continuation Lines:: Lines too wide for the frame.
+* Position Info:: What page, line, row, or column is point on?
+* Arguments:: Numeric arguments for repeating a command.
+
+\1f
+File: xemacs.info, Node: Blank Lines, Next: Continuation Lines, Prev: Basic, Up: Basic
+
+Blank Lines
+===========
+
+ Here are special commands and techniques for entering and removing
+blank lines.
+
+`C-o'
+ Insert one or more blank lines after the cursor (`open-line').
+
+`C-x C-o'
+ Delete all but one of many consecutive blank lines
+ (`delete-blank-lines').
+
+ When you want to insert a new line of text before an existing line,
+you just type the new line of text, followed by <RET>. If you prefer
+to create a blank line first and then insert the desired text, use the
+key `C-o' (`open-line'), which inserts a newline after point but leaves
+point in front of the newline. Then type the text into the new line.
+`C-o F O O' has the same effect as `F O O <RET>', except for the final
+location of point.
+
+ To create several blank lines, type `C-o' several times, or give
+`C-o' an argument indicating how many blank lines to create. *Note
+Arguments::, for more information.
+
+ If you have many blank lines in a row and want to get rid of them,
+use `C-x C-o' (`delete-blank-lines'). If point is on a blank line
+which is adjacent to at least one other blank line, `C-x C-o' deletes
+all but one of the blank lines. If point is on a blank line with no
+other adjacent blank line, the sole blank line is deleted. If point is
+on a non-blank line, `C-x C-o' deletes any blank lines following that
+non-blank line.
+
+\1f
+File: xemacs.info, Node: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic
+
+Continuation Lines
+==================
+
+ If you add too many characters to one line without breaking with a
+<RET>, the line grows to occupy two (or more) screen lines, with a
+curved arrow at the extreme right margin of all but the last line. The
+curved arrow indicates that the following screen line is not really a
+distinct line in the text, but just the "continuation" of a line too
+long to fit the frame. You can use Auto Fill mode (*note Filling::.)
+to have Emacs insert newlines automatically when a line gets too long.
+
+ Instead of continuation, long lines can be displayed by "truncation".
+This means that all the characters that do not fit in the width of the
+frame or window do not appear at all. They remain in the buffer,
+temporarily invisible. Three diagonal dots in the last column (instead
+of the curved arrow inform you that truncation is in effect.
+
+ To turn off continuation for a particular buffer, set the variable
+`truncate-lines' to non-`nil' in that buffer. Truncation instead of
+continuation also happens whenever horizontal scrolling is in use, and
+optionally whenever side-by-side windows are in use (*note Windows::.).
+Altering the value of `truncate-lines' makes it local to the current
+buffer; until that time, the default value is in effect. The default
+is initially `nil'. *Note Locals::.
+
+\1f
+File: xemacs.info, Node: Position Info, Next: Arguments, Prev: Continuation Lines, Up: Basic
+
+Cursor Position Information
+===========================
+
+ If you are accustomed to other display editors, you may be surprised
+that Emacs does not always display the page number or line number of
+point in the mode line. In Emacs, this information is only rarely
+needed, and a number of commands are available to compute and print it.
+Since text is stored in a way that makes it difficult to compute the
+information, it is not displayed all the time.
+
+`M-x what-page'
+ Print page number of point, and line number within page.
+
+`M-x what-line'
+ Print line number of point in the buffer.
+
+`M-='
+ Print number of lines and characters in the current region
+ (`count-lines-region').
+
+`C-x ='
+ Print character code of character after point, character position
+ of point, and column of point (`what-cursor-position').
+
+ There are several commands for printing line numbers:
+ * `M-x what-line' counts lines from the beginning of the file and
+ prints the line number point is on. The first line of the file is
+ line number 1. You can use these numbers as arguments to `M-x
+ goto-line'.
+
+ * `M-x what-page' counts pages from the beginning of the file, and
+ counts lines within the page, printing both of them. *Note
+ Pages::, for the command `C-x l', which counts the lines in the
+ current page.
+
+ * `M-=' (`count-lines-region') prints the number of lines in the
+ region (*note Mark::.).
+
+ The command `C-x =' (`what-cursor-position') provides information
+about point and about the column the cursor is in. It prints a line in
+the echo area that looks like this:
+
+ Char: x (0170) point=65986 of 563027(12%) column 44
+
+(In fact, this is the output produced when point is before `column 44'
+in the example.)
+
+ The two values after `Char:' describe the character following point,
+first by showing it and second by giving its octal character code.
+
+ `point=' is followed by the position of point expressed as a
+character count. The front of the buffer counts as position 1, one
+character later as 2, and so on. The next, larger number is the total
+number of characters in the buffer. Afterward in parentheses comes the
+position expressed as a percentage of the total size.
+
+ `column' is followed by the horizontal position of point, in columns
+from the left edge of the window.
+
+ If the buffer has been narrowed, making some of the text at the
+beginning and the end temporarily invisible, `C-x =' prints additional
+text describing the current visible range. For example, it might say:
+
+ Char: x (0170) point=65986 of 563025(12%) <65102 - 68533> column 44
+
+where the two extra numbers give the smallest and largest character
+position that point is allowed to assume. The characters between those
+two positions are the visible ones. *Note Narrowing::.
+
+ If point is at the end of the buffer (or the end of the visible
+part), `C-x =' omits any description of the character after point. The
+output looks like
+
+ point=563026 of 563025(100%) column 0
+
+\1f
+File: xemacs.info, Node: Arguments, Prev: Position Info, Up: Basic
+
+Numeric Arguments
+=================
+
+ Any Emacs command can be given a "numeric argument". Some commands
+interpret the argument as a repetition count. For example, giving an
+argument of ten to the key `C-f' (the command `forward-char', move
+forward one character) moves forward ten characters. With these
+commands, no argument is equivalent to an argument of one. Negative
+arguments are allowed. Often they tell a command to move or act
+backwards.
+
+ If your keyboard has a <META> key (labelled with a diamond on
+Sun-type keyboards and labelled `Alt' on some other keyboards), the
+easiest way to specify a numeric argument is to type digits and/or a
+minus sign while holding down the <META> key. For example,
+ M-5 C-n
+
+moves down five lines. The characters `Meta-1', `Meta-2', and so on,
+as well as `Meta--', do this because they are keys bound to commands
+(`digit-argument' and `negative-argument') that are defined to
+contribute to an argument for the next command.
+
+ Another way of specifying an argument is to use the `C-u'
+(`universal-argument') command followed by the digits of the argument.
+With `C-u', you can type the argument digits without holding down shift
+keys. To type a negative argument, start with a minus sign. Just a
+minus sign normally means -1. `C-u' works on all terminals.
+
+ `C-u' followed by a character which is neither a digit nor a minus
+sign has the special meaning of "multiply by four". It multiplies the
+argument for the next command by four. `C-u' twice multiplies it by
+sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This
+is a good way to move forward "fast", since it moves about 1/5 of a line
+in the usual size frame. Other useful combinations are `C-u C-n', `C-u
+C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a
+lot" of blank lines), and `C-u C-k' (kill four lines).
+
+ Some commands care only about whether there is an argument and not
+about its value. For example, the command `M-q' (`fill-paragraph') with
+no argument fills text; with an argument, it justifies the text as well.
+(*Note Filling::, for more information on `M-q'.) Just `C-u' is a
+handy way of providing an argument for such commands.
+
+ Some commands use the value of the argument as a repeat count, but do
+something peculiar when there is no argument. For example, the command
+`C-k' (`kill-line') with argument N kills N lines, including their
+terminating newlines. But `C-k' with no argument is special: it kills
+the text up to the next newline, or, if point is right at the end of
+the line, it kills the newline itself. Thus, two `C-k' commands with
+no arguments can kill a non-blank line, just like `C-k' with an
+argument of one. (*Note Killing::, for more information on `C-k'.)
+
+ A few commands treat a plain `C-u' differently from an ordinary
+argument. A few others may treat an argument of just a minus sign
+differently from an argument of -1. These unusual cases will be
+described when they come up; they are always to make the individual
+command more convenient to use.
+
+\1f
+File: xemacs.info, Node: Undo, Next: Minibuffer, Prev: Basic, Up: Top
+
+Undoing Changes
+***************
+
+ Emacs allows you to undo all changes you make to the text of a
+buffer, up to a certain amount of change (8000 characters). Each
+buffer records changes individually, and the undo command always
+applies to the current buffer. Usually each editing command makes a
+separate entry in the undo records, but some commands such as
+`query-replace' make many entries, and very simple commands such as
+self-inserting characters are often grouped to make undoing less
+tedious.
+
+`C-x u'
+ Undo one batch of changes (usually, one command's worth) (`undo').
+
+`C-_'
+ The same.
+
+ The command `C-x u' or `C-_' allows you to undo changes. The first
+time you give this command, it undoes the last change. Point moves to
+the text affected by the undo, so you can see what was undone.
+
+ Consecutive repetitions of the `C-_' or `C-x u' commands undo
+earlier and earlier changes, back to the limit of what has been
+recorded. If all recorded changes have already been undone, the undo
+command prints an error message and does nothing.
+
+ Any command other than an undo command breaks the sequence of undo
+commands. Starting at this moment, the previous undo commands are
+considered ordinary changes that can themselves be undone. Thus, you
+can redo changes you have undone by typing `C-f' or any other command
+that have no important effect, and then using more undo commands.
+
+ If you notice that a buffer has been modified accidentally, the
+easiest way to recover is to type `C-_' repeatedly until the stars
+disappear from the front of the mode line. When that happens, all the
+modifications you made have been canceled. If you do not remember
+whether you changed the buffer deliberately, type `C-_' once. When you
+see Emacs undo the last change you made, you probably remember why you
+made it. If the change was an accident, leave it undone. If it was
+deliberate, redo the change as described in the preceding paragraph.
+
+ Whenever an undo command makes the stars disappear from the mode
+line, the buffer contents is the same as it was when the file was last
+read in or saved.
+
+ Not all buffers record undo information. Buffers whose names start
+with spaces don't; these buffers are used internally by Emacs and its
+extensions to hold text that users don't normally look at or edit.
+Minibuffers, help buffers, and documentation buffers also don't record
+undo information.
+
+ Emacs can remember at most 8000 or so characters of deleted or
+modified text in any one buffer for reinsertion by the undo command.
+There is also a limit on the number of individual insert, delete, or
+change actions that Emacs can remember.
+
+ There are two keys to run the `undo' command, `C-x u' and `C-_',
+because on some keyboards, it is not obvious how to type `C-_'. `C-x u'
+is an alternative you can type in the same fashion on any terminal.
+
+\1f
+File: xemacs.info, Node: Minibuffer, Next: M-x, Prev: Undo, Up: Top
+
+The Minibuffer
+**************
+
+ Emacs commands use the "minibuffer" to read arguments more
+complicated than a single number. Minibuffer arguments can be file
+names, buffer names, Lisp function names, Emacs command names, Lisp
+expressions, and many other things, depending on the command reading the
+argument. To edit the argument in the minibuffer, you can use Emacs
+editing commands.
+
+ When the minibuffer is in use, it appears in the echo area, and the
+cursor moves there. The beginning of the minibuffer line displays a
+"prompt" indicating what kind of input you should supply and how it
+will be used. The prompt is often derived from the name of the command
+the argument is for. The prompt normally ends with a colon.
+
+ Sometimes a "default argument" appears in parentheses after the
+colon; it, too, is part of the prompt. The default is used as the
+argument value if you enter an empty argument (e.g., by just typing
+<RET>). For example, commands that read buffer names always show a
+default, which is the name of the buffer that will be used if you type
+just <RET>.
+
+ The simplest way to give a minibuffer argument is to type the text
+you want, terminated by <RET> to exit the minibuffer. To get out of
+the minibuffer and cancel the command that it was for, type `C-g'.
+
+ Since the minibuffer uses the screen space of the echo area, it can
+conflict with other ways Emacs customarily uses the echo area. Here is
+how Emacs handles such conflicts:
+
+ * If a command gets an error while you are in the minibuffer, this
+ does not cancel the minibuffer. However, the echo area is needed
+ for the error message and therefore the minibuffer itself is
+ hidden for a while. It comes back after a few seconds, or as soon
+ as you type anything.
+
+ * If you use a command in the minibuffer whose purpose is to print a
+ message in the echo area (for example `C-x =') the message is
+ displayed normally, and the minibuffer is hidden for a while. It
+ comes back after a few seconds, or as soon as you type anything.
+
+ * Echoing of keystrokes does not take place while the minibuffer is
+ in use.
+
+* Menu:
+
+* File: Minibuffer File. Entering file names with the minibuffer.
+* Edit: Minibuffer Edit. How to edit in the minibuffer.
+* Completion:: An abbreviation facility for minibuffer input.
+* Repetition:: Re-executing commands that used the minibuffer.
+
+\1f
+File: xemacs.info, Node: Minibuffer File, Next: Minibuffer Edit, Prev: Minibuffer, Up: Minibuffer
+
+Minibuffers for File Names
+==========================
+
+ Sometimes the minibuffer starts out with text in it. For example,
+when you are supposed to give a file name, the minibuffer starts out
+containing the "default directory", which ends with a slash. This
+informs you in which directory the file will be looked for if you do
+not specify a different one. For example, the minibuffer might start
+out with:
+
+ Find File: /u2/emacs/src/
+
+where `Find File: ' is the prompt. Typing `buffer.c' specifies the file
+`/u2/emacs/src/buffer.c'. To find files in nearby directories, use
+`..'; thus, if you type `../lisp/simple.el', the file that you visit
+will be the one named
+`/u2/emacs/lisp/simple.el'. Alternatively, you can use `M-<DEL>' to
+kill directory names you don't want (*note Words::.).
+
+ You can also type an absolute file name, one starting with a slash
+or a tilde, ignoring the default directory. For example, to find the
+file `/etc/termcap', just type the name, giving:
+
+ Find File: /u2/emacs/src//etc/termcap
+
+Two slashes in a row are not normally meaningful in Unix file names, but
+they are allowed in XEmacs. They mean, "ignore everything before the
+second slash in the pair." Thus, `/u2/emacs/src/' is ignored, and you
+get the file `/etc/termcap'.
+
+ If you set `insert-default-directory' to `nil', the default
+directory is not inserted in the minibuffer. This way, the minibuffer
+starts out empty. But the name you type, if relative, is still
+interpreted with respect to the same default directory.
+
+\1f
+File: xemacs.info, Node: Minibuffer Edit, Next: Completion, Prev: Minibuffer File, Up: Minibuffer
+
+Editing in the Minibuffer
+=========================
+
+ The minibuffer is an Emacs buffer (albeit a peculiar one), and the
+usual Emacs commands are available for editing the text of an argument
+you are entering.
+
+ Since <RET> in the minibuffer is defined to exit the minibuffer, you
+must use `C-o' or `C-q <LFD>' to insert a newline into the minibuffer.
+(Recall that a newline is really the <LFD> character.)
+
+ The minibuffer has its own window, which always has space on the
+screen but acts as if it were not there when the minibuffer is not in
+use. The minibuffer window is just like the others; you can switch to
+another window with `C-x o', edit text in other windows, and perhaps
+even visit more files before returning to the minibuffer to submit the
+argument. You can kill text in another window, return to the minibuffer
+window, and then yank the text to use it in the argument. *Note
+Windows::.
+
+ There are, however, some restrictions on the use of the minibuffer
+window. You cannot switch buffers in it--the minibuffer and its window
+are permanently attached. You also cannot split or kill the minibuffer
+window, but you can make it taller with `C-x ^'.
+
+ If you are in the minibuffer and issue a command that displays help
+text in another window, that window will be scrolled if you type
+`M-C-v' while in the minibuffer until you exit the minibuffer. This
+feature is helpful if a completing minibuffer gives you a long list of
+possible completions.
+
+ If the variable `minibuffer-confirm-incomplete' is `t', you are
+asked for confirmation if there is no known completion for the text you
+typed. For example, if you attempted to visit a non-existent file, the
+minibuffer might read:
+ Find File:chocolate_bar.c [no completions, confirm]
+ If you press `Return' again, that confirms the filename. Otherwise,
+you can continue editing it.
+
+ Emacs supports recursive use of the minibuffer. However, it is easy
+to do this by accident (because of autorepeating keyboards, for
+example) and get confused. Therefore, most Emacs commands that use the
+minibuffer refuse to operate if the minibuffer window is selected. If
+the minibuffer is active but you have switched to a different window,
+recursive use of the minibuffer is allowed--if you know enough to try
+to do this, you probably will not get confused.
+
+ If you set the variable `enable-recursive-minibuffers' to be
+non-`nil', recursive use of the minibuffer is always allowed.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Completion, Next: Repetition, Prev: Minibuffer Edit, Up: Minibuffer
+
+Completion
+==========
+
+ When appropriate, the minibuffer provides a "completion" facility.
+You type the beginning of an argument and one of the completion keys,
+and Emacs visibly fills in the rest, depending on what you have already
+typed.
+
+ When completion is available, certain keys--<TAB>, <RET>, and
+<SPC>--are redefined to complete an abbreviation present in the
+minibuffer into a longer string that it stands for, by matching it
+against a set of "completion alternatives" provided by the command
+reading the argument. `?' is defined to display a list of possible
+completions of what you have inserted.
+
+ For example, when the minibuffer is being used by `Meta-x' to read
+the name of a command, it is given a list of all available Emacs command
+names to complete against. The completion keys match the text in the
+minibuffer against all the command names, find any additional
+characters of the name that are implied by the ones already present in
+the minibuffer, and add those characters to the ones you have given.
+
+ Case is normally significant in completion because it is significant
+in most of the names that you can complete (buffer names, file names,
+and command names). Thus, `fo' will not complete to `Foo'. When you
+are completing a name in which case does not matter, case may be ignored
+for completion's sake if specified by program.
+
+ When a completion list is displayed, the completions will highlight
+as you move the mouse over them. Clicking the middle mouse button on
+any highlighted completion will "select" it just as if you had typed it
+in and hit <RET>.
+
+A Completion Example
+--------------------
+
+ Consider the following example. If you type `Meta-x au <TAB>',
+<TAB> looks for alternatives (in this case, command names) that start
+with `au'. There are only two commands: `auto-fill-mode' and
+`auto-save-mode'. They are the same as far as `auto-', so the `au' in
+the minibuffer changes to `auto-'.
+
+ If you type <TAB> again immediately, there are multiple possibilities
+for the very next character--it could be `s' or `f'--so no more
+characters are added; but a list of all possible completions is
+displayed in another window.
+
+ If you go on to type `f <TAB>', this <TAB> sees `auto-f'. The only
+command name starting this way is `auto-fill-mode', so completion
+inserts the rest of that command. You now have `auto-fill-mode' in the
+minibuffer after typing just `au <TAB> f <TAB>'. Note that <TAB> has
+this effect because in the minibuffer it is bound to the function
+`minibuffer-complete' when completion is supposed to be done.
+
+Completion Commands
+-------------------
+
+ Here is a list of all the completion commands defined in the
+minibuffer when completion is available.
+
+`<TAB>'
+ Complete the text in the minibuffer as much as possible
+ (`minibuffer-complete').
+
+`<SPC>'
+ Complete the text in the minibuffer but don't add or fill out more
+ than one word (`minibuffer-complete-word').
+
+`<RET>'
+ Submit the text in the minibuffer as the argument, possibly
+ completing first as described below
+ (`minibuffer-complete-and-exit').
+
+`?'
+ Print a list of all possible completions of the text in the
+ minibuffer (`minibuffer-list-completions').
+
+`<button2>'
+ Select the highlighted text under the mouse as a minibuffer
+ response. When the minibuffer is being used to prompt the user
+ for a completion, any valid completions which are visible on the
+ screen will be highlighted when the mouse moves over them.
+ Clicking <button2> will select the highlighted completion and exit
+ the minibuffer. (`minibuf-select-highlighted-completion').
+
+ <SPC> completes in a way that is similar to <TAB>, but it never goes
+beyond the next hyphen or space. If you have `auto-f' in the
+minibuffer and type <SPC>, it finds that the completion is
+`auto-fill-mode', but it stops completing after `fill-'. The result is
+`auto-fill-'. Another <SPC> at this point completes all the way to
+`auto-fill-mode'. <SPC> in the minibuffer runs the function
+`minibuffer-complete-word' when completion is available.
+
+ There are three different ways that <RET> can work in completing
+minibuffers, depending on how the argument will be used.
+
+ * "Strict" completion is used when it is meaningless to give any
+ argument except one of the known alternatives. For example, when
+ `C-x k' reads the name of a buffer to kill, it is meaningless to
+ give anything but the name of an existing buffer. In strict
+ completion, <RET> refuses to exit if the text in the minibuffer
+ does not complete to an exact match.
+
+ * "Cautious" completion is similar to strict completion, except that
+ <RET> exits only if the text was an exact match already, not
+ needing completion. If the text is not an exact match, <RET> does
+ not exit, but it does complete the text. If it completes to an
+ exact match, a second <RET> will exit.
+
+ Cautious completion is used for reading file names for files that
+ must already exist.
+
+ * "Permissive" completion is used when any string is meaningful, and
+ the list of completion alternatives is just a guide. For example,
+ when `C-x C-f' reads the name of a file to visit, any file name is
+ allowed, in case you want to create a file. In permissive
+ completion, <RET> takes the text in the minibuffer exactly as
+ given, without completing it.
+
+ The completion commands display a list of all possible completions
+in a window whenever there is more than one possibility for the very
+next character. Typing `?' explicitly requests such a list. The list
+of completions counts as help text, so `C-M-v' typed in the minibuffer
+scrolls the list.
+
+ When completion is done on file names, certain file names are usually
+ignored. The variable `completion-ignored-extensions' contains a list
+of strings; a file whose name ends in any of those strings is ignored
+as a possible completion. The standard value of this variable has
+several elements including `".o"', `".elc"', `".dvi"' and `"~"'. The
+effect is that, for example, `foo' completes to `foo.c' even though
+`foo.o' exists as well. If the only possible completions are files
+that end in "ignored" strings, they are not ignored.
+
+ If a completion command finds the next character is undetermined, it
+automatically displays a list of all possible completions. If the
+variable `completion-auto-help' is set to `nil', this does not happen,
+and you must type `?' to display the possible completions.
+
+ If the variable `minibuffer-confirm-incomplete' is set to `t', then
+in contexts where `completing-read' allows answers that are not valid
+completions, an extra <RET> must be typed to confirm the response.
+This is helpful for catching typos.
+
+\1f
+File: xemacs.info, Node: Repetition, Prev: Completion, Up: Minibuffer
+
+Repeating Minibuffer Commands
+=============================
+
+ Every command that uses the minibuffer at least once is recorded on a
+special history list, together with the values of the minibuffer
+arguments, so that you can repeat the command easily. In particular,
+every use of `Meta-x' is recorded, since `M-x' uses the minibuffer to
+read the command name.
+
+`C-x <ESC>'
+ Re-execute a recent minibuffer command
+ (`repeat-complex-command').
+
+`M-p'
+ Within `C-x <ESC>', move to previous recorded command
+ (`previous-history-element').
+
+`M-n'
+ Within `C-x <ESC>', move to the next (more recent) recorded
+ command (`next-history-element').
+
+`M-x list-command-history'
+ Display the entire command history, showing all the commands `C-x
+ <ESC>' can repeat, most recent first.
+
+ `C-x <ESC>' is used to re-execute a recent command that used the
+minibuffer. With no argument, it repeats the last command. A numeric
+argument specifies which command to repeat; 1 means the last one, and
+larger numbers specify earlier commands.
+
+ `C-x <ESC>' works by turning the previous command into a Lisp
+expression and then entering a minibuffer initialized with the text for
+that expression. If you type just <RET>, the command is repeated as
+before. You can also change the command by editing the Lisp expression.
+The expression you finally submit will be executed. The repeated
+command is added to the front of the command history unless it is
+identical to the most recently executed command already there.
+
+ Even if you don't understand Lisp syntax, it will probably be obvious
+which command is displayed for repetition. If you do not change the
+text, you can be sure the command will repeat exactly as before.
+
+ If you are in the minibuffer for `C-x <ESC>' and the command shown
+to you is not the one you want to repeat, you can move around the list
+of previous commands using `M-n' and `M-p'. `M-p' replaces the
+contents of the minibuffer with the next earlier recorded command, and
+`M-n' replaces it with the next later command. After finding the
+desired previous command, you can edit its expression and then resubmit
+it by typing <RET>. Any editing you have done on the command to be
+repeated is lost if you use `M-n' or `M-p'.
+
+ `M-n' and `M-p' are specially defined within `C-x <ESC>' to run the
+commands `previous-history-element' and `next-history-element'.
+
+ The list of previous commands using the minibuffer is stored as a
+Lisp list in the variable `command-history'. Each element of the list
+is a Lisp expression which describes one command and its arguments.
+Lisp programs can reexecute a command by feeding the corresponding
+`command-history' element to `eval'.
+
+\1f
+File: xemacs.info, Node: M-x, Next: Help, Prev: Minibuffer, Up: Top
+
+Running Commands by Name
+************************
+
+ The Emacs commands that are used often or that must be quick to type
+are bound to keys--short sequences of characters--for convenient use.
+Other Emacs commands that are used more rarely are not bound to keys;
+to run them, you must refer to them by name.
+
+ A command name consists, by convention, of one or more words,
+separated by hyphens: for example, `auto-fill-mode' or `manual-entry'.
+The use of English words makes the command name easier to remember than
+a key made up of obscure characters, even though it results in more
+characters to type. You can run any command by name, even if it can be
+run by keys as well.
+
+ To run a command by name, start with `M-x', then type the command
+name, and finish with <RET>. `M-x' uses the minibuffer to read the
+command name. <RET> exits the minibuffer and runs the command.
+
+ Emacs uses the minibuffer for reading input for many different
+purposes; on this occasion, the string `M-x' is displayed at the
+beginning of the minibuffer as a "prompt" to remind you that your input
+should be the name of a command to be run. *Note Minibuffer::, for
+full information on the features of the minibuffer.
+
+ You can use completion to enter a command name. For example, to
+invoke the command `forward-char', type:
+
+ M-x forward-char <RET>
+ or
+ M-x fo <TAB> c <RET>
+
+After you type in `M-x fo TAB' emacs will give you a possible list of
+completions from which you can choose. Note that `forward-char' is the
+same command that you invoke with the key `C-f'. You can call any
+command (interactively callable function) defined in Emacs by its name
+using `M-x' regardless of whether or not any keys are bound to it.
+
+ If you type `C-g' while Emacs reads the command name, you cancel the
+`M-x' command and get out of the minibuffer, ending up at top level.
+
+ To pass a numeric argument to a command you are invoking with `M-x',
+specify the numeric argument before the `M-x'. `M-x' passes the
+argument along to the function that it calls. The argument value
+appears in the prompt while the command name is being read.
+
+ You can use the command `M-x interactive' to specify a way of
+parsing arguments for interactive use of a function. For example,
+write:
+
+ (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
+
+ to make `arg' be the prefix argument when `foo' is called as a
+command. The call to `interactive' is actually a declaration rather
+than a function; it tells `call-interactively' how to read arguments to
+pass to the function. When actually called, `interactive' returns
+`nil'.
+
+ The argument of INTERACTIVE is usually a string containing a code
+letter followed by a prompt. Some code letters do not use I/O to get
+the argument and do not need prompts. To prompt for multiple arguments,
+you must provide a code letter, its prompt, a newline, and another code
+letter, and so forth. If the argument is not a string, it is evaluated
+to get a list of arguments to pass to the function. If you do not
+provide an argument to `interactive', no arguments are passed when
+calling interactively.
+
+ Available code letters are:
+
+`a'
+ Function name: symbol with a function definition
+
+`b'
+ Name of existing buffer
+
+`B'
+ Name of buffer, possibly nonexistent
+
+`c'
+ Character
+
+`C'
+ Command name: symbol with interactive function definition
+
+`d'
+ Value of point as number (does not do I/O)
+
+`D'
+ Directory name
+
+`e'
+ Last mouse event
+
+`f'
+ Existing file name
+
+`F'
+ Possibly nonexistent file name
+
+`k'
+ Key sequence (string)
+
+`m'
+ Value of mark as number (does not do I/O)
+
+`n'
+ Number read using minibuffer
+
+`N'
+ Prefix arg converted to number, or if none, do like code `n'
+
+`p'
+ Prefix arg converted to number (does not do I/O)
+
+`P'
+ Prefix arg in raw form (does not do I/O)
+
+`r'
+ Region: point and mark as two numeric arguments, smallest first
+ (does not do I/O)
+
+`s'
+ Any string
+
+`S'
+ Any symbol
+
+`v'
+ Variable name: symbol that is `user-variable-p'
+
+`x'
+ Lisp expression read but not evaluated
+
+`X'
+ Lisp expression read and evaluated
+
+ In addition, if the string begins with `*', an error is signaled if
+the buffer is read-only. This happens before reading any arguments.
+If the string begins with `@', the window the mouse is over is selected
+before anything else is done. You may use both `@' and `*'; they are
+processed in the order that they appear.
+
+ Normally, when describing a command that is run by name, we omit the
+<RET> that is needed to terminate the name. Thus we may refer to `M-x
+auto-fill-mode' rather than `M-x auto-fill-mode' <RET>. We mention the
+<RET> only when it is necessary to emphasize its presence, for example,
+when describing a sequence of input that contains a command name and
+arguments that follow it.
+
+ `M-x' is defined to run the command `execute-extended-command',
+which is responsible for reading the name of another command and
+invoking it.
+
+\1f
+File: xemacs.info, Node: Help, Next: Mark, Prev: M-x, Up: Top
+
+Help
+****
+
+ Emacs provides extensive help features which revolve around a single
+character, `C-h'. `C-h' is a prefix key that is used only for
+documentation-printing commands. The characters you can type after
+`C-h' are called "help options". One help option is `C-h'; you use it
+to ask for help about using `C-h'.
+
+ `C-h C-h' prints a list of the possible help options, and then asks
+you to type the desired option. It prompts with the string:
+
+ A, B, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-n, C-w or C-h for more help:
+
+You should type one of those characters.
+
+ Typing a third `C-h' displays a description of what the options mean;
+Emacs still waits for you to type an option. To cancel, type `C-g'.
+
+ Here is a summary of the defined help commands.
+
+`C-h a STRING <RET>'
+ Display a list of commands whose names contain STRING (`command-
+ apropos').
+
+`C-h b'
+ Display a table of all key bindings currently in effect, with
+ local bindings of the current major mode first, followed by all
+ global bindings (`describe-bindings').
+
+`C-h c KEY'
+ Print the name of the command that KEY runs (`describe-key-
+ briefly'). `c' is for `character'. For more extensive
+ information on KEY, use `C-h k'.
+
+`C-h f FUNCTION <RET>'
+ Display documentation on the Lisp function named FUNCTION
+ (`describe-function'). Note that commands are Lisp functions, so
+ a command name may be used.
+
+`C-h i'
+ Run Info, the program for browsing documentation files (`info').
+ The complete Emacs manual is available online in Info.
+
+`C-h k KEY'
+ Display name and documentation of the command KEY runs
+ (`describe-key').
+
+`C-h l'
+ Display a description of the last 100 characters you typed
+ (`view-lossage').
+
+`C-h m'
+ Display documentation of the current major mode (`describe-mode').
+
+`C-h n'
+ Display documentation of Emacs changes, most recent first
+ (`view-emacs-news').
+
+`C-h p'
+ Display a table of all mouse bindings currently in effect now, with
+ local bindings of the current major mode first, followed by all
+ global bindings (`describe-pointer').
+
+`C-h s'
+ Display current contents of the syntax table, plus an explanation
+ of what they mean (`describe-syntax').
+
+`C-h t'
+ Display the Emacs tutorial (`help-with-tutorial').
+
+`C-h v VAR <RET>'
+ Display the documentation of the Lisp variable VAR (`describe-
+ variable').
+
+`C-h w COMMAND <RET>'
+ Print which keys run the command named COMMAND (`where-is').
+
+`M-x apropos REGEXP'
+ Show all symbols whose names contain matches for REGEXP.
+
+Documentation for a Key
+=======================
+
+ The most basic `C-h' options are `C-h c' (`describe-key-briefly')
+and `C-h k'
+(`describe-key'). `C-h c KEY' prints the name of the command that KEY
+is bound to in the echo area. For example, `C-h c C-f' prints
+`forward-char'. Since command names are chosen to describe what the
+command does, using this option is a good way to get a somewhat cryptic
+description of what KEY does.
+
+ `C-h k KEY' is similar to `C-h c' but gives more information. It
+displays the documentation string of the function KEY is bound to as
+well as its name. KEY is a string or vector of events. When called
+interactively, KEY may also be a menu selection. This information does
+not usually fit into the echo area, so a window is used for the display.
+
+Help by Command or Variable Name
+================================
+
+ `C-h f' (`describe-function') reads the name of a Lisp function
+using the minibuffer, then displays that function's documentation
+string in a window. Since commands are Lisp functions, you can use the
+argument FUNCTION to get the documentation of a command that you know
+by name. For example,
+
+ C-h f auto-fill-mode <RET>
+
+displays the documentation for `auto-fill-mode'. Using `C-h f' is the
+only way to see the documentation of a command that is not bound to any
+key, that is, a command you would normally call using `M-x'. If the
+variable `describe-function-show-arglist' is `t', `describe-function'
+shows its arglist if the FUNCTION is not an autoload function.
+
+ `C-h f' is also useful for Lisp functions you are planning to use in
+a Lisp program. For example, if you have just written the code
+`(make-vector len)' and want to make sure you are using `make-vector'
+properly, type `C-h f make-vector <RET>'. Because `C-h f' allows all
+function names, not just command names, you may find that some of your
+favorite abbreviations that work in `M-x' don't work in `C-h f'. An
+abbreviation may be unique among command names, yet fail to be unique
+when other function names are allowed.
+
+ If you type <RET>, leaving the minibuffer empty, `C-h f' by default
+describes the function called by the innermost Lisp expression in the
+buffer around point, provided that that is a valid, defined Lisp
+function name. For example, if point is located following the text
+`(make-vector (car x)', the innermost list containing point is the one
+starting with `(make-vector', so the default is to describe the
+function `make-vector'.
+
+ `C-h f' is often useful just to verify that you have the right
+spelling for the function name. If `C-h f' mentions a default in the
+prompt, you have typed the name of a defined Lisp function. If that is
+what you wanted to know, just type `C-g' to cancel the `C-h f' command
+and continue editing.
+
+ `C-h w COMMAND <RET>' (`where-s') tells you what keys are bound to
+COMMAND. It prints a list of the keys in the echo area. Alternatively,
+it informs you that a command is not bound to any keys, which implies
+that you must use `M-x' to call the command.
+
+ `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
+variables instead of Lisp functions. Its default is the Lisp symbol
+around or before point, if that is the name of a known Lisp variable.
+*Note Variables::.
+
+Apropos
+=======
+
+`C-h a'
+ Show only symbols that are names of commands (`command-apropos').
+
+`M-x apropos REGEXP'
+ Show all symbols whose names comtain matches for REGEXP.
+
+ It is possible to ask a question like, "What are the commands for
+working with files?" To do this, type `C-h a file <RET>', which
+displays a list of all command names that contain `file', such as
+`copy-file', `find-file', and so on. With each command name a brief
+description of its use and information on the keys you can use to
+invoke it is displayed. For example, you would be informed that you
+can invoke `find-file' by typing `C-x C-f'. The `a' in `C-h a' stands
+for `Apropos'; `C-h a' runs the Lisp function `command-apropos'.
+
+ Because `C-h a' looks only for functions whose names contain the
+string you specify, you must use ingenuity in choosing the string. If
+you are looking for commands for killing backwards and `C-h a
+kill-backwards <RET>' doesn't reveal any commands, don't give up. Try
+just `kill', or just `backwards', or just `back'. Be persistent.
+Pretend you are playing Adventure. Also note that you can use a
+regular expression as the argument (*note Regexps::.).
+
+ Here is a set of arguments to give to `C-h a' that covers many
+classes of Emacs commands, since there are strong conventions for naming
+standard Emacs commands. By giving you a feeling for the naming
+conventions, this set of arguments can also help you develop a
+technique for picking `apropos' strings.
+
+ char, line, word, sentence, paragraph, region, page, sexp, list,
+ defun, buffer, frame, window, file, dir, register, mode,
+ beginning, end, forward, backward, next, previous, up, down,
+ search, goto, kill, delete, mark, insert, yank, fill, indent, case,
+ change, set, what, list, find, view, describe.
+
+ To list all Lisp symbols that contain a match for a regexp, not just
+the ones that are defined as commands, use the command `M-x apropos'
+instead of `C-h a'.
+
+Other Help Commands
+===================
+
+ `C-h i' (`info') runs the Info program, which is used for browsing
+through structured documentation files. The entire Emacs manual is
+available within Info. Eventually all the documentation of the GNU
+system will be available. Type `h' after entering Info to run a
+tutorial on using Info.
+
+ If something surprising happens, and you are not sure what commands
+you typed, use `C-h l' (`view-lossage'). `C-h l' prints the last 100
+command characters you typed. If you see commands you don't know, use
+`C-h c' to find out what they do.
+
+ Emacs has several major modes. Each mode redefines a few keys and
+makes a few other changes in how editing works. `C-h m'
+(`describe-mode') prints documentation on the current major mode, which
+normally describes all the commands that are changed in this mode.
+
+ `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax')
+present information about the current Emacs mode that is not covered by
+`C-h m'. `C-h b' displays a list of all key bindings currently in
+effect, with the local bindings of the current major mode first,
+followed by the global bindings (*note Key Bindings::.). `C-h s'
+displays the contents of the syntax table with explanations of each
+character's syntax (*note Syntax::.).
+
+ The other `C-h' options display various files of useful information.
+`C-h C-w' (`describe-no-warranty') displays details on the complete
+absence of warranty for XEmacs. `C-h n' (`view-emacs-news') displays
+the file `emacs/etc/NEWS', which contains documentation on Emacs
+changes arranged chronologically. `C-h t' (`help-with-tutorial')
+displays the learn-by-doing Emacs tutorial. `C-h C-c'
+(`describe-copying') displays the file `emacs/etc/COPYING', which tells
+you the conditions you must obey in distributing copies of Emacs. `C-h
+C-d' (`describe-distribution') displays another file named
+`emacs/etc/DISTRIB', which tells you how you can order a copy of the
+latest version of Emacs.
+
+\1f
+File: xemacs.info, Node: Mark, Next: Mouse Selection, Prev: Help, Up: Top
+
+Selecting Text
+**************
+
+ Many Emacs commands operate on an arbitrary contiguous part of the
+current buffer. You can select text in two ways:
+
+ * You use special keys to select text by defining a region between
+ point and the mark.
+
+ * If you are running XEmacs under X, you can also select text with
+ the mouse.
+
+The Mark and the Region
+=======================
+
+ To specify the text for a command to operate on, set "the mark" at
+one end of it, and move point to the other end. The text between point
+and the mark is called "the region". You can move point or the mark to
+adjust the boundaries of the region. It doesn't matter which one is
+set first chronologically, or which one comes earlier in the text.
+
+ Once the mark has been set, it remains until it is set again at
+another place. The mark remains fixed with respect to the preceding
+character if text is inserted or deleted in a buffer. Each Emacs
+buffer has its own mark; when you return to a buffer that had been
+selected previously, it has the same mark it had before.
+
+ Many commands that insert text, such as `C-y' (`yank') and `M-x
+insert-buffer', position the mark at one end of the inserted text--the
+opposite end from where point is positioned, so that the region
+contains the text just inserted.
+
+ Aside from delimiting the region, the mark is useful for marking a
+spot that you may want to go back to. To make this feature more useful,
+Emacs remembers 16 previous locations of the mark in the `mark ring'.
+
+* Menu:
+
+* Setting Mark:: Commands to set the mark.
+* Using Region:: Summary of ways to operate on contents of the region.
+* Marking Objects:: Commands to put region around textual units.
+* Mark Ring:: Previous mark positions saved so you can go back there.
+
+\1f
+File: xemacs.info, Node: Setting Mark, Next: Using Region, Prev: Mark, Up: Mark
+
+Setting the Mark
+----------------
+
+ Here are some commands for setting the mark:
+
+`C-<SPC>'
+ Set the mark where point is (`set-mark-command').
+
+`C-@'
+ The same.
+
+`C-x C-x'
+ Interchange mark and point (`exchange-point-and-mark').
+
+`C-<'
+ Pushes a mark at the beginning of the buffer.
+
+`C->'
+ Pushes a mark at the end of the buffer.
+
+ For example, to convert part of the buffer to all upper-case, you
+can use the `C-x C-u' (`upcase-region') command, which operates on the
+text in the region. First go to the beginning of the text you want to
+capitalize and type `C-<SPC>' to put the mark there, then move to the
+end, and then type `C-x C-u' to capitalize the selected region. You
+can also set the mark at the end of the text, move to the beginning,
+and then type `C-x C-u'. Most commands that operate on the text in the
+region have the word `region' in their names.
+
+ The most common way to set the mark is with the `C-<SPC>' command
+(`set-mark-command'). This command sets the mark where point is. You
+can then move point away, leaving the mark behind. It is actually
+incorrect to speak of the character `C-<SPC>'; there is no such
+character. When you type <SPC> while holding down <CTRL>, you get the
+character `C-@' on most terminals. This character is actually bound to
+`set-mark-command'. But unless you are unlucky enough to have a
+terminal where typing `C-<SPC>' does not produce `C-@', you should
+think of this character as `C-<SPC>'.
+
+ Since terminals have only one cursor, Emacs cannot show you where the
+mark is located. Most people use the mark soon after they set it, before
+they forget where it is. But you can see where the mark is with the
+command `C-x C-x' (`exchange-point-and-mark') which puts the mark where
+point was and point where the mark was. The extent of the region is
+unchanged, but the cursor and point are now at the previous location of
+the mark.
+
+ Another way to set the mark is to push the mark to the beginning of a
+buffer while leaving point at its original location. If you supply an
+argument to `C-<' (`mark-beginning-of-buffer'), the mark is pushed N/10
+of the way from the true beginning of the buffer. You can also set the
+mark at the end of a buffer with `C->' (`mark-end-of-buffer'). It
+pushes the mark to the end of the buffer, leaving point alone.
+Supplying an argument to the command pushes the mark N/10 of the way
+from the true end of the buffer.
+
+ If you are using XEmacs under the X window system, you can set the
+variable `zmacs-regions' to `t'. This makes the current region (defined
+by point and mark) highlight and makes it available as the X clipboard
+selection, which means you can use the menu bar items on it. *Note
+Active Regions::, for more information.
+
+ `C-x C-x' is also useful when you are satisfied with the location of
+point but want to move the mark; do `C-x C-x' to put point there and
+then you can move it. A second use of `C-x C-x', if necessary, puts
+the mark at the new location with point back at its original location.
+
+\1f
+File: xemacs.info, Node: Using Region, Next: Marking Objects, Prev: Setting Mark, Up: Mark
+
+Operating on the Region
+-----------------------
+
+ Once you have created an active region, you can do many things to
+the text in it:
+ * Kill it with `C-w' (*note Killing::.).
+
+ * Save it in a register with `C-x r s' (*note Registers::.).
+
+ * Save it in a buffer or a file (*note Accumulating Text::.).
+
+ * Convert case with `C-x C-l' or `C-x C-u'
+ (*note Case::.).
+
+ * Evaluate it as Lisp code with `M-x eval-region' (*note Lisp
+ Eval::.).
+
+ * Fill it as text with `M-q' (*note Filling::.).
+
+ * Print hardcopy with `M-x print-region' (*note Hardcopy::.).
+
+ * Indent it with `C-x <TAB>' or `C-M-\' (*note Indentation::.).
+
+\1f
+File: xemacs.info, Node: Marking Objects, Next: Mark Ring, Prev: Using Region, Up: Mark
+
+Commands to Mark Textual Objects
+--------------------------------
+
+ There are commands for placing point and the mark around a textual
+object such as a word, list, paragraph or page.
+
+`M-@'
+ Set mark after end of next word (`mark-word'). This command and
+ the following one do not move point.
+
+`C-M-@'
+ Set mark after end of next Lisp expression (`mark-sexp').
+
+`M-h'
+ Put region around current paragraph (`mark-paragraph').
+
+`C-M-h'
+ Put region around current Lisp defun (`mark-defun').
+
+`C-x h'
+ Put region around entire buffer (`mark-whole-buffer').
+
+`C-x C-p'
+ Put region around current page (`mark-page').
+
+ `M-@' (`mark-word') puts the mark at the end of the next word, while
+`C-M-@' (`mark-sexp') puts it at the end of the next Lisp expression.
+These characters sometimes save you some typing.
+
+ A number of commands are available that set both point and mark and
+thus delimit an object in the buffer. `M-h' (`mark-paragraph') moves
+point to the beginning of the paragraph that surrounds or follows
+point, and puts the mark at the end of that paragraph (*note
+Paragraphs::.). You can then indent, case-convert, or kill the whole
+paragraph. In the same fashion, `C-M-h' (`mark-defun') puts point
+before and the mark after the current or following defun (*note
+Defuns::.). `C-x C-p' (`mark-page') puts point before the current page
+(or the next or previous, depending on the argument), and mark at the
+end (*note Pages::.). The mark goes after the terminating page
+delimiter (to include it), while point goes after the preceding page
+delimiter (to exclude it). Finally, `C-x h' (`mark-whole-buffer') sets
+up the entire buffer as the region by putting point at the beginning
+and the mark at the end.
+
+\1f
+File: xemacs.info, Node: Mark Ring, Prev: Marking Objects, Up: Mark
+
+The Mark Ring
+-------------
+
+ Aside from delimiting the region, the mark is also useful for marking
+a spot that you may want to go back to. To make this feature more
+useful, Emacs remembers 16 previous locations of the mark in the "mark
+ring". Most commands that set the mark push the old mark onto this
+ring. To return to a marked location, use `C-u C-<SPC>' (or `C-u
+C-@'); this is the command `set-mark-command' given a numeric argument.
+The command moves point to where the mark was, and restores the mark
+from the ring of former marks. Repeated use of this command moves point
+to all the old marks on the ring, one by one. The marks you have seen
+go to the end of the ring, so no marks are lost.
+
+ Each buffer has its own mark ring. All editing commands use the
+current buffer's mark ring. In particular, `C-u C-<SPC>' always stays
+in the same buffer.
+
+ Many commands that can move long distances, such as `M-<'
+(`beginning-of-buffer'), start by setting the mark and saving the old
+mark on the mark ring. This makes it easier for you to move back
+later. Searches set the mark, unless they do not actually move point.
+When a command sets the mark, `Mark Set' is printed in the echo area.
+
+ The variable `mark-ring-max' is the maximum number of entries to
+keep in the mark ring. If that many entries exist and another entry is
+added, the last entry in the list is discarded. Repeating `C-u
+C-<SPC>' circulates through the entries that are currently in the ring.
+
+ The variable `mark-ring' holds the mark ring itself, as a list of
+marker objects in the order most recent first. This variable is local
+in every buffer.
+
+\1f
+File: xemacs.info, Node: Mouse Selection, Next: Additional Mouse Operations, Prev: Mark, Up: Top
+
+Selecting Text with the Mouse
+=============================
+
+ If you are using XEmacs under X, you can use the mouse pointer to
+select text. (The normal mouse pointer is an I-beam, the same pointer
+that `xterm' uses.)
+
+ The glyph variable `text-pointer-glyph' controls the shape of the
+mouse pointer when over text. You can also control the shape of the
+mouse pointer when over nontext using `nontext-pointer-glyph', and the
+shape of the mouse pointer when over the modeline using
+`modeline-pointer-glyph'. (Remember, you should use `set-glyph-image',
+not `setq', to set one of these variables.)
+
+ If you want to get fancy, you can set the foreground and background
+colors of the mouse pointer by setting the `pointer' face.
+
+ There are two ways to select a region of text with the mouse:
+
+ To select a word in text, double-click with the left mouse button
+while the mouse cursor is over the word. The word is highlighted when
+selected. On monochrome monitors, a stippled background indicates that a
+region of text has been highlighted. On color monitors, a color
+background indicates highlighted text. You can triple-click to select
+whole lines.
+
+ To select an arbitrary region of text:
+
+ 1. Move the mouse cursor over the character at the beginning of the
+ region of text you want to select.
+
+ 2. Press and hold the left mouse button.
+
+ 3. While holding the left mouse button down, drag the cursor to the
+ character at the end of the region of text you want to select.
+
+ 4. Release the left mouse button.
+ The selected region of text is highlighted.
+
+ Once a region of text is selected, it becomes the primary X selection
+(*note Using X Selections::.) as well as the Emacs selected region. You
+can paste it into other X applications and use the options from the
+Edit pull-down menu on it. Since it is also the Emacs region, you can
+use Emacs region commands on it.
+
+\1f
+File: xemacs.info, Node: Additional Mouse Operations, Next: Killing, Prev: Mouse Selection, Up: Top
+
+Additional Mouse Operations
+===========================
+
+ XEmacs also provides the following mouse functions. Most of these
+are not bound to mouse gestures by default, but they are provided for
+your customization pleasure. For example, if you wanted `shift-left'
+(that is, holding down the <Shift> key and clicking the left mouse
+button) to delete the character at which you are pointing, then you
+could do this:
+
+ (global-set-key '(shift button1) 'mouse-del-char)
+
+`mouse-del-char'
+ Delete the character pointed to by the mouse.
+
+`mouse-delete-window'
+ Delete the Emacs window that the mouse is on.
+
+`mouse-keep-one-window'
+ Select the Emacs window that the mouse is on, then delete all other
+ windows on this frame.
+
+`mouse-kill-line'
+ Kill the line pointed to by the mouse.
+
+`mouse-line-length'
+ Print the length of the line indicated by the pointer.
+
+`mouse-scroll'
+ Scroll point to the mouse position.
+
+`mouse-select'
+ Select the Emacs window the mouse is on.
+
+`mouse-select-and-split'
+ Select the Emacs window mouse is on, then split it vertically in
+ half.
+
+`mouse-set-mark'
+ Select the Emacs window the mouse is on and set the mark at the
+ mouse position. Display the cursor at that position for a second.
+
+`mouse-set-point'
+ Select the Emacs window that the mouse is on and move point to the
+ mouse position.
+
+`mouse-track'
+ Make a selection with the mouse. This is the default binding of
+ the left mouse button (<button1>).
+
+`mouse-track-adjust'
+ Extend the existing selection. This is the default binding of
+ <Shift-button1>.
+
+`mouse-track-and-copy-to-cutbuffer'
+ Make a selection like `mouse-track', but also copy it to the cut
+ buffer.
+
+`mouse-track-delete-and-insert'
+ Make a selection with the mouse and insert it at point. This is
+ the default binding of <control-shift-button1>.
+
+`mouse-track-insert'
+ Make a selection with the mouse and insert it at point. This is
+ the default binding of <control-button1>.
+
+`mouse-window-to-region'
+ Narrow a window to the region between the cursor and the mouse
+ pointer.
+
+ The `M-x mouse-track' command should be bound to a mouse button. If
+you click-and-drag, the selection is set to the region between the
+point of the initial click and the point at which you release the
+button. These positions do not need to be ordered.
+
+ If you click-and-release without moving the mouse, the point is
+moved, and the selection is disowned (there will be no selection
+owner.) The mark will be set to the previous position of point.
+
+ If you double-click, the selection will extend by symbols instead of
+by characters. If you triple-click, the selection will extend by lines.
+
+ If you drag the mouse off the top or bottom of the window, you can
+select pieces of text that are larger than the visible part of the
+buffer; the buffer will scroll as necessary.
+
+ The selected text becomes the current X selection, and is also
+copied to the top of the kill ring. Point will be left at the position
+at which you released the button and the mark will be left at the
+initial click position. Bind a mouse click to
+`mouse-track-and-copy-to-cutbuffer' to copy selections to the cut
+buffer. (See also the `mouse-track-adjust' command, on
+`Shift-button1'.)
+
+ The `M-x mouse-track-adjust' command should be bound to a mouse
+button. The selection will be enlarged or shrunk so that the point of
+the mouse click is one of its endpoints. This is only meaningful after
+the `mouse-track' command (<button1>) has been executed.
+
+ The `M-x mouse-track-delete-and-insert' command is exactly the same
+as the `mouse-track' command on <button1>, except that point is not
+moved; the selected text is immediately inserted after being selected;
+and the text of the selection is deleted.
+
+ The `M-x mouse-track-insert' command is exactly the same as the
+`mouse-track' command on <button1>, except that point is not moved; the
+selected text is immediately inserted after being selected; and the
+selection is immediately disowned afterwards.
+
+\1f
+File: xemacs.info, Node: Killing, Next: Yanking, Prev: Additional Mouse Operations, Up: Top
+
+Deletion and Killing
+====================
+
+ Most commands that erase text from the buffer save it. You can get
+the text back if you change your mind, or you can move or copy it to
+other parts of the buffer. Commands which erase text and save it in the
+kill ring are known as "kill" commands. Some other commands erase text
+but do not save it; they are known as "delete" commands. (This
+distinction is made only for erasing text in the buffer.)
+
+ The commands' names and individual descriptions use the words `kill'
+and `delete' to indicate what they do. If you perform a kill or delete
+command by mistake, use the `C-x u' (`undo') command to undo it (*note
+Undo::.). The delete commands include `C-d' (`delete-char') and <DEL>
+(`delete-backward-char'), which delete only one character at a time,
+and those commands that delete only spaces or newlines. Commands that
+can destroy significant amounts of nontrivial data usually kill.
+
+Deletion
+--------
+
+`C-d'
+ Delete next character (`delete-char').
+
+`<DEL>'
+ Delete previous character (`delete-backward-char').
+
+`M-\'
+ Delete spaces and tabs around point (`delete-horizontal-space').
+
+`M-<SPC>'
+ Delete spaces and tabs around point, leaving one space
+ (`just-one-space').
+
+`C-x C-o'
+ Delete blank lines around the current line (`delete-blank-lines').
+
+`M-^'
+ Join two lines by deleting the intervening newline, and any
+ indentation following it (`delete-indentation').
+
+ The most basic delete commands are `C-d' (`delete-char') and <DEL>
+(`delete-backward-char'). `C-d' deletes the character after point, the
+one the cursor is "on top of". Point doesn't move. <DEL> deletes the
+character before the cursor, and moves point back. You can delete
+newlines like any other characters in the buffer; deleting a newline
+joins two lines. Actually, `C-d' and <DEL> aren't always delete
+commands; if you give them an argument, they kill instead, since they
+can erase more than one character this way.
+
+ The other delete commands delete only formatting characters: spaces,
+tabs and newlines. `M-\' (`delete-horizontal-space') deletes all
+spaces and tab characters before and after point. `M-<SPC>'
+(`just-one-space') does the same but leaves a single space after point,
+regardless of the number of spaces that existed previously (even zero).
+
+ `C-x C-o' (`delete-blank-lines') deletes all blank lines after the
+current line. If the current line is blank, it deletes all blank lines
+preceding the current line as well as leaving one blank line, the
+current line. `M-^' (`delete-indentation') joins the current line and
+the previous line, or, if given an argument, joins the current line and
+the next line by deleting a newline and all surrounding spaces, possibly
+leaving a single space. *Note M-^: Indentation.
+
+Killing by Lines
+----------------
+
+`C-k'
+ Kill rest of line or one or more lines (`kill-line').
+
+ The simplest kill command is `C-k'. If given at the beginning of a
+line, it kills all the text on the line, leaving the line blank. If
+given on a blank line, the blank line disappears. As a consequence, a
+line disappears completely if you go to the front of a non-blank line
+and type `C-k' twice.
+
+ More generally, `C-k' kills from point up to the end of the line,
+unless it is at the end of a line. In that case, it kills the newline
+following the line, thus merging the next line into the current one.
+Emacs ignores invisible spaces and tabs at the end of the line when
+deciding which case applies: if point appears to be at the end of the
+line, you can be sure the newline will be killed.
+
+ If you give `C-k' a positive argument, it kills that many lines and
+the newlines that follow them (however, text on the current line before
+point is not killed). With a negative argument, `C-k' kills back to a
+number of line beginnings. An argument of -2 means kill back to the
+second line beginning. If point is at the beginning of a line, that
+line beginning doesn't count, so `C-u - 2 C-k' with point at the front
+of a line kills the two previous lines.
+
+ `C-k' with an argument of zero kills all the text before point on the
+current line.
+
+Other Kill Commands
+-------------------
+
+`C-w'
+ Kill region (from point to the mark) (`kill-region'). *Note
+ Words::.
+
+`M-d'
+ Kill word (`kill-word').
+
+`M-<DEL>'
+ Kill word backwards (`backward-kill-word').
+
+`C-x <DEL>'
+ Kill back to beginning of sentence (`backward-kill-sentence').
+ *Note Sentences::.
+
+`M-k'
+ Kill to end of sentence (`kill-sentence').
+
+`C-M-k'
+ Kill sexp (`kill-sexp'). *Note Lists::.
+
+`M-z CHAR'
+ Kill up to next occurrence of CHAR (`zap-to-char').
+
+ `C-w' (`kill-region') is a very general kill command; it kills
+everything between point and the mark. You can use this command to kill
+any contiguous sequence of characters by first setting the mark at one
+end of a sequence of characters, then going to the other end and typing
+`C-w'.
+
+ A convenient way of killing is combined with searching: `M-z'
+(`zap-to-char') reads a character and kills from point up to (but not
+including) the next occurrence of that character in the buffer. If
+there is no next occurrence, killing goes to the end of the buffer. A
+numeric argument acts as a repeat count. A negative argument means to
+search backward and kill text before point.
+
+ Other syntactic units can be killed: words, with `M-<DEL>' and `M-d'
+(*note Words::.); sexps, with `C-M-k' (*note Lists::.); and sentences,
+with `C-x <DEL>' and `M-k' (*note Sentences::.).
+
+\1f
+File: xemacs.info, Node: Yanking, Next: Using X Selections, Prev: Killing, Up: Top
+
+Yanking
+=======
+
+ "Yanking" means getting back text which was killed. Some systems
+call this "pasting". The usual way to move or copy text is to kill it
+and then yank it one or more times.
+
+`C-y'
+ Yank last killed text (`yank').
+
+`M-y'
+ Replace re-inserted killed text with the previously killed text
+ (`yank-pop').
+
+`M-w'
+ Save region as last killed text without actually killing it
+ (`copy-region-as-kill').
+
+`C-M-w'
+ Append next kill to last batch of killed text (`append-next-kill').
+
+* Menu:
+
+* Kill Ring:: Where killed text is stored. Basic yanking.
+* Appending Kills:: Several kills in a row all yank together.
+* Earlier Kills:: Yanking something killed some time ago.
+
+\1f
+File: xemacs.info, Node: Kill Ring, Next: Appending Kills, Prev: Yanking, Up: Yanking
+
+The Kill Ring
+-------------
+
+ All killed text is recorded in the "kill ring", a list of blocks of
+text that have been killed. There is only one kill ring, used in all
+buffers, so you can kill text in one buffer and yank it in another
+buffer. This is the usual way to move text from one file to another.
+(*Note Accumulating Text::, for some other ways.)
+
+ If you have two separate Emacs processes, you cannot use the kill
+ring to move text. If you are using XEmacs under X, however, you can
+use the X selection mechanism to move text from one to another.
+
+ If you are using XEmacs under X and have one Emacs process with
+multiple frames, they do share the same kill ring. You can kill or
+copy text in one Emacs frame, then yank it in the other frame belonging
+to the same process.
+
+ The command `C-y' (`yank') reinserts the text of the most recent
+kill. It leaves the cursor at the end of the text and sets the mark at
+the beginning of the text. *Note Mark::.
+
+ `C-u C-y' yanks the text, leaves the cursor in front of the text,
+and sets the mark after it, if the argument is with just a `C-u'. Any
+other argument, including `C-u' and digits, has different results,
+described below, under "Yanking Earlier Kills".
+
+ To copy a block of text, you can also use `M-w'
+(`copy-region-as-kill'), which copies the region into the kill ring
+without removing it from the buffer. `M-w' is similar to `C-w' followed
+by `C-y' but does not mark the buffer as "modified" and does not
+actually cut anything.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Appending Kills, Next: Earlier Kills, Prev: Kill Ring, Up: Yanking
+
+Appending Kills
+---------------
+
+ Normally, each kill command pushes a new block onto the kill ring.
+However, two or more kill commands in a row combine their text into a
+single entry, so that a single `C-y' yanks it all back. This means you
+don't have to kill all the text you want to yank in one command; you
+can kill line after line, or word after word, until you have killed what
+you want, then get it all back at once using `C-y'. (Thus we join
+television in leading people to kill thoughtlessly.)
+
+ Commands that kill forward from point add onto the end of the
+previous killed text. Commands that kill backward from point add onto
+the beginning. This way, any sequence of mixed forward and backward
+kill commands puts all the killed text into one entry without
+rearrangement. Numeric arguments do not break the sequence of
+appending kills. For example, suppose the buffer contains:
+
+ This is the first
+ line of sample text
+ and here is the third.
+
+with point at the beginning of the second line. If you type `C-k C-u 2
+M-<DEL> C-k', the first `C-k' kills the text `line of sample text',
+`C-u 2 M-<DEL>' kills `the first' with the newline that followed it,
+and the second `C-k' kills the newline after the second line. The
+result is that the buffer contains `This is and here is the third.' and
+a single kill entry contains `the first<RET>line of sample
+text<RET>'--all the killed text, in its original order.
+
+ If a kill command is separated from the last kill command by other
+commands (not just numeric arguments), it starts a new entry on the kill
+ring. To force a kill command to append, first type the command `C-M-w'
+(`append-next-kill'). `C-M-w' tells the following command, if it is a
+kill command, to append the text it kills to the last killed text,
+instead of starting a new entry. With `C-M-w', you can kill several
+separated pieces of text and accumulate them to be yanked back in one
+place.
+
+\1f
+File: xemacs.info, Node: Earlier Kills, Prev: Appending Kills, Up: Yanking
+
+Yanking Earlier Kills
+---------------------
+
+ To recover killed text that is no longer the most recent kill, you
+need the `Meta-y' (`yank-pop') command. You can use `M-y' only after a
+`C-y' or another `M-y'. It takes the text previously yanked and
+replaces it with the text from an earlier kill. To recover the text of
+the next-to-the-last kill, first use `C-y' to recover the last kill,
+then `M-y' to replace it with the previous kill.
+
+ You can think in terms of a "last yank" pointer which points at an
+item in the kill ring. Each time you kill, the "last yank" pointer
+moves to the new item at the front of the ring. `C-y' yanks the item
+which the "last yank" pointer points to. `M-y' moves the "last yank"
+pointer to a different item, and the text in the buffer changes to
+match. Enough `M-y' commands can move the pointer to any item in the
+ring, so you can get any item into the buffer. Eventually the pointer
+reaches the end of the ring; the next `M-y' moves it to the first item
+again.
+
+ Yanking moves the "last yank" pointer around the ring, but does not
+change the order of the entries in the ring, which always runs from the
+most recent kill at the front to the oldest one still remembered.
+
+ Use `M-y' with a numeric argument to advance the "last yank" pointer
+by the specified number of items. A negative argument moves the
+pointer toward the front of the ring; from the front of the ring, it
+moves to the last entry and starts moving forward from there.
+
+ Once the text you are looking for is brought into the buffer, you can
+stop doing `M-y' commands and the text will stay there. Since the text
+is just a copy of the kill ring item, editing it in the buffer does not
+change what's in the ring. As long you don't kill additional text, the
+"last yank" pointer remains at the same place in the kill ring:
+repeating `C-y' will yank another copy of the same old kill.
+
+ If you know how many `M-y' commands it would take to find the text
+you want, you can yank that text in one step using `C-y' with a numeric
+argument. `C-y' with an argument greater than one restores the text
+the specified number of entries back in the kill ring. Thus, `C-u 2
+C-y' gets the next to the last block of killed text. It is equivalent
+to `C-y M-y'. `C-y' with a numeric argument starts counting from the
+"last yank" pointer, and sets the "last yank" pointer to the entry that
+it yanks.
+
+ The variable `kill-ring-max' controls the length of the kill ring;
+no more than that many blocks of killed text are saved.
+
+\1f
+File: xemacs.info, Node: Using X Selections, Next: Accumulating Text, Prev: Yanking, Up: Top
+
+Using X Selections
+==================
+
+ In the X window system, mouse selections provide a simple mechanism
+for text transfer between different applications. In a typical X
+application, you can select text by pressing the left mouse button and
+dragging the cursor over the text you want to copy. The text becomes
+the primary X selection and is highlighted. The highlighted region is
+also the Emacs selected region.
+
+ * Since the region is the primary X selection, you can go to a
+ different X application and click the middle mouse button: the
+ text that you selected in the previous application is pasted into
+ the current application.
+
+ * Since the region is the Emacs selected region, you can use all
+ region commands (`C-w, M-w' etc.) as well as the options of the
+ Edit menu to manipulate the selected text.
+
+* Menu:
+
+* X Clipboard Selection:: Pasting to the X clipboard.
+* X Selection Commands:: Other operations on the selection.
+* X Cut Buffers:: X cut buffers are available for compatibility.
+* Active Regions:: Using zmacs-style highlighting of the
+ selected region.
+
+\1f
+File: xemacs.info, Node: X Clipboard Selection, Next: X Selection Commands, Prev: Using X Selections, Up: Using X Selections
+
+The Clipboard Selection
+-----------------------
+
+ There are other kinds of X selections besides the Primary selection;
+one common one is the Clipboard selection. Some applications prefer to
+transfer data using this selection in preference to the Primary. One
+can transfer text from the Primary selection to the Clipboard
+selection with the Copy command under the Edit menu in the menubar.
+
+ Usually, the clipboard selection is not visible. However, if you
+run the `xclipboard' application, the text most recently copied to the
+clipboard (with the Copy command) is displayed in a window. Any time
+new text is thus copied, the `xclipboard' application makes a copy of
+it and displays it in its window. The value of the clipboard can
+survive the lifetime of the running Emacs process. The `xclipboard'
+man page provides more details.
+
+ Warning: If you use the `xclipboard' application, remember that it
+maintains a list of all things that have been pasted to the clipboard
+(that is, copied with the Copy command). If you don't manually delete
+elements from this list by clicking on the Delete button in the
+`xclipboard' window, the clipboard will eventually consume a lot of
+memory.
+
+ In summary, some X applications (such as `xterm') allow one to paste
+text in them from XEmacs in the following way:
+
+ * Drag out a region of text in Emacs with the left mouse button,
+ making that text be the Primary selection.
+
+ * Click the middle button in the other application, pasting the
+ Primary selection.
+
+ With some other applications (notably, the OpenWindows and Motif
+tools) you must use this method instead:
+
+ * Drag out a region of text in Emacs with the left mouse button,
+ making that text be the Primary selection.
+
+ * Copy the selected text to the Clipboard selection by selecting the
+ Copy menu item from the Edit menu, or by hitting the Copy key on
+ your keyboard.
+
+ * Paste the text in the other application by selecting Paste from its
+ menu, or by hitting the Paste key on your keyboard.
+
+\1f
+File: xemacs.info, Node: X Selection Commands, Next: X Cut Buffers, Prev: X Clipboard Selection, Up: Using X Selections
+
+Miscellaneous X Selection Commands
+----------------------------------
+
+`M-x x-copy-primary-selection'
+ Copy the primary selection to both the kill ring and the Clipboard.
+
+`M-x x-insert-selection'
+ Insert the current selection into the buffer at point.
+
+`M-x x-delete-primary-selection'
+ Deletes the text in the primary selection without copying it to
+ the kill ring or the Clipboard.
+
+`M-x x-kill-primary-selection'
+ Deletes the text in the primary selection and copies it to both
+ the kill ring and the Clipboard.
+
+`M-x x-mouse-kill'
+ Kill the text between point and the mouse and copy it to the
+ clipboard and to the cut buffer.
+
+`M-x x-own-secondary-selection'
+ Make a secondary X selection of the given argument.
+
+`M-x x-own-selection'
+ Make a primary X selection of the given argument.
+
+`M-x x-set-point-and-insert-selection'
+ Set point where clicked and insert the primary selection or the
+ cut buffer.
+
+\1f
+File: xemacs.info, Node: X Cut Buffers, Next: Active Regions, Prev: X Selection Commands, Up: Using X Selections
+
+X Cut Buffers
+-------------
+
+ X cut buffers are a different, older way of transferring text between
+applications. XEmacs supports cut buffers for compatibility with older
+programs, even though selections are now the preferred way of
+transferring text.
+
+ X has a concept of applications "owning" selections. When you select
+text by clicking and dragging inside an application, the application
+tells the X server that it owns the selection. When another
+application asks the X server for the value of the selection, the X
+server requests the information from the owner. When you use
+selections, the selection data is not actually transferred unless
+someone wants it; the act of making a selection doesn't transfer data.
+Cut buffers are different: when you "own" a cut buffer, the data is
+actually transferred to the X server immediately, and survives the
+lifetime of the application.
+
+ Any time a region of text becomes the primary selection in Emacs,
+Emacs also copies that text to the cut buffer. This makes it possible
+to copy text from an XEmacs buffer and paste it into an older,
+non-selection-based application (such as Emacs 18).
+
+ Note: Older versions of Emacs could not access the X selections, only
+the X cut buffers.
+
+\1f
+File: xemacs.info, Node: Active Regions, Prev: X Cut Buffers, Up: Using X Selections
+
+Active Regions
+--------------
+
+ By default, both the text you select in an Emacs buffer using the
+click-and-drag mechanism and text you select by setting point and the
+mark is highlighted. You can use Emacs region commands as well as the
+Cut and Copy commands on the highlighted region you selected with the
+mouse.
+
+ If you prefer, you can make a distinction between text selected with
+the mouse and text selected with point and the mark by setting the
+variable `zmacs-regions' to `nil'. In that case:
+
+ * The text selected with the mouse becomes both the X selection and
+ the Emacs selected region. You can use menu-bar commands as well
+ as Emacs region commands on it.
+
+ * The text selected with point and the mark is not highlighted. You
+ can only use Emacs region commands on it, not the menu-bar items.
+
+ Active regions originally come from Zmacs, the Lisp Machine editor.
+The idea behind them is that commands can only operate on a region when
+the region is in an "active" state. Put simply, you can only operate on
+a region that is highlighted.
+
+ The variable `zmacs-regions' checks whether LISPM-style active
+regions should be used. This means that commands that operate on the
+region (the area between point and the mark) only work while the region
+is in the active state, which is indicated by highlighting. Most
+commands causes the region to not be in the active state; for example,
+`C-w' only works immediately after activating the region.
+
+ More specifically:
+ * Commands that operate on the region only work if the region is
+ active.
+
+ * Only a very small set of commands causes the region to become
+ active-- those commands whose semantics are to mark an area, such
+ as `mark-defun'.
+
+ * The region is deactivated after each command that is executed,
+ except that motion commands do not change whether the region is
+ active or not.
+
+ `set-mark-command' (`C-SPC') pushes a mark and activates the region.
+Moving the cursor with normal motion commands (`C-n', `C-p', etc.)
+will cause the region between point and the recently-pushed mark to be
+highlighted. It will remain highlighted until some non-motion command
+is executed.
+
+ `exchange-point-and-mark' (`C-x C-x') activates the region. So if
+you mark a region and execute a command that operates on it, you can
+reactivate the same region with `C-x C-x' (or perhaps `C-x C-x C-x
+C-x') to operate on it again.
+
+ Generally, commands that push marks as a means of navigation, such as
+`beginning-of-buffer' (`M-<') and `end-of-buffer' (`M->'), do not
+activate the region. However, commands that push marks as a means of
+marking an area of text, such as `mark-defun' (`M-C-h'), `mark-word'
+(`M-@'), and `mark-whole-buffer' (`C-x h'), do activate the region.
+
+ When `zmacs-regions' is `t', there is no distinction between the
+primary X selection and the active region selected by point and the
+mark. To see this, set the mark (<C-SPC>) and move the cursor with any
+cursor-motion command: the region between point and mark is
+highlighted, and you can watch it grow and shrink as you move the
+cursor.
+
+ Any other commands besides cursor-motion commands (such as inserting
+or deleting text) will cause the region to no longer be active; it will
+no longer be highlighted, and will no longer be the primary selection.
+Region can be explicitly deactivated with `C-g'.
+
+ Commands that require a region (such as `C-w') signal an error if
+the region is not active. Certain commands cause the region to be in
+its active state. The most common ones are `push-mark' (<C-SPC>) and
+`exchange-point-and-mark' (`C-x C-x').
+
+ When `zmacs-regions' is `t', programs can be non-intrusive on the
+state of the region by setting the variable `zmacs-region-stays' to a
+non-`nil' value. If you are writing a new Emacs command that is
+conceptually a "motion" command and should not interfere with the
+current highlightedness of the region, then you may set this variable.
+It is reset to `nil' after each user command is executed.
+
+ When `zmacs-regions' is `t', programs can make the region between
+point and mark go into the active (highlighted) state by using the
+function `zmacs-activate-region'. Only a small number of commands
+should ever do this.
+
+ When `zmacs-regions' is `t', programs can deactivate the region
+between point and the mark by using `zmacs-deactivate-region'. Note:
+you should not have to call this function; the command loop calls it
+when appropriate.
+
+\1f
+File: xemacs.info, Node: Accumulating Text, Next: Rectangles, Prev: Using X Selections, Up: Top
+
+Accumulating Text
+=================
+
+ Usually you copy or move text by killing it and yanking it, but
+there are other ways that are useful for copying one block of text in
+many places, or for copying many scattered blocks of text into one
+place.
+
+ If you like, you can accumulate blocks of text from scattered
+locations either into a buffer or into a file. The relevant commands
+are described here. You can also use Emacs registers for storing and
+accumulating text. *Note Registers::.
+
+`M-x append-to-buffer'
+ Append region to contents of specified buffer (`append-to-buffer').
+
+`M-x prepend-to-buffer'
+ Prepend region to contents of specified buffer.
+
+`M-x copy-to-buffer'
+ Copy region into specified buffer, deleting that buffer's old
+ contents.
+
+`M-x insert-buffer'
+ Insert contents of specified buffer into current buffer at point.
+
+`M-x append-to-file'
+ Append region to the end of the contents of specified file.
+
+ To accumulate text into a buffer, use the command `M-x
+append-to-buffer', which inserts a copy of the region into the buffer
+BUFFERNAME, at the location of point in that buffer. If there is no
+buffer with the given name, one is created.
+
+ If you append text to a buffer that has been used for editing, the
+copied text goes to the place where point is. Point in that buffer is
+left at the end of the copied text, so successive uses of
+`append-to-buffer' accumulate the text in the specified buffer in the
+same order as they were copied. Strictly speaking, this command does
+not always append to the text already in the buffer; but if this command
+is the only command used to alter a buffer, it does always append to the
+existing text because point is always at the end.
+
+ `M-x prepend-to-buffer' is similar to `append-to-buffer', but point
+in the other buffer is left before the copied text, so successive
+prependings add text in reverse order. `M-x copy-to-buffer' is
+similar, except that any existing text in the other buffer is deleted,
+so the buffer is left containing just the text newly copied into it.
+
+ You can retrieve the accumulated text from that buffer with `M-x
+insert-buffer', which takes BUFFERNAME as an argument. It inserts a
+copy of the text in buffer BUFFERNAME into the selected buffer. You
+could alternatively select the other buffer for editing, perhaps moving
+text from it by killing or with `append-to-buffer'. *Note Buffers::,
+for background information on buffers.
+
+ Instead of accumulating text within Emacs in a buffer, you can append
+text directly into a file with `M-x append-to-file', which takes
+FILE-NAME as an argument. It adds the text of the region to the end of
+the specified file. The file is changed immediately on disk. This
+command is normally used with files that are not being visited in
+Emacs. Using it on a file that Emacs is visiting can produce confusing
+results, because the file's text inside Emacs does not change while the
+file itself changes.
+
+\1f
+File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top
+
+Rectangles
+==========
+
+ The rectangle commands affect rectangular areas of text: all
+characters between a certain pair of columns, in a certain range of
+lines. Commands are provided to kill rectangles, yank killed
+rectangles, clear them out, or delete them. Rectangle commands are
+useful with text in multicolumnar formats, like code with comments at
+the right, or for changing text into or out of such formats.
+
+ To specify the rectangle a command should work on, put the mark at
+one corner and point at the opposite corner. The specified rectangle is
+called the "region-rectangle" because it is controlled about the same
+way the region is controlled. Remember that a given combination of
+point and mark values can be interpreted either as specifying a region
+or as specifying a rectangle; it is up to the command that uses them to
+choose the interpretation.
+
+`M-x delete-rectangle'
+ Delete the text of the region-rectangle, moving any following text
+ on each line leftward to the left edge of the region-rectangle.
+
+`M-x kill-rectangle'
+ Similar, but also save the contents of the region-rectangle as the
+ "last killed rectangle".
+
+`M-x yank-rectangle'
+ Yank the last killed rectangle with its upper left corner at point.
+
+`M-x open-rectangle'
+ Insert blank space to fill the space of the region-rectangle. The
+ previous contents of the region-rectangle are pushed rightward.
+
+`M-x clear-rectangle'
+ Clear the region-rectangle by replacing its contents with spaces.
+
+ The rectangle operations fall into two classes: commands deleting and
+moving rectangles, and commands for blank rectangles.
+
+ There are two ways to get rid of the text in a rectangle: you can
+discard the text (delete it) or save it as the "last killed" rectangle.
+The commands for these two ways are `M-x delete-rectangle' and `M-x
+kill-rectangle'. In either case, the portion of each line that falls
+inside the rectangle's boundaries is deleted, causing following text
+(if any) on the line to move left.
+
+ Note that "killing" a rectangle is not killing in the usual sense;
+the rectangle is not stored in the kill ring, but in a special place
+that only records the most recently killed rectangle (that is, does not
+append to a killed rectangle). Different yank commands have to be used
+and only one rectangle is stored, because yanking a rectangle is quite
+different from yanking linear text and yank-popping commands are
+difficult to make sense of.
+
+ Inserting a rectangle is the opposite of deleting one. You specify
+where to put the upper left corner by putting point there. The
+rectangle's first line is inserted at point, the rectangle's second line
+is inserted at a point one line vertically down, and so on. The number
+of lines affected is determined by the height of the saved rectangle.
+
+ To insert the last killed rectangle, type `M-x yank-rectangle'.
+This can be used to convert single-column lists into double-column
+lists; kill the second half of the list as a rectangle and then yank it
+beside the first line of the list.
+
+ There are two commands for working with blank rectangles: `M-x
+clear-rectangle' erases existing text, and `M-x open-rectangle' inserts
+a blank rectangle. Clearing a rectangle is equivalent to deleting it
+and then inserting a blank rectangle of the same size.
+
+ Rectangles can also be copied into and out of registers. *Note
+Rectangle Registers: RegRect.
+
+\1f
+File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top
+
+Registers
+*********
+
+ Emacs "registers" are places in which you can save text or positions
+for later use. Text saved in a register can be copied into the buffer
+once or many times; a position saved in a register is used by moving
+point to that position. Rectangles can also be copied into and out of
+registers (*note Rectangles::.).
+
+ Each register has a name, which is a single character. A register
+can store either a piece of text, a position, or a rectangle, but only
+one thing at any given time. Whatever you store in a register remains
+there until you store something else in that register.
+
+* Menu:
+
+* RegPos:: Saving positions in registers.
+* RegText:: Saving text in registers.
+* RegRect:: Saving rectangles in registers.
+
+`M-x view-register <RET> R'
+ Display a description of what register R contains.
+
+ `M-x view-register' reads a register name as an argument and then
+displays the contents of the specified register.
+
+\1f
+File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers
+
+Saving Positions in Registers
+=============================
+
+ Saving a position records a spot in a buffer so you can move back
+there later. Moving to a saved position re-selects the buffer and
+moves point to the spot.
+
+`C-x r SPC R'
+ Save the location of point in register R (`point-to-register').
+
+`C-x r j R'
+ Jump to the location saved in register R (`register-to-point').
+
+ To save the current location of point in a register, choose a name R
+and type `C-x r SPC R'. The register R retains the location thus saved
+until you store something else in that register.
+
+ The command `C-x r j R' moves point to the location recorded in
+register R. The register is not affected; it continues to record the
+same location. You can jump to the same position using the same
+register as often as you want.
+
+\1f
+File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers
+
+Saving Text in Registers
+========================
+
+ When you want to insert a copy of the same piece of text many times,
+it can be impractical to use the kill ring, since each subsequent kill
+moves the piece of text further down on the ring. It becomes hard to
+keep track of the argument needed to retrieve the same text with `C-y'.
+An alternative is to store the text in a register with `C-x r s'
+(`copy-to-register') and then retrieve it with `C-x r g'
+(`insert-register').
+
+`C-x r s R'
+ Copy region into register R (`copy-to-register').
+
+`C-x r g R'
+ Insert text contents of register R (`insert-register').
+
+ `C-x r s R' stores a copy of the text of the region into the
+register named R. Given a numeric argument, `C-x r s' deletes the text
+from the buffer as well.
+
+ `C-x r g R' inserts the text from register R in the buffer. By
+default it leaves point before the text and places the mark after it.
+With a numeric argument, it puts point after the text and the mark
+before it.
+
+\1f
+File: xemacs.info, Node: RegRect, Prev: RegText, Up: Registers
+
+Saving Rectangles in Registers
+==============================
+
+ A register can contain a rectangle instead of lines of text. The
+rectangle is represented as a list of strings. *Note Rectangles::, for
+basic information on rectangles and how to specify rectangles in a
+buffer.
+
+`C-x r r R'
+ Copy the region-rectangle into register
+ R(`copy-rectangle-to-register'). With a numeric argument, delete
+ it as well.
+
+`C-x r g R'
+ Insert the rectangle stored in register R (if it contains a
+ rectangle) (`insert-register').
+
+ The `C-x r g' command inserts linear text if the register contains
+that, or inserts a rectangle if the register contains one.
+
+\1f
+File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top
+
+Controlling the Display
+***********************
+
+ Since only part of a large buffer fits in the window, XEmacs tries
+to show the part that is likely to be interesting. The display control
+commands allow you to specify which part of the text you want to see.
+
+`C-l'
+ Clear frame and redisplay, scrolling the selected window to center
+ point vertically within it (`recenter').
+
+`C-v'
+`pgdn'
+`next'
+ Scroll forward (a windowful or a specified number of lines)
+ (`scroll-up'). On most X keyboards, you can get this
+ functionality using the key labelled `Page Down', which generates
+ either `next' or `pgdn'.
+
+`M-v'
+`pgup'
+`prior'
+ Scroll backward (`scroll-down'). On most X keyboards, you can get
+ this functionality using the key labelled `Page Up', which
+ generates either `prior' or `pgup'.
+
+`ARG C-l'
+ Scroll so point is on line ARG (`recenter').
+
+`C-x <'
+`C-pgdn'
+`C-next'
+ Scroll text in current window to the left (`scroll-left').
+
+`C-x >'
+`C-pgup'
+`C-prior'
+ Scroll to the right (`scroll-right').
+
+`C-x $'
+ Make deeply indented lines invisible (`set-selective-display').
+
+* Menu:
+
+* Scrolling:: Moving text up and down in a window.
+* Horizontal Scrolling:: Moving text left and right in a window.
+* Selective Display:: Hiding lines with lots of indentation.
+* Display Vars:: Information on variables for customizing display.
+
+\1f
+File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display
+
+Scrolling
+=========
+
+ If a buffer contains text that is too large to fit entirely within
+the window that is displaying the buffer, XEmacs shows a contiguous
+section of the text. The section shown always contains point.
+
+ "Scrolling" means moving text up or down in the window so that
+different parts of the text are visible. Scrolling forward means that
+text moves up, and new text appears at the bottom. Scrolling backward
+moves text down and new text appears at the top.
+
+ Scrolling happens automatically if you move point past the bottom or
+top of the window. You can also explicitly request scrolling with the
+commands in this section.
+
+`C-l'
+ Clear frame and redisplay, scrolling the selected window to center
+ point vertically within it (`recenter').
+
+`C-v'
+`pgdn'
+`next'
+ Scroll forward (a windowful or a specified number of lines)
+ (`scroll-up').
+
+`M-v'
+`pgup'
+`prior'
+ Scroll backward (`scroll-down').
+
+`ARG C-l'
+ Scroll so point is on line ARG (`recenter').
+
+ The most basic scrolling command is `C-l' (`recenter') with no
+argument. It clears the entire frame and redisplays all windows. In
+addition, it scrolls the selected window so that point is halfway down
+from the top of the window.
+
+ The scrolling commands `C-v' and `M-v' let you move all the text in
+the window up or down a few lines. `C-v' (`scroll-up') with an
+argument shows you that many more lines at the bottom of the window,
+moving the text and point up together as `C-l' might. `C-v' with a
+negative argument shows you more lines at the top of the window.
+`Meta-v' (`scroll-down') is like `C-v', but moves in the opposite
+direction.
+
+ To read the buffer a windowful at a time, use `C-v' with no
+argument. `C-v' takes the last two lines at the bottom of the window
+and puts them at the top, followed by nearly a whole windowful of lines
+not previously visible. Point moves to the new top of the window if it
+was in the text scrolled off the top. `M-v' with no argument moves
+backward with similar overlap. The number of lines of overlap across a
+`C-v' or `M-v' is controlled by the variable
+`next-screen-context-lines'; by default, it is two.
+
+ Another way to scroll is using `C-l' with a numeric argument. `C-l'
+does not clear the frame when given an argument; it only scrolls the
+selected window. With a positive argument N, `C-l' repositions text to
+put point N lines down from the top. An argument of zero puts point on
+the very top line. Point does not move with respect to the text;
+rather, the text and point move rigidly on the frame. `C-l' with a
+negative argument puts point that many lines from the bottom of the
+window. For example, `C-u - 1 C-l' puts point on the bottom line, and
+`C-u - 5 C-l' puts it five lines from the bottom. Just `C-u' as
+argument, as in `C-u C-l', scrolls point to the center of the frame.
+
+ Scrolling happens automatically if point has moved out of the visible
+portion of the text when it is time to display. Usually scrolling is
+done to put point vertically centered within the window. However, if
+the variable `scroll-step' has a non-zero value, an attempt is made to
+scroll the buffer by that many lines; if that is enough to bring point
+back into visibility, that is what happens.
+
+ Scrolling happens automatically if point has moved out of the visible
+portion of the text when it is time to display. Usually scrolling is
+done to put point vertically centered within the window. However, if
+the variable `scroll-step' has a non-zero value, an attempt is made to
+scroll the buffer by that many lines; if that is enough to bring point
+back into visibility, that is what happens.
+
+ If you set `scroll-step' to a small value because you want to use
+arrow keys to scroll the screen without recentering, the redisplay
+preemption will likely make XEmacs keep recentering the screen when
+scrolling fast, regardless of `scroll-step'. To prevent this, set
+`scroll-conservatively' to a small value, which will have the result of
+overriding the redisplay preemption.
+
+\1f
+File: xemacs.info, Node: Horizontal Scrolling, Prev: Scrolling, Up: Display
+
+Horizontal Scrolling
+====================
+
+`C-x <'
+ Scroll text in current window to the left (`scroll-left').
+
+`C-x >'
+ Scroll to the right (`scroll-right').
+
+ The text in a window can also be scrolled horizontally. This means
+that each line of text is shifted sideways in the window, and one or
+more characters at the beginning of each line are not displayed at all.
+When a window has been scrolled horizontally in this way, text lines
+are truncated rather than continued (*note Continuation Lines::.), with
+a `$' appearing in the first column when there is text truncated to the
+left, and in the last column when there is text truncated to the right.
+
+ The command `C-x <' (`scroll-left') scrolls the selected window to
+the left by N columns with argument N. With no argument, it scrolls by
+almost the full width of the window (two columns less, to be precise).
+`C-x >' (`scroll-right') scrolls similarly to the right. The window
+cannot be scrolled any farther to the right once it is displaying
+normally (with each line starting at the window's left margin);
+attempting to do so has no effect.
+
+\1f
+File: xemacs.info, Node: Selective Display, Next: Display Vars, Prev: Display, Up: Display
+
+Selective Display
+=================
+
+ XEmacs can hide lines indented more than a certain number of columns
+(you specify how many columns). This allows you to get an overview of
+a part of a program.
+
+ To hide lines, type `C-x $' (`set-selective-display') with a numeric
+argument N. (*Note Arguments::, for information on giving the
+argument.) Lines with at least N columns of indentation disappear from
+the screen. The only indication of their presence are three dots
+(`...'), which appear at the end of each visible line that is followed
+by one or more invisible ones.
+
+ The invisible lines are still present in the buffer, and most editing
+commands see them as usual, so it is very easy to put point in the
+middle of invisible text. When this happens, the cursor appears at the
+end of the previous line, after the three dots. If point is at the end
+of the visible line, before the newline that ends it, the cursor
+appears before the three dots.
+
+ The commands `C-n' and `C-p' move across the invisible lines as if
+they were not there.
+
+ To make everything visible again, type `C-x $' with no argument.
+
+\1f
+File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display
+
+Variables Controlling Display
+=============================
+
+ This section contains information for customization only. Beginning
+users should skip it.
+
+ When you reenter XEmacs after suspending, XEmacs normally clears the
+screen and redraws the entire display. On some terminals with more than
+one page of memory, it is possible to arrange the termcap entry so that
+the `ti' and `te' strings (output to the terminal when XEmacs is
+entered and exited, respectively) switch between pages of memory so as
+to use one page for XEmacs and another page for other output. In that
+case, you might want to set the variable `no-redraw-on-reenter' to
+non-`nil' so that XEmacs will assume, when resumed, that the screen
+page it is using still contains what XEmacs last wrote there.
+
+ The variable `echo-keystrokes' controls the echoing of
+multi-character keys; its value is the number of seconds of pause
+required to cause echoing to start, or zero, meaning don't echo at all.
+*Note Echo Area::.
+
+ If the variable `ctl-arrow' is `nil', control characters in the
+buffer are displayed with octal escape sequences, all except newline and
+tab. If its value is `t', then control characters will be printed with
+an up-arrow, for example `^A'.
+
+ If its value is not `t' and not `nil', then characters whose code is
+greater than 160 (that is, the space character (32) with its high bit
+set) will be assumed to be printable, and will be displayed without
+alteration. This is the default when running under X Windows, since
+XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
+The `ctl-arrow' variable may also be set to an integer, in which case
+all characters whose codes are greater than or equal to that value will
+be assumed to be printable.
+
+ Altering the value of `ctl-arrow' makes it local to the current
+buffer; until that time, the default value is in effect. *Note
+Locals::.
+
+ Normally, a tab character in the buffer is displayed as whitespace
+which extends to the next display tab stop position, and display tab
+stops come at intervals equal to eight spaces. The number of spaces
+per tab is controlled by the variable `tab-width', which is made local
+by changing it, just like `ctl-arrow'. Note that how the tab character
+in the buffer is displayed has nothing to do with the definition of
+<TAB> as a command.
+
+ If you set the variable `selective-display-ellipses' to `nil', the
+three dots at the end of a line that precedes invisible lines do not
+appear. There is no visible indication of the invisible lines. This
+variable becomes local automatically when set.
+
+\1f
+File: xemacs.info, Node: Search, Next: Fixit, Prev: Display, Up: Top
+
+Searching and Replacement
+*************************
+
+ Like other editors, Emacs has commands for searching for occurrences
+of a string. The principal search command is unusual in that it is
+"incremental": it begins to search before you have finished typing the
+search string. There are also non-incremental search commands more like
+those of other editors.
+
+ Besides the usual `replace-string' command that finds all
+occurrences of one string and replaces them with another, Emacs has a
+fancy replacement command called `query-replace' which asks
+interactively which occurrences to replace.
+
+* Menu:
+
+* Incremental Search:: Search happens as you type the string.
+* Non-Incremental Search:: Specify entire string and then search.
+* Word Search:: Search for sequence of words.
+* Regexp Search:: Search for match for a regexp.
+* Regexps:: Syntax of regular expressions.
+* Search Case:: To ignore case while searching, or not.
+* Replace:: Search, and replace some or all matches.
+* Other Repeating Search:: Operating on all matches for some regexp.
+
+\1f
+File: xemacs.info, Node: Incremental Search, Next: Non-Incremental Search, Prev: Search, Up: Search
+
+Incremental Search
+==================
+
+ An incremental search begins searching as soon as you type the first
+character of the search string. As you type in the search string, Emacs
+shows you where the string (as you have typed it so far) is found.
+When you have typed enough characters to identify the place you want,
+you can stop. Depending on what you do next, you may or may not need to
+terminate the search explicitly with a <RET>.
+
+`C-s'
+ Incremental search forward (`isearch-forward').
+
+`C-r'
+ Incremental search backward (`isearch-backward').
+
+ `C-s' starts an incremental search. `C-s' reads characters from the
+keyboard and positions the cursor at the first occurrence of the
+characters that you have typed. If you type `C-s' and then `F', the
+cursor moves right after the first `F'. Type an `O', and see the
+cursor move to after the first `FO'. After another `O', the cursor is
+after the first `FOO' after the place where you started the search.
+Meanwhile, the search string `FOO' has been echoed in the echo area.
+
+ The echo area display ends with three dots when actual searching is
+going on. When search is waiting for more input, the three dots are
+removed. (On slow terminals, the three dots are not displayed.)
+
+ If you make a mistake in typing the search string, you can erase
+characters with <DEL>. Each <DEL> cancels the last character of the
+search string. This does not happen until Emacs is ready to read
+another input character; first it must either find, or fail to find,
+the character you want to erase. If you do not want to wait for this
+to happen, use `C-g' as described below.
+
+ When you are satisfied with the place you have reached, you can type
+<RET> (or <C-m>), which stops searching, leaving the cursor where the
+search brought it. Any command not specially meaningful in searches
+also stops the search and is then executed. Thus, typing `C-a' exits
+the search and then moves to the beginning of the line. <RET> is
+necessary only if the next command you want to type is a printing
+character, <DEL>, <ESC>, or another control character that is special
+within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
+
+ Sometimes you search for `FOO' and find it, but were actually
+looking for a different occurance of it. To move to the next occurrence
+of the search string, type another `C-s'. Do this as often as
+necessary. If you overshoot, you can cancel some `C-s' characters with
+<DEL>.
+
+ After you exit a search, you can search for the same string again by
+typing just `C-s C-s': the first `C-s' is the key that invokes
+incremental search, and the second `C-s' means "search again".
+
+ If the specified string is not found at all, the echo area displays
+the text `Failing I-Search'. The cursor is after the place where Emacs
+found as much of your string as it could. Thus, if you search for
+`FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
+`FOOL'. At this point there are several things you can do. If you
+mistyped the search string, correct it. If you like the place you have
+found, you can type <RET> or some other Emacs command to "accept what
+the search offered". Or you can type `C-g', which removes from the
+search string the characters that could not be found (the `T' in
+`FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second
+`C-g' at that point cancels the search entirely, returning point to
+where it was when the search started.
+
+ If a search is failing and you ask to repeat it by typing another
+`C-s', it starts again from the beginning of the buffer. Repeating a
+failing backward search with `C-r' starts again from the end. This is
+called "wrapping around". `Wrapped' appears in the search prompt once
+this has happened.
+
+ The `C-g' "quit" character does special things during searches; just
+what it does depends on the status of the search. If the search has
+found what you specified and is waiting for input, `C-g' cancels the
+entire search. The cursor moves back to where you started the search.
+If `C-g' is typed when there are characters in the search string that
+have not been found--because Emacs is still searching for them, or
+because it has failed to find them--then the search string characters
+which have not been found are discarded from the search string. The
+search is now successful and waiting for more input, so a second `C-g'
+cancels the entire search.
+
+ To search for a control character such as `C-s' or <DEL> or <ESC>,
+you must quote it by typing `C-q' first. This function of `C-q' is
+analogous to its meaning as an Emacs command: it causes the following
+character to be treated the way a graphic character would normally be
+treated in the same context.
+
+ To search backwards, you can use `C-r' instead of `C-s' to start the
+search; `C-r' is the key that runs the command (`isearch-backward') to
+search backward. You can also use `C-r' to change from searching
+forward to searching backwards. Do this if a search fails because the
+place you started was too far down in the file. Repeated `C-r' keeps
+looking for more occurrences backwards. `C-s' starts going forward
+again. You can cancel `C-r' in a search with <DEL>.
+
+ The characters `C-y' and `C-w' can be used in incremental search to
+grab text from the buffer into the search string. This makes it
+convenient to search for another occurrence of text at point. `C-w'
+copies the word after point as part of the search string, advancing
+point over that word. Another `C-s' to repeat the search will then
+search for a string including that word. `C-y' is similar to `C-w' but
+copies the rest of the current line into the search string.
+
+ The characters `M-p' and `M-n' can be used in an incremental search
+to recall things which you have searched for in the past. A list of
+the last 16 things you have searched for is retained, and `M-p' and
+`M-n' let you cycle through that ring.
+
+ The character `M-<TAB>' does completion on the elements in the
+search history ring. For example, if you know that you have recently
+searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
+If you had searched for other strings beginning with `PO' then you
+would be shown a list of them, and would need to type more to select
+one.
+
+ You can change any of the special characters in incremental search
+via the normal keybinding mechanism: simply add a binding to the
+`isearch-mode-map'. For example, to make the character `C-b' mean
+"search backwards" while in isearch-mode, do this:
+
+ (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
+
+ These are the default bindings of isearch-mode:
+
+`DEL'
+ Delete a character from the incremental search string
+ (`isearch-delete-char').
+
+`RET'
+ Exit incremental search (`isearch-exit').
+
+`C-q'
+ Quote special characters for incremental search
+ (`isearch-quote-char').
+
+`C-s'
+ Repeat incremental search forward (`isearch-repeat-forward').
+
+`C-r'
+ Repeat incremental search backward (`isearch-repeat-backward').
+
+`C-y'
+ Pull rest of line from buffer into search string
+ (`isearch-yank-line').
+
+`C-w'
+ Pull next word from buffer into search string
+ (`isearch-yank-word').
+
+`C-g'
+ Cancels input back to what has been found successfully, or aborts
+ the isearch (`isearch-abort').
+
+`M-p'
+ Recall the previous element in the isearch history ring
+ (`isearch-ring-retreat').
+
+`M-n'
+ Recall the next element in the isearch history ring
+ (`isearch-ring-advance').
+
+`M-<TAB>'
+ Do completion on the elements in the isearch history ring
+ (`isearch-complete').
+
+ Any other character which is normally inserted into a buffer when
+typed is automatically added to the search string in isearch-mode.
+
+Slow Terminal Incremental Search
+--------------------------------
+
+ Incremental search on a slow terminal uses a modified style of
+display that is designed to take less time. Instead of redisplaying
+the buffer at each place the search gets to, it creates a new
+single-line window and uses that to display the line the search has
+found. The single-line window appears as soon as point gets outside of
+the text that is already on the screen.
+
+ When the search is terminated, the single-line window is removed.
+Only at this time the window in which the search was done is
+redisplayed to show its new value of point.
+
+ The three dots at the end of the search string, normally used to
+indicate that searching is going on, are not displayed in slow style
+display.
+
+ The slow terminal style of display is used when the terminal baud
+rate is less than or equal to the value of the variable
+`search-slow-speed', initially 1200.
+
+ The number of lines to use in slow terminal search display is
+controlled by the variable `search-slow-window-lines'. Its normal
+value is 1.
+
+\1f
+File: xemacs.info, Node: Non-Incremental Search, Next: Word Search, Prev: Incremental Search, Up: Search
+
+Non-Incremental Search
+======================
+
+ Emacs also has conventional non-incremental search commands, which
+require you type the entire search string before searching begins.
+
+`C-s <RET> STRING <RET>'
+ Search for STRING.
+
+`C-r <RET> STRING <RET>'
+ Search backward for STRING.
+
+ To do a non-incremental search, first type `C-s <RET>' (or `C-s
+C-m'). This enters the minibuffer to read the search string.
+Terminate the string with <RET> to start the search. If the string is
+not found, the search command gets an error.
+
+ By default, `C-s' invokes incremental search, but if you give it an
+empty argument, which would otherwise be useless, it invokes
+non-incremental search. Therefore, `C-s <RET>' invokes non-incremental
+search. `C-r <RET>' also works this way.
+
+ Forward and backward non-incremental searches are implemented by the
+commands `search-forward' and `search-backward'. You can bind these
+commands to keys. The reason that incremental search is programmed to
+invoke them as well is that `C-s <RET>' is the traditional sequence of
+characters used in Emacs to invoke non-incremental search.
+
+ Non-incremental searches performed using `C-s <RET>' do not call
+`search-forward' right away. They first check if the next character is
+`C-w', which requests a word search. *Note Word Search::.
+
+\1f
+File: xemacs.info, Node: Word Search, Next: Regexp Search, Prev: Non-Incremental Search, Up: Search
+
+Word Search
+===========
+
+ Word search looks for a sequence of words without regard to how the
+words are separated. More precisely, you type a string of many words,
+using single spaces to separate them, and the string is found even if
+there are multiple spaces, newlines or other punctuation between the
+words.
+
+ Word search is useful in editing documents formatted by text
+formatters. If you edit while looking at the printed, formatted
+version, you can't tell where the line breaks are in the source file.
+Word search, allows you to search without having to know the line
+breaks.
+
+`C-s <RET> C-w WORDS <RET>'
+ Search for WORDS, ignoring differences in punctuation.
+
+`C-r <RET> C-w WORDS <RET>'
+ Search backward for WORDS, ignoring differences in punctuation.
+
+ Word search is a special case of non-incremental search. It is
+invoked with `C-s <RET> C-w' followed by the search string, which must
+always be terminated with another <RET>. Being non-incremental, this
+search does not start until the argument is terminated. It works by
+constructing a regular expression and searching for that. *Note Regexp
+Search::.
+
+ You can do a backward word search with `C-r <RET> C-w'.
+
+ Forward and backward word searches are implemented by the commands
+`word-search-forward' and `word-search-backward'. You can bind these
+commands to keys. The reason that incremental search is programmed to
+invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
+sequence of keys for word search.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search
+
+Regular Expression Search
+=========================
+
+ A "regular expression" ("regexp", for short) is a pattern that
+denotes a set of strings, possibly an infinite set. Searching for
+matches for a regexp is a powerful operation that editors on Unix
+systems have traditionally offered. In XEmacs, you can search for the
+next match for a regexp either incrementally or not.
+
+ Incremental search for a regexp is done by typing `M-C-s'
+(`isearch-forward-regexp'). This command reads a search string
+incrementally just like `C-s', but it treats the search string as a
+regexp rather than looking for an exact match against the text in the
+buffer. Each time you add text to the search string, you make the
+regexp longer, and the new regexp is searched for. A reverse regexp
+search command `isearch-backward-regexp' also exists, but no key runs
+it.
+
+ All of the control characters that do special things within an
+ordinary incremental search have the same functionality in incremental
+regexp search. Typing `C-s' or `C-r' immediately after starting a
+search retrieves the last incremental search regexp used: incremental
+regexp and non-regexp searches have independent defaults.
+
+ Non-incremental search for a regexp is done by the functions
+`re-search-forward' and `re-search-backward'. You can invoke them with
+`M-x' or bind them to keys. You can also call `re-search-forward' by
+way of incremental regexp search with `M-C-s <RET>'.
+
+\1f
+File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search
+
+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 which matches that character and nothing
+else. The special characters are `$', `^', `.', `*', `+', `?', `[',
+`]' and `\'; no new special characters will be defined. 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 which 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, you can concatenate the regular expressions `f'
+and `o' to get the regular expression `fo', which matches only the
+string `fo'. To do something nontrivial, you need to use one of the
+following special characters:
+
+`. (Period)'
+ is a special character that matches any single character except a
+ newline. Using concatenation, you can make regular expressions
+ like `a.b', which matches any three-character string which begins
+ with `a' and ends with `b'.
+
+`*'
+ is not a construct by itself; it is a suffix, which means the
+ preceding regular expression is to be repeated 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 immediately matching as
+ many repetitions as it can find. 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,
+ 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.
+
+`+'
+ is a suffix character similar to `*' except that it requires that
+ the preceding expression be matched at least once. For example,
+ `ca+r' will match the strings `car' and `caaaar' but not the
+ string `cr', whereas `ca*r' would match all three strings.
+
+`?'
+ is a suffix character similar to `*' except that it can match the
+ preceding expression either once or not at all. For example,
+ `ca?r' will match `car' or `cr'; nothing else.
+
+`[ ... ]'
+ `[' begins a "character set", which is terminated by a `]'. In
+ the simplest case, the characters between the two 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.
+
+ You can include character ranges in a character set by writing 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 period.
+
+ Note that inside a character set the usual special characters are
+ not special any more. A completely different set of special
+ characters exists inside character sets: `]', `-', and `^'.
+
+ To include a `]' in a character set, you must make it the first
+ character. For example, `[]a]' matches `]' or `a'. To include a
+ `-', write `---', which is a range containing only `-'. To
+ include `^', make it other than the first character in 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 (`-' 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 if
+ 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.
+
+`$'
+ is similar to `^' but matches only at the end of a line. Thus,
+ `xx*$' matches a string of one `x' or more at the end of a line.
+
+`\'
+ does two things: 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: 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; better to quote the special character anyway,
+regardless of where is appears.
+
+ Usually, `\' followed by any character matches only that character.
+However, there are several exceptions: characters which, 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 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 a complicated expression for the postfix `*' to
+ operate on. Thus, `ba\(na\)*' matches `bananana', etc., with
+ any (zero or more) number of `na' strings.
+
+ 3. To mark 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 which happens to
+ be assigned as a second meaning to the same `\( ... \)' construct
+ because in practice there is no conflict between the two meanings.
+ Here is an explanation:
+
+`\DIGIT'
+ 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 mean "match the same text matched the DIGIT'th time by the
+ `\( ... \)' construct."
+
+ The strings matching the first nine `\( ... \)' constructs
+ appearing in a regular expression are assigned numbers 1 through 9
+ in order that the open-parentheses appear in the regular
+ expression. `\1' through `\9' may be used to refer to the text
+ matched by the corresponding `\( ... \)' construct.
+
+ 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.
+
+`\`'
+ matches the empty string, provided it is at the beginning of the
+ buffer.
+
+`\''
+ matches the empty string, provided it is at the end of the buffer.
+
+`\b'
+ matches the empty string, provided it is 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, provided it is not at the beginning or
+ end of a word.
+
+`\<'
+ matches the empty string, provided it is at the beginning of a
+ word.
+
+`\>'
+ matches the empty string, provided it is at the end of a word.
+
+`\w'
+ matches any word-constituent character. The editor syntax table
+ determines which characters these are.
+
+`\W'
+ matches any character that is not a word-constituent.
+
+`\sCODE'
+ matches any character whose syntax is CODE. CODE is a character
+ which represents a syntax code: thus, `w' for word constituent,
+ `-' for whitespace, `(' for open-parenthesis, etc. *Note Syntax::.
+
+`\SCODE'
+ matches any character whose syntax is not CODE.
+
+ Here is a complicated regexp used by Emacs to recognize the end of a
+sentence together with any whitespace that follows. It is given in Lisp
+syntax to enable you to distinguish the spaces from the tab characters.
+In Lisp syntax, the string constant begins and ends with a
+double-quote. `\"' stands for a double-quote as part of the regexp,
+`\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
+a newline.
+
+ "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
+
+This regexp contains four parts: a character set matching period, `?'
+or `!'; a character set matching close-brackets, quotes or parentheses,
+repeated any number of times; an alternative in backslash-parentheses
+that matches end-of-line, a tab or two spaces; and a character set
+matching whitespace characters, repeated any number of times.
+
+\1f
+File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search
+
+Searching and Case
+==================
+
+ All searches in Emacs normally ignore the case of the text they are
+searching through; if you specify searching for `FOO', `Foo' and `foo'
+are also considered a match. Regexps, and in particular character
+sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
+
+ If you want a case-sensitive search, set the variable
+`case-fold-search' to `nil'. Then all letters must match exactly,
+including case. `case-fold-search' is a per-buffer variable; altering
+it affects only the current buffer, but there is a default value which
+you can change as well. *Note Locals::. You can also use Case
+Sensitive Search from the Options menu on your screen.
+
+\1f
+File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search
+
+Replacement Commands
+====================
+
+ Global search-and-replace operations are not needed as often in
+Emacs as they are in other editors, but they are available. In
+addition to the simple `replace-string' command which is like that
+found in most editors, there is a `query-replace' command which asks
+you, for each occurrence of a pattern, whether to replace it.
+
+ The replace commands all replace one string (or regexp) with one
+replacement string. It is possible to perform several replacements in
+parallel using the command `expand-region-abbrevs'. *Note Expanding
+Abbrevs::.
+
+* Menu:
+
+* Unconditional Replace:: Replacing all matches for a string.
+* Regexp Replace:: Replacing all matches for a regexp.
+* Replacement and Case:: How replacements preserve case of letters.
+* Query Replace:: How to use querying.
+
+\1f
+File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace
+
+Unconditional Replacement
+-------------------------
+
+`M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
+ Replace every occurrence of STRING with NEWSTRING.
+
+`M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
+ Replace every match for REGEXP with NEWSTRING.
+
+ To replace every instance of `foo' after point with `bar', use the
+command `M-x replace-string' with the two arguments `foo' and `bar'.
+Replacement occurs only after point: if you want to cover the whole
+buffer you must go to the beginning first. By default, all occurrences
+up to the end of the buffer are replaced. To limit replacement to part
+of the buffer, narrow to that part of the buffer before doing the
+replacement (*note Narrowing::.).
+
+ When `replace-string' exits, point is left at the last occurrence
+replaced. The value of point when the `replace-string' command was
+issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
+
+ A numeric argument restricts replacement to matches that are
+surrounded by word boundaries.
+
+\1f
+File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace
+
+Regexp Replacement
+------------------
+
+ `replace-string' replaces exact matches for a single string. The
+similar command `replace-regexp' replaces any match for a specified
+pattern.
+
+ In `replace-regexp', the NEWSTRING need not be constant. It can
+refer to all or part of what is matched by the REGEXP. `\&' in
+NEWSTRING stands for the entire text being replaced. `\D' in
+NEWSTRING, where D is a digit, stands for whatever matched the D'th
+parenthesized grouping in REGEXP. For example,
+
+ M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
+
+would replace (for example) `cadr' with `cadr-safe' and `cddr' with
+`cddr-safe'.
+
+ M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
+
+would perform exactly the opposite replacements. To include a `\' in
+the text to replace with, you must give `\\'.
+
+\1f
+File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace
+
+Replace Commands and Case
+-------------------------
+
+ If the arguments to a replace command are in lower case, the command
+preserves case when it makes a replacement. Thus, the following
+command:
+
+ M-x replace-string <RET> foo <RET> bar <RET>
+
+replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
+and `Foo' with `Bar'. If upper-case letters are used in the second
+argument, they remain upper-case every time that argument is inserted.
+If upper-case letters are used in the first argument, the second
+argument is always substituted exactly as given, with no case
+conversion. Likewise, if the variable `case-replace' is set to `nil',
+replacement is done without case conversion. If `case-fold-search' is
+set to `nil', case is significant in matching occurrences of `foo' to
+replace; also, case conversion of the replacement string is not done.
+
+\1f
+File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace
+
+Query Replace
+-------------
+
+`M-% STRING <RET> NEWSTRING <RET>'
+`M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
+ Replace some occurrences of STRING with NEWSTRING.
+
+`M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
+ Replace some matches for REGEXP with NEWSTRING.
+
+ If you want to change only some of the occurrences of `foo' to
+`bar', not all of them, you can use `query-replace' instead of `M-%'.
+This command finds occurrences of `foo' one by one, displays each
+occurrence, and asks you whether to replace it. A numeric argument to
+`query-replace' tells it to consider only occurrences that are bounded
+by word-delimiter characters.
+
+ Aside from querying, `query-replace' works just like
+`replace-string', and `query-replace-regexp' works just like
+`replace-regexp'.
+
+ The things you can type when you are shown an occurrence of STRING
+or a match for REGEXP are:
+
+`<SPC>'
+ to replace the occurrence with NEWSTRING. This preserves case,
+ just like `replace-string', provided `case-replace' is non-`nil',
+ as it normally is.
+
+`<DEL>'
+ to skip to the next occurrence without replacing this one.
+
+`, (Comma)'
+ to replace this occurrence and display the result. You are then
+ prompted for another input character. However, since the
+ replacement has already been made, <DEL> and <SPC> are equivalent.
+ At this point, you can type `C-r' (see below) to alter the
+ replaced text. To undo the replacement, you can type `C-x u'.
+ This exits the `query-replace'. If you want to do further
+ replacement you must use `C-x ESC' to restart (*note
+ Repetition::.).
+
+`<ESC>'
+ to exit without doing any more replacements.
+
+`. (Period)'
+ to replace this occurrence and then exit.
+
+`!'
+ to replace all remaining occurrences without asking again.
+
+`^'
+ to go back to the location of the previous occurrence (or what
+ used to be an occurrence), in case you changed it by mistake.
+ This works by popping the mark ring. Only one `^' in a row is
+ allowed, because only one previous replacement location is kept
+ during `query-replace'.
+
+`C-r'
+ to enter a recursive editing level, in case the occurrence needs
+ to be edited rather than just replaced with NEWSTRING. When you
+ are done, exit the recursive editing level with `C-M-c' and the
+ next occurrence will be displayed. *Note Recursive Edit::.
+
+`C-w'
+ to delete the occurrence, and then enter a recursive editing level
+ as in `C-r'. Use the recursive edit to insert text to replace the
+ deleted occurrence of STRING. When done, exit the recursive
+ editing level with `C-M-c' and the next occurrence will be
+ displayed.
+
+`C-l'
+ to redisplay the screen and then give another answer.
+
+`C-h'
+ to display a message summarizing these options, then give another
+ answer.
+
+ If you type any other character, Emacs exits the `query-replace', and
+executes the character as a command. To restart the `query-replace',
+use `C-x <ESC>', which repeats the `query-replace' because it used the
+minibuffer to read its arguments. *Note C-x ESC: Repetition.
+
+\1f
+File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search
+
+Other Search-and-Loop Commands
+==============================
+
+ Here are some other commands that find matches for a regular
+expression. They all operate from point to the end of the buffer.
+
+`M-x occur'
+ Print each line that follows point and contains a match for the
+ specified regexp. A numeric argument specifies the number of
+ context lines to print before and after each matching line; the
+ default is none.
+
+ The buffer `*Occur*' containing the output serves as a menu for
+ finding occurrences in their original context. Find an occurrence
+ as listed in `*Occur*', position point there, and type `C-c C-c';
+ this switches to the buffer that was searched and moves point to
+ the original of the same occurrence.
+
+`M-x list-matching-lines'
+ Synonym for `M-x occur'.
+
+`M-x count-matches'
+ Print the number of matches following point for the specified
+ regexp.
+
+`M-x delete-non-matching-lines'
+ Delete each line that follows point and does not contain a match
+ for the specified regexp.
+
+`M-x delete-matching-lines'
+ Delete each line that follows point and contains a match for the
+ specified regexp.
+
+\1f
+File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top
+
+Commands for Fixing Typos
+*************************
+
+ This chapter describes commands that are especially useful when you
+catch a mistake in your text just after you have made it, or when you
+change your mind while composing text on line.
+
+* Menu:
+
+* Kill Errors:: Commands to kill a batch of recently entered text.
+* Transpose:: Exchanging two characters, words, lines, lists...
+* Fixing Case:: Correcting case of last word entered.
+* Spelling:: Apply spelling checker to a word, or a whole file.
+
+\1f
+File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit
+
+Killing Your Mistakes
+=====================
+
+`<DEL>'
+ Delete last character (`delete-backward-char').
+
+`M-<DEL>'
+ Kill last word (`backward-kill-word').
+
+`C-x <DEL>'
+ Kill to beginning of sentence (`backward-kill-sentence').
+
+ The <DEL> character (`delete-backward-char') is the most important
+correction command. When used among graphic (self-inserting)
+characters, it can be thought of as canceling the last character typed.
+
+ When your mistake is longer than a couple of characters, it might be
+more convenient to use `M-<DEL>' or `C-x <DEL>'. `M-<DEL>' kills back
+to the start of the last word, and `C-x <DEL>' kills back to the start
+of the last sentence. `C-x <DEL>' is particularly useful when you are
+thinking of what to write as you type it, in case you change your mind
+about phrasing. `M-<DEL>' and `C-x <DEL>' save the killed text for
+`C-y' and `M-y' to retrieve. *Note Yanking::.
+
+ `M-<DEL>' is often useful even when you have typed only a few
+characters wrong, if you know you are confused in your typing and aren't
+sure exactly what you typed. At such a time, you cannot correct with
+<DEL> except by looking at the screen to see what you did. It requires
+less thought to kill the whole word and start over.
+
+\1f
+File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit
+
+Transposing Text
+================
+
+`C-t'
+ Transpose two characters (`transpose-chars').
+
+`M-t'
+ Transpose two words (`transpose-words').
+
+`C-M-t'
+ Transpose two balanced expressions (`transpose-sexps').
+
+`C-x C-t'
+ Transpose two lines (`transpose-lines').
+
+ The common error of transposing two adjacent characters can be fixed
+with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes
+the two characters on either side of point. When given at the end of a
+line, `C-t' transposes the last two characters on the line, rather than
+transposing the last character of the line with the newline, which
+would be useless. If you catch a transposition error right away, you
+can fix it with just `C-t'. If you catch the error later, move the
+cursor back to between the two transposed characters. If you
+transposed a space with the last character of the word before it, the
+word motion commands are a good way of getting there. Otherwise, a
+reverse search (`C-r') is often the best way. *Note Search::.
+
+ `Meta-t' (`transpose-words') transposes the word before point with
+the word after point. It moves point forward over a word, dragging the
+word preceding or containing point forward as well. The punctuation
+characters between the words do not move. For example, `FOO, BAR'
+transposes into `BAR, FOO' rather than `BAR FOO,'.
+
+ `C-M-t' (`transpose-sexps') is a similar command for transposing two
+expressions (*note Lists::.), and `C-x C-t' (`transpose-lines')
+exchanges lines. It works like `M-t' but in determines the division of
+the text into syntactic units differently.
+
+ A numeric argument to a transpose command serves as a repeat count:
+it tells the transpose command to move the character (word, sexp, line)
+before or containing point across several other characters (words,
+sexps, lines). For example, `C-u 3 C-t' moves the character before
+point forward across three other characters. This is equivalent to
+repeating `C-t' three times. `C-u - 4 M-t' moves the word before point
+backward across four words. `C-u - C-M-t' would cancel the effect of
+plain `C-M-t'.
+
+ A numeric argument of zero transposes the character (word, sexp,
+line) ending after point with the one ending after the mark (otherwise a
+command with a repeat count of zero would do nothing).
+
+\1f
+File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit
+
+Case Conversion
+===============
+
+`M-- M-l'
+ Convert last word to lower case. Note that `Meta--' is
+ "Meta-minus."
+
+`M-- M-u'
+ Convert last word to all upper case.
+
+`M-- M-c'
+ Convert last word to lower case with capital initial.
+
+ A common error is to type words in the wrong case. Because of this,
+the word case-conversion commands `M-l', `M-u', and `M-c' do not move
+the cursor when used with a negative argument. As soon as you see you
+have mistyped the last word, you can simply case-convert it and
+continue typing. *Note Case::.
+
+\1f
+File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit
+
+Checking and Correcting Spelling
+================================
+
+`M-$'
+ Check and correct spelling of word (`spell-word').
+
+`M-x spell-buffer'
+ Check and correct spelling of each word in the buffer.
+
+`M-x spell-region'
+ Check and correct spelling of each word in the region.
+
+`M-x spell-string'
+ Check spelling of specified word.
+
+ To check the spelling of the word before point, and optionally
+correct it, use the command `M-$' (`spell-word'). This command runs an
+inferior process containing the `spell' program to see whether the word
+is correct English. If it is not, it asks you to edit the word (in the
+minibuffer) into a corrected spelling, and then performs a
+`query-replace' to substitute the corrected spelling for the old one
+throughout the buffer.
+
+ If you exit the minibuffer without altering the original spelling, it
+means you do not want to do anything to that word. In that case, the
+`query-replace' is not done.
+
+ `M-x spell-buffer' checks each word in the buffer the same way that
+`spell-word' does, doing a `query-replace' for every incorrect word if
+appropriate.
+
+ `M-x spell-region' is similar to `spell-buffer' but operates only on
+the region, not the entire buffer.
+
+ `M-x spell-string' reads a string as an argument and checks whether
+that is a correctly spelled English word. It prints a message giving
+the answer in the echo area.
+
+\1f
+File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top
+
+File Handling
+*************
+
+ The basic unit of stored data in Unix is the "file". To edit a file,
+you must tell Emacs to examine the file and prepare a buffer containing
+a copy of the file's text. This is called "visiting" the file. Editing
+commands apply directly to text in the buffer; that is, to the copy
+inside Emacs. Your changes appear in the file itself only when you
+"save" the buffer back into the file.
+
+ In addition to visiting and saving files, Emacs can delete, copy,
+rename, and append to files, and operate on file directories.
+
+* Menu:
+
+* File Names:: How to type and edit file name arguments.
+* Visiting:: Visiting a file prepares Emacs to edit the file.
+* Saving:: Saving makes your changes permanent.
+* Reverting:: Reverting cancels all the changes not saved.
+* Auto Save:: Auto Save periodically protects against loss of data.
+* Version Control:: Version control systems (RCS and SCCS).
+* ListDir:: Listing the contents of a file directory.
+* Comparing Files:: Finding where two files differ.
+* Dired:: "Editing" a directory to delete, rename, etc.
+ the files in it.
+* Misc File Ops:: Other things you can do on files.
+
+\1f
+File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
+
+File Names
+==========
+
+ Most Emacs commands that operate on a file require you to specify the
+file name. (Saving and reverting are exceptions; the buffer knows which
+file name to use for them.) File names are specified in the minibuffer
+(*note Minibuffer::.). "Completion" is available, to make it easier to
+specify long file names. *Note Completion::.
+
+ There is always a "default file name" which is used if you enter an
+empty argument by typing just <RET>. Normally the default file name is
+the name of the file visited in the current buffer; this makes it easy
+to operate on that file with any of the Emacs file commands.
+
+ Each buffer has a default directory, normally the same as the
+directory of the file visited in that buffer. When Emacs reads a file
+name, the default directory is used if you do not specify a directory.
+If you specify a directory in a relative fashion, with a name that does
+not start with a slash, it is interpreted with respect to the default
+directory. The default directory of the current buffer is kept in the
+variable `default-directory', which has a separate value in every
+buffer. The value of the variable should end with a slash.
+
+ For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
+the default directory is `/u/rms/gnu/'. If you type just `foo', which
+does not specify a directory, it is short for `/u/rms/gnu/foo'.
+`../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
+the filename `/u/rms/gnu/new/foo'.
+
+ The variable `default-directory-alist' takes an alist of major modes
+and their opinions on `default-directory' as a Lisp expression to
+evaluate. A resulting value of `nil' is ignored in favor of
+`default-directory'.
+
+ You can create a new directory with the function `make-directory',
+which takes as an argument a file name string. The current directory is
+displayed in the minibuffer when the function is called; you can delete
+the old directory name and supply a new directory name. For example, if
+the current directory is `/u/rms/gnu', you can delete `gnu' and type
+`oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
+similar to creating one. To remove a directory, use
+`remove-directory'; it takes one argument, a file name string.
+
+ The command `M-x pwd' prints the current buffer's default directory,
+and the command `M-x cd' sets it (to a value read using the
+minibuffer). A buffer's default directory changes only when the `cd'
+command is used. A file-visiting buffer's default directory is
+initialized to the directory of the file that is visited there. If a
+buffer is created with `C-x b', its default directory is copied from
+that of the buffer that was current at the time.
+
+ The default directory name actually appears in the minibuffer when
+the minibuffer becomes active to read a file name. This serves two
+purposes: it shows you what the default is, so that you can type a
+relative file name and know with certainty what it will mean, and it
+allows you to edit the default to specify a different directory. To
+inhibit the insertion of the default directory, set the variable
+`insert-default-directory' to `nil'.
+
+ Note that it is legitimate to type an absolute file name after you
+enter the minibuffer, ignoring the presence of the default directory
+name. The final minibuffer contents may look invalid, but that is not
+so. *Note Minibuffer File::.
+
+ `$' in a file name is used to substitute environment variables. For
+example, if you have used the shell command `setenv FOO rms/hacks' to
+set up an environment variable named `FOO', then you can use
+`/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
+`/u/rms/hacks/test.c'. The environment variable name consists of all
+the alphanumeric characters after the `$'; alternatively, it may be
+enclosed in braces after the `$'. Note that the `setenv' command
+affects Emacs only if done before Emacs is started.
+
+ To access a file with `$' in its name, type `$$'. This pair is
+converted to a single `$' at the same time variable substitution is
+performed for single `$'. The Lisp function that performs the
+substitution is called `substitute-in-file-name'. The substitution is
+performed only on filenames read as such using the minibuffer.
+
+\1f
+File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
+
+Visiting Files
+==============
+
+`C-x C-f'
+ Visit a file (`find-file').
+
+`C-x C-v'
+ Visit a different file instead of the one visited last
+ (`find-alternate-file').
+
+`C-x 4 C-f'
+ Visit a file, in another window (`find-file-other-window'). Don't
+ change this window.
+
+`C-x 5 C-f'
+ Visit a file, in another frame (`find-file-other-frame'). Don't
+ change this window or frame.
+
+ "Visiting" a file means copying its contents into an Emacs buffer so
+you can edit it. Emacs creates a new buffer for each file you visit.
+We say that the buffer is visiting the file that it was created to
+hold. Emacs constructs the buffer name from the file name by throwing
+away the directory and keeping just the file name. For example, a file
+named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'.
+If a buffer with that name exists, a unique name is constructed by
+appending `<2>', `<3>',and so on, using the lowest number that makes a
+name that is not already in use.
+
+ Each window's mode line shows the name of the buffer that is being
+displayed in that window, so you can always tell what buffer you are
+editing.
+
+ The changes you make with Emacs are made in the Emacs buffer. They
+do not take effect in the file that you visit, or any other permanent
+place, until you "save" the buffer. Saving the buffer means that Emacs
+writes the current contents of the buffer into its visited file. *Note
+Saving::.
+
+ If a buffer contains changes that have not been saved, the buffer is
+said to be "modified". This is important because it implies that some
+changes will be lost if the buffer is not saved. The mode line displays
+two stars near the left margin if the buffer is modified.
+
+ To visit a file, use the command `C-x C-f' (`find-file'). Follow
+the command with the name of the file you wish to visit, terminated by a
+<RET>. If you are using XEmacs under X, you can also use the Open...
+command from the File menu bar item.
+
+ The file name is read using the minibuffer (*note Minibuffer::.),
+with defaulting and completion in the standard manner (*note File
+Names::.). While in the minibuffer, you can abort `C-x C-f' by typing
+`C-g'.
+
+ `C-x C-f' has completed successfully when text appears on the screen
+and a new buffer name appears in the mode line. If the specified file
+does not exist and could not be created or cannot be read, an error
+results. The error message is printed in the echo area, and includes
+the name of the file that Emacs was trying to visit.
+
+ If you visit a file that is already in Emacs, `C-x C-f' does not make
+another copy. It selects the existing buffer containing that file.
+However, before doing so, it checks that the file itself has not changed
+since you visited or saved it last. If the file has changed, Emacs
+prints a warning message. *Note Simultaneous Editing: Interlocking.
+
+ You can switch to a specific file called out in the current buffer by
+calling the function `find-this-file'. By providing a prefix argument,
+this function calls `filename-at-point' and switches to a buffer
+visiting the file FILENAME. It creates one if none already exists. You
+can use this function to edit the file mentioned in the buffer you are
+working in or to test if the file exists. You can do that by using the
+minibuffer completion after snatching the all or part of the filename.
+
+ If the variable `find-file-use-truenames''s value is non-`nil', a
+buffer's visited filename will always be traced back to the real file.
+The filename will never be a symbolic link, and there will never be a
+symbolic link anywhere in its directory path. In other words, the
+`buffer-file-name' and `buffer-file-truename' will be equal.
+
+ If the variable `find-file-compare-truenames' value is non-`nil',
+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.
+
+ 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
+visited an existing empty file. If you make any changes and save them,
+the file is created.
+
+ If you visit a nonexistent file unintentionally (because you typed
+the wrong file name), use the `C-x C-v' (`find-alternate-file') command
+to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but
+it kills the current buffer (after first offering to save it if it is
+modified). `C-x C-v' is allowed even if the current buffer is not
+visiting a file.
+
+ If the file you specify is actually a directory, Dired is called on
+that directory (*note Dired::.). To inhibit this, set the variable
+`find-file-run-dired' to `nil'; then it is an error to try to visit a
+directory.
+
+ `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
+the buffer containing the specified file is selected in another window.
+The window that was selected before `C-x 4 f' continues to show the
+same buffer it was already showing. If you use this command when only
+one window is being displayed, that window is split in two, with one
+window showing the same buffer as before, and the other one showing the
+newly requested file. *Note Windows::.
+
+ `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that
+it creates a new frame in which the file is displayed.
+
+ Use the function `find-this-file-other-window' to edit a file
+mentioned in the buffer you are editing or to test if that file exists.
+To do this, use the minibuffer completion after snatching the part or
+all of the filename. By providing a prefix argument, the function calls
+`filename-at-point' and switches you to a buffer visiting the file
+FILENAME in another window. The function creates a buffer if none
+already exists. This function is similar to `find-file-other-window'.
+
+ There are two hook variables that allow extensions to modify the
+operation of visiting files. Visiting a file that does not exist runs
+the functions in the list `find-file-not-found-hooks'; the value of this
+variable is expected to be a list of functions which are called one by
+one until one of them returns non-`nil'. Any visiting of a file,
+whether extant or not, expects `find-file-hooks' to contain list of
+functions and calls them all, one by one. In both cases the functions
+receive no arguments. Visiting a nonexistent file runs the
+`find-file-not-found-hooks' first.
+
+\1f
+File: xemacs.info, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files
+
+Saving Files
+============
+
+ "Saving" a buffer in Emacs means writing its contents back into the
+file that was visited in the buffer.
+
+`C-x C-s'
+ Save the current buffer in its visited file (`save-buffer').
+
+`C-x s'
+ Save any or all buffers in their visited files
+ (`save-some-buffers').
+
+`M-~'
+ Forget that the current buffer has been changed (`not-modified').
+
+`C-x C-w'
+ Save the current buffer in a specified file, and record that file
+ as the one visited in the buffer (`write-file').
+
+`M-x set-visited-file-name'
+ Change file the name under which the current buffer will be saved.
+
+ To save a file and make your changes permanent, type `C-x C-s'
+(`save-buffer'). After saving is finished, `C-x C-s' prints a message
+such as:
+
+ Wrote /u/rms/gnu/gnu.tasks
+
+If the selected buffer is not modified (no changes have been made in it
+since the buffer was created or last saved), Emacs does not save it
+because it would have no effect. Instead, `C-x C-s' prints a message
+in the echo area saying:
+
+ (No changes need to be saved)
+
+ The command `C-x s' (`save-some-buffers') can save any or all
+modified buffers. First it asks, for each modified buffer, whether to
+save it. The questions should be answered with `y' or `n'. `C-x C-c',
+the key that kills Emacs, invokes `save-some-buffers' and therefore
+asks the same questions.
+
+ If you have changed a buffer and do not want the changes to be saved,
+you should take some action to prevent it. Otherwise, you are liable to
+save it by mistake each time you use `save-some-buffers' or a related
+command. One thing you can do is type `M-~' (`not-modified'), which
+removes the indication that the buffer is modified. If you do this,
+none of the save commands will believe that the buffer needs to be
+saved. (`~' is often used as a mathematical symbol for `not'; thus
+`Meta-~' is `not', metafied.) You could also use
+`set-visited-file-name' (see below) to mark the buffer as visiting a
+different file name, not in use for anything important.
+
+ You can also undo all the changes made since the file was visited or
+saved, by reading the text from the file again. This is called
+"reverting". *Note Reverting::. Alternatively, you can undo all the
+changes by repeating the undo command `C-x u'; but this only works if
+you have not made more changes than the undo mechanism can remember.
+
+ `M-x set-visited-file-name' alters the name of the file that the
+current buffer is visiting. It prompts you for the new file name in the
+minibuffer. You can also use `set-visited-file-name' on a buffer that
+is not visiting a file. The buffer's name is changed to correspond to
+the file it is now visiting unless the new name is already used by a
+different buffer; in that case, the buffer name is not changed.
+`set-visited-file-name' does not save the buffer in the newly visited
+file; it just alters the records inside Emacs so that it will save the
+buffer in that file. It also marks the buffer as "modified" so that
+`C-x C-s' will save.
+
+ If you wish to mark a buffer as visiting a different file and save it
+right away, use `C-x C-w' (`write-file'). It is precisely equivalent
+to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' used on a
+buffer that is not visiting a file has the same effect as `C-x C-w';
+that is, it reads a file name, marks the buffer as visiting that file,
+and saves it there. The default file name in a buffer that is not
+visiting a file is made by combining the buffer name with the buffer's
+default directory.
+
+ If Emacs is about to save a file and sees that the date of the latest
+version on disk does not match what Emacs last read or wrote, Emacs
+notifies you of this fact, because it probably indicates a problem
+caused by simultaneous editing and requires your immediate attention.
+*Note Simultaneous Editing: Interlocking.
+
+ If the variable `require-final-newline' is non-`nil', Emacs puts a
+newline at the end of any file that doesn't already end in one, every
+time a file is saved or written.
+
+ Use the hook variable `write-file-hooks' to implement other ways to
+write files, and specify things to be done before files are written.
+The value of this variable should be a list of Lisp functions. When a
+file is to be written, the functions in the list are called, one by
+one, with no arguments. If one of them returns a non-`nil' value, Emacs
+takes this to mean that the file has been written in some suitable
+fashion; the rest of the functions are not called, and normal writing is
+not done. Use the hook variable `after-save-hook' to list all the
+functions to be called after writing out a buffer to a file.
+
+* Menu:
+
+* Backup:: How Emacs saves the old version of your file.
+* Interlocking:: How Emacs protects against simultaneous editing
+ of one file by two users.
+
+\1f
+File: xemacs.info, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving
+
+Backup Files
+------------
+
+ Because Unix does not provide version numbers in file names,
+rewriting a file in Unix automatically destroys all record of what the
+file used to contain. Thus, saving a file from Emacs throws away the
+old contents of the file--or it would, except that Emacs carefully
+copies the old contents to another file, called the "backup" file,
+before actually saving. (Make sure that the variable
+`make-backup-files' is non-`nil'. Backup files are not written if this
+variable is `nil').
+
+ At your option, Emacs can keep either a single backup file or a
+series of numbered backup files for each file you edit.
+
+ Emacs makes a backup for a file only the first time a file is saved
+from one buffer. No matter how many times you save a file, its backup
+file continues to contain the contents from before the file was visited.
+Normally this means that the backup file contains the contents from
+before the current editing session; however, if you kill the buffer and
+then visit the file again, a new backup file is made by the next save.
+
+* Menu:
+
+* Names: Backup Names. How backup files are named;
+ Choosing single or numbered backup files.
+* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
+* Copying: Backup Copying. Backups can be made by copying or renaming.
+
+\1f
+File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup
+
+Single or Numbered Backups
+..........................
+
+ If you choose to have a single backup file (the default), the backup
+file's name is constructed by appending `~' to the file name being
+edited; thus, the backup file for `eval.c' is `eval.c~'.
+
+ If you choose to have a series of numbered backup files, backup file
+names are made by appending `.~', the number, and another `~' to the
+original file name. Thus, the backup files of `eval.c' would be called
+`eval.c.~1~', `eval.c.~2~', and so on, through names like
+`eval.c.~259~' and beyond.
+
+ If protection stops you from writing backup files under the usual
+names, the backup file is written as `%backup%~' in your home directory.
+Only one such file can exist, so only the most recently made backup is
+available.
+
+ The choice of single backup or numbered backups is controlled by the
+variable `version-control'. Its possible values are:
+
+`t'
+ Make numbered backups.
+
+`nil'
+ Make numbered backups for files that have numbered backups already.
+ Otherwise, make single backups.
+
+`never'
+ Never make numbered backups; always make single backups.
+
+`version-control' may be set locally in an individual buffer to control
+the making of backups for that buffer's file. For example, Rmail mode
+locally sets `version-control' to `never' to make sure that there is
+only one backup for an Rmail file. *Note Locals::.
+
+\1f
+File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup
+
+Automatic Deletion of Backups
+.............................
+
+ To prevent unlimited consumption of disk space, Emacs can delete
+numbered backup versions automatically. Generally Emacs keeps the
+first few backups and the latest few backups, deleting any in between.
+This happens every time a new backup is made. The two variables that
+control the deletion are `kept-old-versions' and `kept-new-versions'.
+Their values are, respectively the number of oldest (lowest-numbered)
+backups to keep and the number of newest (highest-numbered) ones to
+keep, each time a new backup is made. The values are used just after a
+new backup version is made; that newly made backup is included in the
+count in `kept-new-versions'. By default, both variables are 2.
+
+ If `trim-versions-without-asking' is non-`nil', excess middle
+versions are deleted without notification. If it is `nil', the
+default, you are asked whether the excess middle versions should really
+be deleted.
+
+ You can also use Dired's `.' (Period) command to delete old versions.
+*Note Dired::.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup
+
+Copying vs. Renaming
+....................
+
+ You can make backup files by copying the old file or by renaming it.
+This makes a difference when the old file has multiple names. If you
+rename the old file into the backup file, the alternate names become
+names for the backup file. If you copy the old file instead, the
+alternate names remain names for the file that you are editing, and the
+contents accessed by those names will be the new contents.
+
+ How you make a backup file may also affect the file's owner and
+group. If you use copying, they do not change. If renaming is used,
+you become the file's owner, and the file's group becomes the default
+(different operating systems have different defaults for the group).
+
+ Having the owner change is usually a good idea, because then the
+owner is always the person who last edited the file. Occasionally
+there is a file whose owner should not change. Since most files should
+change owners, it is a good idea to use local variable lists to set
+`backup-by-copying-when-mismatch' for the special cases where the owner
+should not change (*note File Variables::.).
+
+ Three variables control the choice of renaming or copying.
+Normally, renaming is done. If the variable `backup-by-copying' is
+non-`nil', copying is used. Otherwise, if the variable
+`backup-by-copying-when-linked' is non-`nil', copying is done for files
+that have multiple names, but renaming may still be done when the file
+being edited has only one name. If the variable
+`backup-by-copying-when-mismatch' is non-`nil', copying is done if
+renaming would cause the file's owner or group to change.
+
+\1f
+File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving
+
+Protection Against Simultaneous Editing
+---------------------------------------
+
+ Simultaneous editing occurs when two users visit the same file, both
+make changes, and both save their changes. If no one was informed that
+this was happening, and you saved first, you would later find that your
+changes were lost. On some systems, Emacs notices immediately when the
+second user starts to change a file already being edited, and issues a
+warning. When this is not possible, or if the second user has started
+to change the file despite the warning, Emacs checks when the file is
+saved, and issues a second warning when a user is about to overwrite a
+file containing another user's changes. If you are the user editing the
+file, you can take corrective action at this point and prevent actual
+loss of work.
+
+ When you make the first modification in an Emacs buffer that is
+visiting a file, Emacs records that you have locked the file. (It does
+this by writing another file in a directory reserved for this purpose.)
+The lock is removed when you save the changes. The idea is that the
+file is locked whenever the buffer is modified. If you begin to modify
+the buffer while the visited file is locked by someone else, this
+constitutes a collision, and Emacs asks you what to do. It does this
+by calling the Lisp function `ask-user-about-lock', which you can
+redefine to customize what it does. The standard definition of this
+function asks you a question and accepts three possible answers:
+
+`s'
+ Steal the lock. Whoever was already changing the file loses the
+ lock, and you get the lock.
+
+`p'
+ Proceed. Go ahead and edit the file despite its being locked by
+ someone else.
+
+`q'
+ Quit. This causes an error (`file-locked') and the modification
+ you were trying to make in the buffer does not actually take place.
+
+ Note that locking works on the basis of a file name; if a file has
+multiple names, Emacs does not realize that the two names are the same
+file and cannot prevent two users from editing it simultaneously under
+different names. However, basing locking on names means that Emacs can
+interlock the editing of new files that do not really exist until they
+are saved.
+
+ Some systems are not configured to allow Emacs to make locks. On
+these systems, Emacs cannot detect trouble in advance, but it can still
+detect it in time to prevent you from overwriting someone else's
+changes.
+
+ Every time Emacs saves a buffer, it first checks the
+last-modification date of the existing file on disk to see that it has
+not changed since the file was last visited or saved. If the date does
+not match, it implies that changes were made in the file in some other
+way, and these changes are about to be lost if Emacs actually does
+save. To prevent this, Emacs prints a warning message and asks for
+confirmation before saving. Occasionally you will know why the file
+was changed and know that it does not matter; then you can answer `yes'
+and proceed. Otherwise, you should cancel the save with `C-g' and
+investigate the situation.
+
+ The first thing you should do when notified that simultaneous editing
+has already taken place is to list the directory with `C-u C-x C-d'
+(*note Directory Listing: ListDir.). This will show the file's current
+author. You should attempt to contact that person and ask him not to
+continue editing. Often the next step is to save the contents of your
+Emacs buffer under a different name, and use `diff' to compare the two
+files.
+
+ Simultaneous editing checks are also made when you visit a file that
+is already visited with `C-x C-f' and when you start to modify a file.
+This is not strictly necessary, but it is useful to find out about such
+a problem as early as possible, when corrective action takes less work.
+
+ Another way to protect your file is to set the read, write, and
+executable permissions for the file. Use the function
+`set-default-file-modes' to set the UNIX `umask' value to the NMASK
+argument. The `umask' value is the default protection mode for new
+files.
+
+\1f
+File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files
+
+Reverting a Buffer
+==================
+
+ If you have made extensive changes to a file and then change your
+mind about them, you can get rid of all changes by reading in the
+previous version of the file. To do this, use `M-x revert-buffer',
+which operates on the current buffer. Since reverting a buffer can
+result in very extensive changes, you must confirm it with `yes'.
+
+ If the current buffer has been auto-saved more recently than it has
+been saved explicitly, `revert-buffer' offers to read the auto save file
+instead of the visited file (*note Auto Save::.). Emacs asks you about
+the auto-save file before the request for confirmation of the
+`revert-buffer' operation, and demands `y' or `n' as an answer. If you
+have started to type `yes' for confirmation without realizing that the
+auto-save question was going to be asked, the `y' will answer that
+question, but the `es' will not be valid confirmation. This gives you
+a chance to cancel the operation with `C-g' and try again with the
+answers you really intend.
+
+ `revert-buffer' keeps point at the same distance (measured in
+characters) from the beginning of the file. If the file was edited only
+slightly, you will be at approximately the same piece of text after
+reverting as before. If you have made more extensive changes, the
+value of point in the old file may bring you to a totally different
+piece of text than your last editing point.
+
+ A buffer reverted from its visited file is marked "not modified"
+until you make a change.
+
+ Some kinds of buffers whose contents reflect data bases other than
+files, such as Dired buffers, can also be reverted. For them,
+reverting means recalculating their contents from the appropriate data.
+Buffers created randomly with `C-x b' cannot be reverted;
+`revert-buffer' reports an error when asked to do so.
+
+\1f
+File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files
+
+Auto-Saving: Protection Against Disasters
+=========================================
+
+ Emacs saves all the visited files from time to time (based on
+counting your keystrokes) without being asked. This is called
+"auto-saving". It prevents you from losing more than a limited amount
+of work if the system crashes.
+
+ When Emacs determines it is time for auto-saving, each buffer is
+considered and is auto-saved if auto-saving is turned on for it and it
+has changed since the last time it was auto-saved. If any auto-saving
+is done, the message `Auto-saving...' is displayed in the echo area
+until auto-saving is finished. Errors occurring during auto-saving are
+caught so that they do not interfere with the execution of commands you
+have been typing.
+
+* Menu:
+
+* Files: Auto Save Files.
+* Control: Auto Save Control.
+* Recover:: Recovering text from auto-save files.
+
+\1f
+File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save
+
+Auto-Save Files
+---------------
+
+ Auto-saving does not normally write to the files you visited, because
+it can be undesirable to save a program that is in an inconsistent
+state when you have made only half of a planned change. Instead,
+auto-saving is done in a different file called the "auto-save file",
+and the visited file is changed only when you save explicitly, for
+example, with `C-x C-s'.
+
+ Normally, the name of the auto-save file is generated by appending
+`#' to the front and back of the visited file name. Thus, a buffer
+visiting file `foo.c' would be auto-saved in a file `#foo.c#'. Most
+buffers that are not visiting files are auto-saved only if you request
+it explicitly; when they are auto-saved, the auto-save file name is
+generated by appending `#%' to the front and `#' to the back of buffer
+name. For example, the `*mail*' buffer in which you compose messages
+to be sent is auto-saved in a file named `#%*mail*#'. Names of
+auto-save files are generated this way unless you customize the
+functions `make-auto-save-file-name' and `auto-save-file-name-p' to do
+something different. The file name to be used for auto-saving a buffer
+is calculated at the time auto-saving is turned on in that buffer.
+
+ If you want auto-saving to be done in the visited file, set the
+variable `auto-save-visited-file-name' to be non-`nil'. In this mode,
+there is really no difference between auto-saving and explicit saving.
+
+ Emacs deletes a buffer's auto-save file when you explicitly save the
+buffer. To inhibit the deletion, set the variable
+`delete-auto-save-files' to `nil'. Changing the visited file name with
+`C-x C-w' or `set-visited-file-name' renames any auto-save file to
+correspond to the new visited name.
+
+\1f
+File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save
+
+Controlling Auto-Saving
+-----------------------
+
+ Each time you visit a file, auto-saving is turned on for that file's
+buffer if the variable `auto-save-default' is non-`nil' (but not in
+batch mode; *note Entering Emacs::.). The default for this variable is
+`t', so Emacs auto-saves buffers that visit files by default. You can
+use the command `M-x auto-save-mode' to turn auto-saving for a buffer
+on or off. Like other minor mode commands, `M-x auto-save-mode' turns
+auto-saving on with a positive argument, off with a zero or negative
+argument; with no argument, it toggles.
+
+ Emacs performs auto-saving periodically based on counting how many
+characters you have typed since the last time auto-saving happened. The
+variable `auto-save-interval' specifies the number of characters
+between auto-saves. By default, it is 300. Emacs also auto-saves
+whenever you call the function `do-auto-save'.
+
+ Emacs also does auto-saving whenever it gets a fatal error. This
+includes killing the Emacs job with a shell command such as `kill
+-emacs', or disconnecting a phone line or network connection.
+
+ You can set the number of seconds of idle time before an auto-save is
+done. Setting the value of the variable `auto-save-timeout' to zero or
+`nil' will disable auto-saving due to idleness.
+
+ The actual amount of idle time between auto-saves is logarithmically
+related to the size of the current buffer. This variable is the number
+of seconds after which an auto-save will happen when the current buffer
+is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3
+3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k
+buffer.
+
+ For this variable to have any effect, you must do `(require 'timer)'.
+
+\1f
+File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save
+
+Recovering Data from Auto-Saves
+-------------------------------
+
+ If you want to use the contents of an auto-save file to recover from
+a loss of data, use the command `M-x recover-file <RET> FILE <RET>'.
+Emacs visits FILE and then (after your confirmation) restores the
+contents from the auto-save file `#FILE#'. You can then save the file
+with `C-x C-s' to put the recovered text into FILE itself. For
+example, to recover file `foo.c' from its auto-save file `#foo.c#', do:
+
+ M-x recover-file <RET> foo.c <RET>
+ C-x C-s
+
+ Before asking for confirmation, `M-x recover-file' displays a
+directory listing describing the specified file and the auto-save file,
+so you can compare their sizes and dates. If the auto-save file is
+older, `M-x recover-file' does not offer to read it.
+
+ Auto-saving is disabled by `M-x recover-file' because using this
+command implies that the auto-save file contains valuable data from a
+past session. If you save the data in the visited file and then go on
+to make new changes, turn auto-saving back on with `M-x auto-save-mode'.
+
+\1f
+File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files
+
+Version Control
+===============
+
+ "Version control systems" are packages that can record multiple
+versions of a source file, usually storing the unchanged parts of the
+file just once. Version control systems also record history information
+such as the creation time of each version, who created it, and a
+description of what was changed in that version.
+
+ The GNU project recommends the version control system known as RCS,
+which is free software and available from the Free Software Foundation.
+Emacs supports use of either RCS or SCCS (a proprietary, but widely
+used, version control system that is not quite as powerful as RCS)
+through a facility called VC. The same Emacs commands work with either
+RCS or SCCS, so you hardly have to know which one of them you are using.
+
+* Menu:
+
+* Concepts of VC:: Basic version control information;
+ checking files in and out.
+* Editing with VC:: Commands for editing a file maintained
+ with version control.
+* Variables for Check-in/out:: Variables that affect the commands used
+ to check files in or out.
+* Log Entries:: Logging your changes.
+* Change Logs and VC:: Generating a change log file from log
+ entries.
+* Old Versions:: Examining and comparing old versions.
+* VC Status:: Commands to view the VC status of files and
+ look at log entries.
+* Renaming and VC:: A command to rename both the source and
+ master file correctly.
+* Snapshots:: How to make and use snapshots, a set of
+ file versions that can be treated as a unit.
+* Version Headers:: Inserting version control headers into
+ working files.
+
+\1f
+File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control
+
+Concepts of Version Control
+---------------------------
+
+ When a file is under version control, we also say that it is
+"registered" in the version control system. Each registered file has a
+corresponding "master file" which represents the file's present state
+plus its change history, so that you can reconstruct from it either the
+current version or any specified earlier version. Usually the master
+file also records a "log entry" for each version describing what was
+changed in that version.
+
+ The file that is maintained under version control is sometimes called
+the "work file" corresponding to its master file.
+
+ To examine a file, you "check it out". This extracts a version of
+the source file (typically, the most recent) from the master file. If
+you want to edit the file, you must check it out "locked". Only one
+user can do this at a time for any given source file. (This kind of
+locking is completely unrelated to the locking that Emacs uses to
+detect simultaneous editing of a file.)
+
+ When you are done with your editing, you must "check in" the new
+version. This records the new version in the master file, and unlocks
+the source file so that other people can lock it and thus modify it.
+
+ Checkin and checkout are the basic operations of version control.
+You can do both of them with a single Emacs command: `C-x C-q'
+(`vc-toggle-read-only').
+
+ A "snapshot" is a coherent collection of versions of the various
+files that make up a program. *Note Snapshots::.
+
+\1f
+File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control
+
+Editing with Version Control
+----------------------------
+
+ When you visit a file that is maintained using version control, the
+mode line displays `RCS' or `SCCS' to inform you that version control
+is in use, and also (in case you care) which low-level system the file
+is actually stored in. Normally, such a source file is read-only, and
+the mode line indicates this with `%%'. With RCS, the mode line also
+indicates the number of the head version, which is normally also the
+version you are looking at.
+
+ These are the commands for editing a file maintained with version
+control:
+
+`C-x C-q'
+ Check the visited file in or out.
+
+`C-x v u'
+ Revert the buffer and the file to the last checked in version.
+
+`C-x v c'
+ Remove the last-entered change from the master for the visited
+ file. This undoes your last check-in.
+
+`C-x v i'
+ Register the visited file in version control.
+
+(`C-x v' is the prefix key for version control commands; all of these
+commands except for `C-x C-q' start with `C-x v'.)
+
+ When you want to modify a file maintained with version control, type
+`C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and
+tells RCS or SCCS to lock the file. This means making the file
+writable for you (but not for anyone else).
+
+ When you are finished editing the file, type `C-x C-q' again. When
+used on a file that is checked out, this command checks the file in.
+But check-in does not start immediately; first, you must enter the "log
+entry"--a description of the changes in the new version. `C-x C-q'
+pops up a buffer for you to enter this in. When you are finished
+typing in the log entry, type `C-c C-c' to terminate it; this is when
+actual check-in takes place.
+
+ Once you have checked in your changes, the file is unlocked, so that
+other users can lock it and modify it.
+
+ Emacs does not save backup files for source files that are maintained
+with version control. If you want to make backup files despite version
+control, set the variable `vc-make-backup-files' to a non-`nil' value.
+
+ Normally the work file exists all the time, whether it is locked or
+not. If you set `vc-keep-workfiles' to `nil', then checking in a new
+version with `C-x C-q' deletes the work file; but any attempt to visit
+the file with Emacs creates it again.
+
+ It is not impossible to lock a file that someone else has locked. If
+you try to check out a file that is locked, `C-x C-q' asks you whether
+you want to "steal the lock." If you say yes, the file becomes locked
+by you, but a message is sent to the person who had formerly locked the
+file, to inform him of what has happened. The mode line indicates that
+a file is locked by someone else by displaying the login name of that
+person, before the version number.
+
+ If you want to discard your current set of changes and revert to the
+last version checked in, use `C-x v u' (`vc-revert-buffer'). This
+cancels your last check-out, leaving the file unlocked. If you want to
+make a different set of changes, you must first check the file out
+again. `C-x v u' requires confirmation, unless it sees that you
+haven't made any changes since the last checked-in version.
+
+ `C-x v u' is also the command to use if you lock a file and then
+don't actually change it.
+
+ You can cancel a change after checking it in, with `C-x v c'
+(`vc-cancel-version'). This command discards all record of the most
+recent checked in version, so be careful about using it. It requires
+confirmation with `yes'. By default, `C-x v c' reverts your workfile
+and buffer to the previous version (the one that precedes the version
+that is deleted), but you can prevent the reversion by giving the
+command a prefix argument. Then the buffer does not change.
+
+ This command with a prefix argument is useful when you have checked
+in a change and then discover a trivial error in it; you can cancel the
+erroneous check-in, fix the error, and repeat the check-in.
+
+ Be careful when invoking `C-x v c', as it is easy to throw away a
+lot of work with it. To help you be careful, this command always
+requires confirmation with `yes'.
+
+ You can register the visited file for version control using
+`C-x v i' (`vc-register'). If the variable `vc-default-back-end' is
+non-`nil', it specifies which version control system to use; otherwise,
+this uses RCS if it is installed on your system and SCCS if not. After
+`C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you
+wish to edit it.
+
+ By default, the initial version number is 1.1. If you want to use a
+different number, give `C-x v i' a prefix argument; then it reads the
+initial version number using the minibuffer.
+
+ If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
+comment (much like a log entry) to describe the purpose of this source
+file.
+
+ To specify the version number for a subsequent checkin, use the
+command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command
+that `C-x C-q' uses to do the "real work" when the visited file uses
+version control. When used for checkin, and given a prefix argument,
+it reads the version number with the minibuffer.
+
+\1f
+File: xemacs.info, Node: Variables for Check-in/out, Next: Log Entries, Prev: Editing with VC, Up: Version Control
+
+Variables Affecting Check-in and Check-out
+------------------------------------------
+
+ If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i'
+can save the current buffer without asking, and `C-x v u' also operates
+without asking for confirmation. (This variable does not affect `C-x v
+c'; that is so drastic that it should always ask for confirmation.)
+
+ VC mode does much of its work by running the shell commands for RCS
+and SCCS. If `vc-command-messages' is non-`nil', VC displays messages
+to indicate which shell commands it runs, and additional messages when
+the commands finish.
+
+ Normally, VC assumes that it can deduce the locked/unlocked state of
+files by looking at the file permissions of the work file; this is
+fast. However, if the `RCS' or `SCCS' subdirectory is actually a
+symbolic link, then VC does not trust the file permissions to reflect
+this status.
+
+ You can specify the criterion for whether to trust the file
+permissions by setting the variable `vc-mistrust-permissions'. Its
+value may be `t' (always mistrust the file permissions and check the
+master file), `nil' (always trust the file permissions), or a function
+of one argument which makes the decision. The argument is the directory
+name of the `RCS' or `SCCS' subdirectory. A non-`nil' value from the
+function says to mistrust the file permissions.
+
+ If you find that the file permissions of work files are changed
+erroneously, set `vc-mistrust-permissions' to `t'. Then VC always
+checks the master file to determine the file's status.
+
+ You can specify additional directories to search for version control
+programs by setting the variable `vc-path'. These directories are
+searched before the usual search path. The proper result usually
+happens automatically.
+
+\1f
+File: xemacs.info, Node: Log Entries, Next: Change Logs and VC, Prev: Variables for Check-in/out, Up: Version Control
+
+Log Entries
+-----------
+
+ When you're editing an initial comment or log entry for inclusion in
+a master file, finish your entry by typing `C-c C-c'.
+
+`C-c C-c'
+ Finish the comment edit normally (`vc-finish-logentry'). This
+ finishes check-in.
+
+ To abort check-in, just don't type `C-c C-c' in that buffer. You
+can switch buffers and do other editing. As long as you don't try to
+check in another file, the entry you were editing remains in its
+buffer, and you can go back to that buffer at any time to complete the
+check-in.
+
+ If you change several source files for the same reason, it is often
+convenient to specify the same log entry for many of the files. To do
+this, use the history of previous log entries. The commands `M-n',
+`M-p', `M-s' and `M-r' for doing this work just like the minibuffer
+history commands (except that these versions are used outside the
+minibuffer).
+
+ Each time you check in a file, the log entry buffer is put into VC
+Log mode, which involves running two hooks: `text-mode-hook' and
+`vc-log-mode-hook'.
+
+\1f
+File: xemacs.info, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control
+
+Change Logs and VC
+------------------
+
+ If you use RCS for a program and also maintain a change log file for
+it (*note Change Log::.), you can generate change log entries
+automatically from the version control log entries:
+
+`C-x v a'
+ Visit the current directory's change log file and create new
+ entries for versions checked in since the most recent entry in the
+ change log file (`vc-update-change-log').
+
+ This command works with RCS only; it does not work with SCCS.
+
+ For example, suppose the first line of `ChangeLog' is dated 10 April
+1992, and that the only check-in since then was by Nathaniel Bowditch
+to `rcs2log' on 8 May 1992 with log text `Ignore log messages that
+start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text
+like this:
+
+ Fri May 8 21:45:00 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * rcs2log: Ignore log messages that start with `#'.
+
+You can then edit the new change log entry further as you wish.
+
+ Normally, the log entry for file `foo' is displayed as `* foo: TEXT
+OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log
+entry starts with `(FUNCTIONNAME): '. For example, if the log entry
+for `vc.el' is `(vc-do-command): Check call-process status.', then the
+text in `ChangeLog' looks like this:
+
+ Wed May 6 10:53:00 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * vc.el (vc-do-command): Check call-process status.
+
+ When `C-x v a' adds several change log entries at once, it groups
+related log entries together if they all are checked in by the same
+author at nearly the same time. If the log entries for several such
+files all have the same text, it coalesces them into a single entry.
+For example, suppose the most recent checkins have the following log
+entries:
+
+For `vc.texinfo':
+ Fix expansion typos.
+For `vc.el':
+ Don't call expand-file-name.
+For `vc-hooks.el':
+ Don't call expand-file-name.
+
+ They appear like this in `ChangeLog':
+
+ Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * vc.texinfo: Fix expansion typos.
+
+ * vc.el, vc-hooks.el: Don't call expand-file-name.
+
+ Normally, `C-x v a' separates log entries by a blank line, but you
+can mark several related log entries to be clumped together (without an
+intervening blank line) by starting the text of each related log entry
+with a label of the form `{CLUMPNAME} '. The label itself is not
+copied to `ChangeLog'. For example, suppose the log entries are:
+
+For `vc.texinfo':
+ {expand} Fix expansion typos.
+For `vc.el':
+ {expand} Don't call expand-file-name.
+For `vc-hooks.el':
+ {expand} Don't call expand-file-name.
+
+Then the text in `ChangeLog' looks like this:
+
+ Wed Apr 1 08:57:59 1992 Nathaniel Bowditch (nat@apn.org)
+
+ * vc.texinfo: Fix expansion typos.
+ * vc.el, vc-hooks.el: Don't call expand-file-name.
+
+ A log entry whose text begins with `#' is not copied to `ChangeLog'.
+For example, if you merely fix some misspellings in comments, you can
+log the change with an entry beginning with `#' to avoid putting such
+trivia into `ChangeLog'.
+
+\1f
+File: xemacs.info, Node: Old Versions, Next: VC Status, Prev: Change Logs and VC, Up: Version Control
+
+Examining And Comparing Old Versions
+------------------------------------
+
+`C-x v ~ VERSION <RET>'
+ Examine version VERSION of the visited file, in a buffer of its
+ own (`vc-version-other-window').
+
+`C-x v ='
+ Compare the current buffer contents with the latest checked-in
+ version of the file.
+
+`C-u C-x v = FILE <RET> OLDVERS <RET> NEWVERS <RET>'
+ Compare the specified two versions of FILE.
+
+ You can examine any version of a file by first visiting it, and then
+using `C-x v ~ VERSION <RET>' (`vc-version-other-window'). This puts
+the text of version VERSION in a file named `FILENAME.~VERSION~', then
+visits it in a separate window.
+
+ To compare two versions of a file, use the command `C-x v ='
+(`vc-diff').
+
+ Plain `C-x v =' compares the current buffer contents (saving them in
+the file if necessary) with the last checked-in version of the file.
+With a prefix argument, `C-x v =' reads a file name and two version
+numbers, then compares those versions of the specified file.
+
+ If you supply a directory name instead of the name of a work file,
+this command compares the two specified versions of all registered files
+in that directory and its subdirectories. You can also specify a
+snapshot name (*note Snapshots::.) instead of one or both version
+numbers.
+
+ You can specify a checked-in version by its number; you can specify
+the most recent checked-in version with an empty version number.
+
+ This command works by running the `vcdiff' utility, getting the
+options from the variable `diff-switches'. It displays the output in a
+special buffer in another window. Unlike the `M-x diff' command, `C-x
+v =' does not try to find the changes in the old and new versions.
+This is because one or both versions normally do not exist as files.
+They exist only in the records of the master file. *Note Comparing
+Files::, for more information about `M-x diff'.
+
+\1f
+File: xemacs.info, Node: VC Status, Next: Renaming and VC, Prev: Old Versions, Up: Version Control
+
+VC Status Commands
+------------------
+
+ To view the detailed version control status and history of a file,
+type `C-x v l' (`vc-print-log'). It displays the history of changes to
+the current file, including the text of the log entries. The output
+appears in a separate window.
+
+ When you are working on a large program, it's often useful to find
+all the files that are currently locked, or all the files maintained in
+version control at all. You can use `C-x v d' (`vc-directory') to show
+all the locked files in or beneath the current directory. This
+includes all files that are locked by any user. `C-u C-x v d' lists
+all files in or beneath the current directory that are maintained with
+version control.
+
+ The list of files is displayed as a buffer that uses an augmented
+Dired mode. The names of the users locking various files are shown (in
+parentheses) in place of the owner and group. All the normal Dired
+commands work in this buffer. Most interactive VC commands work also,
+and apply to the file name on the current line.
+
+ The `C-x v v' command (`vc-next-action'), when used in the augmented
+Dired buffer, operates on all the marked files (or the file on the
+current line). If it operates on more than one file, it handles each
+file according to its current state; thus, it may check out one file
+and check in another (because it is already checked out). If it has to
+check in any files, it reads a single log entry, then uses that text
+for all the files being checked in. This can be convenient for
+registering or checking in several files at once, as part of the same
+change.
+
+\1f
+File: xemacs.info, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control
+
+Renaming VC Work Files and Master Files
+---------------------------------------
+
+ When you rename a registered file, you must also rename its master
+file correspondingly to get proper results. Use `vc-rename-file' to
+rename the source file as you specify, and rename its master file
+accordingly. It also updates any snapshots (*note Snapshots::.) that
+mention the file, so that they use the new name; despite this, the
+snapshot thus modified may not completely work (*note Snapshot
+Caveats::.).
+
+ You cannot use `vc-rename-file' on a file that is locked by someone
+else.
+
+\1f
+File: xemacs.info, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control
+
+Snapshots
+---------
+
+ A "snapshot" is a named set of file versions (one for each
+registered file) that you can treat as a unit. One important kind of
+snapshot is a "release", a (theoretically) stable version of the system
+that is ready for distribution to users.
+
+* Menu:
+
+* Making Snapshots:: The snapshot facilities.
+* Snapshot Caveats:: Things to be careful of when using snapshots.
+
+\1f
+File: xemacs.info, Node: Making Snapshots, Next: Snapshot Caveats, Prev: Snapshots, Up: Snapshots
+
+Making and Using Snapshots
+..........................
+
+ There are two basic commands for snapshots; one makes a snapshot
+with a given name, the other retrieves a named snapshot.
+
+`C-x v s NAME <RET>'
+ Define the last saved versions of every registered file in or
+ under the current directory as a snapshot named NAME
+ (`vc-create-snapshot').
+
+`C-x v r NAME <RET>'
+ Check out all registered files at or below the current directory
+ level using whatever versions correspond to the snapshot NAME
+ (`vc-retrieve-snapshot').
+
+ This command reports an error if any files are locked at or below
+ the current directory, without changing anything; this is to avoid
+ overwriting work in progress.
+
+ A snapshot uses a very small amount of resources--just enough to
+record the list of file names and which version belongs to the
+snapshot. Thus, you need not hesitate to create snapshots whenever
+they are useful.
+
+ You can give a snapshot name as an argument to `C-x v =' or `C-x v
+~' (*note Old Versions::.). Thus, you can use it to compare a snapshot
+against the current files, or two snapshots against each other, or a
+snapshot against a named version.
+
+\1f
+File: xemacs.info, Node: Snapshot Caveats, Prev: Making Snapshots, Up: Snapshots
+
+Snapshot Caveats
+................
+
+ VC's snapshot facilities are modeled on RCS's named-configuration
+support. They use RCS's native facilities for this, so under VC
+snapshots made using RCS are visible even when you bypass VC.
+
+ For SCCS, VC implements snapshots itself. The files it uses contain
+name/file/version-number triples. These snapshots are visible only
+through VC.
+
+ A snapshot is a set of checked-in versions. So make sure that all
+the files are checked in and not locked when you make a snapshot.
+
+ File renaming and deletion can create some difficulties with
+snapshots. This is not a VC-specific problem, but a general design
+issue in version control systems that no one has solved very well yet.
+
+ If you rename a registered file, you need to rename its master along
+with it (the command `vc-rename-file' does this automatically). If you
+are using SCCS, you must also update the records of the snapshot, to
+mention the file by its new name (`vc-rename-file' does this, too). An
+old snapshot that refers to a master file that no longer exists under
+the recorded name is invalid; VC can no longer retrieve it. It would
+be beyond the scope of this manual to explain enough about RCS and SCCS
+to explain how to update the snapshots by hand.
+
+ Using `vc-rename-file' makes the snapshot remain valid for
+retrieval, but it does not solve all problems. For example, some of the
+files in the program probably refer to others by name. At the very
+least, the makefile probably mentions the file that you renamed. If you
+retrieve an old snapshot, the renamed file is retrieved under its new
+name, which is not the name that the makefile expects. So the program
+won't really work as retrieved.
+
+\1f
+File: xemacs.info, Node: Version Headers, Prev: Snapshots, Up: Version Control
+
+Inserting Version Control Headers
+---------------------------------
+
+ Sometimes it is convenient to put version identification strings
+directly into working files. Certain special strings called "version
+headers" are replaced in each successive version by the number of that
+version.
+
+ You can use the `C-x v h' command (`vc-insert-headers') to insert a
+suitable header string.
+
+`C-x v h'
+ Insert headers in a file for use with your version-control system.
+
+ The default header string is `\$Id\$' for RCS and `\%W\%' for SCCS.
+(The actual strings inserted do not have the backslashes in them. They
+were placed in the Info source file so that the strings don't get
+interpreted as version-control headers when the Info source files are
+maintained under version control.) You can specify other headers to
+insert by setting the variable `vc-header-alist'. Its value is a list
+of elements of the form `(PROGRAM . STRING)' where PROGRAM is `RCS' or
+`SCCS' and STRING is the string to use.
+
+ Instead of a single string, you can specify a list of strings; then
+each string in the list is inserted as a separate header on a line of
+its own.
+
+ It is often necessary to use "superfluous" backslashes when writing
+the strings that you put in this variable. This is to prevent the
+string in the constant from being interpreted as a header itself if the
+Emacs Lisp file containing it is maintained with version control.
+
+ Each header is inserted surrounded by tabs, inside comment
+delimiters, on a new line at the start of the buffer. Normally the
+ordinary comment start and comment end strings of the current mode are
+used, but for certain modes, there are special comment delimiters for
+this purpose; the variable `vc-comment-alist' specifies them. Each
+element of this list has the form `(MODE STARTER ENDER)'.
+
+ The variable `vc-static-header-alist' specifies further strings to
+add based on the name of the buffer. Its value should be a list of
+elements of the form `(REGEXP . FORMAT)'. Whenever REGEXP matches the
+buffer name, FORMAT is inserted as part of the header. A header line
+is inserted for each element that matches the buffer name, and for each
+string specified by `vc-header-alist'. The header line is made by
+processing the string from `vc-header-alist' with the format taken from
+the element. The default value for `vc-static-header-alist' is:
+
+ (("\\.c$" .
+ "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
+ #endif /* lint */\n"))
+
+which specifies insertion of a string of this form:
+
+
+ #ifndef lint
+ static char vcid[] = "STRING";
+ #endif /* lint */
+
+\1f
+File: xemacs.info, Node: ListDir, Next: Comparing Files, Prev: Version Control, Up: Files
+
+Listing a File Directory
+========================
+
+ Files are organized by Unix into "directories". A "directory
+listing" is a list of all the files in a directory. Emacs provides
+directory listings in brief format (file names only) and verbose format
+(sizes, dates, and authors included).
+
+`C-x C-d DIR-OR-PATTERN'
+ Print a brief directory listing (`list-directory').
+
+`C-u C-x C-d DIR-OR-PATTERN'
+ Print a verbose directory listing.
+
+ To print a directory listing, use `C-x C-d' (`list-directory').
+This command prompts in the minibuffer for a file name which is either
+a directory to be listed or pattern containing wildcards for the files
+to be listed. For example,
+
+ C-x C-d /u2/emacs/etc <RET>
+
+lists all the files in directory `/u2/emacs/etc'. An example of
+specifying a file name pattern is:
+
+ C-x C-d /u2/emacs/src/*.c <RET>
+
+ Normally, `C-x C-d' prints a brief directory listing containing just
+file names. A numeric argument (regardless of value) tells it to print
+a verbose listing (like `ls -l').
+
+ Emacs obtains the text of a directory listing by running `ls' in an
+inferior process. Two Emacs variables control the switches passed to
+`ls': `list-directory-brief-switches' is a string giving the switches
+to use in brief listings (`"-CF"' by default).
+`list-directory-verbose-switches' is a string giving the switches to
+use in a verbose listing (`"-l"' by default).
+
+ The variable `directory-abbrev-alist' is an alist of abbreviations
+for file directories. The list consists of elements of the form `(FROM
+. TO)', each meaning to replace `FROM' with `TO' when it appears in a
+directory name. This replacement is done when setting up the default
+directory of a newly visited file. Every `FROM' string should start
+with ``^''.
+
+ Use this feature when you have directories which you normally refer
+to via absolute symbolic links. Make `TO' the name of the link, and
+`FROM' the name it is linked to.
+
+\1f
+File: xemacs.info, Node: Comparing Files, Next: Dired, Prev: ListDir, Up: Files
+
+Comparing Files
+===============
+
+ The command `M-x diff' compares two files, displaying the
+differences in an Emacs buffer named `*Diff*'. It works by running the
+`diff' program, using options taken from the variable `diff-switches',
+whose value should be a string.
+
+ The buffer `*Diff*' has Compilation mode as its major mode, so you
+can use `C-x `' to visit successive changed locations in the two source
+files. You can also move to a particular hunk of changes and type `C-c
+C-c' to find the corresponding source location. You can also use the
+other special commands of Compilation mode: <SPC> and <DEL> for
+scrolling, and `M-p' and `M-n' for cursor motion. *Note Compilation::.
+
+ The command `M-x diff-backup' compares a specified file with its most
+recent backup. If you specify the name of a backup file, `diff-backup'
+compares it with the source file that it is a backup of.
+
+ The command `M-x compare-windows' compares the text in the current
+window with that in the next window. Comparison starts at point in each
+window. Point moves forward in each window, a character at a time in
+each window, until the next characters in the two windows are
+different. Then the command is finished. For more information about
+windows in Emacs, *Note Windows::.
+
+ With a numeric argument, `compare-windows' ignores changes in
+whitespace. If the variable `compare-ignore-case' is non-`nil', it
+ignores differences in case as well.
+
+\1f
+File: xemacs.info, Node: Dired, Next: Misc File Ops, Prev: Comparing Files, Up: Files
+
+Dired, the Directory Editor
+===========================
+
+ Dired makes it easy to delete or visit many of the files in a single
+directory at once. It creates an Emacs buffer containing a listing of
+the directory. You can use the normal Emacs commands to move around in
+this buffer and special Dired commands to operate on the files.
+
+* Menu:
+
+* Enter: Dired Enter. How to invoke Dired.
+* Edit: Dired Edit. Editing the Dired buffer.
+* Deletion: Dired Deletion. Deleting files with Dired.
+* Immed: Dired Immed. Other file operations through Dired.
+
+\1f
+File: xemacs.info, Node: Dired Enter, Next: Dired Edit, Prev: Dired, Up: Dired
+
+Entering Dired
+--------------
+
+ To invoke dired, type `C-x d' or `M-x dired'. The command reads a
+directory name or wildcard file name pattern as a minibuffer argument
+just like the `list-directory' command, `C-x C-d'. Where `dired'
+differs from `list-directory' is in naming the buffer after the
+directory name or the wildcard pattern used for the listing, and putting
+the buffer into Dired mode so that the special commands of Dired are
+available in it. The variable `dired-listing-switches' is a string
+used as an argument to `ls' in making the directory; this string must
+contain `-l'.
+
+ To display the Dired buffer in another window rather than in the
+selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x
+d'.
+
+\1f
+File: xemacs.info, Node: Dired Edit, Next: Dired Deletion, Prev: Dired Enter, Up: Dired
+
+Editing in Dired
+----------------
+
+ Once the Dired buffer exists, you can switch freely between it and
+other Emacs buffers. Whenever the Dired buffer is selected, certain
+special commands are provided that operate on files that are listed.
+The Dired buffer is "read-only", and inserting text in it is not
+useful, so ordinary printing characters such as `d' and `x' are used
+for Dired commands. Most Dired commands operate on the file described
+by the line that point is on. Some commands perform operations
+immediately; others "flag" a file to be operated on later.
+
+ Most Dired commands that operate on the current line's file also
+treat a numeric argument as a repeat count, meaning to act on the files
+of the next few lines. A negative argument means to operate on the
+files of the preceding lines, and leave point on the first of those
+lines.
+
+ All the usual Emacs cursor motion commands are available in Dired
+buffers. Some special purpose commands are also provided. The keys
+`C-n' and `C-p' are redefined so that they try to position the cursor
+at the beginning of the filename on the line, rather than at the
+beginning of the line.
+
+ For extra convenience, <SPC> and `n' in Dired are equivalent to
+`C-n'. `p' is equivalent to `C-p'. Moving by lines is done so often
+in Dired that it deserves to be easy to type. <DEL> (move up and
+unflag) is often useful simply for moving up.
+
+ The `g' command in Dired runs `revert-buffer' to reinitialize the
+buffer from the actual disk directory and show any changes made in the
+directory by programs other than Dired. All deletion flags in the Dired
+buffer are lost when this is done.
+
+\1f
+File: xemacs.info, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired
+
+Deleting Files With Dired
+-------------------------
+
+ The primary use of Dired is to flag files for deletion and then
+delete them.
+
+`d'
+ Flag this file for deletion.
+
+`u'
+ Remove deletion-flag on this line.
+
+`<DEL>'
+ Remove deletion-flag on previous line, moving point to that line.
+
+`x'
+ Delete the files that are flagged for deletion.
+
+`#'
+ Flag all auto-save files (files whose names start and end with `#')
+ for deletion (*note Auto Save::.).
+
+`~'
+ Flag all backup files (files whose names end with `~') for deletion
+ (*note Backup::.).
+
+`. (Period)'
+ Flag excess numeric backup files for deletion. The oldest and
+ newest few backup files of any one file are exempt; the middle
+ ones are flagged.
+
+ You can flag a file for deletion by moving to the line describing the
+file and typing `d' or `C-d'. The deletion flag is visible as a `D' at
+the beginning of the line. Point is moved to the beginning of the next
+line, so that repeated `d' commands flag successive files.
+
+ The files are flagged for deletion rather than deleted immediately to
+avoid the danger of deleting a file accidentally. Until you direct
+Dired to delete the flagged files, you can remove deletion flags using
+the commands `u' and <DEL>. `u' works just like `d', but removes flags
+rather than making flags. <DEL> moves upward, removing flags; it is
+like `u' with numeric argument automatically negated.
+
+ To delete the flagged files, type `x'. This command first displays a
+list of all the file names flagged for deletion, and requests
+confirmation with `yes'. Once you confirm, all the flagged files are
+deleted, and their lines are deleted from the text of the Dired buffer.
+The shortened Dired buffer remains selected. If you answer `no' or
+quit with `C-g', you return immediately to Dired, with the deletion
+flags still present and no files actually deleted.
+
+ The `#', `~', and `.' commands flag many files for deletion, based
+on their names. These commands are useful precisely because they do
+not actually delete any files; you can remove the deletion flags from
+any flagged files that you really wish to keep.
+
+ `#' flags for deletion all files that appear to have been made by
+auto-saving (that is, files whose names begin and end with `#'). `~'
+flags for deletion all files that appear to have been made as backups
+for files that were edited (that is, files whose names end with `~').
+
+ `.' (Period) flags just some of the backup files for deletion: only
+numeric backups that are not among the oldest few nor the newest few
+backups of any one file. Normally `dired-kept-versions' (not
+`kept-new-versions'; that applies only when saving) specifies the
+number of newest versions of each file to keep, and `kept-old-versions'
+specifies the number of oldest versions to keep. Period with a
+positive numeric argument, as in `C-u 3 .', specifies the number of
+newest versions to keep, overriding `dired-kept-versions'. A negative
+numeric argument overrides `kept-old-versions', using minus the value
+of the argument to specify the number of oldest versions of each file
+to keep.
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Dired Immed, Prev: Dired Deletion, Up: Dired
+
+Immediate File Operations in Dired
+----------------------------------
+
+ Some file operations in Dired take place immediately when they are
+requested.
+
+`C'
+ Copies the file described on the current line. You must supply a
+ file name to copy to, using the minibuffer.
+
+`f'
+ Visits the file described on the current line. It is just like
+ typing `C-x C-f' and supplying that file name. If the file on
+ this line is a subdirectory, `f' actually causes Dired to be
+ invoked on that subdirectory. *Note Visiting::.
+
+`o'
+ Like `f', but uses another window to display the file's buffer.
+ The Dired buffer remains visible in the first window. This is
+ like using `C-x 4 C-f' to visit the file. *Note Windows::.
+
+`R'
+ Renames the file described on the current line. You must supply a
+ file name to rename to, using the minibuffer.
+
+`v'
+ Views the file described on this line using `M-x view-file'.
+ Viewing a file is like visiting it, but is slanted toward moving
+ around in the file conveniently and does not allow changing the
+ file. *Note View File: Misc File Ops. Viewing a file that is a
+ directory runs Dired on that directory.
+
+\1f
+File: xemacs.info, Node: Misc File Ops, Prev: Dired, Up: Files
+
+Miscellaneous File Operations
+=============================
+
+ Emacs has commands for performing many other operations on files.
+All operate on one file; they do not accept wildcard file names.
+
+ You can use the command `M-x add-name-to-file' to add a name to an
+existing file without removing the old name. The new name must belong
+on the file system that the file is on.
+
+ `M-x append-to-file' adds the text of the region to the end of the
+specified file.
+
+ `M-x copy-file' reads the file OLD and writes a new file named NEW
+with the same contents. Confirmation is required if a file named NEW
+already exists, because copying overwrites the old contents of the file
+NEW.
+
+ `M-x delete-file' deletes a specified file, like the `rm' command in
+the shell. If you are deleting many files in one directory, it may be
+more convenient to use Dired (*note Dired::.).
+
+ `M-x insert-file' inserts a copy of the contents of a specified file
+into the current buffer at point, leaving point unchanged before the
+contents and the mark after them. *Note Mark::.
+
+ `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and
+then creates a symbolic link named LINKNAME and pointing at OLD.
+Future attempts to open file LINKNAME will then refer to the file named
+OLD at the time the opening is done, or will result in an error if the
+name OLD is not in use at that time. Confirmation is required if you
+create the link while LINKNAME is in use. Note that not all systems
+support symbolic links.
+
+ `M-x rename-file' reads two file names OLD and NEW using the
+minibuffer, then renames file OLD as NEW. If a file named NEW already
+exists, you must confirm with `yes' or renaming is not done; this is
+because renaming causes the previous meaning of the name NEW to be
+lost. If OLD and NEW are on different file systems, the file OLD is
+copied and deleted.
+
+ `M-x view-file' allows you to scan or read a file by sequential
+screenfuls. It reads a file name argument using the minibuffer. After
+reading the file into an Emacs buffer, `view-file' reads and displays
+one windowful. You can then type <SPC> to scroll forward one window,
+or <DEL> to scroll backward. Various other commands are provided for
+moving around in the file, but none for changing it; type `C-h' while
+viewing a file for a list of them. Most commands are the default Emacs
+cursor motion commands. To exit from viewing, type `C-c'.
+
+\1f
+File: xemacs.info, Node: Buffers, Next: Windows, Prev: Files, Up: Top
+
+Using Multiple Buffers
+**********************
+
+ Text you are editing in Emacs resides in an object called a
+"buffer". Each time you visit a file, Emacs creates a buffer to hold
+the file's text. Each time you invoke Dired, Emacs creates a buffer to
+hold the directory listing. If you send a message with `C-x m', a
+buffer named `*mail*' is used to hold the text of the message. When
+you ask for a command's documentation, it appears in a buffer called
+`*Help*'.
+
+ At any time, one and only one buffer is "selected". It is also
+called the "current buffer". Saying a command operates on "the buffer"
+really means that the command operates on the selected buffer, as most
+commands do.
+
+ When Emacs creates multiple windows, each window has a chosen buffer
+which is displayed there, but at any time only one of the windows is
+selected and its chosen buffer is the selected buffer. Each window's
+mode line displays the name of the buffer the window is displaying
+(*note Windows::.).
+
+ Each buffer has a name which can be of any length but is
+case-sensitive. You can select a buffer using its name. Most buffers
+are created when you visit files; their names are derived from the
+files' names. You can also create an empty buffer with any name you
+want. A newly started Emacs has a buffer named `*scratch*' which you
+can use for evaluating Lisp expressions in Emacs.
+
+ Each buffer records what file it is visiting, whether it is
+modified, and what major mode and minor modes are in effect in it
+(*note Major Modes::.). Any Emacs variable can be made "local to" a
+particular buffer, meaning its value in that buffer can be different
+from the value in other buffers. *Note Locals::.
+
+* Menu:
+
+* Select Buffer:: Creating a new buffer or reselecting an old one.
+* List Buffers:: Getting a list of buffers that exist.
+* Misc Buffer:: Renaming; changing read-onliness; copying text.
+* Kill Buffer:: Killing buffers you no longer need.
+* Several Buffers:: How to go through the list of all buffers
+ and operate variously on several of them.
+
+\1f
+File: xemacs.info, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers
+
+Creating and Selecting Buffers
+==============================
+
+`C-x b BUFFER <RET>'
+ Select or create a buffer named BUFFER (`switch-to-buffer').
+
+`C-x 4 b BUFFER <RET>'
+ Similar, but select a buffer named BUFFER in another window
+ (`switch-to-buffer-other-window').
+
+`M-x switch-to-other-buffer N'
+ Switch to the previous buffer.
+
+ To select a buffer named BUFNAME, type `C-x b BUFNAME <RET>'. This
+is the command `switch-to-buffer' with argument BUFNAME. You can use
+completion on an abbreviation for the buffer name you want (*note
+Completion::.). An empty argument to `C-x b' specifies the most
+recently selected buffer that is not displayed in any window.
+
+ Most buffers are created when you visit files, or use Emacs commands
+that display text. You can also create a buffer explicitly by typing
+`C-x b BUFNAME <RET>', which creates a new, empty buffer that is not
+visiting any file, and selects it for editing. The new buffer's major
+mode is determined by the value of `default-major-mode' (*note Major
+Modes::.). Buffers not visiting files are usually used for making
+notes to yourself. If you try to save one, you are asked for the file
+name to use.
+
+ The function `switch-to-buffer-other-frame' is similar to
+`switch-to-buffer' except that it creates a new frame in which to
+display the selected buffer.
+
+ Use `M-x switch-to-other-buffer' to visit the previous buffer. If
+you supply a positive integer N, the Nth most recent buffer is
+displayed. If you supply an argument of 0, the current buffer is moved
+to the bottom of the buffer stack.
+
+ Note that you can also use `C-x C-f' and any other command for
+visiting a file to switch buffers. *Note Visiting::.
+
+\1f
+File: xemacs.info, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers
+
+Listing Existing Buffers
+========================
+
+`C-x C-b'
+ List the existing buffers (`list-buffers').
+
+ To print a list of all existing buffers, type `C-x C-b'. Each line
+in the list shows one buffer's name, major mode, and visited file. A
+`*' at the beginning of a line indicates the buffer has been
+"modified". If several buffers are modified, it may be time to save
+some with `C-x s' (*note Saving::.). A `%' indicates a read-only
+buffer. A `.' marks the selected buffer. Here is an example of a
+buffer list:
+
+ MR Buffer Size Mode File
+ -- ------ ---- ---- ----
+ .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex
+ *Help* 1287 Fundamental
+ files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el
+ % RMAIL 64042 RMAIL /u/rms/RMAIL
+ *% man 747 Dired /u2/emacs/man/
+ net.emacs 343885 Fundamental /u/rms/net.emacs
+ fileio.c 27691 C /u2/emacs/src/fileio.c
+ NEWS 67340 Text /u2/emacs/etc/NEWS
+ *scratch* 0 Lisp Interaction
+
+Note that the buffer `*Help*' was made by a help request; it is not
+visiting any file. The buffer `man' was made by Dired on the directory
+`/u2/emacs/man/'.
+
+ As you move the mouse over the `*Buffer List*' buffer, the lines are
+highlighted. This visual cue indicates that clicking the right mouse
+button (`button3') will pop up a menu of commands on the buffer
+represented by this line. This menu duplicates most of those commands
+which are bound to keys in the `*Buffer List*' buffer.
+
+\1f
+File: xemacs.info, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers
+
+Miscellaneous Buffer Operations
+===============================
+
+`C-x C-q'
+ Toggle read-only status of buffer (`toggle-read-only').
+
+`M-x rename-buffer'
+ Change the name of the current buffer.
+
+`M-x view-buffer'
+ Scroll through a buffer.
+
+ A buffer can be "read-only", which means that commands to change its
+text are not allowed. Normally, read-only buffers are created by
+subsystems such as Dired and Rmail that have special commands to operate
+on the text. Emacs also creates a read-only buffer if you visit a file
+that is protected. To make changes in a read-only buffer, use the
+command `C-x C-q' (`toggle-read-only'). It makes a read-only buffer
+writable, and makes a writable buffer read-only. This works by setting
+the variable `buffer-read-only', which has a local value in each buffer
+and makes a buffer read-only if its value is non-`nil'.
+
+ `M-x rename-buffer' changes the name of the current buffer,
+prompting for the new name in the minibuffer. There is no default. If
+you specify a name that is used by a different buffer, an error is
+signalled and renaming is not done.
+
+ `M-x view-buffer' is similar to `M-x view-file' (*note Misc File
+Ops::.), but it examines an already existing Emacs buffer. View mode
+provides convenient commands for scrolling through the buffer but not
+for changing it. When you exit View mode, the resulting value of point
+remains in effect.
+
+ To copy text from one buffer to another, use the commands `M-x
+append-to-buffer' and `M-x insert-buffer'. *Note Accumulating Text::.
+
+\1f
+File: xemacs.info, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers
+
+Killing Buffers
+===============
+
+ After using Emacs for a while, you may accumulate a large number of
+buffers and may want to eliminate the ones you no longer need. There
+are several commands for doing this.
+
+`C-x k'
+ Kill a buffer, specified by name (`kill-buffer').
+
+`M-x kill-some-buffers'
+ Offer to kill each buffer, one by one.
+
+ `C-x k' (`kill-buffer') kills one buffer, whose name you specify in
+the minibuffer. If you type just <RET> in the minibuffer, the default,
+killing the current buffer, is used. If the current buffer is killed,
+the buffer that has been selected recently but does not appear in any
+window now is selected. If the buffer being killed contains unsaved
+changes, you are asked to confirm with `yes' before the buffer is
+killed.
+
+ The command `M-x kill-some-buffers' asks about each buffer, one by
+one. An answer of `y' means to kill the buffer. Killing the current
+buffer or a buffer containing unsaved changes selects a new buffer or
+asks for confirmation just like `kill-buffer'.
+
+\1f
+File: xemacs.info, Node: Several Buffers, Prev: Kill Buffer, Up: Buffers
+
+Operating on Several Buffers
+============================
+
+ The "buffer-menu" facility is like a "Dired for buffers"; it allows
+you to request operations on various Emacs buffers by editing a buffer
+containing a list of them. You can save buffers, kill them (here
+called "deleting" them, for consistency with Dired), or display them.
+
+`M-x buffer-menu'
+ Begin editing a buffer listing all Emacs buffers.
+
+ The command `buffer-menu' writes a list of all Emacs buffers into
+the buffer `*Buffer List*', and selects that buffer in Buffer Menu
+mode. The buffer is read-only. You can only change it using the
+special commands described in this section. Most of the commands are
+graphic characters. You can use Emacs cursor motion commands in the
+`*Buffer List*' buffer. If the cursor is on a line describing a
+buffer, the following special commands apply to that buffer:
+
+`d'
+ Request to delete (kill) the buffer, then move down. A `D' before
+ the buffer name on a line indicates a deletion request. Requested
+ deletions actually take place when you use the `x' command.
+
+`k'
+ Synonym for `d'.
+
+`C-d'
+ Like `d' but move up afterwards instead of down.
+
+`s'
+ Request to save the buffer. An `S' befor the buffer name on a line
+ indicates the request. Requested saves actually take place when
+ you use the `x' command. You can request both saving and deletion
+ for the same buffer.
+
+`~'
+ Mark buffer "unmodified". The command `~' does this immediately
+ when typed.
+
+`x'
+ Perform previously requested deletions and saves.
+
+`u'
+ Remove any request made for the current line, and move down.
+
+`<DEL>'
+ Move to previous line and remove any request made for that line.
+
+ All commands that add or remove flags to request later operations
+also move down a line. They accept a numeric argument as a repeat
+count, unless otherwise specified.
+
+ There are also special commands to use the buffer list to select
+another buffer, and to specify one or more other buffers for display in
+additional windows.
+
+`1'
+ Select the buffer in a full-frame window. This command takes
+ effect immediately.
+
+`2'
+ Immediately set up two windows, with this buffer in one and the
+ buffer selected before `*Buffer List*' in the other.
+
+`f'
+ Immediately select the buffer in place of the `*Buffer List*'
+ buffer.
+
+`o'
+ Immediately select the buffer in another window as if by `C-x 4 b',
+ leaving `*Buffer List*' visible.
+
+`q'
+ Immediately select this buffer, and display any buffers previously
+ flagged with the `m' command in other windows. If there are no
+ buffers flagged with `m', this command is equivalent to `1'.
+
+`m'
+ Flag this buffer to be displayed in another window if the `q'
+ command is used. The request shows as a `>' at the beginning of
+ the line. The same buffer may not have both a delete request and a
+ display request.
+
+ Going back between a `buffer-menu' buffer and other Emacs buffers is
+easy. You can, for example, switch from the `*Buffer List*' buffer to
+another Emacs buffer, and edit there. You can then reselect the
+`buffer-menu' buffer and perform operations already requested, or you
+can kill that buffer or pay no further attention to it. All that
+`buffer-menu' does directly is create and select a suitable buffer, and
+turn on Buffer Menu mode. All the other capabilities of the buffer
+menu are implemented by special commands provided in Buffer Menu mode.
+
+ The only difference between `buffer-menu' and `list-buffers' is that
+`buffer-menu' selects the `*Buffer List*' buffer and `list-buffers'
+does not. If you run `list-buffers' (that is, type `C-x C-b') and
+select the buffer list manually, you can use all the commands described
+here.
+
+\1f
+File: xemacs.info, Node: Windows, Next: Mule, Prev: Buffers, Up: Top
+
+Multiple Windows
+****************
+
+ Emacs can split the frame into two or many windows, which can display
+parts of different buffers or different parts of one buffer. If you are
+running XEmacs under X, that means you can have the X window that
+contains the Emacs frame have multiple subwindows.
+
+* Menu:
+
+* Basic Window:: Introduction to Emacs windows.
+* Split Window:: New windows are made by splitting existing windows.
+* Other Window:: Moving to another window or doing something to it.
+* Pop Up Window:: Finding a file or buffer in another window.
+* Change Window:: Deleting windows and changing their sizes.
+
+\1f
+File: xemacs.info, Node: Basic Window, Next: Split Window, Prev: Windows, Up: Windows
+
+Concepts of Emacs Windows
+=========================
+
+ When Emacs displays multiple windows, each window has one Emacs
+buffer designated for display. The same buffer may appear in more than
+one window; if it does, any changes in its text are displayed in all
+the windows that display it. Windows showing the same buffer can show
+different parts of it, because each window has its own value of point.
+
+ At any time, one window is the "selected window"; the buffer
+displayed by that window is the current buffer. The cursor shows the
+location of point in that window. Each other window has a location of
+point as well, but since the terminal has only one cursor, it cannot
+show the location of point in the other windows.
+
+ Commands to move point affect the value of point for the selected
+Emacs window only. They do not change the value of point in any other
+Emacs window, including those showing the same buffer. The same is
+true for commands such as `C-x b' to change the selected buffer in the
+selected window; they do not affect other windows at all. However,
+there are other commands such as `C-x 4 b' that select a different
+window and switch buffers in it. Also, all commands that display
+information in a window, including (for example) `C-h f'
+(`describe-function') and `C-x C-b' (`list-buffers'), work by switching
+buffers in a non-selected window without affecting the selected window.
+
+ Each window has its own mode line, which displays the buffer name,
+modification status, and major and minor modes of the buffer that is
+displayed in the window. *Note Mode Line::, for details on the mode
+line.
+
+\1f
+File: xemacs.info, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows
+
+Splitting Windows
+=================
+
+`C-x 2'
+ Split the selected window into two windows, one above the other
+ (`split-window-vertically').
+
+`C-x 3'
+ Split the selected window into two windows positioned side by side
+ (`split-window-horizontally').
+
+`C-x 6'
+ Save the current window configuration in register REG (a letter).
+
+`C-x 7'
+ Restore (make current) the window configuration in register REG (a
+ letter). Use with a register previously set with `C-x 6'.
+
+ The command `C-x 2' (`split-window-vertically') breaks the selected
+window into two windows, one above the other. Both windows start out
+displaying the same buffer, with the same value of point. By default
+each of the two windows gets half the height of the window that was
+split. A numeric argument specifies how many lines to give to the top
+window.
+
+ `C-x 3' (`split-window-horizontally') breaks the selected window
+into two side-by-side windows. A numeric argument specifies how many
+columns to give the one on the left. A line of vertical bars separates
+the two windows. Windows that are not the full width of the frame have
+truncated mode lines which do not always appear in inverse video,
+because Emacs display routines cannot display a region of inverse video
+that is only part of a line on the screen.
+
+ When a window is less than the full width, many text lines are too
+long to fit. Continuing all those lines might be confusing. Set the
+variable `truncate-partial-width-windows' to non-`nil' to force
+truncation in all windows less than the full width of the frame,
+independent of the buffer and its value for `truncate-lines'. *Note
+Continuation Lines::.
+
+ Horizontal scrolling is often used in side-by-side windows. *Note
+Display::.
+
+ You can resize a window and store that configuration in a register by
+supplying a REGISTER argument to `window-configuration-to-register'
+(`C-x 6'). To return to the window configuration established with
+`window-configuration-to-register', use `jump-to-register' (`C-x j').
+
+\1f
+File: xemacs.info, Node: Other Window, Next: Pop Up Window, Prev: Split Window, Up: Windows
+
+Using Other Windows
+===================
+
+`C-x o'
+ Select another window (`other-window'). That is the letter `o',
+ not zero.
+
+`M-C-v'
+ Scroll the next window (`scroll-other-window').
+
+`M-x compare-windows'
+ Find the next place where the text in the selected window does not
+ match the text in the next window.
+
+`M-x other-window-any-frame N'
+ Select the Nth different window on any frame.
+
+ To select a different window, use `C-x o' (`other-window'). That is
+an `o', for `other', not a zero. When there are more than two windows,
+the command moves through all the windows in a cyclic order, generally
+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
+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
+Minibuffer Edit::.
+
+ The command `M-x other-window-any-frame' also selects the window N
+steps away in the cyclic order. However, unlike `other-window', this
+command selects a window on the next or previous frame instead of
+wrapping around to the top or bottom of the current frame, when there
+are no more windows.
+
+ The usual scrolling commands (*note Display::.) apply to the selected
+window only. `M-C-v' (`scroll-other-window') scrolls the window that
+`C-x o' would select. Like `C-v', it takes positive and negative
+arguments.
+
+ The command `M-x compare-windows' compares the text in the current
+window with the text in the next window. Comparison starts at point in
+each window. Point moves forward in each window, a character at a time,
+until the next set of characters in the two windows are different.
+Then the command is finished.
+
+ A prefix argument IGNORE-WHITESPACE means ignore changes in
+whitespace. The variable `compare-windows-whitespace' controls how
+whitespace is skipped.
+
+ If `compare-ignore-case' is non-`nil', changes in case are also
+ignored.
+
+\1f
+File: xemacs.info, Node: Pop Up Window, Next: Change Window, Prev: Other Window, Up: Windows
+
+Displaying in Another Window
+============================
+
+ `C-x 4' is a prefix key for commands that select another window
+(splitting the window if there is only one) and select a buffer in that
+window. Different `C-x 4' commands have different ways of finding the
+buffer to select.
+
+`C-x 4 b BUFNAME <RET>'
+ Select buffer BUFNAME in another window. This runs
+ `switch-to-buffer-other-window'.
+
+`C-x 4 f FILENAME <RET>'
+ Visit file FILENAME and select its buffer in another window. This
+ runs `find-file-other-window'. *Note Visiting::.
+
+`C-x 4 d DIRECTORY <RET>'
+ Select a Dired buffer for directory DIRECTORY in another window.
+ This runs `dired-other-window'. *Note Dired::.
+
+`C-x 4 m'
+ Start composing a mail message in another window. This runs
+ `mail-other-window', and its same-window version is `C-x m' (*note
+ Sending Mail::.).
+
+`C-x 4 .'
+ Find a tag in the current tag table in another window. This runs
+ `find-tag-other-window', the multiple-window variant of `M-.'
+ (*note Tags::.).
+
+ If the variable `display-buffer-function' is non-`nil', its value is
+the function to call to handle `display-buffer'. It receives two
+arguments, the buffer and a flag that if non-`nil' means that the
+currently selected window is not acceptable. Commands such as
+`switch-to-buffer-other-window' and `find-file-other-window' work using
+this function.
+
+\1f
+File: xemacs.info, Node: Change Window, Prev: Pop Up Window, Up: Windows
+
+Deleting and Rearranging Windows
+================================
+
+`C-x 0'
+ Get rid of the selected window (`delete-window'). That is a zero.
+ If there is more than one Emacs frame, deleting the sole remaining
+ window on that frame deletes the frame as well. If the current
+ frame is the only frame, it is not deleted.
+
+`C-x 1'
+ Get rid of all windows except the selected one
+ (`delete-other-windows').
+
+`C-x ^'
+ Make the selected window taller, at the expense of the other(s)
+ (`enlarge-window').
+
+`C-x }'
+ Make the selected window wider (`enlarge-window-horizontally').
+
+ To delete a window, type `C-x 0' (`delete-window'). (That is a
+zero.) The space occupied by the deleted window is distributed among
+the other active windows (but not the minibuffer window, even if that
+is active at the time). Once a window is deleted, its attributes are
+forgotten; there is no automatic way to make another window of the same
+shape or showing the same buffer. The buffer continues to exist, and
+you can select it in any window with `C-x b'.
+
+ `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it
+deletes all the windows except the selected one (and the minibuffer).
+The selected window expands to use the whole frame except for the echo
+area.
+
+ To readjust the division of space among existing windows, use `C-x
+^' (`enlarge-window'). It makes the currently selected window longer
+by one line or as many lines as a numeric argument specifies. With a
+negative argument, it makes the selected window smaller. `C-x }'
+(`enlarge-window-horizontally') makes the selected window wider by the
+specified number of columns. The extra screen space given to a window
+comes from one of its neighbors, if that is possible; otherwise, all
+the competing windows are shrunk in the same proportion. If this makes
+some windows too small, those windows are deleted and their space is
+divided up. Minimum window size is specified by the variables
+`window-min-height' and `window-min-width'.
+
+ You can also resize windows within a frame by clicking the left mouse
+button on a modeline, and dragging.
+
+ Clicking the right button on a mode line pops up a menu of common
+window manager operations. This menu contains the following options:
+
+Delete Window
+ Remove the window above this modeline from the frame.
+
+Delete Other Windows
+ Delete all windows on the frame except for the one above this
+ modeline.
+
+Split Window
+ Split the window above the mode line in half, creating another
+ window.
+
+Split Window Horizontally
+ Split the window above the mode line in half horizontally, so that
+ there will be two windows side-by-side.
+
+Balance Windows
+ Readjust the sizes of all windows on the frame until all windows
+ have roughly the same number of lines.
+
+\1f
+File: xemacs.info, Node: Mule, Next: Major Modes, Prev: Windows, Up: Top
+
+World Scripts Support
+*********************
+
+ If you compile XEmacs with mule option, it supports a wide variety of
+world scripts, including Latin script, as well as Arabic script,
+Simplified Chinese script (for mainland of China), Traditional Chinese
+script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA
+symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts
+(Hangul and Hanja) and Cyrillic script (for Beylorussian, Bulgarian,
+Russian, Serbian and Ukrainian). These features have been merged from
+the modified version of Emacs known as MULE (for "MULti-lingual
+Enhancement to GNU Emacs").
+
+* Menu:
+
+* Mule Intro:: Basic concepts of Mule.
+* Language Environments:: Setting things up for the language you use.
+* Input Methods:: Entering text characters not on your keyboard.
+* Select Input Method:: Specifying your choice of input methods.
+* Coding Systems:: Character set conversion when you read and
+ write files, and so on.
+* Recognize Coding:: How XEmacs figures out which conversion to use.
+* Specify Coding:: Various ways to choose which conversion to use.
+
+\1f
+File: xemacs.info, Node: Mule Intro, Next: Language Environments, Prev: Mule, Up: Mule
+
+Introduction to world scripts
+=============================
+
+ The users of these scripts have established many more-or-less
+standard coding systems for storing files. XEmacs translates between
+the internal character encoding and various other coding systems when
+reading and writing files, when exchanging data with subprocesses, and
+(in some cases) in the `C-q' command (see below).
+
+ The command `C-h h' (`view-hello-file') displays the file
+`etc/HELLO', which shows how to say "hello" in many languages. This
+illustrates various scripts.
+
+ Keyboards, even in the countries where these character sets are used,
+generally don't have keys for all the characters in them. So XEmacs
+supports various "input methods", typically one for each script or
+language, to make it convenient to type them.
+
+ The prefix key `C-x <RET>' is used for commands that pertain to
+world scripts, coding systems, and input methods.
+
+\1f
+File: xemacs.info, Node: Language Environments, Next: Input Methods, Prev: Mule Intro, Up: Mule
+
+Language Environments
+=====================
+
+ All supported character sets are supported in XEmacs buffers if it is
+compile with mule; there is no need to select a particular language in
+order to display its characters in an XEmacs buffer. However, it is
+important to select a "language environment" in order to set various
+defaults. The language environment really represents a choice of
+preferred script (more or less) rather that a choice of language.
+
+ The language environment controls which coding systems to recognize
+when reading text (*note Recognize Coding::.). This applies to files,
+incoming mail, netnews, and any other text you read into XEmacs. It may
+also specify the default coding system to use when you create a file.
+Each language environment also specifies a default input method.
+
+ The command to select a language environment is `M-x
+set-language-environment'. It makes no difference which buffer is
+current when you use this command, because the effects apply globally to
+the XEmacs session. The supported language environments include:
+
+ Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-ISO, English,
+ Ethiopic, Greek, Japanese, Korean, Latin-1, Latin-2, Latin-3,
+ Latin-4, Latin-5.
+
+ Some operating systems let you specify the language you are using by
+setting locale environment variables. XEmacs handles one common special
+case of this: if your locale name for character types contains the
+string `8859-N', XEmacs automatically selects the corresponding
+language environment.
+
+ To display information about the effects of a certain language
+environment LANG-ENV, use the command `C-h L LANG-ENV <RET>'
+(`describe-language-environment'). This tells you which languages this
+language environment is useful for, and lists the character sets,
+coding systems, and input methods that go with it. It also shows some
+sample text to illustrate scripts used in this language environment.
+By default, this command describes the chosen language environment.
+
+\1f
+File: xemacs.info, Node: Input Methods, Next: Select Input Method, Prev: Language Environments, Up: Mule
+
+Input Methods
+=============
+
+ An "input method" is a kind of character conversion designed
+specifically for interactive input. In XEmacs, typically each language
+has its own input method; sometimes several languages which use the same
+characters can share one input method. A few languages support several
+input methods.
+
+ The simplest kind of input method works by mapping ASCII letters into
+another alphabet. This is how the Greek and Russian input methods work.
+
+ A more powerful technique is composition: converting sequences of
+characters into one letter. Many European input methods use composition
+to produce a single non-ASCII letter from a sequence that consists of a
+letter followed by accent characters. For example, some methods convert
+the sequence `'a' into a single accented letter.
+
+ The input methods for syllabic scripts typically use mapping followed
+by composition. The input methods for Thai and Korean work this way.
+First, letters are mapped into symbols for particular sounds or tone
+marks; then, sequences of these which make up a whole syllable are
+mapped into one syllable sign.
+
+ Chinese and Japanese require more complex methods. In Chinese input
+methods, first you enter the phonetic spelling of a Chinese word (in
+input method `chinese-py', among others), or a sequence of portions of
+the character (input methods `chinese-4corner' and `chinese-sw', and
+others). Since one phonetic spelling typically corresponds to many
+different Chinese characters, you must select one of the alternatives
+using special XEmacs commands. Keys such as `C-f', `C-b', `C-n',
+`C-p', and digits have special definitions in this situation, used for
+selecting among the alternatives. <TAB> displays a buffer showing all
+the possibilities.
+
+ In Japanese input methods, first you input a whole word using
+phonetic spelling; then, after the word is in the buffer, XEmacs
+converts it into one or more characters using a large dictionary. One
+phonetic spelling corresponds to many differently written Japanese
+words, so you must select one of them; use `C-n' and `C-p' to cycle
+through the alternatives.
+
+ Sometimes it is useful to cut off input method processing so that the
+characters you have just entered will not combine with subsequent
+characters. For example, in input method `latin-1-postfix', the
+sequence `e '' combines to form an `e' with an accent. What if you
+want to enter them as separate characters?
+
+ One way is to type the accent twice; that is a special feature for
+entering the separate letter and accent. For example, `e ' '' gives
+you the two characters `e''. Another way is to type another letter
+after the `e'--something that won't combine with that--and immediately
+delete it. For example, you could type `e e <DEL> '' to get separate
+`e' and `''.
+
+ Another method, more general but not quite as easy to type, is to use
+`C-\ C-\' between two characters to stop them from combining. This is
+the command `C-\' (`toggle-input-method') used twice. *Note Select
+Input Method::.
+
+ `C-\ C-\' is especially useful inside an incremental search, because
+stops waiting for more characters to combine, and starts searching for
+what you have already entered.
+
+ The variables `input-method-highlight-flag' and
+`input-method-verbose-flag' control how input methods explain what is
+happening. If `input-method-highlight-flag' is non-`nil', the partial
+sequence is highlighted in the buffer. If `input-method-verbose-flag'
+is non-`nil', the list of possible characters to type next is displayed
+in the echo area (but not when you are in the minibuffer).
+
+\1f
+File: xemacs.info, Node: Select Input Method, Next: Coding Systems, Prev: Input Methods, Up: Mule
+
+Selecting an Input Method
+=========================
+
+`C-\'
+ Enable or disable use of the selected input method.
+
+`C-x <RET> C-\ METHOD <RET>'
+ Select a new input method for the current buffer.
+
+`C-h I METHOD <RET>'
+`C-h C-\ METHOD <RET>'
+ Describe the input method METHOD (`describe-input-method'). By
+ default, it describes the current input method (if any).
+
+`M-x list-input-methods'
+ Display a list of all the supported input methods.
+
+ To choose an input method for the current buffer, use `C-x <RET>
+C-\' (`select-input-method'). This command reads the input method name
+with the minibuffer; the name normally starts with the language
+environment that it is meant to be used with. The variable
+`current-input-method' records which input method is selected.
+
+ Input methods use various sequences of ASCII characters to stand for
+non-ASCII characters. Sometimes it is useful to turn off the input
+method temporarily. To do this, type `C-\' (`toggle-input-method').
+To reenable the input method, type `C-\' again.
+
+ If you type `C-\' and you have not yet selected an input method, it
+prompts for you to specify one. This has the same effect as using `C-x
+<RET> C-\' to specify an input method.
+
+ Selecting a language environment specifies a default input method for
+use in various buffers. When you have a default input method, you can
+select it in the current buffer by typing `C-\'. The variable
+`default-input-method' specifies the default input method (`nil' means
+there is none).
+
+ Some input methods for alphabetic scripts work by (in effect)
+remapping the keyboard to emulate various keyboard layouts commonly used
+for those scripts. How to do this remapping properly depends on your
+actual keyboard layout. To specify which layout your keyboard has, use
+the command `M-x quail-set-keyboard-layout'.
+
+ To display a list of all the supported input methods, type `M-x
+list-input-methods'. The list gives information about each input
+method, including the string that stands for it in the mode line.
+
+\1f
+File: xemacs.info, Node: Coding Systems, Next: Recognize Coding, Prev: Select Input Method, Up: Mule
+
+Coding Systems
+==============
+
+ Users of various languages have established many more-or-less
+standard coding systems for representing them. XEmacs does not use
+these coding systems internally; instead, it converts from various
+coding systems to its own system when reading data, and converts the
+internal coding system to other coding systems when writing data.
+Conversion is possible in reading or writing files, in sending or
+receiving from the terminal, and in exchanging data with subprocesses.
+
+ XEmacs assigns a name to each coding system. Most coding systems are
+used for one language, and the name of the coding system starts with the
+language name. Some coding systems are used for several languages;
+their names usually start with `iso'. There are also special coding
+systems `binary' and `no-conversion' which do not convert printing
+characters at all.
+
+ In addition to converting various representations of non-ASCII
+characters, a coding system can perform end-of-line conversion. XEmacs
+handles three different conventions for how to separate lines in a file:
+newline, carriage-return linefeed, and just carriage-return.
+
+`C-h C CODING <RET>'
+ Describe coding system CODING.
+
+`C-h C <RET>'
+ Describe the coding systems currently in use.
+
+`M-x list-coding-systems'
+ Display a list of all the supported coding systems.
+
+ The command `C-h C' (`describe-coding-system') displays information
+about particular coding systems. You can specify a coding system name
+as argument; alternatively, with an empty argument, it describes the
+coding systems currently selected for various purposes, both in the
+current buffer and as the defaults, and the priority list for
+recognizing coding systems (*note Recognize Coding::.).
+
+ To display a list of all the supported coding systems, type `M-x
+list-coding-systems'. The list gives information about each coding
+system, including the letter that stands for it in the mode line (*note
+Mode Line::.).
+
+ Each of the coding systems that appear in this list--except for
+`binary', which means no conversion of any kind--specifies how and
+whether to convert printing characters, but leaves the choice of
+end-of-line conversion to be decided based on the contents of each file.
+For example, if the file appears to use carriage-return linefeed between
+lines, that end-of-line conversion will be used.
+
+ Each of the listed coding systems has three variants which specify
+exactly what to do for end-of-line conversion:
+
+`...-unix'
+ Don't do any end-of-line conversion; assume the file uses newline
+ to separate lines. (This is the convention normally used on Unix
+ and GNU systems.)
+
+`...-dos'
+ Assume the file uses carriage-return linefeed to separate lines,
+ and do the appropriate conversion. (This is the convention
+ normally used on Microsoft systems.)
+
+`...-mac'
+ Assume the file uses carriage-return to separate lines, and do the
+ appropriate conversion. (This is the convention normally used on
+ the Macintosh system.)
+
+ These variant coding systems are omitted from the
+`list-coding-systems' display for brevity, since they are entirely
+predictable. For example, the coding system `iso-8859-1' has variants
+`iso-8859-1-unix', `iso-8859-1-dos' and `iso-8859-1-mac'.
+
+ In contrast, the coding system `binary' specifies no character code
+conversion at all--none for non-Latin-1 byte values and none for end of
+line. This is useful for reading or writing binary files, tar files,
+and other files that must be examined verbatim.
+
+ The easiest way to edit a file with no conversion of any kind is with
+the `M-x find-file-literally' command. This uses `binary', and also
+suppresses other XEmacs features that might convert the file contents
+before you see them. *Note Visiting::.
+
+ The coding system `no-conversion' means that the file contains
+non-Latin-1 characters stored with the internal XEmacs encoding. It
+handles end-of-line conversion based on the data encountered, and has
+the usual three variants to specify the kind of end-of-line conversion.
+
+\1f
+File: xemacs.info, Node: Recognize Coding, Next: Specify Coding, Prev: Coding Systems, Up: Mule
+
+Recognizing Coding Systems
+==========================
+
+ Most of the time, XEmacs can recognize which coding system to use for
+any given file-once you have specified your preferences.
+
+ Some coding systems can be recognized or distinguished by which byte
+sequences appear in the data. However, there are coding systems that
+cannot be distinguished, not even potentially. For example, there is no
+way to distinguish between Latin-1 and Latin-2; they use the same byte
+values with different meanings.
+
+ XEmacs handles this situation by means of a priority list of coding
+systems. Whenever XEmacs reads a file, if you do not specify the coding
+system to use, XEmacs checks the data against each coding system,
+starting with the first in priority and working down the list, until it
+finds a coding system that fits the data. Then it converts the file
+contents assuming that they are represented in this coding system.
+
+ The priority list of coding systems depends on the selected language
+environment (*note Language Environments::.). For example, if you use
+French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you
+use Czech, you probably want Latin-2 to be preferred. This is one of
+the reasons to specify a language environment.
+
+ However, you can alter the priority list in detail with the command
+`M-x prefer-coding-system'. This command reads the name of a coding
+system from the minibuffer, and adds it to the front of the priority
+list, so that it is preferred to all others. If you use this command
+several times, each use adds one element to the front of the priority
+list.
+
+ Sometimes a file name indicates which coding system to use for the
+file. The variable `file-coding-system-alist' specifies this
+correspondence. There is a special function
+`modify-coding-system-alist' for adding elements to this list. For
+example, to read and write all `.txt' using the coding system
+`china-iso-8bit', you can execute this Lisp expression:
+
+ (modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
+
+The first argument should be `file', the second argument should be a
+regular expression that determines which files this applies to, and the
+third argument says which coding system to use for these files.
+
+ You can specify the coding system for a particular file using the
+`-*-...-*-' construct at the beginning of a file, or a local variables
+list at the end (*note File Variables::.). You do this by defining a
+value for the "variable" named `coding'. XEmacs does not really have a
+variable `coding'; instead of setting a variable, it uses the specified
+coding system for the file. For example, `-*-mode: C; coding:
+iso-8859-1;-*-' specifies use of the iso-8859-1 coding system, as well
+as C mode.
+
+ Once XEmacs has chosen a coding system for a buffer, it stores that
+coding system in `buffer-file-coding-system' and uses that coding
+system, by default, for operations that write from this buffer into a
+file. This includes the commands `save-buffer' and `write-region'. If
+you want to write files from this buffer using a different coding
+system, you can specify a different coding system for the buffer using
+`set-buffer-file-coding-system' (*note Specify Coding::.).
+
--- /dev/null
+This is Info file ../../info/xemacs.info, produced by Makeinfo version
+1.68 from the input file xemacs.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* XEmacs: (xemacs). XEmacs Editor.
+END-INFO-DIR-ENTRY
+
+ This file documents the XEmacs editor.
+
+ Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
+1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
+Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
+
+ Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+ Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
+General Public License" are included exactly as in the original, and
+provided that the entire resulting derived work is distributed under the
+terms of a permission notice identical to this one.
+
+ Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the sections entitled "The GNU Manifesto",
+"Distribution" and "GNU General Public License" may be included in a
+translation approved by the author instead of in the original English.
+
+\1f
+File: xemacs.info, Node: Specify Coding, Prev: Recognize Coding, Up: Mule
+
+Specifying a Coding System
+==========================
+
+ In cases where XEmacs does not automatically choose the right coding
+system, you can use these commands to specify one:
+
+`C-x <RET> f CODING <RET>'
+ Use coding system CODING for the visited file in the current
+ buffer.
+
+`C-x <RET> c CODING <RET>'
+ Specify coding system CODING for the immediately following command.
+
+`C-x <RET> k CODING <RET>'
+ Use coding system CODING for keyboard input.
+
+`C-x <RET> t CODING <RET>'
+ Use coding system CODING for terminal output.
+
+`C-x <RET> p CODING <RET>'
+ Use coding system CODING for subprocess input and output in the
+ current buffer.
+
+ The command `C-x RET f' (`set-buffer-file-coding-system') specifies
+the file coding system for the current buffer--in other words, which
+coding system to use when saving or rereading the visited file. You
+specify which coding system using the minibuffer. Since this command
+applies to a file you have already visited, it affects only the way the
+file is saved.
+
+ Another way to specify the coding system for a file is when you visit
+the file. First use the command `C-x <RET> c'
+(`universal-coding-system-argument'); this command uses the minibuffer
+to read a coding system name. After you exit the minibuffer, the
+specified coding system is used for *the immediately following command*.
+
+ So if the immediately following command is `C-x C-f', for example,
+it reads the file using that coding system (and records the coding
+system for when the file is saved). Or if the immediately following
+command is `C-x C-w', it writes the file using that coding system.
+Other file commands affected by a specified coding system include `C-x
+C-i' and `C-x C-v', as well as the other-window variants of `C-x C-f'.
+
+ In addition, if you run some file input commands with the precedent
+`C-u', you can specify coding system to read from minibuffer. So if
+the immediately following command is `C-x C-f', for example, it reads
+the file using that coding system (and records the coding system for
+when the file is saved). Other file commands affected by a specified
+coding system include `C-x C-i' and `C-x C-v', as well as the
+other-window variants of `C-x C-f'.
+
+ The variable `default-buffer-file-coding-system' specifies the
+choice of coding system to use when you create a new file. It applies
+when you find a new file, and when you create a buffer and then save it
+in a file. Selecting a language environment typically sets this
+variable to a good choice of default coding system for that language
+environment.
+
+ The command `C-x <RET> t' (`set-terminal-coding-system') specifies
+the coding system for terminal output. If you specify a character code
+for terminal output, all characters output to the terminal are
+translated into that coding system.
+
+ This feature is useful for certain character-only terminals built to
+support specific languages or character sets--for example, European
+terminals that support one of the ISO Latin character sets.
+
+ By default, output to the terminal is not translated at all.
+
+ The command `C-x <RET> k' (`set-keyboard-coding-system') specifies
+the coding system for keyboard input. Character-code translation of
+keyboard input is useful for terminals with keys that send non-ASCII
+graphic characters--for example, some terminals designed for ISO
+Latin-1 or subsets of it.
+
+ By default, keyboard input is not translated at all.
+
+ There is a similarity between using a coding system translation for
+keyboard input, and using an input method: both define sequences of
+keyboard input that translate into single characters. However, input
+methods are designed to be convenient for interactive use by humans, and
+the sequences that are translated are typically sequences of ASCII
+printing characters. Coding systems typically translate sequences of
+non-graphic characters.
+
+ The command `C-x <RET> p' (`set-buffer-process-coding-system')
+specifies the coding system for input and output to a subprocess. This
+command applies to the current buffer; normally, each subprocess has its
+own buffer, and thus you can use this command to specify translation to
+and from a particular subprocess by giving the command in the
+corresponding buffer.
+
+ By default, process input and output are not translated at all.
+
+ The variable `file-name-coding-system' specifies a coding system to
+use for encoding file names. If you set the variable to a coding
+system name (as a Lisp symbol or a string), XEmacs encodes file names
+using that coding system for all file operations. This makes it
+possible to use non-Latin-1 characters in file names--or, at least,
+those non-Latin-1 characters which the specified coding system can
+encode. By default, this variable is `nil', which implies that you
+cannot use non-Latin-1 characters in file names.
+
+\1f
+File: xemacs.info, Node: Major Modes, Next: Indentation, Prev: Mule, Up: Top
+
+Major Modes
+***********
+
+ Emacs has many different "major modes", each of which customizes
+Emacs for editing text of a particular sort. The major modes are
+mutually exclusive; at any time, each buffer has one major mode. The
+mode line normally contains the name of the current major mode in
+parentheses. *Note Mode Line::.
+
+ The least specialized major mode is called "Fundamental mode". This
+mode has no mode-specific redefinitions or variable settings. Each
+Emacs command behaves in its most general manner, and each option is in
+its default state. For editing any specific type of text, such as Lisp
+code or English text, you should switch to the appropriate major mode,
+such as Lisp mode or Text mode.
+
+ Selecting a major mode changes the meanings of a few keys to become
+more specifically adapted to the language being edited. <TAB>, <DEL>,
+and <LFD> are changed frequently. In addition, commands which handle
+comments use the mode to determine how to delimit comments. Many major
+modes redefine the syntactical properties of characters appearing in
+the buffer. *Note Syntax::.
+
+ The major modes fall into three major groups. Lisp mode (which has
+several variants), C mode, and Muddle mode are for specific programming
+languages. Text mode, Nroff mode, TeX mode, and Outline mode are for
+editing English text. The remaining major modes are not intended for
+use on users' files; they are used in buffers created by Emacs for
+specific purposes and include Dired mode for buffers made by Dired
+(*note Dired::.), Mail mode for buffers made by `C-x m' (*note Sending
+Mail::.), and Shell mode for buffers used for communicating with an
+inferior shell process (*note Interactive Shell::.).
+
+ Most programming language major modes specify that only blank lines
+separate paragraphs. This is so that the paragraph commands remain
+useful. *Note Paragraphs::. They also cause Auto Fill mode to use the
+definition of <TAB> to indent the new lines it creates. This is
+because most lines in a program are usually indented. *Note
+Indentation::.
+
+* Menu:
+
+* Choosing Modes:: How major modes are specified or chosen.
+
+\1f
+File: xemacs.info, Node: Choosing Modes, Prev: Major Modes, Up: Major Modes
+
+Choosing Major Modes
+====================
+
+ You can select a major mode explicitly for the current buffer, but
+most of the time Emacs determines which mode to use based on the file
+name or some text in the file.
+
+ Use a `M-x' command to explicitly select a new major mode. Add
+`-mode' to the name of a major mode to get the name of a command to
+select that mode. For example, to enter Lisp mode, execute `M-x
+lisp-mode'.
+
+ When you visit a file, Emacs usually chooses the right major mode
+based on the file's name. For example, files whose names end in `.c'
+are edited in C mode. The variable `auto-mode-alist' controls the
+correspondence between file names and major mode. Its value is a list
+in which each element has the form:
+
+ (REGEXP . MODE-FUNCTION)
+
+For example, one element normally found in the list has the form
+`("\\.c$" . c-mode)'. It is responsible for selecting C mode for files
+whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to
+include a `\' in the string, which is needed to suppress the special
+meaning of `.' in regexps.) The only practical way to change this
+variable is with Lisp code.
+
+ You can specify which major mode should be used for editing a certain
+file by a special sort of text in the first non-blank line of the file.
+The mode name should appear in this line both preceded and followed by
+`-*-'. Other text may appear on the line as well. For example,
+
+ ;-*-Lisp-*-
+
+tells Emacs to use Lisp mode. Note how the semicolon is used to make
+Lisp treat this line as a comment. Such an explicit specification
+overrides any default mode based on the file name.
+
+ Another format of mode specification is:
+
+ -*-Mode: MODENAME;-*-
+
+which allows other things besides the major mode name to be specified.
+However, Emacs does not look for anything except the mode name.
+
+ The major mode can also be specified in a local variables list.
+*Note File Variables::.
+
+ When you visit a file that does not specify a major mode to use, or
+when you create a new buffer with `C-x b', Emacs uses the major mode
+specified by the variable `default-major-mode'. Normally this value is
+the symbol `fundamental-mode', which specifies Fundamental mode. If
+`default-major-mode' is `nil', the major mode is taken from the
+previously selected buffer.
+
+\1f
+File: xemacs.info, Node: Indentation, Next: Text, Prev: Major Modes, Up: Top
+
+Indentation
+***********
+
+`<TAB>'
+ Indent current line "appropriately" in a mode-dependent fashion.
+
+`<LFD>'
+ Perform <RET> followed by <TAB> (`newline-and-indent').
+
+`M-^'
+ Merge two lines (`delete-indentation'). This would cancel out the
+ effect of <LFD>.
+
+`C-M-o'
+ Split line at point; text on the line after point becomes a new
+ line indented to the same column that it now starts in
+ (`split-line').
+
+`M-m'
+ Move (forward or back) to the first non-blank character on the
+ current line (`back-to-indentation').
+
+`C-M-\'
+ Indent several lines to same column (`indent-region').
+
+`C-x <TAB>'
+ Shift block of lines rigidly right or left (`indent-rigidly').
+
+`M-i'
+ Indent from point to the next prespecified tab stop column
+ (`tab-to-tab-stop').
+
+`M-x indent-relative'
+ Indent from point to under an indentation point in the previous
+ line.
+
+ Most programming languages have some indentation convention. For
+Lisp code, lines are indented according to their nesting in
+parentheses. The same general idea is used for C code, though details
+differ.
+
+ Use the <TAB> command to indent a line whatever the language. Each
+major mode defines this command to perform indentation appropriate for
+the particular language. In Lisp mode, <TAB> aligns a line according
+to its depth in parentheses. No matter where in the line you are when
+you type <TAB>, it aligns the line as a whole. In C mode, <TAB>
+implements a subtle and sophisticated indentation style that knows
+about many aspects of C syntax.
+
+ In Text mode, <TAB> runs the command `tab-to-tab-stop', which
+indents to the next tab stop column. You can set the tab stops with
+`M-x edit-tab-stops'.
+
+* Menu:
+
+* Indentation Commands:: Various commands and techniques for indentation.
+* Tab Stops:: You can set arbitrary "tab stops" and then
+ indent to the next tab stop when you want to.
+* Just Spaces:: You can request indentation using just spaces.
+
+\1f
+File: xemacs.info, Node: Indentation Commands, Next: Tab Stops, Prev: Indentation, Up: Indentation
+
+Indentation Commands and Techniques
+===================================
+
+ If you just want to insert a tab character in the buffer, you can
+type `C-q <TAB>'.
+
+ To move over the indentation on a line, type `Meta-m'
+(`back-to-indentation'). This command, given anywhere on a line,
+positions point at the first non-blank character on the line.
+
+ To insert an indented line before the current line, type `C-a C-o
+<TAB>'. To make an indented line after the current line, use `C-e
+<LFD>'.
+
+ `C-M-o' (`split-line') moves the text from point to the end of the
+line vertically down, so that the current line becomes two lines.
+`C-M-o' first moves point forward over any spaces and tabs. Then it
+inserts after point a newline and enough indentation to reach the same
+column point is on. Point remains before the inserted newline; in this
+regard, `C-M-o' resembles `C-o'.
+
+ To join two lines cleanly, use the `Meta-^' (`delete-indentation')
+command to delete the indentation at the front of the current line, and
+the line boundary as well. Empty spaces are replaced by a single
+space, or by no space if at the beginning of a line, before a close
+parenthesis, or after an open parenthesis. To delete just the
+indentation of a line, go to the beginning of the line and use `Meta-\'
+(`delete-horizontal-space'), which deletes all spaces and tabs around
+the cursor.
+
+ There are also commands for changing the indentation of several
+lines at once. `Control-Meta-\' (`indent-region') gives each line which
+begins in the region the "usual" indentation by invoking <TAB> at the
+beginning of the line. A numeric argument specifies the column to
+indent to. Each line is shifted left or right so that its first
+non-blank character appears in that column. `C-x <TAB>'
+(`indent-rigidly') moves all the lines in the region right by its
+argument (left, for negative arguments). The whole group of lines moves
+rigidly sideways, which is how the command gets its name.
+
+ `M-x indent-relative' indents at point based on the previous line
+(actually, the last non-empty line.) It inserts whitespace at point,
+moving point, until it is underneath an indentation point in the
+previous line. An indentation point is the end of a sequence of
+whitespace or the end of the line. If point is farther right than any
+indentation point in the previous line, the whitespace before point is
+deleted and the first indentation point then applicable is used. If no
+indentation point is applicable even then, `tab-to-tab-stop' is run
+(see next section).
+
+ `indent-relative' is the definition of <TAB> in Indented Text mode.
+*Note Text::.
+
+\1f
+File: xemacs.info, Node: Tab Stops, Next: Just Spaces, Prev: Indentation Commands, Up: Indentation
+
+Tab Stops
+=========
+
+ For typing in tables, you can use Text mode's definition of <TAB>,
+`tab-to-tab-stop'. This command inserts indentation before point,
+enough to reach the next tab stop column. Even if you are not in Text
+mode, this function is associated with `M-i' anyway.
+
+ You can arbitrarily set the tab stops used by `M-i'. They are
+stored as a list of column-numbers in increasing order in the variable
+`tab-stop-list'.
+
+ The convenient way to set the tab stops is using `M-x
+edit-tab-stops', which creates and selects a buffer containing a
+description of the tab stop settings. You can edit this buffer to
+specify different tab stops, and then type `C-c C-c' to make those new
+tab stops take effect. In the tab stop buffer, `C-c C-c' runs the
+function `edit-tab-stops-note-changes' rather than the default
+`save-buffer'. `edit-tab-stops' records which buffer was current when
+you invoked it, and stores the tab stops in that buffer. Normally all
+buffers share the same tab stops and changing them in one buffer
+affects all. If you make `tab-stop-list' local in one buffer
+`edit-tab-stops' in that buffer edits only the local settings.
+
+ Below is the text representing ordinary tab stops every eight
+columns:
+
+ : : : : : :
+ 0 1 2 3 4
+ 0123456789012345678901234567890123456789012345678
+ To install changes, type C-c C-c
+
+ The first line contains a colon at each tab stop. The remaining
+lines help you see where the colons are and tell you what to do.
+
+ Note that the tab stops that control `tab-to-tab-stop' have nothing
+to do with displaying tab characters in the buffer. *Note Display
+Vars::, for more information on that.
+
+\1f
+File: xemacs.info, Node: Just Spaces, Prev: Tab Stops, Up: Indentation
+
+Tabs vs. Spaces
+===============
+
+ Emacs normally uses both tabs and spaces to indent lines. If you
+prefer, all indentation can be made from spaces only. To request this,
+set `indent-tabs-mode' to `nil'. This is a per-buffer variable;
+altering the variable affects only the current buffer, but there is a
+default value which you can change as well. *Note Locals::.
+
+ There are also commands to convert tabs to spaces or vice versa,
+always preserving the columns of all non-blank text. `M-x tabify'
+scans the region for sequences of spaces, and converts sequences of at
+least three spaces to tabs if that is possible without changing
+indentation. `M-x untabify' changes all tabs in the region to
+corresponding numbers of spaces.
+
+\1f
+File: xemacs.info, Node: Text, Next: Programs, Prev: Indentation, Up: Top
+
+Commands for Human Languages
+****************************
+
+ The term "text" has two widespread meanings in our area of the
+computer field. One is data that is a sequence of characters. In this
+sense of the word any file that you edit with Emacs is text. The other
+meaning is more restrictive: a sequence of characters in a human
+language for humans to read (possibly after processing by a text
+formatter), as opposed to a program or commands for a program.
+
+ Human languages have syntactic and stylistic conventions that editor
+commands should support or use to advantage: conventions involving
+words, sentences, paragraphs, and capital letters. This chapter
+describes Emacs commands for all these things. There are also commands
+for "filling", or rearranging paragraphs into lines of approximately
+equal length. The commands for moving over and killing words,
+sentences, and paragraphs, while intended primarily for editing text,
+are also often useful for editing programs.
+
+ Emacs has several major modes for editing human language text. If a
+file contains plain text, use Text mode, which customizes Emacs in
+small ways for the syntactic conventions of text. For text which
+contains embedded commands for text formatters, Emacs has other major
+modes, each for a particular text formatter. Thus, for input to TeX,
+you can use TeX mode; for input to nroff, Nroff mode.
+
+* Menu:
+
+* Text Mode:: The major modes for editing text files.
+* Nroff Mode:: The major mode for editing input to the formatter nroff.
+* TeX Mode:: The major modes for editing input to the formatter TeX.
+* Outline Mode:: The major mode for editing outlines.
+* Words:: Moving over and killing words.
+* Sentences:: Moving over and killing sentences.
+* Paragraphs:: Moving over paragraphs.
+* Pages:: Moving over pages.
+* Filling:: Filling or justifying text
+* Case:: Changing the case of text
+
+\1f
+File: xemacs.info, Node: Text Mode, Next: Words, Prev: Text, Up: Text
+
+Text Mode
+=========
+
+ You should use Text mode--rather than Fundamental or Lisp mode--to
+edit files of text in a human language. Invoke `M-x text-mode' to
+enter Text mode. In Text mode, <TAB> runs the function
+`tab-to-tab-stop', which allows you to use arbitrary tab stops set with
+`M-x edit-tab-stops' (*note Tab Stops::.). Features concerned with
+comments in programs are turned off unless they are explicitly invoked.
+The syntax table is changed so that periods are not considered part of a
+word, while apostrophes, backspaces and underlines are.
+
+ A similar variant mode is Indented Text mode, intended for editing
+text in which most lines are indented. This mode defines <TAB> to run
+`indent-relative' (*note Indentation::.), and makes Auto Fill indent
+the lines it creates. As a result, a line made by Auto Filling, or by
+<LFD>, is normally indented just like the previous line. Use `M-x
+indented-text-mode' to select this mode.
+
+ Entering Text mode or Indented Text mode calls the value of the
+variable `text-mode-hook' with no arguments, if that value exists and
+is not `nil'. This value is also called when modes related to Text
+mode are entered; this includes Nroff mode, TeX mode, Outline mode, and
+Mail mode. Your hook can look at the value of `major-mode' to see
+which of these modes is actually being entered.
+
+ Two modes similar to Text mode are of use for editing text that is to
+be passed through a text formatter before achieving its final readable
+form.
+
+* Menu:
+
+* Nroff Mode:: The major mode for editing input to the formatter nroff.
+* TeX Mode:: The major modes for editing input to the formatter TeX.
+
+
+ Another similar mode is used for editing outlines. It allows you
+to view the text at various levels of detail. You can view either
+the outline headings alone or both headings and text; you can also
+hide some of the headings at lower levels from view to make the high
+level structure more visible.
+
+
+* Outline Mode:: The major mode for editing outlines.
+
+\1f
+File: xemacs.info, Node: Nroff Mode, Next: TeX Mode, Prev: Text Mode, Up: Text Mode
+
+Nroff Mode
+----------
+
+ Nroff mode is a mode like Text mode but modified to handle nroff
+commands present in the text. Invoke `M-x nroff-mode' to enter this
+mode. Nroff mode differs from Text mode in only a few ways. All nroff
+command lines are considered paragraph separators, so that filling never
+garbles the nroff commands. Pages are separated by `.bp' commands.
+Comments start with backslash-doublequote. There are also three special
+commands that are not available in Text mode:
+
+`M-n'
+ Move to the beginning of the next line that isn't an nroff command
+ (`forward-text-line'). An argument is a repeat count.
+
+`M-p'
+ Like `M-n' but move up (`backward-text-line').
+
+`M-?'
+ Prints in the echo area the number of text lines (lines that are
+ not nroff commands) in the region (`count-text-lines').
+
+ The other feature of Nroff mode is Electric Nroff newline mode.
+This is a minor mode that you can turn on or off with `M-x
+electric-nroff-mode' (*note Minor Modes::.). When the mode is on and
+you use <RET> to end a line containing an nroff command that opens a
+kind of grouping, Emacs automatically inserts the matching nroff
+command to close that grouping on the following line. For example, if
+you are at the beginning of a line and type `.(b <RET>', the matching
+command `.)b' will be inserted on a new line following point.
+
+ Entering Nroff mode calls the value of the variable `text-mode-hook'
+with no arguments, if that value exists and is not `nil'; then it does
+the same with the variable `nroff-mode-hook'.
+
+\1f
+File: xemacs.info, Node: TeX Mode, Next: Outline Mode, Prev: Nroff Mode, Up: Text Mode
+
+TeX Mode
+--------
+
+ TeX is a powerful text formatter written by Donald Knuth; like GNU
+Emacs, it is free. LaTeX is a simplified input format for TeX,
+implemented by TeX macros. It is part of TeX.
+
+ Emacs has a special TeX mode for editing TeX input files. It
+provides facilities for checking the balance of delimiters and for
+invoking TeX on all or part of the file.
+
+ TeX mode has two variants, Plain TeX mode and LaTeX mode, which are
+two distinct major modes that differ only slightly. These modes are
+designed for editing the two different input formats. The command `M-x
+tex-mode' looks at the contents of a buffer to determine whether it
+appears to be LaTeX input or not; it then selects the appropriate mode.
+If it can't tell which is right (e.g., the buffer is empty), the
+variable `tex-default-mode' controls which mode is used.
+
+ The commands `M-x plain-tex-mode' and `M-x latex-mode' explicitly
+select one of the variants of TeX mode. Use these commands when `M-x
+tex-mode' does not guess right.
+
+* Menu:
+
+* Editing: TeX Editing. Special commands for editing in TeX mode.
+* Printing: TeX Print. Commands for printing part of a file with TeX.
+
+ TeX for Unix systems can be obtained from the University of
+Washington for a distribution fee.
+
+ To order a full distribution, send $140.00 for a 1/2 inch 9-track
+tape, $165.00 for two 4-track 1/4 inch cartridge tapes (foreign sites
+$150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover the extra
+postage) payable to the University of Washington to:
+
+ The Director
+ Northwest Computer Support Group, DW-10
+ University of Washington
+ Seattle, Washington 98195
+
+Purchase orders are acceptable, but there is an extra charge of $10.00
+to pay for processing charges. (The total cost comes to $150 for
+domestic sites, $175 for foreign sites).
+
+ The normal distribution is a tar tape, blocked 20, 1600 bpi, on an
+industry standard 2400 foot half-inch reel. The physical format for
+the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track
+serpentine recording for the SUN. Also, SystemV tapes can be written
+in cpio format, blocked 5120 bytes, ASCII headers.
+
+\1f
+File: xemacs.info, Node: TeX Editing, Next: TeX Print, Prev: TeX Mode, Up: TeX Mode
+
+TeX Editing Commands
+....................
+
+ Here are the special commands provided in TeX mode for editing the
+text of the file.
+
+`"'
+ Insert, according to context, either ```' or `"' or `'''
+ (`TeX-insert-quote').
+
+`<LFD>'
+ Insert a paragraph break (two newlines) and check the previous
+ paragraph for unbalanced braces or dollar signs (`tex-terminate-
+ paragraph').
+
+`M-x validate-tex-buffer'
+ Check each paragraph in the buffer for unbalanced braces or dollar
+ signs.
+
+`C-c {'
+ Insert `{}' and position point between them (`tex-insert-braces').
+
+`C-c }'
+ Move forward past the next unmatched close brace (`up-list').
+
+`C-c C-e'
+ Close a block for LaTeX (`tex-close-latex-block').
+
+ In TeX, the character `"' is not normally used; you use ```' to
+start a quotation and `''' to end one. TeX mode defines the key `"' to
+insert ```' after whitespace or an open brace, `"' after a backslash,
+or `''' otherwise. This is done by the command `tex-insert-quote'. If
+you need the character `"' itself in unusual contexts, use `C-q' to
+insert it. Also, `"' with a numeric argument always inserts that
+number of `"' characters.
+
+ In TeX mode, `$' has a special syntax code which attempts to
+understand the way TeX math mode delimiters match. When you insert a
+`$' that is meant to exit math mode, the position of the matching `$'
+that entered math mode is displayed for a second. This is the same
+feature that displays the open brace that matches a close brace that is
+inserted. However, there is no way to tell whether a `$' enters math
+mode or leaves it; so when you insert a `$' that enters math mode, the
+previous `$' position is shown as if it were a match, even though they
+are actually unrelated.
+
+ If you prefer to keep braces balanced at all times, you can use `C-c
+{' (`tex-insert-braces') to insert a pair of braces. It leaves point
+between the two braces so you can insert the text that belongs inside.
+Afterward, use the command `C-c }' (`up-list') to move forward past the
+close brace.
+
+ There are two commands for checking the matching of braces. <LFD>
+(`tex-terminate-paragraph') checks the paragraph before point, and
+inserts two newlines to start a new paragraph. It prints a message in
+the echo area if any mismatch is found. `M-x validate-tex-buffer'
+checks the entire buffer, paragraph by paragraph. When it finds a
+paragraph that contains a mismatch, it displays point at the beginning
+of the paragraph for a few seconds and pushes a mark at that spot.
+Scanning continues until the whole buffer has been checked or until you
+type another key. The positions of the last several paragraphs with
+mismatches can be found in the mark ring (*note Mark Ring::.).
+
+ Note that square brackets and parentheses, not just braces, are
+matched in TeX mode. This is wrong if you want to check TeX syntax.
+However, parentheses and square brackets are likely to be used in text
+as matching delimiters and it is useful for the various motion commands
+and automatic match display to work with them.
+
+ In LaTeX input, `\begin' and `\end' commands must balance. After
+you insert a `\begin', use `C-c C-f' (`tex-close-latex-block') to
+insert automatically a matching `\end' (on a new line following the
+`\begin'). A blank line is inserted between the two, and point is left
+there.
+
+\1f
+File: xemacs.info, Node: TeX Print, Prev: TeX Editing, Up: TeX Mode
+
+TeX Printing Commands
+.....................
+
+ You can invoke TeX as an inferior of Emacs on either the entire
+contents of the buffer or just a region at a time. Running TeX in this
+way on just one chapter is a good way to see what your changes look
+like without taking the time to format the entire file.
+
+`C-c C-r'
+ Invoke TeX on the current region, plus the buffer's header
+ (`tex-region').
+
+`C-c C-b'
+ Invoke TeX on the entire current buffer (`tex-buffer').
+
+`C-c C-l'
+ Recenter the window showing output from the inferior TeX so that
+ the last line can be seen (`tex-recenter-output-buffer').
+
+`C-c C-k'
+ Kill the inferior TeX (`tex-kill-job').
+
+`C-c C-p'
+ Print the output from the last `C-c C-r' or `C-c C-b' command
+ (`tex-print').
+
+`C-c C-q'
+ Show the printer queue (`tex-show-print-queue').
+
+ You can pass the current buffer through an inferior TeX using `C-c
+C-b' (`tex-buffer'). The formatted output appears in a file in `/tmp';
+to print it, type `C-c C-p' (`tex-print'). Afterward use `C-c C-q'
+(`tex-show-print-queue') to view the progress of your output towards
+being printed.
+
+ The console output from TeX, including any error messages, appears
+in a buffer called `*TeX-shell*'. If TeX gets an error, you can switch
+to this buffer and feed it input (this works as in Shell mode; *note
+Interactive Shell::.). Without switching to this buffer, you can scroll
+it so that its last line is visible by typing `C-c C-l'.
+
+ Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see
+that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also
+kills any TeX process still running.
+
+ You can pass an arbitrary region through an inferior TeX by typing
+`C-c C-r' (`tex-region'). This is tricky, however, because most files
+of TeX input contain commands at the beginning to set parameters and
+define macros. Without them, no later part of the file will format
+correctly. To solve this problem, `C-c C-r' allows you to designate a
+part of the file as containing essential commands; it is included
+before the specified region as part of the input to TeX. The
+designated part of the file is called the "header".
+
+ To indicate the bounds of the header in Plain TeX mode, insert two
+special strings in the file: `%**start of header' before the header,
+and `%**end of header' after it. Each string must appear entirely on
+one line, but there may be other text on the line before or after. The
+lines containing the two strings are included in the header. If
+`%**start of header' does not appear within the first 100 lines of the
+buffer, `C-c C-r' assumes there is no header.
+
+ In LaTeX mode, the header begins with `\documentstyle' and ends with
+`\begin{document}'. These are commands that LaTeX requires you to use,
+so you don't need to do anything special to identify the header.
+
+ When you enter either kind of TeX mode, Emacs calls with no
+arguments the value of the variable `text-mode-hook', if that value
+exists and is not `nil'. Emacs then calls the variable `TeX-mode-hook'
+and either `plain-TeX-mode-hook' or `LaTeX-mode-hook' under the same
+conditions.
+
+\1f
+File: xemacs.info, Node: Outline Mode, Prev: TeX Mode, Up: Text Mode
+
+Outline Mode
+------------
+
+ Outline mode is a major mode similar to Text mode but intended for
+editing outlines. It allows you to make parts of the text temporarily
+invisible so that you can see just the overall structure of the
+outline. Type `M-x outline-mode' to turn on Outline mode in the
+current buffer.
+
+ When you enter Outline mode, Emacs calls with no arguments the value
+of the variable `text-mode-hook', if that value exists and is not
+`nil'; then it does the same with the variable `outline-mode-hook'.
+
+ When a line is invisible in outline mode, it does not appear on the
+screen. The screen appears exactly as if the invisible line were
+deleted, except that an ellipsis (three periods in a row) appears at
+the end of the previous visible line (only one ellipsis no matter how
+many invisible lines follow).
+
+ All editing commands treat the text of the invisible line as part of
+the previous visible line. For example, `C-n' moves onto the next
+visible line. Killing an entire visible line, including its
+terminating newline, really kills all the following invisible lines as
+well; yanking everything back yanks the invisible lines and they remain
+invisible.
+
+* Menu:
+
+* Format: Outline Format. What the text of an outline looks like.
+* Motion: Outline Motion. Special commands for moving through outlines.
+* Visibility: Outline Visibility. Commands to control what is visible.
+
+\1f
+File: xemacs.info, Node: Outline Format, Next: Outline Motion, Prev: Outline Mode, Up: Outline Mode
+
+Format of Outlines
+..................
+
+ Outline mode assumes that the lines in the buffer are of two types:
+"heading lines" and "body lines". A heading line represents a topic in
+the outline. Heading lines start with one or more stars; the number of
+stars determines the depth of the heading in the outline structure.
+Thus, a heading line with one star is a major topic; all the heading
+lines with two stars between it and the next one-star heading are its
+subtopics; and so on. Any line that is not a heading line is a body
+line. Body lines belong to the preceding heading line. Here is an
+example:
+
+ * Food
+
+ This is the body,
+ which says something about the topic of food.
+
+ ** Delicious Food
+
+ This is the body of the second-level header.
+
+ ** Distasteful Food
+
+ This could have
+ a body too, with
+ several lines.
+
+ *** Dormitory Food
+
+ * Shelter
+
+ A second first-level topic with its header line.
+
+ A heading line together with all following body lines is called
+collectively an "entry". A heading line together with all following
+deeper heading lines and their body lines is called a "subtree".
+
+ You can customize the criterion for distinguishing heading lines by
+setting the variable `outline-regexp'. Any line whose beginning has a
+match for this regexp is considered a heading line. Matches that start
+within a line (not at the beginning) do not count. The length of the
+matching text determines the level of the heading; longer matches make
+a more deeply nested level. Thus, for example, if a text formatter has
+commands `@chapter', `@section' and `@subsection' to divide the
+document into chapters and sections, you can make those lines count as
+heading lines by setting `outline-regexp' to
+`"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words
+`chapter' and `section' are the same length, but by defining the regexp
+to match only `chap' we ensure that the length of the text matched on a
+chapter heading is shorter, so that Outline mode will know that
+sections are contained in chapters. This works as long as no other
+command starts with `@chap'.
+
+ Outline mode makes a line invisible by changing the newline before it
+into an ASCII Control-M (code 015). Most editing commands that work on
+lines treat an invisible line as part of the previous line because,
+strictly speaking, it is part of that line, since there is no longer a
+newline in between. When you save the file in Outline mode, Control-M
+characters are saved as newlines, so the invisible lines become ordinary
+lines in the file. Saving does not change the visibility status of a
+line inside Emacs.
+
+\1f
+File: xemacs.info, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode
+
+Outline Motion Commands
+.......................
+
+ Some special commands in Outline mode move backward and forward to
+heading lines.
+
+`C-c C-n'
+ Move point to the next visible heading line
+ (`outline-next-visible-heading').
+
+`C-c C-p'
+ Move point to the previous visible heading line
+ (`outline-previous-visible-heading').
+
+`C-c C-f'
+ Move point to the next visible heading line at the same level as
+ the one point is on (`outline-forward-same-level').
+
+`C-c C-b'
+ Move point to the previous visible heading line at the same level
+ (`outline-backward-same-level').
+
+`C-c C-u'
+ Move point up to a lower-level (more inclusive) visible heading
+ line (`outline-up-heading').
+
+ `C-c C-n' (`next-visible-heading') moves down to the next heading
+line. `C-c C-p' (`previous-visible-heading') moves similarly backward.
+Both accept numeric arguments as repeat counts. The names emphasize
+that invisible headings are skipped, but this is not really a special
+feature. All editing commands that look for lines ignore the invisible
+lines automatically.
+
+ More advanced motion commands understand the levels of headings.
+The commands `C-c C-f' (`outline-forward-same-level') and `C-c C-b'
+(`outline-backward-same-level') move from one heading line to another
+visible heading at the same depth in the outline. `C-c C-u'
+(`outline-up-heading') moves backward to another heading that is less
+deeply nested.
+
+\1f
+File: xemacs.info, Node: Outline Visibility, Prev: Outline Motion, Up: Outline Mode
+
+Outline Visibility Commands
+...........................
+
+ The other special commands of outline mode are used to make lines
+visible or invisible. Their names all start with `hide' or `show'.
+Most of them exist as pairs of opposites. They are not undoable;
+instead, you can undo right past them. Making lines visible or
+invisible is simply not recorded by the undo mechanism.
+
+`M-x hide-body'
+ Make all body lines in the buffer invisible.
+
+`M-x show-all'
+ Make all lines in the buffer visible.
+
+`C-c C-d'
+ Make everything under this heading invisible, not including this
+ heading itself (`hide-subtree').
+
+`C-c C-s'
+ Make everything under this heading visible, including body,
+ subheadings, and their bodies (`show-subtree').
+
+`M-x hide-leaves'
+ Make the body of this heading line, and of all its subheadings,
+ invisible.
+
+`M-x show-branches'
+ Make all subheadings of this heading line, at all levels, visible.
+
+`C-c C-i'
+ Make immediate subheadings (one level down) of this heading line
+ visible (`show-children').
+
+`M-x hide-entry'
+ Make this heading line's body invisible.
+
+`M-x show-entry'
+ Make this heading line's body visible.
+
+ Two commands that are exact opposites are `M-x hide-entry' and `M-x
+show-entry'. They are used with point on a heading line, and apply
+only to the body lines of that heading. The subtopics and their bodies
+are not affected.
+
+ Two more powerful opposites are `C-c C-h' (`hide-subtree') and `C-c
+C-s' (`show-subtree'). Both should be used when point is on a heading
+line, and both apply to all the lines of that heading's "subtree": its
+body, all its subheadings, both direct and indirect, and all of their
+bodies. In other words, the subtree contains everything following this
+heading line, up to and not including the next heading of the same or
+higher rank.
+
+ Intermediate between a visible subtree and an invisible one is having
+all the subheadings visible but none of the body. There are two
+commands for doing this, one that hides the bodies and one that makes
+the subheadings visible. They are `M-x hide-leaves' and `M-x
+show-branches'.
+
+ A little weaker than `show-branches' is `C-c C-i' (`show-children').
+It makes just the direct subheadings visible--those one level down.
+Deeper subheadings remain invisible.
+
+ Two commands have a blanket effect on the whole file. `M-x
+hide-body' makes all body lines invisible, so that you see just the
+outline structure. `M-x show-all' makes all lines visible. You can
+think of these commands as a pair of opposites even though `M-x
+show-all' applies to more than just body lines.
+
+ You can turn off the use of ellipses at the ends of visible lines by
+setting `selective-display-ellipses' to `nil'. The result is no
+visible indication of the presence of invisible lines.
+
+\1f
+File: xemacs.info, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
+
+Words
+=====
+
+ Emacs has commands for moving over or operating on words. By
+convention, the keys for them are all `Meta-' characters.
+
+`M-f'
+ Move forward over a word (`forward-word').
+
+`M-b'
+ Move backward over a word (`backward-word').
+
+`M-d'
+ Kill up to the end of a word (`kill-word').
+
+`M-<DEL>'
+ Kill back to the beginning of a word (`backward-kill-word').
+
+`M-@'
+ Mark the end of the next word (`mark-word').
+
+`M-t'
+ Transpose two words; drag a word forward or backward across other
+ words (`transpose-words').
+
+ Notice how these keys form a series that parallels the
+character-based `C-f', `C-b', `C-d', `C-t' and <DEL>. `M-@' is related
+to `C-@', which is an alias for `C-<SPC>'.
+
+ The commands `Meta-f' (`forward-word') and `Meta-b'
+(`backward-word') move forward and backward over words. They are
+analogous to `Control-f' and `Control-b', which move over single
+characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
+move several words if given an argument. `Meta-f' with a negative
+argument moves backward, and `Meta-b' with a negative argument moves
+forward. Forward motion stops after the last letter of the word, while
+backward motion stops before the first letter.
+
+ `Meta-d' (`kill-word') kills the word after point. To be precise,
+it kills everything from point to the place `Meta-f' would move to.
+Thus, if point is in the middle of a word, `Meta-d' kills just the part
+after point. If some punctuation comes between point and the next
+word, it is killed along with the word. (To kill only the next word
+but not the punctuation before it, simply type `Meta-f' to get to the
+end and kill the word backwards with `Meta-<DEL>'.) `Meta-d' takes
+arguments just like `Meta-f'.
+
+ `Meta-<DEL>' (`backward-kill-word') kills the word before point. It
+kills everything from point back to where `Meta-b' would move to. If
+point is after the space in `FOO, BAR', then `FOO, ' is killed. To
+kill just `FOO', type `Meta-b Meta-d' instead of `Meta-<DEL>'.
+
+ `Meta-t' (`transpose-words') exchanges the word before or containing
+point with the following word. The delimiter characters between the
+words do not move. For example, transposing `FOO, BAR' results in
+`BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on
+transposition and on arguments to transposition commands.
+
+ To operate on the next N words with an operation which applies
+between point and mark, you can either set the mark at point and then
+move over the words, or you can use the command `Meta-@' (`mark-word')
+which does not move point but sets the mark where `Meta-f' would move
+to. It can be given arguments just like `Meta-f'.
+
+ The word commands' understanding of syntax is completely controlled
+by the syntax table. For example, any character can be declared to be
+a word delimiter. *Note Syntax::.
+
+\1f
+File: xemacs.info, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
+
+Sentences
+=========
+
+ The Emacs commands for manipulating sentences and paragraphs are
+mostly on `Meta-' keys, and therefore are like the word-handling
+commands.
+
+`M-a'
+ Move back to the beginning of the sentence (`backward-sentence').
+
+`M-e'
+ Move forward to the end of the sentence (`forward-sentence').
+
+`M-k'
+ Kill forward to the end of the sentence (`kill-sentence').
+
+`C-x <DEL>'
+ Kill back to the beginning of the sentence
+ (`backward-kill-sentence').
+
+ The commands `Meta-a' and `Meta-e' (`backward-sentence' and
+`forward-sentence') move to the beginning and end of the current
+sentence, respectively. They resemble `Control-a' and `Control-e',
+which move to the beginning and end of a line. Unlike their
+counterparts, `Meta-a' and `Meta-e' move over successive sentences if
+repeated or given numeric arguments. Emacs assumes the typist's
+convention is followed, and thus considers a sentence to end wherever
+there is a `.', `?', or `!' followed by the end of a line or two
+spaces, with any number of `)', `]', `'', or `"' characters allowed in
+between. A sentence also begins or ends wherever a paragraph begins or
+ends.
+
+ Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
+sentence edge at which it is stopping.
+
+ `M-a' and `M-e' have a corresponding kill command, just like `C-a'
+and `C-e' have `C-k'. The command is `M-k' (`kill-sentence') which
+kills from point to the end of the sentence. With minus one as an
+argument it kills back to the beginning of the sentence. Larger
+arguments serve as repeat counts.
+
+ There is a special command, `C-x <DEL>' (`backward-kill-sentence'),
+for killing back to the beginning of a sentence, which is useful when
+you change your mind in the middle of composing text.
+
+ The variable `sentence-end' controls recognition of the end of a
+sentence. It is a regexp that matches the last few characters of a
+sentence, together with the whitespace following the sentence. Its
+normal value is:
+
+ "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
+
+This example is explained in the section on regexps. *Note Regexps::.
+
+\1f
+File: xemacs.info, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
+
+Paragraphs
+==========
+
+ The Emacs commands for manipulating paragraphs are also `Meta-' keys.
+
+`M-['
+ Move back to previous paragraph beginning
+ (`backward-paragraph').
+
+`M-]'
+ Move forward to next paragraph end (`forward-paragraph').
+
+`M-h'
+ Put point and mark around this or next paragraph
+ (`mark-paragraph').
+
+ `Meta-[' moves to the beginning of the current or previous paragraph,
+while `Meta-]' moves to the end of the current or next paragraph.
+Blank lines and text formatter command lines separate paragraphs and are
+not part of any paragraph. An indented line starts a new paragraph.
+
+ In major modes for programs (as opposed to Text mode), paragraphs
+begin and end only at blank lines. As a result, the paragraph commands
+continue to be useful even though there are no paragraphs per se.
+
+ When there is a fill prefix, paragraphs are delimited by all lines
+which don't start with the fill prefix. *Note Filling::.
+
+ To operate on a paragraph, you can use the command `Meta-h'
+(`mark-paragraph') to set the region around it. This command puts
+point at the beginning and mark at the end of the paragraph point was
+in. If point is between paragraphs (in a run of blank lines or at a
+boundary), the paragraph following point is surrounded by point and
+mark. If there are blank lines preceding the first line of the
+paragraph, one of the blank lines is included in the region. Thus, for
+example, `M-h C-w' kills the paragraph around or after point.
+
+ The precise definition of a paragraph boundary is controlled by the
+variables `paragraph-separate' and `paragraph-start'. The value of
+`paragraph-start' is a regexp that matches any line that either starts
+or separates paragraphs. The value of `paragraph-separate' is another
+regexp that matches only lines that separate paragraphs without being
+part of any paragraph. Lines that start a new paragraph and are
+contained in it must match both regexps. For example, normally
+`paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is `"^[
+\t\f]*$"'.
+
+ Normally it is desirable for page boundaries to separate paragraphs.
+The default values of these variables recognize the usual separator for
+pages.
+
--- /dev/null
+/* Checkbox Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Checkbox.c 1.1 */
+
+/*
+ * Checkbox.c - Checkbox button widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: June 30, 1997
+ *
+ * Overview: This widget is identical to the Radio widget in behavior,
+ * except that the button is square and has a check mark.
+ */
+
+
+#include <config.h>
+#include <stdio.h>
+
+#include <X11/IntrinsicP.h>
+#include <X11/StringDefs.h>
+#include <X11/Xaw/XawInit.h>
+#include "../src/xmu.h"
+#include "xlwcheckboxP.h"
+
+
+/* by using the same size for the checkbox as for the diamond box,
+ * we can let the Radio widget do the vast majority of the work.
+ */
+
+#define BOX_SIZE 8
+#define DRAW_CHECK 0 /* don't draw the check mark */
+
+#define cclass(w) ((CheckboxWidgetClass)((w)->core.widget_class))
+
+#ifdef _ThreeDP_h
+#define swid(cw) ((cw)->threeD.shadow_width)
+#else
+#define swid(cw) ((cw)->core.border_width)
+#endif
+
+#define bsize(cw) (cclass(cw)->radio_class.dsize)
+#define bs(cw) (bsize(cw) + 2*swid(cw))
+
+
+#if DRAW_CHECK
+#define check_width 14
+#define check_height 14
+static u_char check_bits[] = {
+ 0x00, 0x00, 0x00, 0x20, 0x00, 0x18, 0x00, 0x0c, 0x00, 0x06, 0x00, 0x03,
+ 0x8c, 0x03, 0xde, 0x01, 0xff, 0x01, 0xfe, 0x00, 0xfc, 0x00, 0x78, 0x00,
+ 0x70, 0x00, 0x20, 0x00};
+#endif
+
+
+/****************************************************************
+ *
+ * Full class record constant
+ *
+ ****************************************************************/
+
+
+#if DRAW_CHECK
+static char defaultTranslations[] =
+ "<EnterWindow>: highlight()\n\
+ <LeaveWindow>: unpress(draw) unhighlight()\n\
+ <Btn1Down>: press()\n\
+ <Btn1Down>,<Btn1Up>: unpress(nodraw) toggle() notify()";
+#endif
+
+
+
+#define offset(field) XtOffsetOf(CheckboxRec, field)
+static XtResource resources[] = {
+ {XtNtristate, XtCTristate, XtRBoolean, sizeof(Boolean),
+ offset(checkbox.tristate), XtRImmediate, (XtPointer)FALSE},
+} ;
+#undef offset
+
+ /* Member functions */
+
+static void CheckboxClassInit (void);
+static void CheckboxInit (Widget, Widget, ArgList, Cardinal *);
+#if DRAW_CHECK
+static void CheckboxRealize (Widget, Mask *, XSetWindowAttributes *);
+#endif
+static void DrawCheck (Widget);
+
+
+ /* Action procs */
+#if DRAW_CHECK
+static void CheckboxPress (Widget, XEvent *, String *, Cardinal *);
+static void CheckboxUnpress (Widget, XEvent *, String *, Cardinal *);
+#endif
+
+ /* internal privates */
+
+#if DRAW_CHECK
+static XtActionsRec actionsList[] =
+{
+ {"press", CheckboxPress},
+ {"unpress", CheckboxUnpress},
+} ;
+#endif
+
+#define SuperClass ((RadioWidgetClass)&radioClassRec)
+
+CheckboxClassRec checkboxClassRec = {
+ {
+ (WidgetClass) SuperClass, /* superclass */
+ "Checkbox", /* class_name */
+ sizeof(CheckboxRec), /* size */
+ CheckboxClassInit, /* class_initialize */
+ NULL, /* class_part_initialize */
+ FALSE, /* class_inited */
+ CheckboxInit, /* initialize */
+ NULL, /* initialize_hook */
+#if DRAW_CHECK
+ CheckboxRealize, /* realize */
+ actionsList, /* actions */
+ XtNumber(actionsList), /* num_actions */
+#else
+ XtInheritRealize, /* realize */
+ NULL, /* actions */
+ 0, /* num_actions */
+#endif
+ resources, /* resources */
+ XtNumber(resources), /* resource_count */
+ NULLQUARK, /* xrm_class */
+ TRUE, /* compress_motion */
+ TRUE, /* compress_exposure */
+ TRUE, /* compress_enterleave */
+ FALSE, /* visible_interest */
+ NULL, /* destroy */
+ XtInheritResize, /* resize */
+ XtInheritExpose, /* expose */
+ NULL, /* set_values */
+ NULL, /* set_values_hook */
+ XtInheritSetValuesAlmost, /* set_values_almost */
+ NULL, /* get_values_hook */
+ NULL, /* accept_focus */
+ XtVersion, /* version */
+ NULL, /* callback_private */
+#if DRAW_CHECK
+ defaultTranslations, /* tm_table */
+#else
+ XtInheritTranslations, /* tm_table */
+#endif
+ XtInheritQueryGeometry, /* query_geometry */
+ XtInheritDisplayAccelerator, /* display_accelerator */
+ NULL /* extension */
+ }, /* CoreClass fields initialization */
+ {
+ XtInheritChangeSensitive /* change_sensitive */
+ }, /* SimpleClass fields initialization */
+#ifdef _ThreeDP_h
+ {
+ XtInheritXaw3dShadowDraw /* field not used */
+ }, /* ThreeDClass fields initialization */
+#endif
+ {
+ 0 /* field not used */
+ }, /* LabelClass fields initialization */
+ {
+ 0 /* field not used */
+ }, /* CommandClass fields initialization */
+ {
+ RadioSet, /* Set Procedure. */
+ RadioUnset, /* Unset Procedure. */
+ NULL /* extension. */
+ }, /* ToggleClass fields initialization */
+ {
+ BOX_SIZE,
+ DrawCheck, /* draw procedure */
+ NULL /* extension. */
+ }, /* RadioClass fields initialization */
+ {
+ NULL /* extension. */
+ }, /* CheckboxClass fields initialization */
+};
+
+ /* for public consumption */
+WidgetClass checkboxWidgetClass = (WidgetClass) &checkboxClassRec;
+
+
+
+\f
+
+
+/****************************************************************
+ *
+ * Class Methods
+ *
+ ****************************************************************/
+
+static void
+CheckboxClassInit (void)
+{
+ XawInitializeWidgetSet();
+}
+
+
+/*ARGSUSED*/
+static void
+CheckboxInit (Widget request,
+ Widget new,
+ ArgList args,
+ Cardinal *num_args)
+{
+#if DRAW_CHECK
+ CheckboxWidget cw = (CheckboxWidget) new;
+ cw->checkbox.checkmark = None ;
+ cw->checkbox.checkmark_GC = None ;
+#endif
+}
+
+
+#if DRAW_CHECK
+static void
+CheckboxRealize(Widget w,
+ Mask *valueMask,
+ XSetWindowAttributes *attributes)
+{
+ CheckboxWidget cw = (CheckboxWidget) w;
+ XtGCMask value_mask, dynamic_mask, dontcare_mask ;
+ XGCValues values ;
+
+ /* first, call superclass realize */
+ (*checkboxWidgetClass->core_class.superclass->core_class.realize)
+ (w, valueMask, attributes);
+
+ /* TODO: cache this via xmu */
+ if( cw->checkbox.checkmark == None )
+ cw->checkbox.checkmark =
+ XCreateBitmapFromData( XtDisplay(w), XtWindow(w),
+ check_bits,check_width,check_height);
+
+ values.fill_style = FillStippled ;
+ values.stipple = cw->checkbox.checkmark ;
+ values.foreground = cw->label.foreground ;
+ value_mask = GCFillStyle | GCStipple | GCForeground ;
+ dynamic_mask = GCTileStipXOrigin | GCTileStipYOrigin ;
+ dontcare_mask = GCLineWidth | GCLineStyle | GCCapStyle | GCJoinStyle |
+ GCFont | GCSubwindowMode | GCGraphicsExposures |
+ GCDashOffset | GCDashList | GCArcMode ;
+ cw->checkbox.checkmark_GC =
+ XtAllocateGC(w, 0, value_mask, &values, dynamic_mask, dontcare_mask) ;
+}
+#endif
+
+
+/* Function Name: CheckboxDestroy
+ * Description: Destroy Callback for checkbox widget.
+ * Arguments: w - the checkbox widget that is being destroyed.
+ * junk, grabage - not used.
+ * Returns: none.
+ */
+
+/* ARGSUSED */
+static void
+CheckboxDestroy (Widget w,
+ XtPointer junk,
+ XtPointer garbage)
+{
+#if DRAW_CHECK
+ CheckboxWidget cw = (CheckboxWidget) w;
+
+ /* TODO: cache this via xmu */
+ if( cw->checkbox.checkmark != None )
+ XFreePixmap( XtDisplay(w), cw->checkbox.checkmark ) ;
+ if( cw->checkbox.checkmark_GC != None )
+ XtReleaseGC(w, cw->checkbox.checkmark_GC) ;
+#endif
+}
+
+\f
+
+#if DRAW_CHECK
+/************************************************************
+ *
+ * Actions Procedures
+ *
+ ************************************************************/
+
+/* ARGSUSED */
+static void
+CheckboxPress (Widget w,
+ XEvent *event,
+ String *params, /* unused */
+ Cardinal *num_params) /* unused */
+{
+ CheckboxWidget cw = (CheckboxWidget) w ;
+ if( !cw->checkbox.pressed ) {
+ cw->checkbox.pressed = TRUE ;
+ ((CheckboxWidgetClass)(w->core.widget_class))->radio_class.drawDiamond(w) ;
+ }
+}
+
+static void
+CheckboxUnpress (Widget w,
+ XEvent *event,
+ String *params, /* unused */
+ Cardinal *num_params) /* unused */
+{
+ CheckboxWidget cw = (CheckboxWidget) w ;
+ int i ;
+
+ if( cw->checkbox.pressed ) {
+ cw->checkbox.pressed = FALSE ;
+ if( *num_params > 0 && **params == 'd' )
+ ((CheckboxWidgetClass)(w->core.widget_class))->radio_class.drawDiamond(w);
+ }
+}
+#endif
+
+
+
+\f
+
+/************************************************************
+ *
+ * Internal Procedures
+ *
+ ************************************************************/
+
+static void
+DrawCheck (Widget w)
+{
+ CheckboxWidget cw = (CheckboxWidget) w ;
+ Display *dpy = XtDisplay(w) ;
+ Window win = XtWindow(w) ;
+ GC gc ;
+
+#ifdef _ThreeDP_h
+ XPoint pts[6] ;
+#endif
+ Dimension s = swid(cw);
+ Dimension bsz = bsize(cw);
+ Position bx,by ; /* Check upper-left */
+ Dimension bw,bh ;
+#ifdef _ThreeDP_h
+ GC top, bot;
+#endif
+ GC ctr ;
+
+ /* foreground GC */
+ gc = XtIsSensitive(w) ? cw->command.normal_GC : cw->label.gray_GC ;
+
+ bw = bh = bs(cw) ;
+ bx = cw->label.internal_width ;
+ by = cw->core.height/2 - bh/2 ;
+
+#ifdef _ThreeDP_h
+ if( !cw->command.set ) {
+ top = cw->threeD.top_shadow_GC ;
+ bot = cw->threeD.bot_shadow_GC ;
+ } else {
+ top = cw->threeD.bot_shadow_GC ;
+ bot = cw->threeD.top_shadow_GC ;
+ }
+ ctr = cw->command.inverse_GC ;
+#else
+ ctr = cw->command.set ? cw->command.normal_GC : cw->command.inverse_GC ;
+#endif
+
+ XFillRectangle(dpy,win,ctr, bx+s,by+s, bsz,bsz) ;
+
+#ifdef _ThreeDP_h
+ /* top-left shadow */
+ pts[0].x = bx ; pts[0].y = by ;
+ pts[1].x = bw ; pts[1].y = 0 ;
+ pts[2].x = -s ; pts[2].y = s ;
+ pts[3].x = -bsz ; pts[3].y = 0 ;
+ pts[4].x = 0 ; pts[4].y = bsz ;
+ pts[5].x = -s ; pts[5].y = s ;
+ XFillPolygon(dpy,win,top, pts,6, Nonconvex,CoordModePrevious) ;
+ /* bottom-right shadow */
+ pts[0].x = bx+bw ; pts[0].y = by+bh ;
+ pts[1].x = -bw ; pts[1].y = 0 ;
+ pts[2].x = s ; pts[2].y = -s ;
+ pts[3].x = bsz ; pts[3].y = 0 ;
+ pts[4].x = 0 ; pts[4].y = -bsz ;
+ pts[5].x = s ; pts[5].y = -s ;
+ XFillPolygon(dpy,win,bot, pts,6, Nonconvex,CoordModePrevious) ;
+#else
+ XDrawRectangle(dpy,win,gc, bx+s,by+s, bsz,bsz) ;
+#endif
+
+#if DRAW_CHECK
+ if( cw->command.set && cw->checkbox.checkmark_GC != None ) {
+ XSetTSOrigin(dpy,cw->checkbox.checkmark_GC, bx+s, by+s) ;
+ XFillRectangle(dpy,win,cw->checkbox.checkmark_GC,
+ bx+s, by+s, check_width,check_height) ;
+ }
+#endif
+}
--- /dev/null
+/* Checkbox Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Checkbox.h 1.1 */
+
+/*
+ * Checkbox.h - Checkbox widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: June 30, 1997
+ */
+
+#ifndef _XawCheckbox_h
+#define _XawCheckbox_h
+
+/***********************************************************************
+ *
+ * Checkbox Widget
+ *
+ * The Checkbox widget is identical to the Radio widget in behavior but
+ * not in appearance. The Checkbox widget looks like a small diamond
+ * shaped button to the left of the label.
+ *
+ ***********************************************************************/
+
+#include "xlwradio.h"
+
+/* Resources:
+
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ tristate Tristate Boolean FALSE
+
+ radioGroup RadioGroup Widget NULL
+ radioData RadioData Pointer (XPointer) Widget
+ state State Boolean Off
+ background Background Pixel XtDefaultBackground
+ bitmap Pixmap Pixmap None
+ border BorderColor Pixel XtDefaultForeground
+ borderWidth BorderWidth Dimension 1
+ callback Callback Pointer NULL
+ cursor Cursor Cursor None
+ destroyCallback Callback Pointer NULL
+ font Font XFontStructx* XtDefaultFont
+ foreground Foreground Pixel XtDefaultForeground
+ height Height Dimension text height
+ highlightThickness Thickness Dimension 2
+ insensitiveBorder sensitive Pixmap Gray
+ internalHeight Height Dimension 2
+ internalWidth Width Dimension 4
+ justify Justify XtJustify XtJustifyCenter
+ label Label String NULL
+ mappedWhenManaged MappedWhenManaged Boolean True
+ resize Resize Boolean True
+ sensitive Sensitive Boolean True
+ width Width Dimension text width
+ x Position Position 0
+ y Position Position 0
+
+*/
+
+/*
+ * These should be in StringDefs.h but aren't so we will define
+ * them here if they are needed.
+ */
+
+
+#define XtCTristate "Tristate"
+
+#define XtNtristate "tristate"
+
+extern WidgetClass checkboxWidgetClass;
+
+typedef struct _CheckboxClassRec *CheckboxWidgetClass;
+typedef struct _CheckboxRec *CheckboxWidget;
+
+
+/************************************************************
+ *
+ * Public Functions
+ *
+ ************************************************************/
+
+#endif /* _XawCheckbox_h */
--- /dev/null
+/* Checkbox Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/*
+ * CheckboxP.h - Private definitions for Checkbox widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: June 30, 1997
+ */
+
+#ifndef _XawCheckboxP_h
+#define _XawCheckboxP_h
+
+#include "xlwcheckbox.h"
+#include "xlwradioP.h"
+
+/************************************
+ *
+ * Class structure
+ *
+ ***********************************/
+
+ /* New fields for the Checkbox widget class record */
+typedef struct _CheckboxClass {
+ XtPointer extension;
+} CheckboxClassPart;
+
+ /* Full class record declaration */
+typedef struct _CheckboxClassRec {
+ CoreClassPart core_class;
+ SimpleClassPart simple_class;
+#ifdef _ThreeDP_h
+ ThreeDClassPart threeD_class;
+#endif
+ LabelClassPart label_class;
+ CommandClassPart command_class;
+ ToggleClassPart toggle_class;
+ RadioClassPart radio_class;
+ CheckboxClassPart checkbox_class;
+} CheckboxClassRec;
+
+extern CheckboxClassRec checkboxClassRec;
+
+/***************************************
+ *
+ * Instance (widget) structure
+ *
+ **************************************/
+
+ /* New fields for the Checkbox widget record */
+typedef struct {
+ /* resources */
+ Boolean tristate ;
+
+ /* private data */
+ Boolean pressed ;
+ Pixmap checkmark ; /* TODO: share these via xmu? */
+ GC checkmark_GC ;
+ XtPointer extension;
+} CheckboxPart;
+
+ /* Full widget declaration */
+typedef struct _CheckboxRec {
+ CorePart core;
+ SimplePart simple;
+#ifdef _ThreeDP_h
+ ThreeDPart threeD;
+#endif
+ LabelPart label;
+ CommandPart command;
+ TogglePart toggle;
+ RadioPart radio;
+ CheckboxPart checkbox;
+} CheckboxRec;
+
+#endif /* _XawCheckboxP_h */
--- /dev/null
+/* Gauge Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Gauge.c 1.2 */
+
+/*
+ * Gauge.c - Gauge widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: July 9, 1997
+ *
+ * Note: for fun and demonstration purposes, I have added selection
+ * capabilities to this widget. If you select the widget, you create
+ * a primary selection containing the current value of the widget in
+ * both integer and string form. If you copy into the widget, the
+ * primary selection is converted to an integer value and the gauge is
+ * set to that value.
+ */
+
+/* TODO: display time instead of value
+ */
+
+#define DEF_LEN 50 /* default width (or height for vertical gauge) */
+#define MIN_LEN 10 /* minimum reasonable width (height) */
+#define TIC_LEN 6 /* length of tic marks */
+#define GA_WID 3 /* width of gauge */
+#define MS_PER_SEC 1000
+
+#include <config.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <ctype.h>
+#include <X11/IntrinsicP.h>
+#include <X11/Xatom.h>
+#include <X11/StringDefs.h>
+#include <X11/Xaw/XawInit.h>
+#include "xlwgaugeP.h"
+#include "../src/xmu.h"
+#ifdef HAVE_XMU
+#include <X11/Xmu/Atoms.h>
+#include <X11/Xmu/Drawing.h>
+#include <X11/Xmu/StdSel.h>
+#endif
+
+
+/****************************************************************
+ *
+ * Gauge resources
+ *
+ ****************************************************************/
+
+
+static char defaultTranslations[] =
+ "<Btn1Up>: select()\n\
+ <Key>F1: select(CLIPBOARD)\n\
+ <Btn2Up>: paste()\n\
+ <Key>F2: paste(CLIPBOARD)" ;
+
+
+
+#define offset(field) XtOffsetOf(GaugeRec, field)
+static XtResource resources[] = {
+ {XtNvalue, XtCValue, XtRInt, sizeof(int),
+ offset(gauge.value), XtRImmediate, (XtPointer)0},
+ {XtNminValue, XtCMinValue, XtRInt, sizeof(int),
+ offset(gauge.v0), XtRImmediate, (XtPointer)0},
+ {XtNmaxValue, XtCMaxValue, XtRInt, sizeof(int),
+ offset(gauge.v1), XtRImmediate, (XtPointer)100},
+ {XtNntics, XtCNTics, XtRInt, sizeof(int),
+ offset(gauge.ntics), XtRImmediate, (XtPointer) 0},
+ {XtNnlabels, XtCNLabels, XtRInt, sizeof(int),
+ offset(gauge.nlabels), XtRImmediate, (XtPointer) 0},
+ {XtNlabels, XtCLabels, XtRStringArray, sizeof(String *),
+ offset(gauge.labels), XtRStringArray, NULL},
+ {XtNautoScaleUp, XtCAutoScaleUp, XtRBoolean, sizeof(Boolean),
+ offset(gauge.autoScaleUp), XtRImmediate, FALSE},
+ {XtNautoScaleDown, XtCAutoScaleDown, XtRBoolean, sizeof(Boolean),
+ offset(gauge.autoScaleDown), XtRImmediate, FALSE},
+ {XtNorientation, XtCOrientation, XtROrientation, sizeof(XtOrientation),
+ offset(gauge.orientation), XtRImmediate, (XtPointer)XtorientHorizontal},
+ {XtNupdate, XtCInterval, XtRInt, sizeof(int),
+ offset(gauge.update), XtRImmediate, (XtPointer)0},
+ {XtNgetValue, XtCCallback, XtRCallback, sizeof(XtPointer),
+ offset(gauge.getValue), XtRImmediate, (XtPointer)NULL},
+};
+#undef offset
+
+
+
+ /* member functions */
+
+static void GaugeClassInit (void);
+static void GaugeInit (Widget, Widget, ArgList, Cardinal *);
+static void GaugeDestroy (Widget);
+static void GaugeResize (Widget);
+static void GaugeExpose (Widget, XEvent *, Region);
+static Boolean GaugeSetValues (Widget, Widget, Widget, ArgList, Cardinal *);
+static XtGeometryResult GaugeQueryGeometry (Widget, XtWidgetGeometry *,
+ XtWidgetGeometry *);
+
+ /* action procs */
+
+static void GaugeSelect (Widget, XEvent *, String *, Cardinal *);
+static void GaugePaste (Widget, XEvent *, String *, Cardinal *);
+
+ /* internal privates */
+
+static void GaugeSize (GaugeWidget, Dimension *, Dimension *, Dimension);
+static void MaxLabel (GaugeWidget, Dimension *, Dimension *,
+ Dimension *, Dimension *);
+static void AutoScale (GaugeWidget);
+static void EnableUpdate (GaugeWidget);
+static void DisableUpdate (GaugeWidget);
+
+static void GaugeGetValue (XtPointer, XtIntervalId *);
+static void GaugeMercury (Display *, Window, GC, GaugeWidget, Cardinal, Cardinal);
+
+static Boolean GaugeConvert (Widget, Atom *, Atom *, Atom *,
+ XtPointer *, u_long *, int *);
+static void GaugeLoseSel (Widget, Atom *);
+static void GaugeDoneSel (Widget, Atom *, Atom *);
+static void GaugeGetSelCB (Widget, XtPointer, Atom *, Atom *,
+ XtPointer, u_long *, int *);
+
+static GC Get_GC (GaugeWidget, Pixel);
+
+
+static XtActionsRec actionsList[] =
+{
+ {"select", GaugeSelect},
+ {"paste", GaugePaste},
+} ;
+
+
+
+/****************************************************************
+ *
+ * Full class record constant
+ *
+ ****************************************************************/
+
+GaugeClassRec gaugeClassRec = {
+ {
+/* core_class fields */
+ /* superclass */ (WidgetClass) &labelClassRec,
+ /* class_name */ "Gauge",
+ /* widget_size */ sizeof(GaugeRec),
+ /* class_initialize */ GaugeClassInit,
+ /* class_part_initialize */ NULL,
+ /* class_inited */ FALSE,
+ /* initialize */ GaugeInit,
+ /* initialize_hook */ NULL,
+ /* realize */ XtInheritRealize, /* TODO? */
+ /* actions */ actionsList,
+ /* num_actions */ XtNumber(actionsList),
+ /* resources */ resources,
+ /* num_resources */ XtNumber(resources),
+ /* xrm_class */ NULLQUARK,
+ /* compress_motion */ TRUE,
+ /* compress_exposure */ TRUE,
+ /* compress_enterleave */ TRUE,
+ /* visible_interest */ FALSE,
+ /* destroy */ GaugeDestroy,
+ /* resize */ GaugeResize,
+ /* expose */ GaugeExpose,
+ /* set_values */ GaugeSetValues,
+ /* set_values_hook */ NULL,
+ /* set_values_almost */ XtInheritSetValuesAlmost,
+ /* get_values_hook */ NULL,
+ /* accept_focus */ NULL,
+ /* version */ XtVersion,
+ /* callback_private */ NULL,
+ /* tm_table */ defaultTranslations,
+ /* query_geometry */ GaugeQueryGeometry,
+ /* display_accelerator */ XtInheritDisplayAccelerator,
+ /* extension */ NULL
+ },
+/* Simple class fields initialization */
+ {
+ /* change_sensitive */ XtInheritChangeSensitive
+ },
+#ifdef _ThreeDP_h
+/* ThreeD class fields initialization */
+ {
+ XtInheritXaw3dShadowDraw /* shadowdraw */
+ },
+#endif
+/* Label class fields initialization */
+ {
+ /* ignore */ 0
+ },
+/* Gauge class fields initialization */
+ {
+ /* extension */ NULL
+ },
+};
+
+WidgetClass gaugeWidgetClass = (WidgetClass)&gaugeClassRec;
+
+
+\f
+
+/****************************************************************
+ *
+ * Member Procedures
+ *
+ ****************************************************************/
+
+static void
+GaugeClassInit (void)
+{
+ XawInitializeWidgetSet();
+#ifdef HAVE_XMU
+ XtAddConverter(XtRString, XtROrientation, XmuCvtStringToOrientation,
+ NULL, 0) ;
+#endif
+}
+
+
+
+/* ARGSUSED */
+static void
+GaugeInit (Widget request,
+ Widget new,
+ ArgList args,
+ Cardinal *num_args)
+{
+ GaugeWidget gw = (GaugeWidget) new;
+
+ if( gw->gauge.v0 == 0 && gw->gauge.v1 == 0 ) {
+ gw->gauge.autoScaleUp = gw->gauge.autoScaleDown = TRUE ;
+ AutoScale(gw) ;
+ }
+
+ /* If size not explicitly set, set it to our preferred size now. */
+
+ if( request->core.width == 0 || request->core.height == 0 )
+ {
+ Dimension w,h ;
+ GaugeSize(gw, &w,&h, DEF_LEN) ;
+ if( request->core.width == 0 )
+ new->core.width = w ;
+ if( request->core.height == 0 )
+ new->core.height = h ;
+ gw->core.widget_class->core_class.resize(new) ;
+ }
+
+ gw->gauge.selected = None ;
+ gw->gauge.selstr = NULL ;
+
+ if( gw->gauge.update > 0 )
+ EnableUpdate(gw) ;
+
+ gw->gauge.inverse_GC = Get_GC(gw, gw->core.background_pixel) ;
+}
+
+static void
+GaugeDestroy (Widget w)
+{
+ GaugeWidget gw = (GaugeWidget)w;
+
+ if( gw->gauge.selstr != NULL )
+ XtFree(gw->gauge.selstr) ;
+
+ if( gw->gauge.selected != None )
+ XtDisownSelection(w, gw->gauge.selected, CurrentTime) ;
+
+ XtReleaseGC(w, gw->gauge.inverse_GC) ;
+
+ if( gw->gauge.update > 0 )
+ DisableUpdate(gw) ;
+}
+
+
+/* React to size change from manager. Label widget will compute some
+ * internal stuff, but we need to override.
+ */
+
+static void
+GaugeResize (Widget w)
+{
+ GaugeWidget gw = (GaugeWidget)w;
+ int size ; /* height (width) of gauge */
+ int vmargin ; /* vertical (horizontal) margin */
+ int hmargin ; /* horizontal (vertical) margin */
+
+ vmargin = gw->gauge.orientation == XtorientHorizontal ?
+ gw->label.internal_height : gw->label.internal_width ;
+ hmargin = gw->gauge.orientation == XtorientHorizontal ?
+ gw->label.internal_width : gw->label.internal_height ;
+
+ /* TODO: need to call parent resize proc? I don't think so since
+ * we're recomputing everything from scratch anyway.
+ */
+
+ /* find total height (width) of contents */
+
+ size = GA_WID+2 ; /* gauge itself + edges */
+
+ if( gw->gauge.ntics > 1 ) /* tic marks */
+ size += vmargin + TIC_LEN ;
+
+ if( gw->gauge.nlabels > 1 )
+ {
+ Dimension lwm, lw0, lw1 ; /* width of max, left, right labels */
+ Dimension lh ;
+
+ MaxLabel(gw,&lwm,&lh, &lw0,&lw1) ;
+
+ if( gw->gauge.orientation == XtorientHorizontal )
+ {
+ gw->gauge.margin0 = lw0 / 2 ;
+ gw->gauge.margin1 = lw1 / 2 ;
+ size += lh + vmargin ;
+ }
+ else
+ {
+ gw->gauge.margin0 =
+ gw->gauge.margin1 = lh / 2 ;
+ size += lwm + vmargin ;
+ }
+ }
+ else
+ gw->gauge.margin0 = gw->gauge.margin1 = 0 ;
+
+ gw->gauge.margin0 += hmargin ;
+ gw->gauge.margin1 += hmargin ;
+
+ /* Now distribute height (width) over components */
+
+ if( gw->gauge.orientation == XtorientHorizontal )
+ gw->gauge.gmargin = (gw->core.height-size)/2 ;
+ else
+ gw->gauge.gmargin = (gw->core.width-size)/2 ;
+
+ gw->gauge.tmargin = gw->gauge.gmargin + GA_WID+2 + vmargin ;
+ if( gw->gauge.ntics > 1 )
+ gw->gauge.lmargin = gw->gauge.tmargin + TIC_LEN + vmargin ;
+ else
+ gw->gauge.lmargin = gw->gauge.tmargin ;
+}
+
+/*
+ * Repaint the widget window
+ */
+
+/* ARGSUSED */
+static void
+GaugeExpose (Widget w,
+ XEvent *event,
+ Region region)
+{
+ GaugeWidget gw = (GaugeWidget) w;
+register Display *dpy = XtDisplay(w) ;
+register Window win = XtWindow(w) ;
+ GC gc; /* foreground, background */
+ GC gctop, gcbot ; /* dark, light shadows */
+
+ int len ; /* length (width or height) of widget */
+ int hgt ; /* height (width) of widget */
+ int e0,e1 ; /* ends of the gauge */
+ int x ;
+ int y ; /* vertical (horizontal) position */
+ int i ;
+ int v0 = gw->gauge.v0 ;
+ int v1 = gw->gauge.v1 ;
+ int value = gw->gauge.value ;
+
+ gc = XtIsSensitive(w) ? gw->label.normal_GC : gw->label.gray_GC ;
+
+
+#ifdef _ThreeDP_h
+ gctop = gw->threeD.bot_shadow_GC ;
+ gcbot = gw->threeD.top_shadow_GC ;
+#else
+ gctop = gcbot = gc ;
+#endif
+
+ if( gw->gauge.orientation == XtorientHorizontal ) {
+ len = gw->core.width ;
+ hgt = gw->core.height ;
+ } else {
+ len = gw->core.height ;
+ hgt = gw->core.width ;
+ }
+
+ /* if the gauge is selected, signify by drawing the background
+ * in a constrasting color.
+ */
+
+ if( gw->gauge.selected )
+ {
+ XFillRectangle(dpy,win, gc, 0,0, w->core.width,w->core.height) ;
+ gc = gw->gauge.inverse_GC ;
+ }
+
+ e0 = gw->gauge.margin0 ; /* left (top) end */
+ e1 = len - gw->gauge.margin1 -1 ; /* right (bottom) end */
+
+ /* Draw the Gauge itself */
+
+ y = gw->gauge.gmargin ;
+
+ if( gw->gauge.orientation == XtorientHorizontal ) /* horizontal */
+ {
+ XDrawLine(dpy,win,gctop, e0+1,y, e1-1,y) ;
+ XDrawLine(dpy,win,gctop, e0,y+1, e0,y+GA_WID) ;
+ XDrawLine(dpy,win,gcbot, e0+1, y+GA_WID+1, e1-1, y+GA_WID+1) ;
+ XDrawLine(dpy,win,gcbot, e1,y+1, e1,y+GA_WID) ;
+ }
+ else /* vertical */
+ {
+ XDrawLine(dpy,win,gctop, y,e0+1, y,e1-1) ;
+ XDrawLine(dpy,win,gctop, y+1,e0, y+GA_WID,e0) ;
+ XDrawLine(dpy,win,gcbot, y+GA_WID+1,e0+1, y+GA_WID+1, e1-1) ;
+ XDrawLine(dpy,win,gcbot, y+1,e1, y+GA_WID,e1) ;
+ }
+
+
+ /* draw the mercury */
+
+ GaugeMercury(dpy, win, gc, gw, 0,value) ;
+
+
+ if( gw->gauge.ntics > 1 )
+ {
+ y = gw->gauge.tmargin ;
+ for(i=0; i<gw->gauge.ntics; ++i)
+ {
+ x = e0 + i*(e1-e0-1)/(gw->gauge.ntics-1) ;
+ if( gw->gauge.orientation == XtorientHorizontal ) {
+ XDrawLine(dpy,win,gcbot, x,y+1, x,y+TIC_LEN-2) ;
+ XDrawLine(dpy,win,gcbot, x,y, x+1,y) ;
+ XDrawLine(dpy,win,gctop, x+1,y+1, x+1,y+TIC_LEN-2) ;
+ XDrawLine(dpy,win,gctop, x,y+TIC_LEN-1, x+1,y+TIC_LEN-1) ;
+ }
+ else {
+ XDrawLine(dpy,win,gcbot, y+1,x, y+TIC_LEN-2,x) ;
+ XDrawLine(dpy,win,gcbot, y,x, y,x+1) ;
+ XDrawLine(dpy,win,gctop, y+1,x+1, y+TIC_LEN-2,x+1) ;
+ XDrawLine(dpy,win,gctop, y+TIC_LEN-1,x, y+TIC_LEN-1,x+1) ;
+ }
+ }
+ }
+
+ /* draw labels */
+ if( gw->gauge.nlabels > 1 )
+ {
+ char label[20], *s = label ;
+ int len, w,h =0 ;
+
+ if( gw->gauge.orientation == XtorientHorizontal )
+ y = gw->gauge.lmargin + gw->label.font->max_bounds.ascent - 1 ;
+ else {
+ y = gw->gauge.lmargin ;
+ h = gw->label.font->max_bounds.ascent / 2 ;
+ }
+
+ for(i=0; i<gw->gauge.nlabels; ++i)
+ {
+ if( gw->gauge.labels == NULL )
+ sprintf(label, "%d", v0+i*(v1 - v0)/(gw->gauge.nlabels - 1)) ;
+ else
+ s = gw->gauge.labels[i] ;
+ if( s != NULL ) {
+ x = e0 + i*(e1-e0-1)/(gw->gauge.nlabels-1) ;
+ len = strlen(s) ;
+ if( gw->gauge.orientation == XtorientHorizontal ) {
+ w = XTextWidth(gw->label.font, s, len) ;
+ XDrawString(dpy,win,gc, x-w/2,y, s,len) ;
+ }
+ else {
+ XDrawString(dpy,win,gc, y,x+h, s,len) ;
+ }
+ }
+ }
+ }
+}
+
+
+/*
+ * Set specified arguments into widget
+ */
+
+static Boolean
+GaugeSetValues (Widget old,
+ Widget request,
+ Widget new,
+ ArgList args,
+ Cardinal *num_args)
+{
+ GaugeWidget oldgw = (GaugeWidget) old;
+ GaugeWidget gw = (GaugeWidget) new;
+ Boolean was_resized = False;
+
+ if( gw->gauge.selected != None ) {
+ XtDisownSelection(new, gw->gauge.selected, CurrentTime) ;
+ gw->gauge.selected = None ;
+ }
+
+ /* Changes to v0,v1,labels, ntics, nlabels require resize & redraw. */
+ /* Change to value requires redraw and possible resize if autoscale */
+
+ was_resized =
+ gw->gauge.v0 != oldgw->gauge.v0 ||
+ gw->gauge.v1 != oldgw->gauge.v1 ||
+ gw->gauge.ntics != oldgw->gauge.ntics ||
+ gw->gauge.nlabels != oldgw->gauge.nlabels ||
+ gw->gauge.labels != oldgw->gauge.labels ;
+
+ if( (gw->gauge.autoScaleUp && gw->gauge.value > gw->gauge.v1) ||
+ (gw->gauge.autoScaleDown && gw->gauge.value < gw->gauge.v1/3 ))
+ {
+ AutoScale(gw) ;
+ was_resized = TRUE ;
+ }
+
+ if( was_resized ) {
+ if( gw->label.resize )
+ GaugeSize(gw, &gw->core.width, &gw->core.height, DEF_LEN) ;
+ else
+ GaugeResize(new) ;
+ }
+
+ if( gw->gauge.update != oldgw->gauge.update )
+ {
+ if( gw->gauge.update > 0 )
+ EnableUpdate(gw) ;
+ else
+ DisableUpdate(gw) ;
+ }
+
+ if( gw->core.background_pixel != oldgw->core.background_pixel )
+ {
+ XtReleaseGC(new, gw->gauge.inverse_GC) ;
+ gw->gauge.inverse_GC = Get_GC(gw, gw->core.background_pixel) ;
+ }
+
+ return was_resized || gw->gauge.value != oldgw->gauge.value ||
+ XtIsSensitive(old) != XtIsSensitive(new);
+}
+
+
+static XtGeometryResult
+GaugeQueryGeometry (Widget w,
+ XtWidgetGeometry *intended,
+ XtWidgetGeometry *preferred)
+{
+ register GaugeWidget gw = (GaugeWidget)w;
+
+ if( intended->width == w->core.width &&
+ intended->height == w->core.height )
+ return XtGeometryNo ;
+
+ preferred->request_mode = CWWidth | CWHeight;
+ GaugeSize(gw, &preferred->width, &preferred->height, DEF_LEN) ;
+
+ if( (!(intended->request_mode & CWWidth) ||
+ intended->width >= preferred->width) &&
+ (!(intended->request_mode & CWHeight) ||
+ intended->height >= preferred->height) )
+ return XtGeometryYes;
+ else
+ return XtGeometryAlmost;
+}
+
+
+\f
+
+/****************************************************************
+ *
+ * Action Procedures
+ *
+ ****************************************************************/
+
+static void
+GaugeSelect (Widget w,
+ XEvent *event,
+ String *params,
+ Cardinal *num_params)
+{
+ GaugeWidget gw = (GaugeWidget)w ;
+ Atom seln = XA_PRIMARY ;
+
+ if( gw->gauge.selected != None ) {
+ XtDisownSelection(w, gw->gauge.selected, CurrentTime) ;
+ gw->gauge.selected = None ;
+ }
+
+ if( *num_params > 0 ) {
+ seln = XInternAtom(XtDisplay(w), params[0], False) ;
+ printf("atom %s is %ld\n", params[0], seln) ;
+ }
+
+ if( ! XtOwnSelection(w, seln, event->xbutton.time, GaugeConvert,
+ GaugeLoseSel, GaugeDoneSel) )
+ {
+ /* in real code, this error message would be replaced by
+ * something more elegant, or at least deleted
+ */
+
+ fprintf(stderr, "Gauge failed to get selection, try again\n") ;
+ }
+ else
+ {
+ gw->gauge.selected = TRUE ;
+ gw->gauge.selstr = (String)XtMalloc(4*sizeof(int)) ;
+ sprintf(gw->gauge.selstr, "%d", gw->gauge.value) ;
+ GaugeExpose(w,0,0) ;
+ }
+}
+
+
+static Boolean
+GaugeConvert (Widget w,
+ Atom *selection, /* usually XA_PRIMARY */
+ Atom *target, /* requested target */
+ Atom *type, /* returned type */
+ XtPointer *value, /* returned value */
+ u_long *length, /* returned length */
+ int *format) /* returned format */
+{
+ GaugeWidget gw = (GaugeWidget)w ;
+ XSelectionRequestEvent *req ;
+
+ printf( "requesting selection %s:%s\n",
+ XGetAtomName(XtDisplay(w),*selection),
+ XGetAtomName(XtDisplay(w),*target));
+
+#ifdef HAVE_XMU
+ if( *target == XA_TARGETS(XtDisplay(w)) )
+ {
+ Atom *rval, *stdTargets ;
+ u_long stdLength ;
+
+ /* XmuConvertStandardSelection can handle this. This function
+ * will return a list of standard targets. We prepend TEXT,
+ * STRING and INTEGER to the list and return it.
+ */
+
+ req = XtGetSelectionRequest(w, *selection, NULL) ;
+ XmuConvertStandardSelection(w, req->time, selection, target,
+ type, (XPointer*)&stdTargets, &stdLength, format) ;
+
+ *type = XA_ATOM ; /* TODO: needed? */
+ *length = stdLength + 3 ;
+ rval = (Atom *) XtMalloc(sizeof(Atom)*(stdLength+3)) ;
+ *value = (XtPointer) rval ;
+ *rval++ = XA_INTEGER ;
+ *rval++ = XA_STRING ;
+ *rval++ = XA_TEXT(XtDisplay(w)) ;
+ bcopy((char *)stdTargets, (char *)rval, stdLength*sizeof(Atom)) ;
+ XtFree((char*) stdTargets) ;
+ *format = 8*sizeof(Atom) ; /* TODO: needed? */
+ return True ;
+ }
+
+ else
+#endif
+ if( *target == XA_INTEGER )
+ {
+ *type = XA_INTEGER ;
+ *length = 1 ;
+ *value = (XtPointer) &gw->gauge.value ;
+ *format = 8*sizeof(int) ;
+ return True ;
+ }
+
+ else if( *target == XA_STRING
+#ifdef HAVE_XMU
+ ||
+ *target == XA_TEXT(XtDisplay(w))
+#endif
+ )
+ {
+ *type = *target ;
+ *length = strlen(gw->gauge.selstr)*sizeof(char) ;
+ *value = (XtPointer) gw->gauge.selstr ;
+ *format = 8 ;
+ return True ;
+ }
+
+ else
+ {
+ /* anything else, we just give it to XmuConvertStandardSelection() */
+#ifdef HAVE_XMU
+ req = XtGetSelectionRequest(w, *selection, NULL) ;
+ if( XmuConvertStandardSelection(w, req->time, selection, target,
+ type, (XPointer *) value, length, format) )
+ return True ;
+ else
+#endif
+ {
+ printf(
+ "Gauge: requestor is requesting unsupported selection %s:%s\n",
+ XGetAtomName(XtDisplay(w),*selection),
+ XGetAtomName(XtDisplay(w),*target));
+ return False ;
+ }
+ }
+}
+
+
+
+static void
+GaugeLoseSel (Widget w,
+ Atom *selection) /* usually XA_PRIMARY */
+{
+ GaugeWidget gw = (GaugeWidget)w ;
+ Display *dpy = XtDisplay(w) ;
+ Window win = XtWindow(w) ;
+
+ if( gw->gauge.selstr != NULL ) {
+ XtFree(gw->gauge.selstr) ;
+ gw->gauge.selstr = NULL ;
+ }
+
+ gw->gauge.selected = False ;
+ XClearWindow(dpy,win) ;
+ GaugeExpose(w,0,0) ;
+}
+
+
+static void
+GaugeDoneSel (Widget w,
+ Atom *selection, /* usually XA_PRIMARY */
+ Atom *target) /* requested target */
+{
+ /* selection done, anything to do? */
+}
+
+
+static void
+GaugePaste (Widget w,
+ XEvent *event,
+ String *params,
+ Cardinal *num_params)
+{
+ Atom seln = XA_PRIMARY ;
+
+ if( *num_params > 0 ) {
+ seln = XInternAtom(XtDisplay(w), params[0], False) ;
+ printf("atom %s is %ld\n", params[0], seln) ;
+ }
+
+ /* try for integer value first */
+ XtGetSelectionValue(w, seln, XA_INTEGER,
+ GaugeGetSelCB, (XtPointer)XA_INTEGER,
+ event->xbutton.time) ;
+}
+
+static void
+GaugeGetSelCB (Widget w,
+ XtPointer client,
+ Atom *selection,
+ Atom *type,
+ XtPointer value,
+ u_long *length,
+ int *format)
+{
+ Display *dpy = XtDisplay(w) ;
+ Atom target = (Atom)client ;
+ int *iptr ;
+ char *cptr ;
+
+ if( *type == XA_INTEGER ) {
+ iptr = (int *)value ;
+ XawGaugeSetValue(w, *iptr) ;
+ }
+
+ else if( *type == XA_STRING
+#ifdef HAVE_XMU
+ ||
+ *type == XA_TEXT(dpy)
+#endif
+ )
+ {
+ cptr = (char *)value ;
+ XawGaugeSetValue(w, atoi(cptr)) ;
+ }
+
+ /* failed, try string */
+ else if( *type == None && target == XA_INTEGER )
+ XtGetSelectionValue(w, *selection, XA_STRING,
+ GaugeGetSelCB, (XtPointer)XA_STRING,
+ CurrentTime) ;
+}
+
+\f
+
+/****************************************************************
+ *
+ * Public Procedures
+ *
+ ****************************************************************/
+
+
+ /* Change gauge value. Only undraw or draw what needs to be
+ * changed.
+ */
+
+void
+XawGaugeSetValue (Widget w,
+ Cardinal value)
+{
+ GaugeWidget gw = (GaugeWidget)w ;
+ int oldvalue ;
+ GC gc ;
+
+ if( gw->gauge.selected != None ) {
+ XtDisownSelection(w, gw->gauge.selected, CurrentTime) ;
+ gw->gauge.selected = None ;
+ }
+
+ if( !XtIsRealized(w) ) {
+ gw->gauge.value = value ;
+ return ;
+ }
+
+ /* need to rescale? */
+ if(( gw->gauge.autoScaleUp && value > gw->gauge.v1) ||
+ (gw->gauge.autoScaleDown && value < gw->gauge.v1/3 ))
+ {
+ XtVaSetValues(w, XtNvalue, value, 0) ;
+ return ;
+ }
+
+ oldvalue = gw->gauge.value ;
+ gw->gauge.value = value ;
+
+ gc = XtIsSensitive(w) ? gw->label.normal_GC : gw->label.gray_GC ;
+ GaugeMercury(XtDisplay(w), XtWindow(w), gc, gw, oldvalue,value) ;
+}
+
+
+Cardinal
+XawGaugeGetValue (Widget w)
+{
+ GaugeWidget gw = (GaugeWidget)w ;
+ return gw->gauge.value ;
+}
+
+
+\f
+
+/****************************************************************
+ *
+ * Private Procedures
+ *
+ ****************************************************************/
+
+ /* draw the mercury over a specific region */
+
+static void
+GaugeMercury (Display *dpy,
+ Window win,
+ GC gc,
+ GaugeWidget gw,
+ Cardinal val0,
+ Cardinal val1)
+{
+ int v0 = gw->gauge.v0 ;
+ int v1 = gw->gauge.v1 ;
+ int vd = v1 - v0 ;
+ Dimension len ; /* length (width or height) of gauge */
+ Position e0, e1 ; /* gauge ends */
+ Position p0, p1 ; /* mercury ends */
+ int y ; /* vertical (horizontal) position */
+ Boolean undraw = FALSE ;
+
+ len = gw->gauge.orientation == XtorientHorizontal ?
+ gw->core.width : gw->core.height ;
+
+ e0 = gw->gauge.margin0 ; /* left (top) end */
+ e1 = len - gw->gauge.margin1 -1 ; /* right (bottom) end */
+
+ if( vd <= 0 ) vd = 1 ;
+
+ if( val0 < v0 ) val0 = v0 ;
+ else if( val0 > v1 ) val0 = v1 ;
+ if( val1 < v0 ) val1 = v0 ;
+ else if( val1 > v1 ) val1 = v1 ;
+
+ p0 = (val0-v0)*(e1-e0-1)/vd ;
+ p1 = (val1-v0)*(e1-e0-1)/vd ;
+
+ if( p1 == p0 )
+ return ;
+
+ y = gw->gauge.gmargin ;
+
+ if( p1 < p0 )
+ {
+ Position tmp = p0 ;
+ p0 = p1 ;
+ p1 = tmp ;
+ gc = gw->label.normal_GC ;
+ XSetForeground(dpy,gc, gw->core.background_pixel) ;
+ undraw = TRUE ;
+ }
+
+ if( gw->gauge.orientation == XtorientHorizontal )
+ XFillRectangle(dpy,win,gc, e0+p0+1,y+1, p1-p0,GA_WID) ;
+ else
+ XFillRectangle(dpy,win,gc, y+1,e1-p1, GA_WID,p1-p0) ;
+
+ if( undraw )
+ XSetForeground(dpy,gc, gw->label.foreground) ;
+}
+
+
+
+/* Search the labels, find the largest one. */
+/* TODO: handle vertical fonts? */
+
+static void
+MaxLabel (GaugeWidget gw,
+ Dimension *wid, /* max label width */
+ Dimension *hgt, /* max label height */
+ Dimension *w0, /* width of first label */
+ Dimension *w1) /* width of last label */
+{
+ char lstr[80], *lbl ;
+ int w ;
+ XFontStruct *font = gw->label.font ;
+ int i ;
+ int lw = 0;
+ int v0 = gw->gauge.v0 ;
+ int dv = gw->gauge.v1 - v0 ;
+ int n = gw->gauge.nlabels ;
+
+ if( n > 0 )
+ {
+ if( --n <= 0 ) {n = 1 ; v0 += dv/2 ;}
+
+ /* loop through all labels, figure out how much room they
+ * need.
+ */
+ w = 0 ;
+ for(i=0; i<gw->gauge.nlabels; ++i)
+ {
+ if( gw->gauge.labels == NULL ) /* numeric labels */
+ sprintf(lbl = lstr,"%d", v0 + i*dv/n) ;
+ else
+ lbl = gw->gauge.labels[i] ;
+
+ if( lbl != NULL ) {
+ lw = XTextWidth(font, lbl, strlen(lbl)) ;
+ w = Max( w, lw ) ;
+ }
+ else
+ lw = 0 ;
+
+ if( i == 0 && w0 != NULL ) *w0 = lw ;
+ }
+ if( w1 != NULL ) *w1 = lw ;
+
+ *wid = w ;
+ *hgt = font->max_bounds.ascent + font->max_bounds.descent ;
+ }
+ else
+ *wid = *hgt = 0 ;
+}
+
+
+/* Determine the preferred size for this widget. choose 100x100 for
+ * debugging.
+ */
+
+static void
+GaugeSize (GaugeWidget gw,
+ Dimension *wid,
+ Dimension *hgt,
+ Dimension min_len)
+{
+ int w,h ; /* width, height of gauge */
+ int vmargin ; /* vertical margin */
+ int hmargin ; /* horizontal margin */
+
+ hmargin = gw->label.internal_width ;
+ vmargin = gw->label.internal_height ;
+
+ /* find total height (width) of contents */
+
+
+ /* find minimum size for undecorated gauge */
+
+ if( gw->gauge.orientation == XtorientHorizontal )
+ {
+ w = min_len ;
+ h = GA_WID+2 ; /* gauge itself + edges */
+ }
+ else
+ {
+ w = GA_WID+2 ;
+ h = min_len ;
+ }
+
+ if( gw->gauge.ntics > 0 )
+ {
+ if( gw->gauge.orientation == XtorientHorizontal )
+ {
+ w = Max(w, gw->gauge.ntics*3) ;
+ h += vmargin + TIC_LEN ;
+ }
+ else
+ {
+ w += hmargin + TIC_LEN ;
+ h = Max(h, gw->gauge.ntics*3) ;
+ }
+ }
+
+
+ /* If labels are requested, this gets a little interesting.
+ * We want the end labels centered on the ends of the gauge and
+ * the centers of the labels evenly spaced. The labels at the ends
+ * will not be the same width, meaning that the gauge itself need
+ * not be centered in the widget.
+ *
+ * First, determine the spacing. This is the width of the widest
+ * label, plus the internal margin. Total length of the gauge is
+ * spacing * (nlabels-1). To this, we add half the width of the
+ * left-most label and half the width of the right-most label
+ * to get the entire desired width of the widget.
+ */
+ if( gw->gauge.nlabels > 0 )
+ {
+ Dimension lwm, lw0, lw1 ; /* width of max, left, right labels */
+ Dimension lh ;
+
+ MaxLabel(gw,&lwm,&lh, &lw0,&lw1) ;
+
+ if( gw->gauge.orientation == XtorientHorizontal )
+ {
+ lwm = (lwm+hmargin) * (gw->gauge.nlabels-1) + (lw0+lw1)/2 ;
+ w = Max(w, lwm) ;
+ h += lh + vmargin ;
+ }
+ else
+ {
+ lh = lh*gw->gauge.nlabels + (gw->gauge.nlabels - 1)*vmargin ;
+ h = Max(h, lh) ;
+ w += lwm + hmargin ;
+ }
+ }
+
+ w += hmargin*2 ;
+ h += vmargin*2 ;
+
+ *wid = w ;
+ *hgt = h ;
+}
+
+
+
+static void
+AutoScale (GaugeWidget gw)
+{
+ static int scales[3] = {1,2,5} ;
+ int sptr = 0, smult=1 ;
+
+ if( gw->gauge.autoScaleDown )
+ gw->gauge.v1 = 0 ;
+ while( gw->gauge.value > gw->gauge.v1 )
+ {
+ if( ++sptr > 2 ) {
+ sptr = 0 ;
+ smult *= 10 ;
+ }
+ gw->gauge.v1 = scales[sptr] * smult ;
+ }
+}
+
+static void
+EnableUpdate (GaugeWidget gw)
+{
+ gw->gauge.intervalId =
+ XtAppAddTimeOut(XtWidgetToApplicationContext((Widget)gw),
+ gw->gauge.update * MS_PER_SEC, GaugeGetValue,
+ (XtPointer)gw) ;
+}
+
+static void
+DisableUpdate (GaugeWidget gw)
+{
+ XtRemoveTimeOut(gw->gauge.intervalId) ;
+}
+
+static void
+GaugeGetValue (XtPointer clientData,
+ XtIntervalId *intervalId)
+{
+ GaugeWidget gw = (GaugeWidget)clientData ;
+ Cardinal value ;
+
+ if( gw->gauge.update > 0 )
+ EnableUpdate(gw) ;
+
+ if( gw->gauge.getValue != NULL )
+ {
+ XtCallCallbackList((Widget)gw, gw->gauge.getValue, (XtPointer)&value);
+ XawGaugeSetValue((Widget)gw, value) ;
+ }
+}
+
+
+static GC
+Get_GC (GaugeWidget gw,
+ Pixel fg)
+{
+ XGCValues values ;
+#define vmask GCForeground
+#define umask (GCBackground|GCSubwindowMode|GCGraphicsExposures|GCDashOffset\
+ |GCFont|GCDashList|GCArcMode)
+
+ values.foreground = fg ;
+
+ return XtAllocateGC((Widget)gw, 0, vmask, &values, 0L, umask) ;
+}
--- /dev/null
+/* Gauge Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Gauge.h 1.1 */
+
+/*
+ * Gauge.h - Gauge widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: July 8, 1997
+ */
+
+#ifndef _XawGauge_h
+#define _XawGauge_h
+
+/***********************************************************************
+ *
+ * Gauge Widget
+ *
+ * The Gauge widget looks something like a thermometer. Application
+ * defines the values at the ends of the range and the current value
+ * and Gauge draws accordingly. Gauge does not accept input.
+ *
+ ***********************************************************************/
+
+#include <X11/Xaw/Label.h>
+
+/* Resources:
+
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ value Value Cardinal 0
+ minValue MinValue Cardinal 0
+ maxValue MaxValue Cardinal 100
+ ntics NTics Cardinal 0 +
+ nlabels NLabels Cardinal 0 ++
+ labels Labels String * NULL +++
+ orientation Orientation XtOrientation horizontal
+ autoScaleUp AutoScaleUp Boolean FALSE ++++
+ autoScaleDown AutoScaleDown Boolean FALSE ++++
+ getValue Callback XtCallbackList NULL +++++
+ update Interval int 0 (seconds) = disabled
+
+ encoding Encoding unsigned char XawTextEncoding8bit
+ font Font XFontStruct* XtDefaultFont
+ foreground Foreground Pixel XtDefaultForeground
+ internalHeight Height Dimension 2
+ internalWidth Width Dimension 4
+ resize Resize Boolean True
+ background Background Pixel XtDefaultBackground
+ bitmap Pixmap Pixmap None
+ border BorderColor Pixel XtDefaultForeground
+ borderWidth BorderWidth Dimension 1
+ cursor Cursor Cursor None
+ cursorName Cursor String NULL
+ destroyCallback Callback XtCallbackList NULL
+ height Height Dimension varies
+ insensitiveBorder Insensitive Pixmap Gray
+ mappedWhenManaged MappedWhenManaged Boolean True
+ pointerColor Foreground Pixel XtDefaultForeground
+ pointerColorBackground Background Pixel XtDefaultBackground
+ sensitive Sensitive Boolean True
+ width Width Dimension text width
+ x Position Position 0
+ y Position Position 0
+
+ + Ntics sets the number of tic marks next to the gauge. If 0, no
+ tic marks will be drawn.
+ ++ Nlabels sets the number of labels next to the gauge.
+ +++ Labels is an array of nul-terminated strings to be used as labels.
+ If this field is NULL but nlabels is > 0, then numeric labels will be
+ provided. NOTE: the labels are not copied to any internal memory; they
+ must be stored in static memory provided by the appliction.
+ ++++ AutoScale allows the gauge to set its own value limits. Default is
+ False unless upper & lower limits are both 0.
+
+ +++++ The GetValue() callback proc is called with these arguments:
+ static void
+ myGetValue(gauge, client, rval)
+ Widget gauge ;
+ XtPointer client ;
+ XtPointer rval ;
+ {
+ *(Cardinal *)rval = value ;
+ }
+
+*/
+
+/*
+ * Resource names not provided in StringDefs.h
+ */
+
+#ifndef XtNvalue
+#define XtNvalue "value"
+#define XtCValue "Value"
+#endif
+
+#ifndef XtNorientation
+#define XtNorientation "orientation"
+#define XtCOrientation "Orientation"
+#endif
+
+#define XtNntics "ntics"
+#define XtCNTics "NTics"
+
+#ifndef XtNnlabels
+#define XtNnlabels "nlabels"
+#define XtCNLabels "NLabels"
+#endif
+#ifndef XtNlabels
+#define XtNlabels "labels"
+#define XtCLabels "Labels"
+#endif
+
+#ifndef XtNminValue
+#define XtNminValue "minValue"
+#define XtCMinValue "MinValue"
+#endif
+#ifndef XtNmaxValue
+#define XtNmaxValue "maxValue"
+#define XtCMaxValue "MaxValue"
+#endif
+
+#ifndef XtNautoScaleUp
+#define XtNautoScaleUp "autoScaleUp"
+#define XtCAutoScaleUp "AutoScaleUp"
+#define XtNautoScaleDown "autoScaleDown"
+#define XtCAutoScaleDown "AutoScaleDown"
+#endif
+
+#ifndef XtNupdate
+#define XtNupdate "update"
+#endif
+
+#ifndef XtNgetValue
+#define XtNgetValue "getValue"
+#endif
+
+
+/* Class record constants */
+
+extern WidgetClass gaugeWidgetClass;
+
+typedef struct _GaugeClassRec *GaugeWidgetClass;
+typedef struct _GaugeRec *GaugeWidget;
+
+
+_XFUNCPROTOBEGIN
+
+extern void XawGaugeSetValue(
+#if NeedFunctionPrototypes
+ Widget gauge,
+ Cardinal value
+#endif
+);
+
+extern Cardinal XawGaugeGetValue(
+#if NeedFunctionPrototypes
+ Widget gauge
+#endif
+);
+
+_XFUNCPROTOEND
+
+#endif /* _XawGauge_h */
--- /dev/null
+/* Gauge Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/*
+ * GaugeP.h - Gauge widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: July 9, 1997
+ */
+
+#ifndef _XawGaugeP_h
+#define _XawGaugeP_h
+
+/***********************************************************************
+ *
+ * Gauge Widget Private Data
+ *
+ * Gauge has little in common with the label widget, but can make use
+ * of some label resources, so is subclassed from label.
+ *
+ ***********************************************************************/
+
+#include "xlwgauge.h"
+#include <X11/Xaw/LabelP.h>
+
+/* New fields for the Gauge widget class record */
+
+typedef struct {XtPointer extension;} GaugeClassPart;
+
+/* Full class record declaration */
+typedef struct _GaugeClassRec {
+ CoreClassPart core_class;
+ SimpleClassPart simple_class;
+#ifdef _ThreeDP_h
+ ThreeDClassPart threeD_class;
+#endif
+ LabelClassPart label_class;
+ GaugeClassPart gauge_class;
+} GaugeClassRec;
+
+extern GaugeClassRec gaugeClassRec;
+
+/* New fields for the Gauge widget record */
+typedef struct {
+ /* resources */
+ int value, v0,v1 ;
+ int ntics, nlabels ;
+ String *labels ;
+ XtOrientation orientation ;
+ Boolean autoScaleUp ; /* scales automatically */
+ Boolean autoScaleDown ; /* scales automatically */
+ int update ; /* update interval */
+ XtCallbackList getValue ; /* proc to call to fetch a point */
+
+ /* private state */
+ Dimension gmargin ; /* edges <-> gauge */
+ Dimension tmargin ; /* top (left) edge <-> tic marks */
+ Dimension lmargin ; /* tic marks <-> labels */
+ Dimension margin0 ; /* left/bottom margin */
+ Dimension margin1 ; /* right/top margin */
+ XtIntervalId intervalId ;
+ Atom selected ;
+ String selstr ; /* selection string, if any */
+ GC inverse_GC ;
+} GaugePart;
+
+
+/****************************************************************
+ *
+ * Full instance record declaration
+ *
+ ****************************************************************/
+
+typedef struct _GaugeRec {
+ CorePart core;
+ SimplePart simple;
+#ifdef _ThreeDP_h
+ ThreeDPart threeD;
+#endif
+ LabelPart label;
+ GaugePart gauge;
+} GaugeRec;
+
+#endif /* _XawGaugeP_h */
--- /dev/null
+ /* Tabs Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+ This file is part of XEmacs.
+
+ XEmacs is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the
+ Free Software Foundation; either version 2, or (at your option) any
+ later version.
+
+ XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with XEmacs; see the file COPYING. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Gcs.c 1.7 */
+
+ /* #### This code is duplicated many times within lwlib and XEmacs. It
+ should be modularised. */
+
+/*
+ * Gcs.c - Utility functions to allocate GCs.
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: Sept 29, 1998
+ */
+
+/* Functions:
+ *
+ * GC AllocFgGC(w, fg, font)
+ * Return a GC with foreground set as specified.
+ * If font is None, then the returned GC is allocated with font specified
+ * as a "don't care" value.
+ *
+ * GC
+ * AllocBackgroundGC(w, font)
+ * Return a GC with the foreground set to the widget's background color.
+ *
+ * GC
+ * AllocGreyGC(w, fg, font, contrast, be_nice_to_cmap)
+ * Widget w ;
+ * Pixel fg ;
+ * Font font ;
+ * int contrast ;
+ * int be_nice_to_cmap ;
+ *
+ * Return a GC suitable for rendering a widget in its "inactive" color.
+ * Normally returns a GC with a color somewhere between the widget's
+ * background color and the specified foreground. If font is None, then
+ * the returned GC is allocated with font specified as "don't care".
+ * If be_nice_to_cmap is True, the returned GC is created using a 50%
+ * dither instead of a new color.
+ *
+ *
+ * GC
+ * AllocShadeGC(w, fg, bg, font, contrast, be_nice_to_cmap)
+ * Widget w ;
+ * Pixel fg, bg ;
+ * Font font ;
+ * int contrast ;
+ * int be_nice_to_cmap ;
+ *
+ * Return a GC suitable for rendering in a shade somewhere between
+ * bg and fg, as determined by contrast (0 = bg, 100 = fg)
+ * If font is None, then the returned GC is allocated with
+ * font specified as "don't care". If be_nice_to_cmap
+ * is True, the returned GC is created using a 50% dither
+ * instead of a new color.
+ *
+ *
+ * GC
+ * AllocTopShadowGC(w, contrast, be_nice_to_cmap)
+ * Return a GC suitable for rendering the "top shadow" decorations of
+ * a widget. Returns a GC with foreground computed from widget's
+ * background color and contrast. If be_nice_to_cmap is True, the
+ * returned GC will use a foreground color of white. If widget depth
+ * is 1, this function will use a foreground color of black.
+ *
+ * GC
+ * AllocBotShadowGC(w, contrast, be_nice_to_cmap)
+ * Return a GC suitable for rendering the "bottom shadow" decorations
+ * of a widget. Returns a GC with foreground computed from widget's
+ * background color and contrast. If be_nice_to_cmap is True, the
+ * returned GC will use a foreground color of black.
+ *
+ * GC
+ * AllocArmGC(w, contrast, be_nice_to_cmap)
+ * Return a GC suitable for rendering the "armed" decorations of a
+ * widget. This GC would typically be used to fill in the widget's
+ * background. Returns a GC with foreground computed from widget's
+ * background color and contrast. If be_nice_to_cmap is True, the
+ * returned GC will use a foreground color of black and a 50% dither.
+ *
+ *
+ * void
+ * Draw3dBox(w, x,y,wid,hgt,s, topgc, botgc)
+ * Utility function. Draws a raised shadow box with outside dimensions
+ * as specified by x,y,wid,hgt and shadow width specified by s.
+ * A lowered shadow box may be generated by swapping topgc and botgc.
+ *
+ */
+
+#include <config.h>
+#include <stdio.h>
+
+#include <X11/Xlib.h>
+#include <X11/IntrinsicP.h>
+#include <X11/StringDefs.h>
+#include "../src/xmu.h"
+#include "xlwgcs.h"
+
+ /* Color & GC allocation.
+ *
+ * Frame widgets use the following graphics contexts:
+ *
+ * Foreground tab label text drawn this way
+ * Insensitive Fg foreground color greyed out.
+ * Background frame background color
+ * Top shadow upper-left highlight around widget
+ * Bottom shadow lower-right highlight around widget
+ * Arm shadow button pressed and ready to be released
+ *
+ *
+ * GC's are defined as follows, depending on attributes and
+ * window depth:
+ *
+ * Monochrome:
+ * Foreground = foreground color attribute or BlackPixel()
+ * Grey = Foreground color + 50% dither
+ * Background = background color attribute or WhitePixel()
+ * top shadow = foreground
+ * bottom shadow = foreground
+ * arm shadow = (what?)
+ *
+ * Color, beNiceToColormap=true:
+ * Foreground = foreground color attribute or BlackPixel()
+ * Grey = Foreground color + 50% dither
+ * Background = background color attribute or WhitePixel()
+ * top shadow = white
+ * bottom shadow = black
+ * arm shadow = (what?)
+ *
+ * Color, beNiceToColormap=false:
+ * Foreground = foreground color attribute or BlackPixel()
+ * Grey = (foreground color + background color)/2
+ * Background = background color attribute or WhitePixel()
+ * top shadow = background * 1.2
+ * bottom shadow = background * .6
+ * arm shadow = background * .8
+ *
+ * Special cases:
+ * If background is white, ??
+ * if background is black, ??
+ *
+ *
+ * If the widget's background is solid white or solid black,
+ * this code just picks some numbers. (The choice is designed
+ * to be compatibile with ThreeD interface.)
+ */
+
+
+
+#if XtSpecificationRelease < 5
+
+static GC XtAllocateGC(Widget, int, u_long, XGCValues *, u_long, u_long) ;
+
+#endif
+
+
+#if NeedFunctionPrototypes
+static Pixmap getDitherPixmap(Widget, int contrast) ;
+#else
+static Pixmap getDitherPixmap() ;
+#endif
+
+ /* return a GC with the specified foreground and optional font */
+
+GC
+AllocFgGC(Widget w, Pixel fg, Font font)
+{
+ XGCValues values ;
+ u_long vmask, dcmask ;
+
+ values.foreground = fg ;
+ values.font = font ;
+
+ if( font != None ) {
+ vmask = GCForeground|GCFont ;
+ dcmask = GCSubwindowMode|GCDashOffset|
+ GCDashList|GCArcMode|GCBackground|GCGraphicsExposures ;
+ } else {
+ vmask = GCForeground ;
+ dcmask = GCFont|GCSubwindowMode|GCDashOffset|
+ GCDashList|GCArcMode|GCBackground|GCGraphicsExposures ;
+ }
+
+ return XtAllocateGC(w, w->core.depth, vmask, &values, 0L, dcmask) ;
+}
+
+
+ /* return gc with widget background color as the foreground */
+
+GC
+AllocBackgroundGC(Widget w, Font font)
+{
+ return AllocFgGC(w, w->core.background_pixel, font) ;
+}
+
+
+ /* Allocate an "inactive" GC. Color is grey (possibly via
+ * dither pattern).
+ */
+
+GC
+AllocGreyGC(Widget w, Pixel fg, Font font, int contrast, Bool be_nice_to_cmap)
+{
+ return AllocShadeGC(w, fg, w->core.background_pixel,
+ font, contrast, be_nice_to_cmap) ;
+}
+
+
+ /* Allocate a GC somewhere between two colors. */
+
+GC
+AllocShadeGC(Widget w, Pixel fg, Pixel bg, Font font,
+ int contrast, Bool be_nice_to_cmap)
+{
+ XGCValues values ;
+ u_long vmask, dcmask ;
+
+ values.foreground = fg ;
+ values.background = bg ;
+ values.font = font ;
+
+ if( font != None ) {
+ vmask = GCForeground|GCFont ;
+ dcmask = GCSubwindowMode|GCDashOffset|
+ GCDashList|GCArcMode|GCGraphicsExposures ;
+ } else {
+ vmask = GCForeground;
+ dcmask = GCFont|GCSubwindowMode|GCDashOffset|
+ GCDashList|GCArcMode|GCGraphicsExposures ;
+ }
+#ifdef HAVE_XMU
+ if( be_nice_to_cmap || w->core.depth == 1)
+ {
+ if( contrast <= 5 )
+ values.foreground = bg ;
+ else if( contrast >= 95 )
+ values.foreground = fg ;
+ else {
+ vmask |= GCBackground|GCStipple|GCFillStyle ;
+ values.fill_style = FillOpaqueStippled ;
+ values.stipple = getDitherPixmap(w, contrast) ;
+ }
+
+ return XtAllocateGC(w, w->core.depth, vmask, &values, 0L, dcmask) ;
+ }
+ else
+#endif
+ {
+ dcmask |= GCBackground ;
+ values.foreground = AllocGreyPixel(w, fg, bg, contrast) ;
+ return XtAllocateGC(w, w->core.depth, vmask, &values, 0L, dcmask) ;
+ }
+}
+
+ /* return top-shadow gc. */
+
+GC
+AllocTopShadowGC(Widget w, int contrast, Bool be_nice_to_cmap)
+{
+ Screen *scr = XtScreen (w);
+ XGCValues values ;
+
+ if( w->core.depth == 1 )
+ values.foreground = BlackPixelOfScreen(scr) ;
+ else if( be_nice_to_cmap )
+ values.foreground = WhitePixelOfScreen(scr) ;
+ else
+ values.foreground = AllocShadowPixel(w, 100+contrast) ;
+
+ return XtAllocateGC(w, w->core.depth,
+ GCForeground, &values,
+ 0L,
+ GCBackground|GCFont|GCSubwindowMode|GCGraphicsExposures|
+ GCDashOffset|GCDashList|GCArcMode) ;
+}
+
+ /* return bottom-shadow gc. */
+
+GC
+AllocBotShadowGC(Widget w, int contrast, Bool be_nice_to_cmap)
+{
+ Screen *scr = XtScreen (w);
+ XGCValues values ;
+
+ if( w->core.depth == 1 || be_nice_to_cmap )
+ values.foreground = BlackPixelOfScreen(scr) ;
+ else
+ values.foreground = AllocShadowPixel(w, 100-contrast) ;
+
+ return XtAllocateGC(w, w->core.depth,
+ GCForeground, &values,
+ 0L,
+ GCBackground|GCFont|GCSubwindowMode|GCGraphicsExposures|
+ GCDashOffset|GCDashList|GCArcMode) ;
+}
+
+ /* return arm-shadow gc. */
+
+GC
+AllocArmGC(Widget w, int contrast, Bool be_nice_to_cmap)
+{
+ Screen *scr = XtScreen (w);
+ XGCValues values ;
+
+ /* Not clear exactly what we should do here. Take a look at
+ * Xaw3d to see what they do.
+ */
+#ifdef HAVE_XMU
+ if( w->core.depth == 1 || be_nice_to_cmap )
+ {
+ values.background = w->core.background_pixel ;
+ if( values.background == BlackPixelOfScreen(scr) )
+ values.foreground = WhitePixelOfScreen(scr) ;
+ else
+ values.foreground = BlackPixelOfScreen(scr) ;
+ values.fill_style = FillStippled ;
+ values.stipple = XmuCreateStippledPixmap(XtScreen(w), 1L, 0L, 1) ;
+
+ return XtAllocateGC(w, w->core.depth,
+ GCForeground|GCBackground|GCStipple|GCFillStyle,
+ &values, 0L,
+ GCFont|GCSubwindowMode|GCGraphicsExposures|
+ GCDashOffset|GCDashList|GCArcMode) ;
+ }
+ else
+#endif
+ {
+ values.foreground = AllocShadowPixel(w, 100-contrast) ;
+ return XtAllocateGC(w, w->core.depth,
+ GCForeground, &values,
+ 0L,
+ GCBackground|GCFont|GCSubwindowMode|GCGraphicsExposures|
+ GCDashOffset|GCDashList|GCArcMode) ;
+ }
+}
+
+
+Pixel
+AllocShadowPixel(Widget w, int scale)
+{
+ XColor get_c, set_c ;
+ Display *dpy = XtDisplay(w) ;
+ Screen *scr = XtScreen(w) ;
+ Colormap cmap ;
+ Pixel maxColor ;
+
+ cmap = w->core.colormap ;
+
+ get_c.pixel = w->core.background_pixel ;
+ if( get_c.pixel == WhitePixelOfScreen(scr) ||
+ get_c.pixel == BlackPixelOfScreen(scr) )
+ {
+ /* what we *ought* to do is choose gray75 as the base color,
+ * or perhaps gray83. Instead, we choose colors that are
+ * the same as ThreeD would choose.
+ */
+ if( scale > 100 ) scale = 200 - scale ;
+ set_c.red = set_c.green = set_c.blue = 65535*scale/100 ;
+ }
+ else
+ {
+ XQueryColor(dpy, cmap, &get_c) ;
+ /* adjust scale so that brightest component does not
+ * exceed 65535; otherwise hue would change.
+ */
+ if( scale > 100 ) {
+ maxColor = Max(get_c.red, Max(get_c.green, get_c.blue)) ;
+ if( scale*maxColor > 65535*100 )
+ scale = 65535*100/maxColor ;
+ }
+ set_c.red = scale * get_c.red / 100 ;
+ set_c.green = scale * get_c.green / 100 ;
+ set_c.blue = scale * get_c.blue / 100 ;
+ }
+ set_c.flags = DoRed | DoGreen | DoBlue ;
+ if( XAllocColor(dpy, cmap, &set_c) )
+ return set_c.pixel ;
+ else if( scale > 100 )
+ return WhitePixelOfScreen(scr) ;
+ else
+ return BlackPixelOfScreen(scr) ;
+}
+
+
+ /* Allocate a pixel partway between foreground and background */
+
+
+Pixel
+AllocGreyPixel(Widget w, Pixel fg, Pixel bg, int scale)
+{
+ XColor get_cf, get_cb ;
+ Display *dpy = XtDisplay(w) ;
+ Colormap cmap ;
+
+ cmap = w->core.colormap ;
+
+ get_cf.pixel = fg ;
+ get_cb.pixel = bg ;
+
+ XQueryColor(dpy, cmap, &get_cf) ;
+ XQueryColor(dpy, cmap, &get_cb) ;
+
+ return AllocGreyPixelC(w, &get_cf, &get_cb, scale) ;
+}
+
+
+
+ /* Allocate a pixel partway between foreground and background */
+
+
+Pixel
+AllocGreyPixelC(Widget w, XColor *fg, XColor *bg, int scale)
+{
+ XColor set_c ;
+ Display *dpy = XtDisplay(w) ;
+ int r,g,b ;
+ Colormap cmap = w->core.colormap ;
+
+ r = (fg->red * scale + bg->red * (100-scale)) / 100 ;
+ g = (fg->green * scale + bg->green * (100-scale)) / 100 ;
+ b = (fg->blue * scale + bg->blue * (100-scale)) / 100 ;
+
+ if( scale > 100 || scale < 0 ) /* look out for overflow */
+ {
+ int minc, maxc ;
+ maxc = Max(r, Max(g,b)) ;
+ minc = Min(r, Min(g,b)) ;
+ if( maxc > 65535 )
+ {
+ maxc /= 16 ;
+ r = r*(65535/16) / maxc ;
+ g = g*(65535/16) / maxc ;
+ b = b*(65535/16) / maxc ;
+ }
+ if( minc < 0 )
+ {
+ r = Max(r,0) ;
+ g = Max(g,0) ;
+ b = Max(b,0) ;
+ }
+ }
+
+ set_c.red = r ; set_c.green = g ; set_c.blue = b ;
+ set_c.flags = DoRed | DoGreen | DoBlue ;
+ (void)XAllocColor(dpy, cmap, &set_c) ;
+ return set_c.pixel ;
+}
+
+
+
+
+
+ /* draw a 3-d box */
+
+void
+Draw3dBox(Widget w, int x, int y, int wid, int hgt, int s, GC topgc, GC botgc)
+{
+ Display *dpy = XtDisplay(w) ;
+ Window win = XtWindow(w) ;
+
+ if( s == 0 ) return ;
+
+ if( s == 1 ) {
+ XDrawLine(dpy,win,botgc, x,y+hgt-1, x+wid-1,y+hgt-1) ;
+ XDrawLine(dpy,win,botgc, x+wid-1,y, x+wid-1,y+hgt-1) ;
+ XDrawLine(dpy,win,topgc, x,y, x,y+hgt-1) ;
+ XDrawLine(dpy,win,topgc, x,y, x+wid-1,y) ;
+ }
+ else
+ {
+ XPoint pts[6] ;
+
+ /* bottom-right shadow */
+ pts[0].x = x ; pts[0].y = y + hgt ;
+ pts[1].x = s ; pts[1].y = -s ;
+ pts[2].x = wid-2*s ; pts[2].y = 0 ;
+ pts[3].x = 0 ; pts[3].y = -(hgt-2*s) ;
+ pts[4].x = s ; pts[4].y = -s ;
+ pts[5].x = 0 ; pts[5].y = hgt ;
+ XFillPolygon(dpy,win,botgc, pts,6, Nonconvex,CoordModePrevious) ;
+
+ /* top-left shadow */
+ pts[0].x = x ; pts[0].y = y ;
+ pts[1].x = wid ; pts[1].y = 0 ;
+ pts[2].x = -s ; pts[2].y = s ;
+ pts[3].x = -wid+2*s ; pts[3].y = 0 ;
+ pts[4].x = 0 ; pts[4].y = hgt-2*s ;
+ pts[5].x = -s ; pts[5].y = s ;
+ XFillPolygon(dpy,win,topgc, pts,6, Nonconvex,CoordModePrevious) ;
+ }
+}
+
+#if XtSpecificationRelease < 5
+
+static GC
+XtAllocateGC(Widget w, int depth, u_long mask, XGCValues *values,
+ u_long dynamic, du_long ontcare)
+{
+ return XtGetGC(w, mask, values) ;
+}
+#endif
+
+
+static u_char screen0[2] = {0,0} ;
+static u_char screen25[2] = {0,0xaa} ;
+static u_char screen75[2] = {0xaa,0xff} ;
+static u_char screen100[2] = {0xff,0xff} ;
+
+static Pixmap
+getDitherPixmap(Widget w, int contrast)
+{
+ Display *dpy = XtDisplay(w) ;
+ Window win = XtWindow(w) ;
+
+ if( contrast <= 5 )
+ return XCreateBitmapFromData(dpy,win, (char *)screen0, 2,2) ;
+ else if( contrast <= 37 )
+ return XCreateBitmapFromData(dpy,win, (char *)screen25, 2,2) ;
+ else if( contrast <= 62 )
+ return XmuCreateStippledPixmap(XtScreen(w), 1L, 0L, 1) ;
+ else if( contrast <= 95 )
+ return XCreateBitmapFromData(dpy,win, (char *)screen75, 2,2) ;
+ else
+ return XCreateBitmapFromData(dpy,win, (char *)screen100, 2,2) ;
+}
--- /dev/null
+ /* Tabs Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+ This file is part of XEmacs.
+
+ XEmacs is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the
+ Free Software Foundation; either version 2, or (at your option) any
+ later version.
+
+ XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with XEmacs; see the file COPYING. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA. */
+
+ /* Synched up with: Gcs 1.7 */
+
+
+#ifndef GCS_H
+#define GCS_H
+
+/* Overview of functions provided here:
+ *
+ * AllocFgGC()
+ * Given a foreground pixel & a font, return an appropriate GC
+ *
+ * AllocBackgroundGC()
+ * Given a widget, return a GC for painting the background color
+ *
+ * AllocShadeGC()
+ * Given foreground, background, a contrast value & be_nice_to_colormap
+ * flag, return a GC suitable for rendering in an intermediate color,
+ * as determined by constrast. May return a dither pattern or a
+ * solid color, as appropriate.
+ *
+ * Contrast 0 = background color, 100 = foreground color. It is legal
+ * for contrast to be more than 100 or less than 0.
+ *
+ * AllocGreyGC()
+ * Given widget, foreground, font, contrast & be_nice_to_colormap,
+ * return a shade GC (see above) based on foreground and widget
+ * background.
+ *
+ * AllocTopShadowGC()
+ * Given widget, contrast & be_nice_to_colormap, return a GC suitable
+ * for rendering the top shadow.
+ *
+ * Contrast 0 = use background pixel. Contrast > 0 = use brighter
+ * colors.
+ *
+ * AllocBotShadowGC()
+ * Given widget, contrast & be_nice_to_colormap, return a GC suitable
+ * for rendering the bottom shadow.
+ *
+ * Contrast 0 = use background pixel. Contrast > 0 = use darker
+ * colors.
+ *
+ * AllocArmShadowGC()
+ * Given widget, contrast & be_nice_to_colormap, return a GC suitable
+ * for rendering the "armed" shadow.
+ *
+ * Contrast 0 = use background pixel. Contrast > 0 = use darker
+ * colors.
+ *
+ * AllocShadowPixel()
+ * Given a widget & scale factor, allocate & return a color darker
+ * or lighter than the background pixel, as determined by scale.
+ *
+ * Scale 100 = use background pixel. Scale > 100 = brighter color,
+ * Scale < 100 = darker color.
+ *
+ * AllocGreyPixel()
+ * Given two pixel values and scale factor, allocate & return a
+ * pixel value between them, according to scale.
+ *
+ * Scale == 0: background color
+ * Scale == 100: foreground color
+ * 0<Scale<100: intermediate color
+ * Scale > 100: more foreground
+ * Scale < 0: more background
+ *
+ *
+ * AllocGreyPixelC()
+ * Given two color values and scale factor, allocate & return a
+ * pixel value between them, according to scale.
+ *
+ * Scale == 0: background color
+ * Scale == 100: foreground color
+ * 0<Scale<100: intermediate color
+ * Scale > 100: more foreground
+ * Scale < 0: more background
+ *
+ * Draw3dBox()
+ * Given box dimensions, shadow width, top shadow GC & bottom shadow GC,
+ * draw a 3-d box.
+ */
+
+#if NeedFunctionPrototypes
+
+extern GC AllocFgGC( Widget w, Pixel fg, Font font) ;
+extern GC AllocBackgroundGC( Widget w, Font font) ;
+extern GC AllocShadeGC( Widget w, Pixel fg, Pixel bg, Font,
+ int contrast, Bool ) ;
+extern GC AllocGreyGC( Widget w, Pixel fg, Font, int, Bool ) ;
+extern GC AllocTopShadowGC( Widget w, int contrast, int ) ;
+extern GC AllocBotShadowGC( Widget w, int contrast, int ) ;
+extern GC AllocArmGC( Widget w, int contrast, int) ;
+extern Pixel AllocShadowPixel(Widget, int scale) ;
+extern Pixel AllocGreyPixel(Widget, Pixel fg, Pixel bg, int scale) ;
+extern Pixel AllocGreyPixelC(Widget, XColor *fg, XColor *bg, int scale) ;
+extern void Draw3dBox(Widget w, int x, int y, int wid, int hgt, int s,
+ GC topgc, GC botgc) ;
+
+#if XtSpecificationRelease < 5
+extern GC XtAllocateGC(Widget, int depth, u_long mask,
+ XGCValues *, u_long dynamic, u_long dontcare) ;
+#endif
+
+#else
+
+extern GC AllocFgGC() ;
+extern GC AllocBackgroundGC() ;
+extern GC AllocShadeGC() ;
+extern GC AllocGreyGC() ;
+extern GC AllocTopShadowGC() ;
+extern GC AllocBotShadowGC() ;
+extern GC AllocArmGC() ;
+extern Pixel AllocShadowPixel() ;
+extern Pixel AllocGreyPixel() ;
+extern Pixel AllocGreyPixelC() ;
+extern void Draw3dBox() ;
+
+#if XtSpecificationRelease < 5
+extern GC XtAllocateGC() ;
+#endif
+
+#endif
+
+#endif /* GCS_H */
--- /dev/null
+/* Radio Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Radio.c 1.1 */
+
+/*
+ * Radio.c - Radio button widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: June 30, 1997
+ *
+ *
+ * Overview: This widget is identical to the Toggle widget in behavior,
+ * but completely different in appearance. This widget looks like a small
+ * diamond-shaped button with a label to the right.
+ *
+ * To make this work, we subclass the Toggle widget to inherit its behavior
+ * and to inherit the label-drawing function from which Toggle is
+ * subclassed. We then completely replace the Expose, Set, Unset
+ * and Highlight member functions.
+ *
+ * The Set and Unset actions are slightly unorthodox. In Toggle's
+ * ClassInit function, Toggle searches the Command actions list and
+ * "steals" the Set and Unset functions, caching pointers to them in its
+ * class record. It then calls these functions from its own ToggleSet
+ * and Toggle actions.
+ *
+ * We, in turn, override the Set() and Unset() actions in our own ClassRec.
+ */
+
+
+#include <config.h>
+#include <stdio.h>
+
+#include <X11/IntrinsicP.h>
+#include <X11/StringDefs.h>
+#include <X11/Xaw/XawInit.h>
+#include "../src/xmu.h"
+#include "xlwradioP.h"
+
+#define BOX_SIZE 13
+
+#define rclass(w) ((RadioWidgetClass)((w)->core.widget_class))
+
+
+#ifdef _ThreeDP_h
+#define swid(rw) ((rw)->threeD.shadow_width)
+#else
+#define swid(rw) ((rw)->core.border_width)
+#endif
+
+#define bsize(rw) (rclass(rw)->radio_class.dsize)
+#define bs(rw) (bsize(rw) + 2*swid(rw))
+
+
+
+/****************************************************************
+ *
+ * Full class record constant
+ *
+ ****************************************************************/
+
+ /* The translations table from Toggle do not need to be
+ * overridden by Radio
+ */
+
+
+ /* Member functions */
+
+static void RadioInit (Widget, Widget, ArgList, Cardinal *);
+static void RadioExpose (Widget, XEvent *, Region);
+static void RadioResize (Widget);
+static void RadioDestroy (Widget, XtPointer, XtPointer);
+static void RadioClassInit (void);
+static void RadioClassPartInit (WidgetClass);
+static Boolean RadioSetValues (Widget, Widget, Widget, ArgList, Cardinal *);
+static void DrawDiamond (Widget);
+static XtGeometryResult RadioQueryGeometry (Widget, XtWidgetGeometry *,
+ XtWidgetGeometry *);
+
+ /* Action procs */
+
+static void RadioHighlight (Widget, XEvent *, String *, Cardinal *);
+static void RadioUnhighlight (Widget, XEvent *, String *, Cardinal *);
+
+ /* internal privates */
+
+static void RadioSize (RadioWidget, Dimension *, Dimension *);
+
+ /* The actions table from Toggle is almost perfect, but we need
+ * to override Highlight, Set, and Unset.
+ */
+
+static XtActionsRec actionsList[] =
+{
+ {"highlight", RadioHighlight},
+ {"unhighlight", RadioUnhighlight},
+};
+
+#define SuperClass ((ToggleWidgetClass)&toggleClassRec)
+
+RadioClassRec radioClassRec = {
+ {
+ (WidgetClass) SuperClass, /* superclass */
+ "Radio", /* class_name */
+ sizeof(RadioRec), /* size */
+ RadioClassInit, /* class_initialize */
+ RadioClassPartInit, /* class_part_initialize */
+ FALSE, /* class_inited */
+ RadioInit, /* initialize */
+ NULL, /* initialize_hook */
+ XtInheritRealize, /* realize */
+ actionsList, /* actions */
+ XtNumber(actionsList), /* num_actions */
+ NULL, /* resources */
+ 0, /* resource_count */
+ NULLQUARK, /* xrm_class */
+ TRUE, /* compress_motion */
+ TRUE, /* compress_exposure */
+ TRUE, /* compress_enterleave */
+ FALSE, /* visible_interest */
+ NULL, /* destroy */
+ RadioResize, /* resize */
+ RadioExpose, /* expose */
+ RadioSetValues, /* set_values */
+ NULL, /* set_values_hook */
+ XtInheritSetValuesAlmost, /* set_values_almost */
+ NULL, /* get_values_hook */
+ NULL, /* accept_focus */
+ XtVersion, /* version */
+ NULL, /* callback_private */
+ XtInheritTranslations, /* tm_table */
+ RadioQueryGeometry, /* query_geometry */
+ XtInheritDisplayAccelerator, /* display_accelerator */
+ NULL /* extension */
+ }, /* CoreClass fields initialization */
+ {
+ XtInheritChangeSensitive /* change_sensitive */
+ }, /* SimpleClass fields initialization */
+#ifdef _ThreeDP_h
+ {
+ XtInheritXaw3dShadowDraw /* field not used */
+ }, /* ThreeDClass fields initialization */
+#endif
+ {
+ 0 /* field not used */
+ }, /* LabelClass fields initialization */
+ {
+ 0 /* field not used */
+ }, /* CommandClass fields initialization */
+ {
+ RadioSet, /* Set Procedure. */
+ RadioUnset, /* Unset Procedure. */
+ NULL /* extension. */
+ }, /* ToggleClass fields initialization */
+ {
+ BOX_SIZE,
+ DrawDiamond, /* draw procedure */
+ NULL /* extension. */
+ } /* RadioClass fields initialization */
+};
+
+ /* for public consumption */
+WidgetClass radioWidgetClass = (WidgetClass) &radioClassRec;
+
+
+
+\f
+
+
+/****************************************************************
+ *
+ * Class Methods
+ *
+ ****************************************************************/
+
+static void
+RadioClassInit (void)
+{
+ XawInitializeWidgetSet();
+}
+
+static void
+RadioClassPartInit (WidgetClass class)
+{
+ RadioWidgetClass c = (RadioWidgetClass) class ;
+ RadioWidgetClass super = (RadioWidgetClass)c->core_class.superclass ;
+
+ if( c->radio_class.drawDiamond == NULL ||
+ c->radio_class.drawDiamond == XtInheritDrawDiamond )
+ {
+ c->radio_class.drawDiamond = super->radio_class.drawDiamond ;
+ }
+}
+
+
+
+
+/*ARGSUSED*/
+static void
+RadioInit (Widget request,
+ Widget new,
+ ArgList args,
+ Cardinal *num_args)
+{
+ RadioWidget rw = (RadioWidget) new;
+ RadioWidget rw_req = (RadioWidget) request;
+ Dimension w,h ;
+
+ /* Select initial size for the widget */
+ if( rw_req->core.width == 0 || rw_req->core.height == 0 )
+ {
+ RadioSize(rw, &w,&h) ;
+ if( rw_req->core.width == 0 )
+ rw->core.width = w ;
+ if( rw_req->core.height == 0 )
+ rw->core.height = h ;
+ rw->core.widget_class->core_class.resize(new) ;
+ }
+}
+
+/* Function Name: RadioDestroy
+ * Description: Destroy Callback for radio widget.
+ * Arguments: w - the radio widget that is being destroyed.
+ * junk, grabage - not used.
+ * Returns: none.
+ */
+
+/* ARGSUSED */
+static void
+RadioDestroy (Widget w,
+ XtPointer junk,
+ XtPointer garbage)
+{
+ /* TODO: get rid of this */
+}
+
+
+/* React to size change from manager. Label widget will compute some internal
+ * stuff, but we need to override. This code requires knowledge of the
+ * internals of the Label widget.
+ */
+
+static void
+RadioResize (Widget w)
+{
+ RadioWidget rw = (RadioWidget)w ;
+
+ /* call parent resize proc */
+ SuperClass->core_class.resize(w) ;
+
+ /* override label offset */
+
+ switch( rw->label.justify ) {
+ case XtJustifyLeft:
+ rw->label.label_x += bs(rw) + rw->label.internal_width ;
+ break ;
+ case XtJustifyRight:
+ break ;
+ case XtJustifyCenter:
+ default:
+ rw->label.label_x += (bs(rw) + rw->label.internal_width)/2 ;
+ break ;
+ }
+}
+
+
+/*
+ * Repaint the widget window.
+ */
+
+static void
+RadioExpose (Widget w,
+ XEvent *event,
+ Region region)
+{
+ RadioWidget rw = (RadioWidget) w ;
+ Display *dpy = XtDisplay(w) ;
+ Window win = XtWindow(w) ;
+ GC gc ;
+ Pixmap left_bitmap ;
+ extern WidgetClass labelWidgetClass ;
+
+ /* Note: the Label widget examines the region to decide if anything
+ * needs to be drawn. I'm not sure that this is worth the effort,
+ * but it bears thinking on.
+ */
+
+ /* Command widget may sometimes override the label GC in order
+ * to draw inverse video. We don't use inverse video, so we need
+ * to restore the label's normal GC.
+ */
+ rw->label.normal_GC = rw->command.normal_GC ;
+
+
+ /* Let label widget draw the label. If there was an lbm_x
+ * field, we could let Label draw the bitmap too. But there
+ * isn't, so we need to temporarily remove the bitmap and
+ * draw it ourself later.
+ */
+ left_bitmap = rw->label.left_bitmap ;
+ rw->label.left_bitmap = None ;
+ labelWidgetClass->core_class.expose(w,event,region) ;
+ rw->label.left_bitmap = left_bitmap ;
+
+ /* now manually draw the left bitmap. TODO: 3-d look, xaw-xpm */
+ gc = XtIsSensitive(w) ? rw->label.normal_GC : rw->label.gray_GC ;
+ if( left_bitmap != None && rw->label.lbm_width > 0 )
+ {
+ /* TODO: handle pixmaps */
+ XCopyPlane(dpy, left_bitmap, win, gc,
+ 0,0, rw->label.lbm_width, rw->label.lbm_height,
+ (int) rw->label.internal_width*2 + bs(rw),
+ (int) rw->label.internal_height + rw->label.lbm_y,
+ (u_long) 1L) ;
+ }
+
+ /* Finally, the button itself */
+ ((RadioWidgetClass)(w->core.widget_class))->radio_class.drawDiamond(w) ;
+}
+
+
+
+
+/************************************************************
+ *
+ * Set specified arguments into widget
+ *
+ ***********************************************************/
+
+
+/* ARGSUSED */
+static Boolean
+RadioSetValues (Widget current,
+ Widget request,
+ Widget new,
+ ArgList args,
+ Cardinal *num_args)
+{
+ RadioWidget oldrw = (RadioWidget) current;
+ RadioWidget newrw = (RadioWidget) new;
+
+ /* Need to find out if the size of the widget changed. Set new size
+ * if it did and resize is permitted. One way to determine of the
+ * widget changed size would be to scan the args list. Another way
+ * is to compare the old and new widgets and see if any of several
+ * size-related fields have been changed. The Label widget chose the
+ * former method, but I choose the latter.
+ */
+
+ if( newrw->label.resize &&
+ ( newrw->core.width != oldrw->core.width ||
+ newrw->core.height != oldrw->core.height ||
+ newrw->core.border_width != oldrw->core.border_width ) )
+ {
+ RadioSize(newrw, &newrw->core.width, &newrw->core.height) ;
+ }
+
+ return FALSE ;
+}
+
+static XtGeometryResult
+RadioQueryGeometry (Widget w,
+ XtWidgetGeometry *intended,
+ XtWidgetGeometry *preferred)
+{
+ RadioWidget rw = (RadioWidget) w;
+
+ preferred->request_mode = CWWidth | CWHeight;
+ RadioSize(rw, &preferred->width, &preferred->height) ;
+
+ if ( ((intended->request_mode & (CWWidth | CWHeight))
+ == (CWWidth | CWHeight)) &&
+ intended->width == preferred->width &&
+ intended->height == preferred->height)
+ return XtGeometryYes;
+ else if (preferred->width == w->core.width &&
+ preferred->height == w->core.height)
+ return XtGeometryNo;
+ else
+ return XtGeometryAlmost;
+}
+
+
+
+\f
+
+/************************************************************
+ *
+ * Action Procedures
+ *
+ ************************************************************/
+
+/*
+ * Draw the highlight border around the widget. The Command widget
+ * did this by drawing through a mask. We do it by just drawing the
+ * border.
+ */
+
+static void
+DrawHighlight (Widget w,
+ GC gc)
+{
+ RadioWidget rw = (RadioWidget)w;
+ XRectangle rects[4] ;
+ Dimension ht = rw->command.highlight_thickness ;
+
+ if( ht <= 0 ||
+ ht > rw->core.width/2 ||
+ ht > rw->core.height/2 )
+ return ;
+
+ if( ! XtIsRealized(w) )
+ return ;
+
+ rects[0].x = 0 ; rects[0].y = 0 ;
+ rects[0].width = rw->core.width ; rects[0].height = ht ;
+ rects[1].x = 0 ; rects[1].y = rw->core.height - ht ;
+ rects[1].width = rw->core.width ; rects[1].height = ht ;
+ rects[2].x = 0 ; rects[2].y = ht ;
+ rects[2].width = ht ; rects[2].height = rw->core.height - ht*2 ;
+ rects[3].x = rw->core.width - ht ; rects[3].y = ht ;
+ rects[3].width = ht ; rects[3].height = rw->core.height - ht*2 ;
+ XFillRectangles( XtDisplay(w), XtWindow(w), gc, rects, 4) ;
+}
+
+static void
+RadioHighlight (Widget w,
+ XEvent *event,
+ String *params,
+ Cardinal *num_params)
+{
+ RadioWidget rw = (RadioWidget)w;
+ DrawHighlight(w, rw->command.normal_GC) ;
+}
+
+
+static void
+RadioUnhighlight (Widget w,
+ XEvent *event,
+ String *params,
+ Cardinal *num_params)
+{
+ RadioWidget rw = (RadioWidget)w;
+ DrawHighlight(w, rw->command.inverse_GC) ;
+}
+
+
+/* ARGSUSED */
+void
+RadioSet (Widget w,
+ XEvent *event,
+ String *params, /* unused */
+ Cardinal *num_params) /* unused */
+{
+ RadioWidget rw = (RadioWidget)w;
+ RadioWidgetClass class = (RadioWidgetClass) w->core.widget_class ;
+
+ if( rw->command.set )
+ return ;
+
+ rw->command.set = TRUE ;
+ if( XtIsRealized(w) )
+ class->radio_class.drawDiamond(w) ;
+}
+
+
+/* ARGSUSED */
+void
+RadioUnset (Widget w,
+ XEvent *event,
+ String *params, /* unused */
+ Cardinal *num_params) /* unused */
+{
+ RadioWidget rw = (RadioWidget)w;
+ RadioWidgetClass class = (RadioWidgetClass) w->core.widget_class ;
+
+ if( ! rw->command.set )
+ return ;
+
+ rw->command.set = FALSE ;
+ if( XtIsRealized(w) )
+ class->radio_class.drawDiamond(w) ;
+}
+
+
+\f
+
+/************************************************************
+ *
+ * Internal Procedures
+ *
+ ************************************************************/
+
+
+/* Size of widget. Width is size of box plus width of border around
+ * box plus width of label plus three margins plus the size of the left
+ * bitmap, if any. Height is max(box,bitmap,label) plus two margins.
+ */
+
+static void
+RadioSize (RadioWidget rw,
+ Dimension *w,
+ Dimension *h)
+{
+ *w = rw->label.label_width + bs(rw) + LEFT_OFFSET(rw) +
+ 3 * rw->label.internal_width ;
+ *h = Max( rw->label.label_height, bs(rw) ) +
+ 2 * rw->label.internal_width ;
+}
+
+
+static void
+DrawDiamond (Widget w)
+{
+ RadioWidget rw = (RadioWidget) w ;
+ Display *dpy = XtDisplay(w) ;
+ Window win = XtWindow(w) ;
+ GC gc, gci ;
+
+ XPoint pts[5] ;
+ Dimension del = bsize(rw)/2 ;
+ Position x,y ; /* diamond center */
+#ifdef _ThreeDP_h
+ int i=0;
+ Dimension s = swid(rw) ;
+ GC top, bot, ctr ;
+#endif
+ gc = XtIsSensitive(w) ? rw->command.normal_GC : rw->label.gray_GC ;
+
+ gci = rw->command.set ? rw->command.normal_GC : rw->command.inverse_GC ;
+
+ x = rw->label.internal_width + bs(rw)/2 ;
+ y = rw->core.height/2 ;
+
+#ifdef _ThreeDP_h
+ if( ! rw->command.set ) {
+ top = rw->threeD.top_shadow_GC ;
+ bot = rw->threeD.bot_shadow_GC ;
+ ctr = gc ; /* TODO */
+ } else {
+ top = rw->threeD.bot_shadow_GC ;
+ bot = rw->threeD.top_shadow_GC ;
+ ctr = gc ; /* TODO */
+ }
+#endif
+
+ pts[0].x = x - del ;
+ pts[0].y = y ;
+ pts[1].x = x ;
+ pts[1].y = y - del ;
+ pts[2].x = x + del ;
+ pts[2].y = y ;
+ pts[3].x = x ;
+ pts[3].y = y + del ;
+ pts[4] = pts[0] ;
+ XFillPolygon(dpy,win,gci, pts,4, Convex, CoordModeOrigin) ;
+
+#ifdef _ThreeDP_h
+ for(i=0; i<s; ++i) {
+ XDrawLine(dpy,win,bot, x-i-del,y, x,y+del+i) ;
+ XDrawLine(dpy,win,bot, x+del+i,y, x,y+del+i) ;
+ }
+ for(i=0; i<s; ++i) {
+ XDrawLine(dpy,win,top, x-del-i,y, x,y-del-i) ;
+ XDrawLine(dpy,win,top, x+del+i,y, x,y-del-i) ;
+ }
+#else
+ XDrawLines(dpy,win,gc, pts,5, CoordModeOrigin) ;
+#endif
+}
--- /dev/null
+/* Radio Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: Radio.h 1.1 */
+
+/*
+ * Radio.h - Radio button widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: June 30, 1997
+ */
+
+#ifndef _XawRadio_h
+#define _XawRadio_h
+
+/***********************************************************************
+ *
+ * Radio Widget
+ *
+ * The Radio widget is identical to the Toggle widget in behavior but
+ * not in appearance. The Radio widget looks like a small diamond
+ * shaped button to the left of the label.
+ *
+ ***********************************************************************/
+
+#include <X11/Xaw/Toggle.h>
+
+/* Resources:
+
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ radioGroup RadioGroup Widget NULL
+ radioData RadioData Pointer (XPointer) Widget
+ state State Boolean Off
+ background Background Pixel XtDefaultBackground
+ bitmap Pixmap Pixmap None
+ border BorderColor Pixel XtDefaultForeground
+ borderWidth BorderWidth Dimension 1
+ callback Callback Pointer NULL
+ cursor Cursor Cursor None
+ destroyCallback Callback Pointer NULL
+ font Font XFontStructx* XtDefaultFont
+ foreground Foreground Pixel XtDefaultForeground
+ height Height Dimension text height
+ highlightThickness Thickness Dimension 2
+ insensitiveBorder sensitive Pixmap Gray
+ internalHeight Height Dimension 2
+ internalWidth Width Dimension 4
+ justify Justify XtJustify XtJustifyCenter
+ label Label String NULL
+ mappedWhenManaged MappedWhenManaged Boolean True
+ resize Resize Boolean True
+ sensitive Sensitive Boolean True
+ width Width Dimension text width
+ x Position Position 0
+ y Position Position 0
+
+*/
+
+/*
+ * These should be in StringDefs.h but aren't so we will define
+ * them here if they are needed.
+ */
+
+
+extern WidgetClass radioWidgetClass;
+
+typedef struct _RadioClassRec *RadioWidgetClass;
+typedef struct _RadioRec *RadioWidget;
+
+
+/************************************************************
+ *
+ * Public Functions
+ *
+ ************************************************************/
+
+#endif /* _XawRadio_h */
--- /dev/null
+/* Radio Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/*
+ * RadioP.h - Private definitions for Radio widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: June 30, 1997
+ *
+ */
+
+#ifndef _XawRadioP_h
+#define _XawRadioP_h
+
+#include "xlwradio.h"
+#include <X11/Xaw/ToggleP.h>
+
+/***********************************************************************
+ *
+ * Radio Widget Private Data
+ *
+ ***********************************************************************/
+
+#define streq(a, b) ( strcmp((a), (b)) == 0 )
+
+typedef void (*XawDiamondProc) (Widget);
+
+void RadioSet (Widget w,
+ XEvent *event,
+ String *params, /* unused */
+ Cardinal *num_params); /* unused */
+
+void RadioUnset (Widget w,
+ XEvent *event,
+ String *params, /* unused */
+ Cardinal *num_params); /* unused */
+
+/************************************
+ *
+ * Class structure
+ *
+ ***********************************/
+
+ /* New fields for the Radio widget class record */
+typedef struct _RadioClass {
+ Dimension dsize ; /* diamond size */
+ XawDiamondProc drawDiamond ;
+ /* TODO: 3-d and xaw-xpm features? */
+ XtPointer extension;
+} RadioClassPart;
+
+#define XtInheritDrawDiamond ((XawDiamondProc)_XtInherit)
+
+ /* Full class record declaration */
+typedef struct _RadioClassRec {
+ CoreClassPart core_class;
+ SimpleClassPart simple_class;
+#ifdef _ThreeDP_h
+ ThreeDClassPart threeD_class;
+#endif
+ LabelClassPart label_class;
+ CommandClassPart command_class;
+ ToggleClassPart toggle_class;
+ RadioClassPart radio_class;
+} RadioClassRec;
+
+extern RadioClassRec radioClassRec;
+
+/***************************************
+ *
+ * Instance (widget) structure
+ *
+ **************************************/
+
+ /* New fields for the Radio widget record */
+typedef struct {
+ /* resources */
+ /* TODO: 3-d and xaw-xpm features? */
+
+ /* private data */
+ XtPointer extension;
+} RadioPart;
+
+ /* Full widget declaration */
+typedef struct _RadioRec {
+ CorePart core;
+ SimplePart simple;
+#ifdef _ThreeDP_h
+ ThreeDPart threeD;
+#endif
+ LabelPart label;
+ CommandPart command;
+ TogglePart toggle;
+ RadioPart radio;
+} RadioRec;
+
+#endif /* _XawRadioP_h */
--- /dev/null
+ /* Tabs Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+ This file is part of XEmacs.
+
+ XEmacs is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the
+ Free Software Foundation; either version 2, or (at your option) any
+ later version.
+
+ XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with XEmacs; see the file COPYING. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA. */
+
+ /* Synched up with: Tabs.c 1.23 */
+
+ /*
+ * Tabs.c - Index Tabs composite widget
+ *
+ * Author: Edward A. Falk
+ * falk@falconer.vip.best.com
+ *
+ * Date: July 29, 1997
+ *
+ *
+ * Overall layout of this widget is as follows:
+ *
+ * ________ ,---------. _________
+ * | label || Label || Label | \ tabs
+ * |________|| ||_________| /
+ * |+----------------------------+| \
+ * || || |
+ * || child widget window || > frame
+ * |+----------------------------+| |
+ * +------------------------------+ /
+ *
+ * The height of the tabs includes the shadow width, top and bottom
+ * margins, and the height of the text.
+ *
+ * The height of the frame includes the top and bottom shadow width and the
+ * size of the child widget window.
+ *
+ * The tabs overlap the frame and each other vertically by the shadow
+ * width, so that when the topmost tab is drawn, it obliterates part of
+ * the frame.
+ */
+
+/* TODO: min child height = tab height
+ *
+ */
+
+#include <config.h>
+#include <stdio.h>
+
+#include <X11/Xlib.h>
+#include <X11/IntrinsicP.h>
+#include <X11/StringDefs.h>
+#include "../src/xmu.h"
+#include "xlwtabsP.h"
+#include "xlwgcs.h"
+
+#define MIN_WID 10
+#define MIN_HGT 10
+#define INDENT 3 /* tabs indented from edge by this much */
+#define SPACING 0 /* distance between tabs */
+#define SHADWID 1 /* default shadow width */
+#define TABDELTA 2 /* top tab grows this many pixels */
+#define TABLDELTA 2 /* top tab label offset this many pixels */
+
+
+/****************************************************************
+ *
+ * IndexTabs Resources
+ *
+ ****************************************************************/
+
+static char defaultTranslations[] = "\
+ <BtnUp>: select() \n\
+ <FocusIn>: highlight() \n\
+ <FocusOut>: unhighlight() \n\
+ <Key>Page_Up: page(up) \n\
+ <Key>KP_Page_Up: page(up) \n\
+ <Key>Prior: page(up) \n\
+ <Key>KP_Prior: page(up) \n\
+ <Key>Page_Down: page(down) \n\
+ <Key>KP_Page_Down: page(down) \n\
+ <Key>Next: page(down) \n\
+ <Key>KP_Next: page(down) \n\
+ <Key>Home: page(home) \n\
+ <Key>KP_Home: page(home) \n\
+ <Key>End: page(end) \n\
+ <Key>KP_End: page(end) \n\
+ <Key>Up: highlight(up) \n\
+ <Key>KP_Up: highlight(up) \n\
+ <Key>Down: highlight(down) \n\
+ <Key>KP_Down: highlight(down) \n\
+ <Key> : page(select) \n\
+ " ;
+
+static char accelTable[] = " #augment\n\
+ <Key>Page_Up: page(up) \n\
+ <Key>KP_Page_Up: page(up) \n\
+ <Key>Prior: page(up) \n\
+ <Key>KP_Prior: page(up) \n\
+ <Key>Page_Down: page(down) \n\
+ <Key>KP_Page_Down: page(down) \n\
+ <Key>Next: page(down) \n\
+ <Key>KP_Next: page(down) \n\
+ <Key>Home: page(home) \n\
+ <Key>KP_Home: page(home) \n\
+ <Key>End: page(end) \n\
+ <Key>KP_End: page(end) \n\
+ <Key>Up: highlight(up) \n\
+ <Key>KP_Up: highlight(up) \n\
+ <Key>Down: highlight(down) \n\
+ <Key>KP_Down: highlight(down) \n\
+ <Key> : page(select) \n\
+ " ;
+static XtAccelerators defaultAccelerators ;
+
+#define offset(field) XtOffsetOf(TabsRec, tabs.field)
+static XtResource resources[] = {
+
+ {XtNselectInsensitive, XtCSelectInsensitive, XtRBoolean, sizeof(Boolean),
+ offset(selectInsensitive), XtRImmediate, (XtPointer) True},
+ {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *),
+ offset(font), XtRString, (XtPointer) XtDefaultFont},
+ {XtNinternalWidth, XtCWidth, XtRDimension, sizeof(Dimension),
+ offset(internalWidth), XtRImmediate, (XtPointer)4 },
+ {XtNinternalHeight, XtCHeight, XtRDimension, sizeof(Dimension),
+ offset(internalHeight), XtRImmediate, (XtPointer)4 },
+ {XtNborderWidth, XtCBorderWidth, XtRDimension, sizeof(Dimension),
+ XtOffsetOf(RectObjRec,rectangle.border_width), XtRImmediate, (XtPointer)0},
+ {XtNtopWidget, XtCTopWidget, XtRWidget, sizeof(Widget),
+ offset(topWidget), XtRImmediate, NULL},
+ {XtNcallback, XtCCallback, XtRCallback, sizeof(XtPointer),
+ offset(callbacks), XtRCallback, NULL},
+ {XtNpopdownCallback, XtCCallback, XtRCallback, sizeof(XtPointer),
+ offset(popdownCallbacks), XtRCallback, NULL},
+ {XtNbeNiceToColormap, XtCBeNiceToColormap, XtRBoolean, sizeof(Boolean),
+ offset(be_nice_to_cmap), XtRImmediate, (XtPointer) True},
+ {XtNtopShadowContrast, XtCTopShadowContrast, XtRInt, sizeof(int),
+ offset(top_shadow_contrast), XtRImmediate, (XtPointer) 20},
+ {XtNbottomShadowContrast, XtCBottomShadowContrast, XtRInt, sizeof(int),
+ offset(bot_shadow_contrast), XtRImmediate, (XtPointer) 40},
+ {XtNinsensitiveContrast, XtCInsensitiveContrast, XtRInt, sizeof(int),
+ offset(insensitive_contrast), XtRImmediate, (XtPointer) 33},
+ {XtNaccelerators, XtCAccelerators, XtRAcceleratorTable,sizeof(XtTranslations),
+ XtOffsetOf(TabsRec,core.accelerators), XtRString, accelTable},
+};
+#undef offset
+
+
+
+ /* constraint resources */
+
+#define offset(field) XtOffsetOf(TabsConstraintsRec, tabs.field)
+static XtResource tabsConstraintResources[] = {
+ {XtNtabLabel, XtCLabel, XtRString, sizeof(String),
+ offset(label), XtRString, NULL},
+ {XtNtabLeftBitmap, XtCLeftBitmap, XtRBitmap, sizeof(Pixmap),
+ offset(left_bitmap), XtRImmediate, None},
+ {XtNtabForeground, XtCForeground, XtRPixel, sizeof(Pixel),
+ offset(foreground), XtRString, (XtPointer) XtDefaultForeground},
+ {XtNresizable, XtCResizable, XtRBoolean, sizeof(Boolean),
+ offset(resizable), XtRImmediate, (XtPointer) True},
+} ;
+#undef offset
+
+
+
+
+#if !NeedFunctionPrototypes
+
+ /* FORWARD REFERENCES: */
+
+ /* member functions */
+
+static void TabsClassInit();
+static void TabsInit();
+static void TabsResize();
+static void TabsExpose();
+static void TabsDestroy();
+static void TabsRealize();
+static Boolean TabsSetValues();
+static XtGeometryResult TabsQueryGeometry();
+static XtGeometryResult TabsGeometryManager();
+static void TabsChangeManaged();
+static void TabsConstraintInitialize() ;
+static Boolean TabsConstraintSetValues() ;
+
+ /* action procs */
+
+static void TabsSelect() ;
+static void TabsPage() ;
+static void TabsHighlight() ;
+static void TabsUnhighlight() ;
+
+ /* internal privates */
+
+static void TabsAllocGCs() ; /* get rendering GCs */
+static void TabsFreeGCs() ; /* return rendering GCs */
+static void DrawTabs() ; /* draw all tabs */
+static void DrawTab() ; /* draw one index tab */
+static void DrawFrame() ; /* draw frame around contents */
+static void DrawTrim() ; /* draw trim around a tab */
+static void DrawBorder() ; /* draw border */
+static void DrawHighlight() ; /* draw highlight */
+static void UndrawTab() ; /* undraw interior of a tab */
+static void TabWidth() ; /* recompute tab size */
+static void GetPreferredSizes() ; /* query all children for their sizes */
+static void MaxChild() ; /* find max preferred child size */
+static int PreferredSize() ; /* compute preferred size */
+static int PreferredSize2() ; /* compute preferred size */
+static int PreferredSize3() ; /* compute preferred size */
+static void MakeSizeRequest() ; /* try to change size */
+static void getBitmapInfo() ;
+static int TabLayout() ; /* lay out tabs */
+static void TabsShuffleRows() ; /* bring current tab to bottom row */
+
+static void TabsAllocFgGC() ;
+static void TabsAllocGreyGC() ;
+
+#else
+
+static void TabsClassInit(void) ;
+static void TabsInit( Widget req, Widget new, ArgList, Cardinal *nargs) ;
+static void TabsConstraintInitialize(Widget, Widget, ArgList, Cardinal *) ;
+static void TabsRealize(Widget, Mask *, XSetWindowAttributes *) ;
+static void TabsDestroy( Widget w) ;
+static void TabsResize( Widget w) ;
+static void TabsExpose( Widget w, XEvent *event, Region region) ;
+static Boolean TabsSetValues(Widget, Widget, Widget, ArgList, Cardinal *) ;
+static Boolean TabsConstraintSetValues(Widget, Widget, Widget,
+ ArgList, Cardinal *) ;
+static XtGeometryResult TabsQueryGeometry(Widget,
+ XtWidgetGeometry *, XtWidgetGeometry *) ;
+static XtGeometryResult TabsGeometryManager(Widget,
+ XtWidgetGeometry *, XtWidgetGeometry *) ;
+static void TabsChangeManaged( Widget w) ;
+
+static void TabsSelect(Widget, XEvent *, String *, Cardinal *) ;
+static void TabsPage(Widget, XEvent *, String *, Cardinal *) ;
+static void TabsHighlight(Widget, XEvent *, String *, Cardinal *) ;
+static void TabsUnhighlight(Widget, XEvent *, String *, Cardinal *) ;
+
+static void DrawTabs( TabsWidget tw, Bool labels) ;
+static void DrawTab( TabsWidget tw, Widget child, Bool labels) ;
+static void DrawFrame( TabsWidget tw) ;
+static void DrawTrim( TabsWidget, int x, int y,
+ int wid, int hgt, Bool bottom, Bool undraw) ;
+static void DrawBorder( TabsWidget tw, Widget child, Bool undraw) ;
+static void DrawHighlight( TabsWidget tw, Widget child, Bool undraw) ;
+static void UndrawTab( TabsWidget tw, Widget child) ;
+
+static void TabWidth( Widget w) ;
+static int TabLayout( TabsWidget, int wid, int hgt, Dimension *r_hgt,
+ Bool query_only) ;
+static void GetPreferredSizes(TabsWidget) ;
+static void MaxChild(TabsWidget) ;
+static void TabsShuffleRows( TabsWidget tw) ;
+static int PreferredSize( TabsWidget,
+ Dimension *reply_width, Dimension *reply_height,
+ Dimension *reply_cw, Dimension *reply_ch) ;
+static int PreferredSize2( TabsWidget, int cw, int ch,
+ Dimension *rw, Dimension *rh) ;
+static int PreferredSize3( TabsWidget, int wid, int hgt,
+ Dimension *rw, Dimension *rh) ;
+static void MakeSizeRequest(TabsWidget) ;
+
+static void TabsAllocGCs(TabsWidget) ;
+static void TabsFreeGCs(TabsWidget) ;
+static void getBitmapInfo( TabsWidget tw, TabsConstraints tab) ;
+static void TabsAllocFgGC( TabsWidget tw) ;
+static void TabsAllocGreyGC( TabsWidget tw) ;
+
+#endif
+
+#define AddRect(i,xx,yy,w,h) \
+ do{rects[(i)].x=(xx); rects[i].y=(yy); \
+ rects[i].width=(w); rects[i].height=(h);}while(0)
+
+static XtActionsRec actionsList[] =
+ {
+ {"select", TabsSelect},
+ {"page", TabsPage},
+ {"highlight", TabsHighlight},
+ {"unhighlight", TabsUnhighlight},
+ } ;
+
+
+/****************************************************************
+*
+* Full class record constant
+*
+****************************************************************/
+
+#ifndef NEED_MOTIF
+#define SuperClass (&constraintClassRec)
+#else
+#define SuperClass (&xmManagerClassRec)
+#endif
+
+TabsClassRec tabsClassRec = {
+ {
+/* core_class fields */
+ /* superclass */ (WidgetClass) SuperClass,
+ /* class_name */ "Tabs",
+ /* widget_size */ sizeof(TabsRec),
+ /* class_initialize */ TabsClassInit,
+ /* class_part_init */ NULL, /* TODO? */
+ /* class_inited */ FALSE,
+ /* initialize */ TabsInit,
+ /* initialize_hook */ NULL,
+ /* realize */ TabsRealize,
+ /* actions */ actionsList,
+ /* num_actions */ XtNumber(actionsList),
+ /* resources */ resources,
+ /* num_resources */ XtNumber(resources),
+ /* xrm_class */ NULLQUARK,
+ /* compress_motion */ TRUE,
+ /* compress_exposure */ TRUE,
+ /* compress_enterleave*/ TRUE,
+ /* visible_interest */ FALSE,
+ /* destroy */ TabsDestroy,
+ /* resize */ TabsResize,
+ /* expose */ TabsExpose,
+ /* set_values */ TabsSetValues,
+ /* set_values_hook */ NULL,
+ /* set_values_almost */ XtInheritSetValuesAlmost,
+ /* get_values_hook */ NULL,
+ /* accept_focus */ NULL,
+ /* version */ XtVersion,
+ /* callback_private */ NULL,
+ /* tm_table */ defaultTranslations,
+ /* query_geometry */ TabsQueryGeometry,
+ /* display_accelerator*/ XtInheritDisplayAccelerator,
+ /* extension */ NULL
+ },
+ {
+/* composite_class fields */
+ /* geometry_manager */ TabsGeometryManager,
+ /* change_managed */ TabsChangeManaged,
+ /* insert_child */ XtInheritInsertChild, /* TODO? */
+ /* delete_child */ XtInheritDeleteChild, /* TODO? */
+ /* extension */ NULL
+ },
+ {
+/* constraint_class fields */
+ /* subresources */ tabsConstraintResources,
+ /* subresource_count */ XtNumber(tabsConstraintResources),
+ /* constraint_size */ sizeof(TabsConstraintsRec),
+ /* initialize */ TabsConstraintInitialize,
+ /* destroy */ NULL,
+ /* set_values */ TabsConstraintSetValues,
+ /* extension */ NULL,
+ },
+#ifdef NEED_MOTIF
+/* Manager Class fields */
+ {
+ /* translations */ NULL,
+ /* syn_resources */ NULL,
+ /* num_syn_resources */ 0,
+ /* syn_constraint_resources */ NULL,
+ /* num_syn_constraint_resources */ 0,
+ /* parent_process */ XmInheritParentProcess,
+ /* extension */ NULL
+ },
+#endif
+ {
+/* Tabs class fields */
+ /* extension */ NULL,
+ }
+};
+
+WidgetClass tabsWidgetClass = (WidgetClass)&tabsClassRec;
+
+
+
+#ifdef DEBUG
+#ifdef __STDC__
+#define assert(e) \
+ if(!(e)) fprintf(stderr,"yak! %s at %s:%d\n",#e,__FILE__,__LINE__)
+#else
+#define assert(e) \
+ if(!(e)) fprintf(stderr,"yak! e at %s:%d\n",__FILE__,__LINE__)
+#endif
+#else
+#define assert(e)
+#endif
+
+
+\f
+
+/****************************************************************
+ *
+ * Member Procedures
+ *
+ ****************************************************************/
+
+static void
+TabsClassInit(void)
+{
+ defaultAccelerators = XtParseAcceleratorTable(accelTable) ;
+ /* TODO: register converter for labels? */
+}
+
+
+
+ /* Init a newly created tabs widget. Compute height of tabs
+ * and optionally compute size of widget. */
+
+/* ARGSUSED */
+
+static void
+TabsInit(Widget request, Widget new, ArgList args, Cardinal *num_args)
+{
+ TabsWidget newTw = (TabsWidget)new;
+
+ newTw->tabs.numRows = 0 ;
+ newTw->tabs.displayChildren = 0;
+
+ GetPreferredSizes(newTw) ;
+
+ /* height is easy, it's the same for all tabs:
+ * TODO: font height + height of tallest bitmap.
+ */
+ newTw->tabs.tab_height = 2 * newTw->tabs.internalHeight + SHADWID ;
+
+ if( newTw->tabs.font != NULL )
+ newTw->tabs.tab_height += newTw->tabs.font->max_bounds.ascent +
+ newTw->tabs.font->max_bounds.descent ;
+
+ /* GC allocation is deferred until XtRealize() */
+
+ /* if size not explicitly set, set it to our preferred size now. */
+
+ if( request->core.width == 0 || request->core.height == 0 )
+ {
+ Dimension w,h ;
+ PreferredSize(newTw, &w, &h, NULL,NULL) ;
+ if( request->core.width == 0 ) new->core.width = w ;
+ if( request->core.height == 0 ) new->core.height = h ;
+ XtClass(new)->core_class.resize(new) ;
+ }
+
+ /* defer GC allocation, etc., until Realize() time. */
+ newTw->tabs.foregroundGC =
+ newTw->tabs.backgroundGC =
+ newTw->tabs.greyGC =
+ newTw->tabs.topGC =
+ newTw->tabs.botGC = None ;
+
+ newTw->tabs.grey50 = None ;
+
+ newTw->tabs.needs_layout = False ;
+
+ newTw->tabs.hilight = NULL ;
+
+#ifdef NEED_MOTIF
+ newTw->manager.navigation_type = XmTAB_GROUP ;
+ newTw->manager.traversal_on = True ;
+#endif
+}
+
+
+ /* Init the constraint part of a new tab child. Compute the
+ * size of the tab.
+ */
+/* ARGSUSED */
+static void
+TabsConstraintInitialize(Widget request, Widget new,
+ ArgList args, Cardinal *num_args)
+{
+ TabsConstraints tab = (TabsConstraints) new->core.constraints ;
+ tab->tabs.greyAlloc = False ; /* defer allocation of pixel */
+ tab->tabs.queried = False ; /* defer size query */
+
+ getBitmapInfo((TabsWidget)XtParent(new), tab) ;
+ TabWidth(new) ;
+}
+
+
+
+ /* Called when tabs widget first realized. Create the window
+ * and allocate the GCs
+ */
+
+static void
+TabsRealize(Widget w, Mask *valueMask, XSetWindowAttributes *attributes)
+{
+ TabsWidget tw = (TabsWidget) w;
+
+ attributes->bit_gravity = NorthWestGravity;
+ *valueMask |= CWBitGravity;
+
+ SuperClass->core_class.realize(w, valueMask, attributes);
+
+ TabsAllocGCs(tw) ;
+}
+
+
+
+static void
+TabsDestroy(Widget w)
+{
+ TabsFreeGCs((TabsWidget)w) ;
+}
+
+
+ /* Parent has resized us. This will require that the tabs be
+ * laid out again.
+ */
+
+static void
+TabsResize(Widget w)
+{
+ TabsWidget tw = (TabsWidget) w;
+ int i ;
+ int num_children = tw->composite.num_children ;
+ Widget *childP ;
+ TabsConstraints tab ;
+ Dimension cw,ch,bw ;
+
+ /* Our size has now been dictated by the parent. Lay out the
+ * tabs, lay out the frame, lay out the children. Remember
+ * that the tabs overlap each other and the frame by shadowWidth.
+ * Also, the top tab is larger than the others, so if there's only
+ * one row, the widget must be made taller to accommodate this.
+ *
+ * Once the tabs are laid out, if there is more than one
+ * row, we may need to shuffle the rows to bring the top tab
+ * to the bottom row.
+ */
+
+ if( num_children > 0 && tw->composite.children != NULL )
+ {
+ /* Loop through the tabs and assign rows & x positions */
+ (void) TabLayout(tw, tw->core.width, tw->core.height, NULL, False) ;
+ num_children = tw->tabs.displayChildren;
+
+ /* assign a top widget, bring it to bottom row. */
+ TabsShuffleRows(tw) ;
+
+ /* now assign child positions & sizes. Positions are all the
+ * same: just inside the frame. Sizes are also all the same.
+ */
+
+ tw->tabs.child_width = cw = tw->core.width - 2 * SHADWID ;
+ tw->tabs.child_height = ch =
+ tw->core.height - tw->tabs.tab_total - 2 * SHADWID ;
+
+
+ for(i=0, childP=tw->composite.children;
+ i < num_children;
+ ++i, ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints) (*childP)->core.constraints ;
+ bw = tab->tabs.bwid ;
+ XtConfigureWidget(*childP, SHADWID,tw->tabs.tab_total+SHADWID,
+ cw-bw*2,ch-bw*2, bw) ;
+ }
+ if( XtIsRealized(w) )
+ XClearWindow(XtDisplay((Widget)tw), XtWindow((Widget)tw)) ;
+ }
+
+ tw->tabs.needs_layout = False ;
+} /* Resize */
+
+
+
+ /* Redraw entire Tabs widget */
+
+/* ARGSUSED */
+static void
+TabsExpose(Widget w, XEvent *event, Region region)
+{
+ TabsWidget tw = (TabsWidget) w;
+
+ if( tw->tabs.needs_layout )
+ XtClass(w)->core_class.resize(w) ;
+
+ DrawTabs(tw, True) ;
+}
+
+
+ /* Called when any Tabs widget resources are changed. */
+
+/* ARGSUSED */
+static Boolean
+TabsSetValues(Widget current, Widget request, Widget new,
+ ArgList args, Cardinal *num_args)
+{
+ TabsWidget curtw = (TabsWidget) current ;
+ TabsWidget tw = (TabsWidget) new ;
+ Boolean needRedraw = False ;
+ Widget *childP ;
+ int i ;
+
+
+ if( tw->tabs.font != curtw->tabs.font ||
+ tw->tabs.internalWidth != curtw->tabs.internalWidth ||
+ tw->tabs.internalHeight != curtw->tabs.internalHeight )
+ {
+ tw->tabs.tab_height = 2 * tw->tabs.internalHeight + SHADWID ;
+
+ if( tw->tabs.font != NULL )
+ tw->tabs.tab_height += tw->tabs.font->max_bounds.ascent +
+ tw->tabs.font->max_bounds.descent ;
+
+ /* Tab size has changed. Resize all tabs and request a new size */
+ for(i=0, childP=tw->composite.children;
+ i < tw->composite.num_children;
+ ++i, ++childP)
+ if( XtIsManaged(*childP) )
+ TabWidth(*childP) ;
+ PreferredSize(tw, &tw->core.width, &tw->core.height, NULL,NULL) ;
+ needRedraw = True ;
+ tw->tabs.needs_layout = True ;
+ }
+
+ /* TODO: if any color changes, need to recompute GCs and redraw */
+
+ if( tw->core.background_pixel != curtw->core.background_pixel ||
+ tw->core.background_pixmap != curtw->core.background_pixmap )
+ if( XtIsRealized(new) )
+ {
+ TabsFreeGCs(tw) ;
+ TabsAllocGCs(tw) ;
+ needRedraw = True ;
+ }
+
+ if( tw->core.sensitive != curtw->core.sensitive )
+ needRedraw = True ;
+
+ /* If top widget changes, need to change stacking order, redraw tabs.
+ * Window system will handle the redraws.
+ */
+
+ if( tw->tabs.topWidget != curtw->tabs.topWidget )
+ if( XtIsRealized(tw->tabs.topWidget) )
+ {
+ Widget w = tw->tabs.topWidget ;
+ TabsConstraints tab = (TabsConstraints) w->core.constraints ;
+
+ XRaiseWindow(XtDisplay(w), XtWindow(w)) ;
+#ifdef NEED_MOTIF
+ XtVaSetValues(curtw->tabs.topWidget, XmNtraversalOn, False, 0) ;
+ XtVaSetValues(w, XmNtraversalOn, True, 0) ;
+#endif
+
+ if( tab->tabs.row != tw->tabs.numRows-1 )
+ TabsShuffleRows(tw) ;
+
+ needRedraw = True ;
+ }
+ else
+ tw->tabs.needs_layout = True ;
+
+ return needRedraw ;
+}
+
+
+ /* Called when any child constraint resources change. */
+
+/* ARGSUSED */
+static Boolean
+TabsConstraintSetValues(Widget current, Widget request, Widget new,
+ ArgList args, Cardinal *num_args)
+{
+ TabsWidget tw = (TabsWidget) XtParent(new) ;
+ TabsConstraints ctab = (TabsConstraints) current->core.constraints ;
+ TabsConstraints tab = (TabsConstraints) new->core.constraints ;
+
+
+ /* if label changes, need to re-layout the entire widget */
+ /* if foreground changes, need to redraw tab label */
+
+ /* TODO: only need resize of new bitmap has different dimensions
+ * from old bitmap.
+ */
+
+ if( tab->tabs.label != ctab->tabs.label || /* Tab size has changed. */
+ tab->tabs.left_bitmap != ctab->tabs.left_bitmap )
+ {
+ TabWidth(new) ;
+ tw->tabs.needs_layout = True ;
+
+ if( tab->tabs.left_bitmap != ctab->tabs.left_bitmap )
+ getBitmapInfo(tw, tab) ;
+
+ /* If there are no subclass ConstraintSetValues procedures remaining
+ * to be invoked, and if the preferred size has changed, ask
+ * for a resize.
+ */
+ if( XtClass((Widget)tw) == tabsWidgetClass )
+ MakeSizeRequest(tw) ;
+ }
+
+
+ /* The child widget itself never needs a redisplay, but the parent
+ * Tabs widget might.
+ */
+
+ if( XtIsRealized(new) )
+ {
+ if( tw->tabs.needs_layout ) {
+ XClearWindow(XtDisplay((Widget)tw), XtWindow((Widget)tw)) ;
+ XtClass(tw)->core_class.expose((Widget)tw,NULL,None) ;
+ }
+
+ else if( tab->tabs.foreground != ctab->tabs.foreground )
+ DrawTab(tw, new, True) ;
+ }
+
+ return False ;
+}
+
+
+
+/*
+ * Return preferred size. Happily accept anything >= our preferred size.
+ * (TODO: is that the right thing to do? Should we always return "almost"
+ * if offerred more than we need?)
+ */
+
+static XtGeometryResult
+TabsQueryGeometry(Widget w,
+ XtWidgetGeometry *intended, XtWidgetGeometry *preferred)
+{
+ register TabsWidget tw = (TabsWidget)w ;
+ XtGeometryMask mode = intended->request_mode ;
+
+ preferred->request_mode = CWWidth | CWHeight ;
+ PreferredSize(tw, &preferred->width, &preferred->height, NULL,NULL) ;
+
+ if( (!(mode & CWWidth) || intended->width == w->core.width) &&
+ (!(mode & CWHeight) || intended->height == w->core.height) )
+ return XtGeometryNo ;
+
+#ifdef COMMENT
+ if( (!(mode & CWWidth) || intended->width >= preferred->width) &&
+ (!(mode & CWHeight) || intended->height >= preferred->height) )
+ return XtGeometryYes;
+#endif /* COMMENT */
+
+ return XtGeometryAlmost;
+}
+
+
+
+/*
+ * Geometry Manager; called when a child wants to be resized.
+ */
+
+static XtGeometryResult
+TabsGeometryManager(Widget w, XtWidgetGeometry *req, XtWidgetGeometry *reply)
+{
+ TabsWidget tw = (TabsWidget) XtParent(w);
+ Dimension s = SHADWID ;
+ TabsConstraints tab = (TabsConstraints)w->core.constraints;
+ XtGeometryResult result ;
+
+ /* Position request always denied */
+
+ if( ((req->request_mode & CWX) && req->x != w->core.x) ||
+ ((req->request_mode & CWY) && req->y != w->core.y) ||
+ !tab->tabs.resizable )
+ return XtGeometryNo ;
+
+ /* Make all three fields in the request valid */
+ if( !(req->request_mode & CWWidth) )
+ req->width = w->core.width;
+ if( !(req->request_mode & CWHeight) )
+ req->height = w->core.height;
+ if( !(req->request_mode & CWBorderWidth) )
+ req->border_width = w->core.border_width;
+
+ if( req->width == w->core.width &&
+ req->height == w->core.height &&
+ req->border_width == w->core.border_width )
+ return XtGeometryNo ;
+
+ /* updated cached preferred size of the child */
+ tab->tabs.bwid = req->border_width ;
+ tab->tabs.wid = req->width + req->border_width * 2 ;
+ tab->tabs.hgt = req->height + req->border_width * 2 ;
+ MaxChild(tw) ;
+
+
+ /* Size changes must see if the new size can be accommodated.
+ * The Tabs widget keeps all of its children the same
+ * size. A request to shrink will be accepted only if the
+ * new size is still big enough for all other children. A
+ * request to shrink that is not big enough for all children
+ * returns an "almost" response with the new proposed size.
+ * A request to grow will be accepted only if the Tabs parent can
+ * grow to accommodate.
+ *
+ * TODO:
+ * We could get fancy here and re-arrange the tabs if it is
+ * necessary to compromise with the parent, but we'll save that
+ * for another day.
+ */
+
+ if (req->request_mode & (CWWidth | CWHeight | CWBorderWidth))
+ {
+ Dimension rw,rh ; /* child's requested width, height */
+ Dimension cw,ch ; /* children's preferred size */
+ Dimension aw,ah ; /* available size we can give child */
+ Dimension th ; /* space used by tabs */
+ Dimension wid,hgt ; /* Tabs widget size */
+
+ rw = tab->tabs.wid ;
+ rh = tab->tabs.hgt ;
+
+ /* find out what the resulting preferred size would be */
+
+#ifdef COMMENT
+ MaxChild(tw, &cw, &ch) ;
+#endif /* COMMENT */
+ PreferredSize2(tw, tw->tabs.max_cw,tw->tabs.max_ch, &wid, &hgt) ;
+
+ /* Ask to be resized to accommodate. */
+
+ if( wid != tw->core.width || hgt != tw->core.height )
+ {
+ Dimension oldWid = tw->core.width, oldHgt = tw->core.height ;
+ XtWidgetGeometry myrequest, myreply ;
+
+ myrequest.width = wid ;
+ myrequest.height = hgt ;
+ myrequest.request_mode = CWWidth | CWHeight ;
+
+ /* If child is only querying, or if we're going to have to
+ * offer the child a compromise, then make this a query only.
+ */
+
+ if( (req->request_mode & XtCWQueryOnly) || rw < cw || rh < ch )
+ myrequest.request_mode |= XtCWQueryOnly ;
+
+ result = XtMakeGeometryRequest((Widget)tw, &myrequest, &myreply) ;
+
+ /* !$@# Box widget changes the core size even if QueryOnly
+ * is set. I'm convinced this is a bug. At any rate, to work
+ * around the bug, we need to restore the core size after every
+ * query geometry request. This is only partly effective,
+ * as there may be other boxes further up the tree.
+ */
+ if( myrequest.request_mode & XtCWQueryOnly ) {
+ tw->core.width = oldWid ;
+ tw->core.height = oldHgt ;
+ }
+
+ /* based on the parent's response, determine what the
+ * resulting Tabs widget size would be.
+ */
+
+ switch( result ) {
+ case XtGeometryYes:
+ case XtGeometryDone:
+ break ;
+
+ case XtGeometryNo:
+ wid = tw->core.width ;
+ hgt = tw->core.height ;
+ break ;
+
+ case XtGeometryAlmost:
+ wid = myreply.width ;
+ hgt = myreply.height ;
+ }
+ }
+
+ /* Within the constraints imposed by the parent, what is
+ * the max size we can give the child?
+ */
+ (void) TabLayout(tw, wid, hgt, &th, True) ;
+ aw = wid - 2*s ;
+ ah = hgt - th - 2*s ;
+
+ /* OK, make our decision. If requested size is >= max sibling
+ * preferred size, AND requested size <= available size, then
+ * we accept. Otherwise, we offer a compromise.
+ */
+
+ if( rw == aw && rh == ah )
+ {
+ /* Acceptable. If this wasn't a query, change *all* children
+ * to this size.
+ */
+ if( req->request_mode & XtCWQueryOnly )
+ return XtGeometryYes ;
+ else
+ {
+ Widget *childP = tw->composite.children ;
+ int i,bw ;
+ w->core.border_width = req->border_width ;
+ for(i=tw->tabs.displayChildren; --i >= 0; ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ bw = (*childP)->core.border_width ;
+ XtConfigureWidget(*childP, s,tw->tabs.tab_total+s,
+ rw-2*bw, rh-2*bw, bw) ;
+ }
+#ifdef COMMENT
+ /* TODO: under what conditions will we need to redraw? */
+ XClearWindow(XtDisplay((Widget)tw), XtWindow((Widget)tw)) ;
+ XtClass(tw)->core_class.expose((Widget)tw,NULL,NULL) ;
+#endif /* COMMENT */
+ return XtGeometryDone ;
+ }
+ }
+
+ /* Cannot grant child's request. Describe what we *can* do
+ * and return counter-offer.
+ */
+ reply->width = aw - 2 * req->border_width ;
+ reply->height = ah - 2 * req->border_width ;
+ reply->border_width = req->border_width ;
+ reply->request_mode = CWWidth | CWHeight | CWBorderWidth ;
+ return XtGeometryAlmost ;
+ }
+
+ return XtGeometryYes ;
+}
+
+
+
+
+ /* The number of children we manage has changed; recompute
+ * size from scratch.
+ */
+
+static void
+TabsChangeManaged(Widget w)
+{
+ TabsWidget tw = (TabsWidget)w ;
+ Widget *childP = tw->composite.children ;
+ int i ;
+
+ if( tw->tabs.topWidget != NULL &&
+ ( !XtIsManaged(tw->tabs.topWidget) ||
+ tw->tabs.topWidget->core.being_destroyed ) )
+ tw->tabs.topWidget = NULL ;
+
+ GetPreferredSizes(tw) ;
+ MakeSizeRequest(tw) ;
+
+ XtClass(w)->core_class.resize(w) ;
+ if( XtIsRealized(w) )
+ {
+ Display *dpy = XtDisplay(w) ;
+ XClearWindow(dpy, XtWindow(w)) ;
+ XtClass(w)->core_class.expose(w,NULL,NULL) ;
+
+ /* make sure the top widget stays on top. This requires
+ * making sure that all new children are realized first.
+ */
+ if( tw->tabs.topWidget != NULL && XtIsRealized(tw->tabs.topWidget) )
+ {
+ for(i=tw->tabs.displayChildren; --i >= 0; ++childP)
+ if( !XtIsRealized(*childP) )
+ XtRealizeWidget(*childP) ;
+
+ XRaiseWindow(dpy, XtWindow(tw->tabs.topWidget)) ;
+ }
+ }
+
+#ifdef NEED_MOTIF
+ /* Only top widget may receive input */
+
+ for(childP = tw->composite.children, i=tw->composite.num_children;
+ --i >= 0;
+ ++childP)
+ {
+ XtVaSetValues(*childP, XmNtraversalOn, False, 0) ;
+ }
+
+ if( tw->tabs.topWidget != NULL )
+ XtVaSetValues(tw->tabs.topWidget, XmNtraversalOn, True, 0) ;
+#endif
+
+
+
+}
+
+
+\f
+
+/****************************************************************
+ *
+ * Action Procedures
+ *
+ ****************************************************************/
+
+
+ /* User clicks on a tab, figure out which one it was. */
+
+/* ARGSUSED */
+static void
+TabsSelect(Widget w, XEvent *event, String *params, Cardinal *num_params)
+{
+ TabsWidget tw = (TabsWidget) w ;
+ Widget *childP ;
+ Position x,y ;
+ Dimension h = tw->tabs.tab_height ;
+ int i ;
+
+#ifdef NEED_MOTIF
+ XmProcessTraversal (w, XmTRAVERSE_CURRENT) ;
+#endif
+
+ /* TODO: is there an Xmu function or something to do this instead? */
+ switch( event->type ) {
+ case ButtonPress:
+ case ButtonRelease:
+ x = event->xbutton.x ; y = event->xbutton.y ; break ;
+ case KeyPress:
+ case KeyRelease:
+ x = event->xkey.x ; y = event->xkey.y ; break ;
+ default:
+ return ;
+ }
+
+ /* TODO: determine which tab was clicked, if any. Set that
+ * widget to be top of stacking order with XawTabsSetTop().
+ */
+ for(i=0, childP=tw->composite.children;
+ i < tw->tabs.displayChildren;
+ ++i, ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ TabsConstraints tab = (TabsConstraints)(*childP)->core.constraints;
+ if( x > tab->tabs.x && x < tab->tabs.x + tab->tabs.width &&
+ y > tab->tabs.y && y < tab->tabs.y + h )
+ {
+ if( *childP != tw->tabs.topWidget &&
+ (XtIsSensitive(*childP) || tw->tabs.selectInsensitive) )
+ XawTabsSetTop(*childP, True) ;
+ break ;
+ }
+ }
+}
+
+
+ /* User hits a key */
+
+static void
+TabsPage(Widget w, XEvent *event, String *params, Cardinal *num_params)
+{
+ TabsWidget tw = (TabsWidget) w ;
+ Widget newtop ;
+ Widget *childP ;
+ int idx ;
+ int i ;
+ int nc = tw->composite.num_children ;
+
+ if( nc <= 0 )
+ return ;
+
+ if( *num_params < 1 ) {
+ XtAppWarning(XtWidgetToApplicationContext(w),
+ "Tabs: page() action called with no arguments") ;
+ return ;
+ }
+
+ if( tw->tabs.topWidget == NULL )
+ tw->tabs.topWidget = tw->composite.children[0] ;
+
+ for(idx=0, childP=tw->composite.children; idx < nc; ++idx, ++childP )
+ if( tw->tabs.topWidget == *childP )
+ break ;
+
+ switch( params[0][0] ) {
+ case 'u': /* up */
+ case 'U':
+ if( idx == 0 )
+ idx = nc ;
+ newtop = tw->composite.children[idx-1] ;
+ break ;
+
+ case 'd': /* down */
+ case 'D':
+ if( ++idx >= nc )
+ idx = 0 ;
+ newtop = tw->composite.children[idx] ;
+ break ;
+
+ case 'h':
+ case 'H':
+ newtop = tw->composite.children[0] ;
+ break ;
+
+ case 'e':
+ case 'E':
+ newtop = tw->composite.children[nc-1] ;
+ break ;
+
+ case 's': /* selected */
+ case 'S':
+ if( (newtop = tw->tabs.hilight) == NULL )
+ return ;
+ break ;
+ }
+
+ XawTabsSetTop(newtop, True) ;
+}
+
+
+ /* User hits up/down key */
+
+static void
+TabsHighlight(Widget w, XEvent *event, String *params, Cardinal *num_params)
+{
+ TabsWidget tw = (TabsWidget) w ;
+ Widget newhl ;
+ Widget *childP ;
+ int idx ;
+ int i ;
+ int nc = tw->composite.num_children ;
+
+ if( nc <= 0 )
+ return ;
+
+ if( *num_params < 1 )
+ {
+ if( tw->tabs.hilight != NULL )
+ DrawHighlight(tw, tw->tabs.hilight, False) ;
+ return ;
+ }
+
+ if( tw->tabs.hilight == NULL )
+ newhl = tw->composite.children[0] ;
+
+ else
+ {
+ for(idx=0, childP=tw->composite.children; idx < nc; ++idx, ++childP )
+ if( tw->tabs.hilight == *childP )
+ break ;
+
+ switch( params[0][0] ) {
+ case 'u': /* up */
+ case 'U':
+ if( idx == 0 )
+ idx = nc ;
+ newhl = tw->composite.children[idx-1] ;
+ break ;
+
+ case 'd': /* down */
+ case 'D':
+ if( ++idx >= nc )
+ idx = 0 ;
+ newhl = tw->composite.children[idx] ;
+ break ;
+
+ case 'h':
+ case 'H':
+ newhl = tw->composite.children[0] ;
+ break ;
+
+ case 'e':
+ case 'E':
+ newhl = tw->composite.children[nc-1] ;
+ break ;
+ }
+ }
+
+ XawTabsSetHighlight(w, newhl) ;
+}
+
+
+
+static void
+TabsUnhighlight(Widget w, XEvent *event, String *params, Cardinal *num_params)
+{
+ TabsWidget tw = (TabsWidget) w ;
+ int nc = tw->composite.num_children ;
+
+ if( nc <= 0 )
+ return ;
+
+ if( tw->tabs.hilight != NULL )
+ DrawHighlight(tw, tw->tabs.hilight, True) ;
+}
+
+
+
+\f
+
+/****************************************************************
+ *
+ * Public Procedures
+ *
+ ****************************************************************/
+
+
+ /* Set the top tab, optionally call all callbacks. */
+void
+XawTabsSetTop(Widget w, Bool callCallbacks)
+{
+ TabsWidget tw = (TabsWidget)w->core.parent ;
+ TabsConstraints tab ;
+ Widget oldtop = tw->tabs.topWidget ;
+
+ if( !XtIsSubclass(w->core.parent, tabsWidgetClass) )
+ {
+ char line[1024] ;
+ sprintf(line, "XawTabsSetTop: widget \"%s\" is not the child of a tabs widget.", XtName(w)) ;
+ XtAppWarning(XtWidgetToApplicationContext(w), line) ;
+ return ;
+ }
+
+ if( callCallbacks )
+ XtCallCallbackList(w, tw->tabs.popdownCallbacks,
+ (XtPointer)tw->tabs.topWidget) ;
+
+ if( !XtIsRealized(w) ) {
+ tw->tabs.topWidget = w ;
+ tw->tabs.needs_layout = True ;
+ return ;
+ }
+
+ XRaiseWindow(XtDisplay(w), XtWindow(w)) ;
+#ifdef NEED_MOTIF
+ XtVaSetValues(oldtop, XmNtraversalOn, False, 0) ;
+ XtVaSetValues(w, XmNtraversalOn, True, 0) ;
+#endif
+
+ tab = (TabsConstraints) w->core.constraints ;
+ if( tab->tabs.row == 0 )
+ {
+ /* Easy case; undraw current top, undraw new top, assign new
+ * top, redraw all borders.
+ * We *could* just erase and execute a full redraw, but I like to
+ * reduce screen flicker.
+ */
+ UndrawTab(tw, oldtop) ; /* undraw old */
+ DrawBorder(tw, oldtop, True) ;
+ UndrawTab(tw, w) ; /* undraw new */
+ DrawBorder(tw, w, True) ;
+ tw->tabs.topWidget = w ;
+ DrawTab(tw, oldtop, True) ; /* redraw old */
+ DrawTab(tw, w, True) ; /* redraw new */
+ DrawTabs(tw, False) ;
+ }
+ else
+ {
+ tw->tabs.topWidget = w ;
+ TabsShuffleRows(tw) ;
+ XClearWindow(XtDisplay((Widget)tw), XtWindow((Widget)tw)) ;
+ XtClass(tw)->core_class.expose((Widget)tw,NULL,None) ;
+ }
+
+ XawTabsSetHighlight((Widget)tw, w) ;
+
+ if( callCallbacks )
+ XtCallCallbackList(w, tw->tabs.callbacks, (XtPointer)w) ;
+}
+
+
+ /* Set the top tab, optionally call all callbacks. */
+void
+XawTabsSetHighlight(Widget t, Widget w)
+{
+ TabsWidget tw = (TabsWidget)t ;
+ TabsConstraints tab ;
+ Widget oldtop = tw->tabs.topWidget ;
+
+ if( !XtIsSubclass(t, tabsWidgetClass) )
+ return ;
+
+ if( XtIsRealized(t) && w != tw->tabs.hilight )
+ {
+ if( tw->tabs.hilight != NULL )
+ DrawHighlight(tw, tw->tabs.hilight, True) ;
+ if( w != NULL )
+ DrawHighlight(tw, w, False) ;
+ }
+
+ tw->tabs.hilight = w ;
+}
+
+
+\f
+
+/****************************************************************
+ *
+ * Private Procedures
+ *
+ ****************************************************************/
+
+
+static void
+TabsAllocGCs(TabsWidget tw)
+{
+ TabsAllocFgGC(tw) ;
+ TabsAllocGreyGC(tw) ;
+ tw->tabs.backgroundGC = AllocBackgroundGC((Widget)tw, None) ;
+ tw->tabs.topGC = AllocTopShadowGC((Widget)tw,
+ tw->tabs.top_shadow_contrast, tw->tabs.be_nice_to_cmap) ;
+ tw->tabs.botGC = AllocBotShadowGC((Widget)tw,
+ tw->tabs.bot_shadow_contrast, tw->tabs.be_nice_to_cmap) ;
+}
+
+
+static void
+TabsFreeGCs(TabsWidget tw)
+{
+ Widget w = (Widget) tw;
+
+ XtReleaseGC(w, tw->tabs.foregroundGC) ;
+ XtReleaseGC(w, tw->tabs.greyGC) ;
+ XtReleaseGC(w, tw->tabs.backgroundGC) ;
+ XtReleaseGC(w, tw->tabs.topGC) ;
+ XtReleaseGC(w, tw->tabs.botGC) ;
+#ifdef HAVE_XMU
+ XmuReleaseStippledPixmap(XtScreen(w), tw->tabs.grey50) ;
+#endif
+}
+
+
+
+
+
+ /* Redraw entire Tabs widget */
+
+static void
+DrawTabs(TabsWidget tw, Bool labels)
+{
+ Widget *childP ;
+ int i,j ;
+ Dimension s = SHADWID ;
+ Dimension th = tw->tabs.tab_height ;
+ Position y ;
+ TabsConstraints tab ;
+
+ if( !XtIsRealized((Widget)tw))
+ return ;
+
+ /* draw tabs and frames by row except for the top tab, which
+ * is drawn last. (This is inefficiently written, but should not
+ * be too slow as long as there are not a lot of rows.)
+ */
+
+ y = tw->tabs.numRows == 1 ? TABDELTA : 0 ;
+ for(i=0; i<tw->tabs.numRows; ++i, y += th)
+ {
+ for( j=tw->tabs.displayChildren, childP=tw->composite.children;
+ --j >= 0; ++childP )
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints)(*childP)->core.constraints;
+ if( tab->tabs.row == i && *childP != tw->tabs.topWidget )
+ DrawTab(tw, *childP, labels) ;
+ }
+ if( i != tw->tabs.numRows -1 )
+ DrawTrim(tw, 0,y+th, tw->core.width, th+s, False,False) ;
+ }
+
+ DrawFrame(tw) ;
+
+ /* and now the top tab */
+ if( tw->tabs.topWidget != NULL )
+ DrawTab(tw, tw->tabs.topWidget, labels) ;
+}
+
+
+
+/* Draw one tab. Corners are rounded very slightly. */
+
+static void
+DrawTab(TabsWidget tw, Widget child, Bool labels)
+{
+ GC gc ;
+ int x,y ;
+
+ if( !XtIsRealized((Widget)tw))
+ return ;
+
+ DrawBorder(tw, child, False) ;
+
+ if( labels )
+ {
+ TabsConstraints tab = (TabsConstraints)child->core.constraints;
+ Display *dpy = XtDisplay((Widget)tw) ;
+ Window win = XtWindow((Widget)tw) ;
+ String lbl = tab->tabs.label != NULL ?
+ tab->tabs.label : XtName(child) ;
+
+ if( XtIsSensitive(child) )
+ {
+ gc = tw->tabs.foregroundGC ;
+ XSetForeground(dpy, gc, tab->tabs.foreground) ;
+ }
+ else
+ {
+ /* grey pixel allocation deferred until now */
+ if( !tab->tabs.greyAlloc )
+ {
+ if( tw->tabs.be_nice_to_cmap || tw->core.depth == 1 )
+ tab->tabs.grey = tab->tabs.foreground ;
+ else
+ tab->tabs.grey = AllocGreyPixel((Widget)tw,
+ tab->tabs.foreground,
+ tw->core.background_pixel,
+ tw->tabs.insensitive_contrast ) ;
+ tab->tabs.greyAlloc = True ;
+ }
+ gc = tw->tabs.greyGC ;
+ XSetForeground(dpy, gc, tab->tabs.grey) ;
+ }
+
+ x = tab->tabs.x ;
+ y = tab->tabs.y ;
+ if( child == tw->tabs.topWidget )
+ y -= TABLDELTA ;
+
+ if( tab->tabs.left_bitmap != None && tab->tabs.lbm_width > 0 )
+ {
+ if( tab->tabs.lbm_depth == 1 )
+ XCopyPlane(dpy, tab->tabs.left_bitmap, win,gc,
+ 0,0, tab->tabs.lbm_width, tab->tabs.lbm_height,
+ x+tab->tabs.lbm_x, y+tab->tabs.lbm_y, 1L) ;
+ else
+ XCopyArea(dpy, tab->tabs.left_bitmap, win,gc,
+ 0,0, tab->tabs.lbm_width, tab->tabs.lbm_height,
+ x+tab->tabs.lbm_x, y+tab->tabs.lbm_y) ;
+ }
+
+ if( lbl != NULL && tw->tabs.font != NULL )
+ XDrawString(dpy,win,gc,
+ x+tab->tabs.l_x, y+tab->tabs.l_y,
+ lbl, (int)strlen(lbl)) ;
+ }
+
+ if( child == tw->tabs.hilight )
+ DrawHighlight(tw, child, False) ;
+}
+
+
+ /* draw frame all the way around the child windows. */
+
+static void
+DrawFrame(TabsWidget tw)
+{
+ GC topgc = tw->tabs.topGC ;
+ GC botgc = tw->tabs.botGC ;
+ Dimension s = SHADWID ;
+ Dimension ch = tw->tabs.child_height ;
+ Draw3dBox((Widget)tw, 0,tw->tabs.tab_total,
+ tw->core.width, ch+2*s, s, topgc, botgc) ;
+}
+
+
+ /* draw trim around a tab or underneath a row of tabs */
+
+static void
+DrawTrim(TabsWidget tw, /* widget */
+ int x, /* upper-left corner */
+ int y,
+ int wid, /* total size */
+ int hgt,
+ Bool bottom, /* draw bottom? */
+ Bool undraw) /* undraw all */
+{
+ Display *dpy = XtDisplay((Widget)tw) ;
+ Window win = XtWindow((Widget)tw) ;
+ GC bggc = tw->tabs.backgroundGC ;
+ GC topgc = undraw ? bggc : tw->tabs.topGC ;
+ GC botgc = undraw ? bggc : tw->tabs.botGC ;
+ if( bottom )
+ XDrawLine(dpy,win,bggc, x,y+hgt-1, x+wid-1,y+hgt-1) ; /* bottom */
+ XDrawLine(dpy,win,topgc, x,y+2, x,y+hgt-2) ; /* left */
+ XDrawPoint(dpy,win,topgc, x+1,y+1) ; /* corner */
+ XDrawLine(dpy,win,topgc, x+2,y, x+wid-3,y) ; /* top */
+ XDrawLine(dpy,win,botgc, x+wid-2,y+1, x+wid-2,y+hgt-2) ; /* right */
+ XDrawLine(dpy,win,botgc, x+wid-1,y+2, x+wid-1,y+hgt-2) ; /* right */
+}
+
+
+/* Draw one tab border. */
+
+static void
+DrawBorder(TabsWidget tw, Widget child, Bool undraw)
+{
+ TabsConstraints tab = (TabsConstraints)child->core.constraints;
+ Position x = tab->tabs.x ;
+ Position y = tab->tabs.y ;
+ Dimension twid = tab->tabs.width ;
+ Dimension thgt = tw->tabs.tab_height ;
+
+ /* top tab requires a little special attention; it overlaps
+ * neighboring tabs slightly, so the background must be cleared
+ * in the region of the overlap to partially erase those neighbors.
+ * TODO: is this worth doing with regions instead?
+ */
+ if( child == tw->tabs.topWidget )
+ {
+ Display *dpy = XtDisplay((Widget)tw) ;
+ Window win = XtWindow((Widget)tw) ;
+ GC bggc = tw->tabs.backgroundGC ;
+ XRectangle rects[3] ;
+ x -= TABDELTA ;
+ y -= TABDELTA ;
+ twid += TABDELTA*2 ;
+ thgt += TABDELTA ;
+ AddRect(0, x,y+1,twid,TABDELTA) ;
+ AddRect(1, x+1,y,TABDELTA,thgt) ;
+ AddRect(2, x+twid-TABDELTA-1,y,TABDELTA,thgt) ;
+ XFillRectangles(dpy,win,bggc, rects, 3) ;
+ }
+
+ DrawTrim(tw, x,y,twid,thgt+1, child == tw->tabs.topWidget, undraw) ;
+}
+
+
+/* Draw highlight around tab that has focus */
+
+static void
+DrawHighlight(TabsWidget tw, Widget child, Bool undraw)
+{
+ TabsConstraints tab = (TabsConstraints)child->core.constraints;
+ Display *dpy = XtDisplay((Widget)tw) ;
+ Window win = XtWindow((Widget)tw) ;
+ GC gc ;
+ Position x = tab->tabs.x ;
+ Position y = tab->tabs.y ;
+ Dimension wid = tab->tabs.width ;
+ Dimension hgt = tw->tabs.tab_height ;
+ XPoint points[6] ;
+
+ /* top tab does not have a highlight */
+
+ if( child == tw->tabs.topWidget )
+ return ;
+
+ if( undraw )
+ gc = tw->tabs.backgroundGC ;
+
+ else if( XtIsSensitive(child) )
+ {
+ gc = tw->tabs.foregroundGC ;
+ XSetForeground(dpy, gc, tab->tabs.foreground) ;
+ }
+ else
+ {
+ gc = tw->tabs.greyGC ;
+ XSetForeground(dpy, gc, tab->tabs.grey) ;
+ }
+
+ points[0].x = x+1 ; points[0].y = y+hgt-1 ;
+ points[1].x = x+1 ; points[1].y = y+2 ;
+ points[2].x = x+2 ; points[2].y = y+1 ;
+ points[3].x = x+wid-4 ; points[3].y = y+1 ;
+ points[4].x = x+wid-3 ; points[4].y = y+2 ;
+ points[5].x = x+wid-3 ; points[5].y = y+hgt-1 ;
+
+ XDrawLines(dpy,win,gc, points,6, CoordModeOrigin) ;
+}
+
+
+/* Undraw one tab interior */
+
+static void
+UndrawTab(TabsWidget tw, Widget child)
+{
+ TabsConstraints tab = (TabsConstraints)child->core.constraints;
+ Position x = tab->tabs.x ;
+ Position y = tab->tabs.y ;
+ Dimension twid = tab->tabs.width ;
+ Dimension thgt = tw->tabs.tab_height ;
+ Display *dpy = XtDisplay((Widget)tw) ;
+ Window win = XtWindow((Widget)tw) ;
+ GC bggc = tw->tabs.backgroundGC ;
+
+ XFillRectangle(dpy,win,bggc, x,y, twid,thgt) ;
+}
+
+
+
+
+\f
+ /* GEOMETRY UTILITIES */
+
+
+ /* Compute the size of one child's tab. Positions will be computed
+ * elsewhere.
+ *
+ * height: font height + vertical_space*2 + shadowWid*2
+ * width: string width + horizontal_space*2 + shadowWid*2
+ *
+ * All tabs are the same height, so that is computed elsewhere.
+ */
+
+static void
+TabWidth(Widget w)
+{
+ TabsConstraints tab = (TabsConstraints) w->core.constraints ;
+ TabsWidget tw = (TabsWidget)XtParent(w) ;
+ String lbl = tab->tabs.label != NULL ?
+ tab->tabs.label : XtName(w) ;
+ XFontStruct *font = tw->tabs.font ;
+ int iw = tw->tabs.internalWidth ;
+
+ tab->tabs.width = iw + SHADWID*2 ;
+ tab->tabs.l_x = tab->tabs.lbm_x = SHADWID + iw ;
+
+ if( tab->tabs.left_bitmap != None )
+ {
+ tab->tabs.width += tab->tabs.lbm_width + iw ;
+ tab->tabs.l_x += tab->tabs.lbm_width + iw ;
+ tab->tabs.lbm_y = (tw->tabs.tab_height - tab->tabs.lbm_height)/2 ;
+ }
+
+ if( lbl != NULL && font != NULL )
+ {
+ tab->tabs.width += XTextWidth( font, lbl, (int)strlen(lbl) ) + iw ;
+ tab->tabs.l_y = (tw->tabs.tab_height +
+ tw->tabs.font->max_bounds.ascent -
+ tw->tabs.font->max_bounds.descent)/2 ;
+ }
+}
+
+
+
+ /* Lay out tabs to fit in given width. Compute x,y position and
+ * row number for each tab. Return number of rows and total height
+ * required by all tabs. If there is only one row, add TABDELTA
+ * height to the total. Rows are assigned bottom to top.
+ *
+ * Tabs are indented from the edges by INDENT.
+ *
+ * TODO: if they require more than two rows and the total height:width
+ * ratio is more than 2:1, then try something else.
+ */
+
+static int
+TabLayout(TabsWidget tw, int wid, int hgt, Dimension *reply_height, Bool query_only)
+{
+ int i, row ;
+ int num_children = tw->composite.num_children ;
+ Widget *childP ;
+ Dimension w ;
+ Position x,y ;
+ TabsConstraints tab ;
+
+ if (!query_only)
+ tw->tabs.displayChildren = 0;
+
+ /* Algorithm: loop through children, assign X positions. If a tab
+ * would extend beyond the right edge, start a new row. After all
+ * rows are assigned, make a second pass and assign Y positions.
+ */
+
+ if( num_children > 0 )
+ {
+ /* Loop through the tabs and see how much space they need. */
+
+ row = 0 ;
+ x = INDENT ;
+ y = 0 ;
+ wid -= INDENT ;
+ for(i=num_children, childP=tw->composite.children; --i >= 0; ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints) (*childP)->core.constraints ;
+ w = tab->tabs.width ;
+ if( x + w > wid ) { /* new row */
+ if (y + tw->tabs.tab_height > hgt)
+ break;
+ ++row ;
+ x = INDENT ;
+ y += tw->tabs.tab_height ;
+ }
+ if( !query_only ) {
+ tab->tabs.x = x ;
+ tab->tabs.y = y ;
+ tab->tabs.row = row ;
+ }
+ x += w + SPACING ;
+ if (!query_only)
+ tw->tabs.displayChildren++;
+ }
+ /* If there was only one row, increse the height by TABDELTA */
+ if( ++row == 1 )
+ {
+ y = TABDELTA ;
+ if( !query_only )
+ for(i=num_children, childP=tw->composite.children;
+ --i >= 0 ; ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints) (*childP)->core.constraints ;
+ tab->tabs.y = y ;
+ }
+ }
+ y += tw->tabs.tab_height ;
+ }
+ else
+ row = y = 0 ;
+
+ if( !query_only ) {
+ tw->tabs.tab_total = y ;
+ tw->tabs.numRows = row ;
+ }
+
+ if( reply_height != NULL )
+ *reply_height = y ;
+
+ return row ;
+}
+
+
+
+ /* Find max preferred child size. Returned sizes include child
+ * border widths. We only ever ask a child its preferred
+ * size once. After that, the preferred size is updated only
+ * if the child makes a geometry request.
+ */
+
+static void
+GetPreferredSizes(TabsWidget tw)
+{
+ int i ;
+ Widget *childP = tw->composite.children ;
+ XtWidgetGeometry preferred ;
+ TabsConstraints tab ;
+ Dimension cw = 0, ch = 0 ;
+
+ for(i=tw->tabs.displayChildren; --i >= 0; ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints) (*childP)->core.constraints ;
+ if( !tab->tabs.queried ) {
+ (void) XtQueryGeometry(*childP, NULL, &preferred) ;
+ tab->tabs.bwid = preferred.border_width ;
+ tab->tabs.wid = preferred.width + preferred.border_width * 2 ;
+ tab->tabs.hgt = preferred.height + preferred.border_width * 2 ;
+ tab->tabs.queried = True ;
+ }
+ cw = Max(cw, tab->tabs.wid ) ;
+ ch = Max(ch, tab->tabs.hgt ) ;
+ }
+ tw->tabs.max_cw = cw ;
+ tw->tabs.max_ch = ch ;
+}
+
+
+
+ /* Find max preferred child size. Returned sizes include child
+ * border widths. */
+
+static void
+MaxChild(TabsWidget tw)
+{
+ Dimension cw,ch ; /* child width, height */
+ int i ;
+ Widget *childP = tw->composite.children ;
+ TabsConstraints tab ;
+
+ cw = ch = 0 ;
+
+ for(i=tw->composite.num_children; --i >=0; ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints) (*childP)->core.constraints ;
+ cw = Max(cw, tab->tabs.wid ) ;
+ ch = Max(ch, tab->tabs.hgt ) ;
+ }
+
+ tw->tabs.max_cw = cw ;
+ tw->tabs.max_ch = ch ;
+}
+
+
+
+ /* rotate row numbers to bring current widget to bottom row,
+ * compute y positions for all tabs
+ */
+
+static void
+TabsShuffleRows(TabsWidget tw)
+{
+ TabsConstraints tab ;
+ int move ;
+ int nrows ;
+ Widget *childP ;
+ Dimension th = tw->tabs.tab_height ;
+ Position bottom ;
+ int i ;
+
+ /* There must be a top widget. If not, assign one. */
+ if( tw->tabs.topWidget == NULL && tw->composite.children != NULL )
+ for(i=tw->composite.num_children, childP=tw->composite.children;
+ --i >= 0;
+ ++childP)
+ if( XtIsManaged(*childP) ) {
+ tw->tabs.topWidget = *childP ;
+ break ;
+ }
+
+ if( tw->tabs.topWidget != NULL )
+ {
+ nrows = tw->tabs.numRows ;
+ assert( nrows > 0 ) ;
+
+ if( nrows > 1 )
+ {
+ tab = (TabsConstraints) tw->tabs.topWidget->core.constraints ;
+ assert( tab != NULL ) ;
+
+ /* how far to move top row */
+ move = nrows - tab->tabs.row ;
+ bottom = tw->tabs.tab_total - th ;
+
+ for(i=tw->tabs.displayChildren, childP=tw->composite.children;
+ --i >= 0;
+ ++childP)
+ if( XtIsManaged(*childP) )
+ {
+ tab = (TabsConstraints) (*childP)->core.constraints ;
+ tab->tabs.row = (tab->tabs.row + move) % nrows ;
+ tab->tabs.y = bottom - tab->tabs.row * th ;
+ }
+ }
+ }
+}
+
+
+ /* find preferred size. Ask children, find size of largest,
+ * add room for tabs & return. This can get a little involved,
+ * as we don't want to have too many rows of tabs; we may widen
+ * the widget to reduce # of rows.
+ */
+
+static int
+PreferredSize(
+ TabsWidget tw,
+ Dimension *reply_width, /* total widget size */
+ Dimension *reply_height,
+ Dimension *reply_cw, /* child widget size */
+ Dimension *reply_ch)
+{
+ Dimension cw,ch ; /* child width, height */
+ Dimension wid,hgt ;
+ Dimension rwid,rhgt ;
+ int nrow ;
+
+
+ /* find max desired child height */
+#ifdef COMMENT
+ MaxChild(tw, &cw, &ch) ;
+#endif /* COMMENT */
+
+ wid = cw = tw->tabs.max_cw ;
+ hgt = ch = tw->tabs.max_ch ;
+
+ nrow = PreferredSize2(tw, wid,hgt, &rwid, &rhgt) ;
+
+ /* Check for absurd results (more than 2 rows, high aspect
+ * ratio). Try wider size if needed.
+ * TODO: make sure this terminates.
+ */
+
+ if( nrow > 2 && rhgt > rwid )
+ {
+ Dimension w0, w1 ;
+
+ /* step 1: start doubling size until it's too big */
+ do {
+ w0 = wid ;
+ wid = Max(wid*2, wid+20) ;
+ nrow = PreferredSize2(tw, wid,hgt, &rwid,&rhgt) ;
+ } while( nrow > 2 && rhgt > rwid ) ;
+ w1 = wid ;
+
+ /* step 2: use Newton's method to find ideal size. Stop within
+ * 8 pixels.
+ */
+ while( w1 > w0 + 8 )
+ {
+ wid = (w0+w1)/2 ;
+ nrow = PreferredSize2(tw, wid,hgt, &rwid,&rhgt) ;
+ if( nrow > 2 && rhgt > rwid )
+ w0 = wid ;
+ else
+ w1 = wid ;
+ }
+ wid = w1 ;
+ }
+
+ *reply_width = rwid ;
+ *reply_height = rhgt ;
+ if( reply_cw != NULL ) *reply_cw = cw ;
+ if( reply_ch != NULL ) *reply_ch = ch ;
+ return nrow ;
+}
+
+
+ /* Find preferred size, given size of children. */
+
+static int
+PreferredSize2(
+ TabsWidget tw,
+ int cw, /* child width, height */
+ int ch,
+ Dimension *reply_width, /* total widget size */
+ Dimension *reply_height)
+{
+ Dimension s = SHADWID ;
+
+ /* make room for shadow frame */
+ cw += s*2 ;
+ ch += s*2 ;
+
+ return PreferredSize3(tw, cw, ch, reply_width, reply_height) ;
+}
+
+
+ /* Find preferred size, given size of children+shadow. */
+
+static int
+PreferredSize3(
+ TabsWidget tw,
+ int wid, /* child width, height */
+ int hgt,
+ Dimension *reply_width, /* total widget size */
+ Dimension *reply_height)
+{
+ Dimension th ; /* space used by tabs */
+ int nrows ;
+
+ if( tw->composite.num_children > 0 )
+ nrows = TabLayout(tw, wid, hgt, &th, True) ;
+ else {
+ th = 0 ;
+ nrows = 0 ;
+ }
+
+ *reply_width = Max(wid, MIN_WID) ;
+ *reply_height = Max(th+hgt, MIN_HGT) ;
+
+ return nrows ;
+}
+
+
+static void
+MakeSizeRequest(TabsWidget tw)
+{
+ Widget w = (Widget)tw ;
+ XtWidgetGeometry request, reply ;
+ XtGeometryResult result ;
+ Dimension cw,ch ;
+
+ request.request_mode = CWWidth | CWHeight ;
+ PreferredSize(tw, &request.width, &request.height, &cw, &ch) ;
+
+ if( request.width == tw->core.width &&
+ request.height == tw->core.height )
+ return ;
+
+ result = XtMakeGeometryRequest(w, &request, &reply) ;
+
+ if( result == XtGeometryAlmost )
+ {
+ /* Bugger. Didn't get what we want, but were offered a
+ * compromise. If the width was too small, recompute
+ * based on the too-small width and try again.
+ * If the height was too small, make a wild-ass guess
+ * at a wider width and try again.
+ */
+
+ if( reply.width < request.width && reply.height >= request.height )
+ {
+ Dimension s = SHADWID ;
+ ch += s*2 ;
+ PreferredSize3(tw, reply.width,ch, &request.width, &request.height);
+ result = XtMakeGeometryRequest(w, &request, &reply) ;
+ if( result == XtGeometryAlmost )
+ (void) XtMakeGeometryRequest(w, &reply, NULL) ;
+ }
+
+ else
+ (void) XtMakeGeometryRequest(w, &reply, NULL) ;
+ }
+}
+
+
+static void
+getBitmapInfo(TabsWidget tw, TabsConstraints tab)
+{
+ Window root ;
+ int x,y ;
+ unsigned int bw ;
+
+ if( tab->tabs.left_bitmap == None ||
+ !XGetGeometry(XtDisplay(tw), tab->tabs.left_bitmap, &root, &x, &y,
+ &tab->tabs.lbm_width, &tab->tabs.lbm_height,
+ &bw, &tab->tabs.lbm_depth) )
+ tab->tabs.lbm_width = tab->tabs.lbm_height = 0 ;
+}
+
+\f
+
+
+ /* Code copied & modified from Gcs.c. This version has dynamic
+ * foreground.
+ */
+
+static void
+TabsAllocFgGC(TabsWidget tw)
+{
+ Widget w = (Widget) tw;
+ XGCValues values ;
+
+ values.background = tw->core.background_pixel ;
+ values.font = tw->tabs.font->fid ;
+ values.line_style = LineOnOffDash ;
+ values.line_style = LineSolid ;
+
+ tw->tabs.foregroundGC =
+ XtAllocateGC(w, w->core.depth,
+ GCBackground|GCFont|GCLineStyle, &values,
+ GCForeground,
+ GCSubwindowMode|GCGraphicsExposures|GCDashOffset|
+ GCDashList|GCArcMode) ;
+}
+
+static void
+TabsAllocGreyGC(TabsWidget tw)
+{
+ Widget w = (Widget) tw;
+ XGCValues values ;
+
+ values.background = tw->core.background_pixel ;
+ values.font = tw->tabs.font->fid ;
+#ifdef HAVE_XMU
+ if( tw->tabs.be_nice_to_cmap || w->core.depth == 1)
+ {
+ values.fill_style = FillStippled ;
+ tw->tabs.grey50 =
+ values.stipple = XmuCreateStippledPixmap(XtScreen(w), 1L, 0L, 1) ;
+
+ tw->tabs.greyGC =
+ XtAllocateGC(w, w->core.depth,
+ GCBackground|GCFont|GCStipple|GCFillStyle, &values,
+ GCForeground,
+ GCSubwindowMode|GCGraphicsExposures|GCDashOffset|
+ GCDashList|GCArcMode) ;
+ }
+ else
+#endif
+ {
+ tw->tabs.greyGC =
+ XtAllocateGC(w, w->core.depth,
+ GCFont, &values,
+ GCForeground,
+ GCBackground|GCSubwindowMode|GCGraphicsExposures|GCDashOffset|
+ GCDashList|GCArcMode) ;
+ }
+}
--- /dev/null
+/* Tabs Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+ This file is part of XEmacs.
+
+ XEmacs is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the
+ Free Software Foundation; either version 2, or (at your option) any
+ later version.
+
+ XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with XEmacs; see the file COPYING. If not, write to
+ the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA. */
+
+/*
+ * This widget manages one or more child widgets, exactly one of which is
+ * visible. Above the child widgets is a graphic that looks like index
+ * tabs from file folders. Each tab corresponds to one of the child widgets.
+ * By clicking on a tab, the user can bring the corresponding widget to
+ * the top of the stack.
+ */
+
+
+#ifndef _Tabs_h
+#define _Tabs_h
+
+#include <X11/Constraint.h>
+
+
+/***********************************************************************
+ *
+ * Tabs Widget (subclass of CompositeClass)
+ *
+ ***********************************************************************/
+
+/* Parameters:
+
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ font Font XFontStruct* XtDefaultFont
+ internalWidth Width Dimension 4 *1
+ internalHeight Height Dimension 2 *1
+ topWidget TopWidget Widget *2
+ callback Callback XtCallbackList NULL *3
+ popdownCallback Callback XtCallbackList NULL *4
+ selectInsensitive SelectInsensitive Boolean True *5
+ beNiceToColormap BeNiceToColormap Boolean False *6
+ topShadowContrast TopShadowContrast int 20
+ bottomShadowContrast BottomShadowContrast int 40
+ insensitiveContrast InsensitiveContrast int 33 *7
+
+ background Background Pixel XtDefaultBackground
+ border BorderColor Pixel XtDefaultForeground
+ borderWidth BorderWidth Dimension 1
+ destroyCallback Callback Pointer NULL
+ hSpace HSpace Dimension 4
+ height Height Dimension 0
+ mappedWhenManaged MappedWhenManaged Boolean True
+ orientation Orientation XtOrientation vertical
+ vSpace VSpace Dimension 4
+ width Width Dimension 0
+ x Position Position 0
+ y Position Position 0
+
+ Notes:
+
+ 1 internalWidth, internalHeight specify the margins around the text
+ in the tabs.
+ 2 topWidget identifies the widget which is currently visible.
+ 3 callbacks are called whenever the user selects a tab. Call_data is
+ the new top widget.
+ 4 popdownCallbacks are called whenever the user selects a tab. Call_data is
+ the old (no longer visible) top widget. Note that popdownCallbacks
+ are called before callbacks.
+ 5 SelectInsensitive determines whether or not insensitive children may
+ be selected anyway.
+ 6 BeNiceToColormap causes the Tabs widget to use fewer colors.
+ 7 InsensitiveContrast sets the contrast used for labels of insensitive widgets.
+
+*/
+
+/* Constraint parameters:
+ Name Class RepType Default Value
+ ---- ----- ------- -------------
+ tabLabel Label String widget name
+ tabLeftBitmap LeftBitmap Pixmap None
+ tabForeground Foreground Pixel XtDefaultForeground
+ resizable Resizable Boolean False
+*/
+
+/* New fields */
+
+#ifndef XtNtabLabel
+#define XtNtabLabel "tabLabel"
+#define XtNtabForeground "tabForeground"
+#endif
+
+#ifndef XtNtabLeftBitmap
+#define XtNtabLeftBitmap "tabLeftBitmap"
+#endif
+
+#ifndef XtCLeftBitmap
+#define XtCLeftBitmap "LeftBitmap"
+#endif
+
+#ifndef XtCResizable
+#define XtCResizable "Resizable"
+#endif
+
+#ifndef XtNselectInsensitive
+#define XtNselectInsensitive "selectInsensitive"
+#define XtCSelectInsensitive "SelectInsensitive"
+#endif
+
+#ifndef XtNnlabels
+#define XtNnlabels "nlabels"
+#define XtCNLabels "NLabels"
+#endif
+#ifndef XtNlabels
+#define XtNlabels "labels"
+#define XtCLabels "Labels"
+#endif
+
+#ifndef XtNtopWidget
+#define XtNtopWidget "topWidget"
+#define XtCTopWidget "TopWidget"
+#endif
+
+#ifndef XtNhSpace
+#define XtNhSpace "hSpace"
+#define XtCHSpace "HSpace"
+#define XtNvSpace "vSpace"
+#define XtCVSpace "VSpace"
+#endif
+
+#ifndef XtNresizable
+#define XtNresizable "resizable"
+#endif
+
+#ifndef XtNinsensitiveContrast
+#define XtNinsensitiveContrast "insensitiveContrast"
+#define XtCInsensitiveContrast "InsensitiveContrast"
+#endif
+
+#ifndef XtNshadowWidth
+#define XtNshadowWidth "shadowWidth"
+#define XtCShadowWidth "ShadowWidth"
+#define XtNtopShadowPixel "topShadowPixel"
+#define XtCTopShadowPixel "TopShadowPixel"
+#define XtNbottomShadowPixel "bottomShadowPixel"
+#define XtCBottomShadowPixel "BottomShadowPixel"
+#define XtNtopShadowContrast "topShadowContrast"
+#define XtCTopShadowContrast "TopShadowContrast"
+#define XtNbottomShadowContrast "bottomShadowContrast"
+#define XtCBottomShadowContrast "BottomShadowContrast"
+#endif
+
+#ifndef XtNtopShadowPixmap
+#define XtNtopShadowPixmap "topShadowPixmap"
+#define XtCTopShadowPixmap "TopShadowPixmap"
+#define XtNbottomShadowPixmap "bottomShadowPixmap"
+#define XtCBottomShadowPixmap "BottomShadowPixmap"
+#endif
+
+#ifndef XtNbeNiceToColormap
+#define XtNbeNiceToColormap "beNiceToColormap"
+#define XtCBeNiceToColormap "BeNiceToColormap"
+#define XtNbeNiceToColourmap "beNiceToColormap"
+#define XtCBeNiceToColourmap "BeNiceToColormap"
+#endif
+
+/* Class record constants */
+
+extern WidgetClass tabsWidgetClass;
+
+typedef struct _TabsClassRec *TabsWidgetClass;
+typedef struct _TabsRec *TabsWidget;
+
+_XFUNCPROTOBEGIN
+
+extern void
+XawTabsSetTop(
+#if NeedFunctionPrototypes
+ Widget w,
+ Bool callCallbacks
+#endif
+) ;
+
+extern void
+XawTabsSetHighlight(
+#if NeedFunctionPrototypes
+ Widget tabs,
+ Widget w
+#endif
+) ;
+
+_XFUNCPROTOEND
+
+#endif /* _Tabs_h */
--- /dev/null
+/* Tabs Widget for XEmacs.
+ Copyright (C) 1999 Edward A. Falk
+
+This file is part of XEmacs.
+
+XEmacs is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+XEmacs is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+You should have received a copy of the GNU General Public License
+along with XEmacs; see the file COPYING. If not, write to
+the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA 02111-1307, USA. */
+
+/* Synched up with: TabsP.h 1.7 */
+
+/*
+ * TabsP.h - Private definitions for Index Tabs widget
+ */
+
+#ifndef _TabsP_h
+#define _TabsP_h
+
+/***********************************************************************
+ *
+ * Tabs Widget Private Data
+ *
+ ***********************************************************************/
+
+#include <X11/IntrinsicP.h>
+
+#ifdef NEED_MOTIF
+#include <Xm/XmP.h>
+#include <Xm/ManagerP.h>
+#endif
+
+#include "xlwtabs.h"
+
+/* New fields for the Tabs widget class record */
+typedef struct {XtPointer extension;} TabsClassPart;
+
+/* Full class record declaration */
+typedef struct _TabsClassRec {
+ CoreClassPart core_class;
+ CompositeClassPart composite_class;
+ ConstraintClassPart constraint_class;
+#ifdef NEED_MOTIF
+ XmManagerClassPart manager_class;
+#endif
+ TabsClassPart tabs_class;
+} TabsClassRec;
+
+extern TabsClassRec tabsClassRec;
+
+
+
+/****************************************************************
+ *
+ * instance record declaration
+ *
+ ****************************************************************/
+
+/* New fields for the Tabs widget record */
+typedef struct {
+ /* resources */
+ XFontStruct *font ;
+ Dimension internalHeight, internalWidth ;
+ Widget topWidget ;
+ XtCallbackList callbacks ;
+ XtCallbackList popdownCallbacks ;
+ Boolean selectInsensitive ;
+ Boolean be_nice_to_cmap ;
+ int top_shadow_contrast ;
+ int bot_shadow_contrast ;
+ int insensitive_contrast ;
+
+ /* private state */
+ Widget hilight ;
+ GC foregroundGC ;
+ GC backgroundGC ;
+ GC greyGC ;
+ GC topGC ;
+ GC botGC ;
+ Dimension tab_height ; /* height of tabs (all the same) */
+ /* Note: includes top shadow only */
+ Dimension tab_total ; /* total height of all tabs */
+ Dimension child_width, child_height; /* child size, including borders */
+ Dimension max_cw, max_ch ; /* max child preferred size */
+ Cardinal numRows ;
+ Cardinal displayChildren ;
+ XtGeometryMask last_query_mode;
+ Boolean needs_layout ;
+ Pixmap grey50 ; /* TODO: cache this elsewhere */
+} TabsPart;
+
+
+typedef struct _TabsRec {
+ CorePart core;
+ CompositePart composite;
+ ConstraintPart constraint;
+#ifdef NEED_MOTIF
+ XmManagerPart manager;
+#endif
+ TabsPart tabs;
+} TabsRec;
+
+
+
+
+/****************************************************************
+ *
+ * constraint record declaration
+ *
+ ****************************************************************/
+
+typedef struct _TabsConstraintsPart {
+ /* resources */
+ String label ;
+ Pixmap left_bitmap ;
+ Pixel foreground ;
+ Boolean resizable ;
+
+ /* private state */
+ Pixel grey ;
+ Boolean greyAlloc ;
+ Dimension width ; /* tab width */
+ Position x,y ; /* tab base position */
+ short row ; /* tab row */
+ Dimension wid,hgt ; /* desired size */
+ Dimension bwid ; /* desired border width */
+ Boolean queried ; /* we've asked child it's pref. size */
+ Position l_x, l_y ; /* label position */
+ Position lbm_x, lbm_y ; /* bitmap position */
+ unsigned int lbm_width, lbm_height, lbm_depth ;
+} TabsConstraintsPart ;
+
+typedef struct _TabsConstraintsRec {
+#ifdef NEED_MOTIF
+ XmManagerConstraintPart manager;
+#endif
+ TabsConstraintsPart tabs ;
+} TabsConstraintsRec, *TabsConstraints ;
+
+
+#endif /* _TabsP_h */
--- /dev/null
+*.ell
+*_i.c
--- /dev/null
+*.ell
+*_i.c
--- /dev/null
+*.ell
+*_i.c
--- /dev/null
+*.ell
+*_i.c
\ No newline at end of file
--- /dev/null
+To use:
+
+You need to build and install the XEmacs distribution. Also you need
+the xemacs packages in both source and installed versions.
+
+Edit "dirs.py" to reflect the locations of the above components.
+
+Edit "version.py" to reflect the current version, as well as the
+welcome message.
+
+Run
+ python pre_wise.py > xemacs-XXX.wse
+
+ (for XXX use a version or date code of your choosing)
+
+Run
+ cmd /c xemacs-XXX.wse
+
+to produce xemacs-XXX.exe
+
+
+"pre_wise.py" is a preprocessor for the Wise installer maker. It
+reads "xemacs.tmpl" which is a Wise input file, except that certain
+portions are enclosed in triple angle brackets <<<like this>>>
+
+These portions are evaluated as Python expressions and replaced by the
+string representations of the resulting value. This allows for
+things to change from release to release without having to re-do the
+Wise installation each time. Also it keeps you from having to
+manually drag-n-drop all the package files, which is rather tedious!
+
--- /dev/null
+#Configuration variables\r
+\r
+#where the source is:\r
+\r
+source = r"X:\XEmacs-21"\r
+#where the installed distribution is:\r
+installed = r"C:\Program Files\XEmacs\xemacs-21.0-b62"\r
+\r
+#where the (built and installed) packages are\r
+packages = r"C:\Program Files\XEmacs\xemacs-packages"\r
+\r
+#where the package source is\r
+pkg_src = r"X:\xemacs-packages"\r
+\r
+#Subdirs relative to the base installation directory\r
+#Everything except packages goes here:\r
+dst = "XEmacs-21.0-b62"\r
+#packages go here:\r
+pkg_dst = "xemacs-packages"\r
+\r
+\r
--- /dev/null
+Document Type: DLG\r
+item: Custom Dialog\r
+ Name=Display ReadMe\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Read Me File\r
+ Title French=Fichier Lisez-moi\r
+ Title German=Liesmich-Datei\r
+ Title Portuguese=Ficheiro Leia-me\r
+ Title Spanish=Archivo Léeme\r
+ Title Italian=File Leggimi\r
+ Title Danish=Vigtigt fil\r
+ Title Dutch=Leesmij-bestand\r
+ Title Norwegian=Informasjonsfil\r
+ Title Swedish=Läs mig-fil\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=I &Agree >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Slet\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Editbox\r
+ Rectangle=85 11 254 170\r
+ Value=%TEMP%\%READMEFILE%\r
+ Help Context=16711681\r
+ Create Flags=01010000101000000000100000000100\r
+ end\r
+ end\r
+end\r
--- /dev/null
+
+REGEDIT4
+
+[HKEY_CLASSES_ROOT\.el]
+@="elfile"
+"Content Type"="text/plain"
+
+[HKEY_CLASSES_ROOT\elfile]
+@="Emacs lisp"
+"EditFlags"=hex:00,00,01,00
+
+[HKEY_CLASSES_ROOT\elfile\Shell]
+@=""
+
+[HKEY_CLASSES_ROOT\elfile\Shell\open]
+
+[HKEY_CLASSES_ROOT\elfile\Shell\open\command]
+@="\"C:\\Program Files\\XEmacs\\XEmacs-21.0\\i386-pc-win32\\runemacs.exe\" \"%1\""
+
+[HKEY_CLASSES_ROOT\elfile\Shell\open\ddeexec]
+@="open(\"%1\")"
+
+[HKEY_CLASSES_ROOT\elfile\Shell\open\ddeexec\Application]
+@="XEmacs"
+
+[HKEY_CLASSES_ROOT\elfile\Shell\open\ddeexec\topic]
+@="System"
+
+[HKEY_CLASSES_ROOT\elfile\DefaultIcon]
+@="C:\\Program Files\\XEmacs\\XEmacs-21.0\\i386-pc-win32\\runemacs.exe,2"
+
+[HKEY_CLASSES_ROOT\elfile\QuickView]
+@="*"
+
+
+
--- /dev/null
+import os
+import dirs
+import string
+
+def listdir_recursive(basedir):
+ ret = []
+ for f in os.listdir(basedir):
+ if os.path.isfile(basedir+"\\"+f):
+ ret.append(f)
+ elif os.path.isdir(basedir+"\\"+f):
+ for f1 in listdir_recursive(basedir+"\\"+f):
+ ret.append(f+"\\"+f1)
+ return ret
+
+all = []
+
+
+
+for f in listdir_recursive(dirs.installed):
+ if string.find(f,'CVS')>=0:
+ continue
+ all.append((f, dirs.installed, dirs.dst))
+
--- /dev/null
+import os
+import dirs
+
+def listdir_recursive(basedir):
+ ret = []
+ for f in os.listdir(basedir):
+ if os.path.isfile(basedir+"\\"+f):
+ ret.append(f)
+ elif os.path.isdir(basedir+"\\"+f):
+ for f1 in listdir_recursive(basedir+"\\"+f):
+ ret.append(f+"\\"+f1)
+ return ret
+
+install = []
+
+for f in os.listdir(dirs.source+"\\lib-src"):
+ if f == "DOC" or f[-4:]==".exe":
+ install.append((f,dirs.source+"\\lib-src",dirs.bin_dst))
+
+
+for f in ['runemacs.exe', 'xemacs.exe']:
+ install.append((f,dirs.source+"\\src",dirs.bin_dst))
+
+for f in listdir_recursive(dirs.source+"\\lisp"):
+ install.append((f,dirs.source+"\\lisp",dirs.lisp_dst))
+
+for f in listdir_recursive(dirs.source+"\\etc"):
+ install.append((f,dirs.source+"\\etc",dirs.etc_dst))
+
+
+for f in os.listdir(dirs.source+"\\info"):
+ install.append((f,dirs.source+"\\info",dirs.info_dst))
+
+
+
+
--- /dev/null
+Document Type: DLG\r
+item: Custom Dialog\r
+ Name=Select Components\r
+ Display Variable=DISPLAY\r
+ Flags=00000001\r
+ item: Dialog\r
+ Title=Select Components \r
+ Title French=Sélectionner les éléments\r
+ Title German=Komponenten auswählen\r
+ Title Portuguese=Seleccionar Componentes\r
+ Title Spanish=Seleccione los Componentes\r
+ Title Italian=Seleziona Componenti\r
+ Title Danish=Vælg komponenter\r
+ Title Dutch=Selecteer onderdelen\r
+ Title Norwegian=Velg komponenter\r
+ Title Swedish=Välj komponenter\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=130 185 172 199\r
+ Variable=DIRECTION\r
+ Value=B\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=< &Back\r
+ Text French=<&Retour\r
+ Text German=<&Zurück\r
+ Text Portuguese=<&Retornar\r
+ Text Spanish=<&Retroceder\r
+ Text Italian=< &Indietro\r
+ Text Danish=<&Tilbage\r
+ Text Dutch=<&Terug\r
+ Text Norwegian=<&Tilbake\r
+ Text Swedish=< &Tillbaka\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Annuller\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=205 156 253 166\r
+ Variable=COMPONENTS\r
+ Value=MAINDIR\r
+ Create Flags=01010000000000000000000000000010\r
+ end\r
+ item: Static\r
+ Rectangle=205 148 253 157\r
+ Variable=COMPONENTS\r
+ Create Flags=01010000000000000000000000000010\r
+ end\r
+ item: Static\r
+ Rectangle=95 147 184 158\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Disk Space Required:\r
+ Text French=Espace disque requis\r
+ Text German=Benötigter Festplattenspeicher:\r
+ Text Portuguese=Espaço de disco necessário:\r
+ Text Spanish=Espacio de Disco Requerido:\r
+ Text Italian=Spazio su disco richiesto:\r
+ Text Danish=Nødvendig diskplads:\r
+ Text Dutch=Vereiste hoeveelheid schijfruimte\r
+ Text Norwegian=Diskplass nødvendig:\r
+ Text Swedish=Erforderligt diskutrymme\r
+ end\r
+ item: Static\r
+ Rectangle=95 157 190 167\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Disk Space Remaining:\r
+ Text French=Espace disque disponible\r
+ Text German=Verbleibender Festplattenspeicher:\r
+ Text Portuguese=Espaço de disco restante:\r
+ Text Spanish=Espacio de Disco Remanente:\r
+ Text Italian=Spazio su disco rimanente:\r
+ Text Danish=Ledig diskplads:\r
+ Text Dutch=Resterende schijfruimte\r
+ Text Norwegian=Ledig diskplass:\r
+ Text Swedish=Återstående diskutrymme\r
+ end\r
+ item: Static\r
+ Rectangle=90 138 264 168\r
+ Action=1\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=90 8 260 41\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=In the options list below, select the checkboxes for the options that you would like to have installed. The disk space fields reflect the requirements of the options you have selected.\r
+ Text French=Dans la liste d'options suivante, veuillez sélectionner les cases des options que vous désirez installer. Le champ d'espace disque indique les conditions requises pour les options choisies\r
+ Text German=Wählen Sie in der Optionenliste unten die Kontrollkästchen für diejenigen Optionen, die Sie installieren möchten. Die Speicherfelder zeigen die benötigte Speicherkapazität für die gewählten Optionen an.\r
+ Text Portuguese=Na lista de opções abaixo, seleccione as caixas de verificação para as opções que gostaria de ter instalado. Os campos de espaço de disco reflectem os requerimentos das opções que seleccionou.\r
+ Text Spanish=En la lista de opciones que se ofrece a continuación, seleccione las casillas de comprobación para las opciones que desea instalar. Los campos del espacio en el disco reflejan los requerimientos de las opciones que ha seleccionado.\r
+ Text Italian=Nell\92elenco delle opzioni sotto, marca le caselle di controllo delle opzioni che vuoi installare. I campi dello spazio sul disco riflettono i requisiti delle opzioni selezionate.\r
+ Text Danish=Marker afkrydsningsfelterne for de komponenter, der skal installeres, på listen herunder. Diskpladsfelterne angiver pladskravene for de valgte komponenter.\r
+ Text Dutch=Kruis in de onderstaande lijst het vakje aan naast de opties die u wilt installeren. Achter elke optie staat de benodigde schijfruimte vermeld.\r
+ Text Norwegian=I listen over alternativer nedenfor, klikk i kontrollrutene for de alternativene du ønsker å installere. Diskplassfeltene gjenspeiler kravene for de alternativene du har valgt.\r
+ Text Swedish=Kryssa för i rutorna nedan vilka alternativ du vill få installerade. I diskutrymmesfälten anges utrymmesbehoven för de alternativ du väljer.\r
+ end\r
+ item: Checkbox\r
+ Rectangle=91 41 126 56\r
+ Variable=COMPONENTS LIBS\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000010000000000000011\r
+ Flags=0000000000000010\r
+ Text=Libraries\r
+ Text=\r
+ end\r
+ item: Checkbox\r
+ Rectangle=90 56 148 71\r
+ Variable=COMPONENTS COMM\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000010000000000000011\r
+ Flags=0000000000000010\r
+ Text=Communications\r
+ Text=\r
+ end\r
+ end\r
+ item: Dialog\r
+ Title=Library Packages\r
+ Width=268\r
+ Height=204\r
+ Font Name=Helv\r
+ Font Size=8\r
+ end\r
+ item: Dialog\r
+ Title=Library Packages\r
+ Width=268\r
+ Height=204\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=219 170 254 185\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=OK\r
+ end\r
+ end\r
+end\r
--- /dev/null
+#configuration variables
+
+#package categories
+category_names = ["libs", "comm", "oa", "os", "prog", "wp", "games"]
+
+category_descriptions = {"libs":"Libraries",
+ "comm":"Communication",
+ "oa": "Productivity", #???
+ "os": "Operating System",
+ "prog": "Programming",
+ "wp": "Word Processing",
+ "games": "Games and Amusements"}
+
+
+#packages to install by default
+default=["xemacs-base","edit-utils","efs",
+ "text-modes","prog-modes",
+ "dired","apel",
+ "c-support","cc-mode",
+ "mail-lib","pc","sounds-wav"]
+
+def category_of_letter(x):
+ return category_names[ord(x)-ord('A')]
+
+def letter_of_category(cat):
+ return chr(ord('A')+category_names.index(cat))
+
+def letter_of_package(x):
+ return chr(ord('A')+packages_of_category(category_of_package(x)).index(x))
+
+import dirs, os
+catpkg = {}
+pkgcat = {}
+
+for cat in category_names:
+ pkgcat[cat]=[]
+ dd = os.path.join(dirs.pkg_src,cat)
+ for d in os.listdir(dd):
+ if d == "CVS":
+ continue
+ manifest = dirs.packages + "\\pkginfo\\MANIFEST." + d
+ if not os.path.exists(manifest): #it's not installed, skip it
+ continue
+ if os.path.isdir(os.path.join(dd,d)):
+ catpkg[d] = cat
+ pkgcat[cat].append(d)
+
+def category_of_package(p):
+ return catpkg[p]
+
+def packages_of_category(c):
+ return pkgcat[c]
+
+#Brief descriptions of the packages.
+#This data is up-to-date as of 13 January 1998.
+package_descriptions={
+ "Sun":"Support for Sparcworks.",
+ "apel":"A Portable Emacs Library",
+ "edebug":"A Lisp debugger",
+ "dired":"The DIRectory EDitor",
+ "efs":"Access remote filesystems",
+ "mail-lib":"Fundamental email support",
+ "tooltalk":"Tooltalk",
+ "xemacs-base":"Fundamental XEmacs support",
+ "xemacs-devel":"Lisp developer support.",
+ "footnote":"Footnoting in mail messages",
+ "gnats":"XEmacs bug reports",
+ "gnus":"Newsreader and Mailreader",
+ "mailcrypt":"Message encryption with PGP.",
+ "mh-e":"Support for MH mailreader",
+ "net-utils":"Networking Utilities",
+ "ph":"CCSO/qi directory client",
+ "rmail":"An obsolete Emacs mailer",
+ "supercite":"Mail/News Citation tool",
+ "tm":"Emacs MIME support",
+ "vm":"An Emacs mailer",
+ "w3":"A Web browser",
+ "cookie":"Spook and Yow (Zippy quotes)",
+ "games":"Tetris, Sokoban, and Snake",
+ "mine":"Minehunt",
+ "misc-games":"Other amusements and diversions",
+ "egg-its":"Wnn(4.2 and 6)/SJ3 support",
+ "leim":"Quail",
+ "locale":"Localized menubars",
+ "mule-base":"Basic Mule support",
+ "skk":"Another Japanese Language Input Method",
+ "calendar":"Calendar and diary",
+ "edit-utils":"Various XEmacs goodies",
+ "forms":"Obsolete forms editing support",
+ "frame-icon":"Change icon based on 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":"Packages for editing text files",
+ "time":"Display time and date",
+ "eterm":"Terminal emulator",
+ "igrep":"Enhanced Grep",
+ "ilisp":"Front-end for Inferior Lisp",
+ "os-utils":"Misc. OS utilities",
+ "view-process":"Unix process viewer",
+ "ada":"Ada language support",
+ "c-support":"Add-ons for editing C code",
+ "cc-mode":"C, C++ and Java language editing",
+ "debug": "GUD, gdb, dbx debugging support",
+ "ediff": "Compare files",
+ "emerge": "Merge files",
+ "pcl-cvs":"CVS frontend.",
+ "prog-modes":"Various programming languages",
+ "scheme":"Front-end for Inferior Scheme",
+ "sh-script":"Support for editing shell scripts",
+ "vc":"Version Control",
+ "vc-cc":"Broken",
+ "vhdl":"Support for VHDL",
+ "auctex":"Basic TeX/LaTeX support",
+ "crisp":"Crisp/Brief emulation",
+ "edt":"DEC EDIT/EDT emulation",
+ "texinfo":"XEmacs TeXinfo support.",
+ "textools":"TeX support",
+ "tpu":"DEC EDIT/TPU support",
+ "viper":"VI emulation",
+ "elib":"Portable elisp utility library",
+ "fsf-compat": "FSF Emacs compatibility files",
+ "sounds-wav": "XEmacs Microsoft sound files",
+ "bbdb": "The Big Brother Data Base",
+ "eudc": "Emacs Unified Directory Client",
+ "mew": "Messaging in an Emacs World",
+ "zenirc": "IRC client",
+ "calc": "Emacs calculator",
+ "jde": "Java development environment",
+ "reftex": "LaTeX cross-referencing and citations"
+}
+
+
+
+
--- /dev/null
+import string\r
+import re\r
+import os\r
+import types\r
+\r
+infile=open("xemacs.tmpl","r")\r
+\r
+import version\r
+import dirs\r
+import filelist\r
+import packages\r
+\r
+def letter(package):\r
+ index = packages.all.index(package)\r
+ if index>29:\r
+ raise "WISE error: too many components"\r
+ return chr(ord("A")+index)\r
+\r
+def letters(package_list):\r
+ ret = ""\r
+ for p in package_list: \r
+ ret = ret+letter(p)\r
+ return ret\r
+\r
+def describe(package):\r
+ if package in packages.descriptions.keys():\r
+ return ": "+packages.descriptions[package]\r
+ else: return ""\r
+\r
+def ifblock(var,val):\r
+ return("item: If/While Statement\n Variable=%s\n Value=%s\n Flags=00001010\nend\n" % (var,val))\r
+\r
+def endblock():\r
+ return("item: End Block\nend\n")\r
+\r
+def setvar(var,val):\r
+ return("item: Set Variable\n Variable=%s\n Value=%s\n Flags=10000000\nend\n" % (string.upper(var), val))\r
+\r
+def default_letters_of_category(cat):\r
+ val = ""\r
+ for p in packages.default:\r
+ if packages.category_of_package(p) == cat:\r
+ val = val + packages.letter_of_package(p)\r
+ return val\r
+\r
+def set_category_defaults():\r
+ ret = ""\r
+ for c in packages.category_names:\r
+ ret = ret + setvar(c, default_letters_of_category(c))\r
+ return ret\r
+\r
+def do_category(cat):\r
+ ret = ifblock("COMPONENTS", packages.letter_of_category(cat))\r
+ for pkg in packages.packages_of_category(cat):\r
+ ret = ret + ifblock(string.upper(cat),packages.letter_of_package(pkg))\r
+ for f in files_of_package(pkg):\r
+ ret = ret+install_pkg_file(f)\r
+ ret = ret + endblock()\r
+ ret = ret + endblock()\r
+ return ret\r
+\r
+def files_of_package(package):\r
+ manifest_file = dirs.packages + "\\pkginfo\\MANIFEST." + package\r
+ manifest = open(manifest_file,"r")\r
+ lines = manifest.readlines()\r
+ lines = map(lambda s:s[:-1], lines)\r
+ lines = map(lambda s:string.replace(s,'/','\\'), lines)\r
+ return lines\r
+\r
+def category_dialog(cat):\r
+ npkg = len(packages.packages_of_category(cat))\r
+ ret=""\r
+ ret=ret+" item: Dialog\n Title="+packages.category_descriptions[cat]+" Packages\n"\r
+ ret=ret+" Width=210\n"\r
+ ret=ret+" Height=%d\n" % (45+npkg*10)\r
+ ret=ret+" Font Name=Helv\n"\r
+ ret=ret+" Font Size=8\n"\r
+ ret=ret+" item: Push Button\n"\r
+ ret=ret+" Rectangle=107 %d 147 %d\n" % (5+npkg*10+2, 5+npkg*10+17)\r
+ ret=ret+" Create Flags=01010000000000010000000000000001\n"\r
+ ret=ret+" Text=OK\n"\r
+ ret=ret+" end\n"\r
+ ret=ret+" item: Push Button\n"\r
+ ret=ret+" Rectangle=153 %d 193 %d\n" % (5+npkg*10+2, 5+npkg*10+17)\r
+ ret=ret+" Variable=%s\n" % string.upper(cat)\r
+ ret=ret+" Value=%%%s_SAVE%%\n" % string.upper(cat)\r
+ ret=ret+" Create Flags=01010000000000010000000000000000\n"\r
+ ret=ret+" Flags=0000000000000001\n"\r
+ ret=ret+" Text=Cancel\n"\r
+ ret=ret+" end\n"\r
+ ret=ret+" item: Checkbox\n"\r
+ ret=ret+" Rectangle=0 5 191 %d\n" % (10*npkg)\r
+ ret=ret+" Variable=%s\n"%string.upper(cat)\r
+ ret=ret+" Create Flags=01010000000000010000000000000011\n"\r
+ ret=ret+" Flags=0000000000000010\n"\r
+ for pkg in packages.packages_of_category(cat):\r
+ ret = ret+" Text=%s: %s\n"%( pkg, packages.package_descriptions[pkg])\r
+ ret=ret+" Text=\n"\r
+ ret=ret+" end\n"\r
+ ret=ret+" end\n"\r
+ return ret\r
+\r
+def src_path(src,name):\r
+ return src + "\\" + name\r
+\r
+def dst_path(dst,name):\r
+ return "%MAINDIR%"+"\\"+dst+"\\" + name\r
+\r
+def install_file(name,src,dst):\r
+ return("item: Install File\n Source=%s\n Destination=%s\n Flags=0000000010000010\nend\n" % (src_path(src,name),dst_path(dst,name)))\r
+\r
+def install_pkg_file(name):\r
+ return install_file(name,dirs.packages,dirs.pkg_dst)\r
+\r
+def do_package(package):\r
+ return ifblock("COMPONENTS",letter(package)) + \\r
+ string.join(map(install_pkg_file,files(package)),"")+ \\r
+ endblock()\r
+\r
+for line in infile.readlines():\r
+ left=string.find(line,"<<<")\r
+ if left>=0:\r
+ right=string.find(line,">>>")\r
+ expr=line[left+3:right]\r
+ val=eval(expr)\r
+ if type(val)==types.StringType:\r
+ print line[:left] + val + line[right+3:],\r
+ elif type(val)==types.ListType:\r
+ for v in val:\r
+ print line[:left] + v + line[right+3:],\r
+ else: print line,\r
+\r
+\r
--- /dev/null
+Document Type: DLG\r
+item: Custom Dialog\r
+ Name=type\r
+ item: Dialog\r
+ Title=type\r
+ Width=238\r
+ Height=208\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Radio Button\r
+ Rectangle=5 5 40 20\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000010000000000001001\r
+ Text=minimal\r
+ Text=\r
+ end\r
+ item: Radio Button\r
+ Rectangle=5 25 40 40\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000010000000000001001\r
+ Text=custom\r
+ Text=\r
+ end\r
+ item: Radio Button\r
+ Rectangle=5 45 40 60\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000010000000000001001\r
+ Text=full\r
+ Text=\r
+ end\r
+ end\r
+end\r
--- /dev/null
+title="XEmacs 21.0b62 EXPERIMENTAL"\r
+welcome="Welcome to the %APPTITLE% setup program. Please note that this is an experimental release and some features may not work correctly, especially on machines running Windows 95. Please read the file PROBLEMS in the xemacs installation directory. Send comments or bug reports to xemacs-nt@xemacs.org. For more info see http://www.xemacs.org"\r
+\r
--- /dev/null
+Document Type: DLG\r
+item: Custom Dialog\r
+ Name=Welcome\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Welcome\r
+ Title French=Bienvenue\r
+ Title German=Willkommen\r
+ Title Portuguese=Bem-vindo \r
+ Title Spanish=Bienvenido\r
+ Title Italian=Benvenuto\r
+ Title Danish=Velkommen\r
+ Title Dutch=Welkom\r
+ Title Norwegian=Velkommen\r
+ Title Swedish=Välkommen\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Annuller\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=91 22 245 118\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Welcome to the %APPTITLE% setup program. Please note that this is an experimental release and some features may not work correctly. Send comments or bug reports to xemacs-nt@xemacs.org rather than one of the other XEmacs mailing lists. For more info see http://www.xemacs.org\r
+ end\r
+ end\r
+end\r
--- /dev/null
+Document Type: WSE\r
+item: Global\r
+ Version=7.0\r
+ Title=<<<version.title + " Installation">>>\r
+ Flags=00000100\r
+ Languages=65 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0\r
+ Japanese Font Name=MS Gothic\r
+ Japanese Font Size=10\r
+ Progress Bar DLL=%_WISE_%\Progress\WIZ%_EXE_OS_TYPE_%.DLL\r
+ Start Gradient=0 0 255\r
+ End Gradient=0 0 0\r
+ Windows Flags=00000100000000010010110000001000\r
+ Log Pathname=%MAINDIR%\INSTALL.LOG\r
+ Message Font=MS Sans Serif\r
+ Font Size=8\r
+ Disk Filename=SETUP\r
+ Patch Flags=0000000000000001\r
+ Patch Threshold=85\r
+ Patch Memory=4000\r
+ FTP Cluster Size=20\r
+ Dialogs Version=6\r
+ Variable Name1=_SYS_\r
+ Variable Default1=C:\WINDOWS\SYSTEM\r
+ Variable Flags1=00001000\r
+ Variable Name2=_WISE_\r
+ Variable Default2=C:\PROGRAM FILES\WISE INSTALLBUILDER\r
+ Variable Flags2=00001000\r
+end\r
+item: Get Temporary Filename\r
+ Variable=READMEFILE\r
+end\r
+item: Install File\r
+ Source=<<<dirs.source>>>\nt\Wise\Copying.txt\r
+ Destination=%TEMP%\%READMEFILE%\r
+ Flags=0000000000100010\r
+end\r
+item: Open/Close INSTALL.LOG\r
+ Flags=00000001\r
+end\r
+item: Check if File/Dir Exists\r
+ Pathname=%SYS%\r
+ Flags=10000100\r
+end\r
+item: Set Variable\r
+ Variable=SYS\r
+ Value=%WIN%\r
+end\r
+item: End Block\r
+end\r
+item: Set Variable\r
+ Variable=APPTITLE\r
+ Value=<<<version.title>>>\r
+ Flags=10000000\r
+end\r
+item: Set Variable\r
+ Variable=GROUP\r
+ Value=XEmacs\r
+ Flags=10000000\r
+end\r
+item: Set Variable\r
+ Variable=DISABLED\r
+ Value=!\r
+end\r
+item: Set Variable\r
+ Variable=MAINDIR\r
+ Value=XEmacs\r
+ Flags=10000000\r
+end\r
+item: Check Configuration\r
+ Flags=10111011\r
+end\r
+item: Get Registry Key Value\r
+ Variable=COMMON\r
+ Key=SOFTWARE\Microsoft\Windows\CurrentVersion\r
+ Default=C:\Program Files\Common Files\r
+ Value Name=CommonFilesDir\r
+ Flags=00000100\r
+end\r
+item: Get Registry Key Value\r
+ Variable=PROGRAM_FILES\r
+ Key=SOFTWARE\Microsoft\Windows\CurrentVersion\r
+ Default=C:\Program Files\r
+ Value Name=ProgramFilesDir\r
+ Flags=00000100\r
+end\r
+item: Set Variable\r
+ Variable=MAINDIR\r
+ Value=%PROGRAM_FILES%\%MAINDIR%\r
+ Flags=00001100\r
+end\r
+item: Set Variable\r
+ Variable=EXPLORER\r
+ Value=1\r
+end\r
+item: Else Statement\r
+end\r
+item: Set Variable\r
+ Variable=MAINDIR\r
+ Value=C:\%MAINDIR%\r
+ Flags=00001100\r
+end\r
+item: End Block\r
+end\r
+item: Set Variable\r
+ Variable=BACKUP\r
+ Value=%MAINDIR%\BACKUP\r
+ Flags=10000000\r
+end\r
+item: Set Variable\r
+ Variable=DOBACKUP\r
+ Value=B\r
+ Flags=10000000\r
+end\r
+item: Set Variable\r
+ Variable=COMPONENTS\r
+ Value=ACE\r
+ Flags=10000000\r
+end\r
+<<<set_category_defaults()>>>\r
+item: Wizard Block\r
+ Direction Variable=DIRECTION\r
+ Display Variable=DISPLAY\r
+ Bitmap Pathname=<<<dirs.source>>>\nt\Wise\gnu.bmp\r
+ X Position=9\r
+ Y Position=10\r
+ Filler Color=8421440\r
+ Dialog=Select Program Manager Group\r
+ Dialog=Select Backup Directory\r
+ Dialog=Display Registration Information\r
+ Dialog=Get Registration Information\r
+ Variable=EXPLORER\r
+ Variable=DOBACKUP\r
+ Variable=DOBRAND\r
+ Variable=DOBRAND\r
+ Value=1\r
+ Value=A\r
+ Value=1\r
+ Value=1\r
+ Compare=0\r
+ Compare=1\r
+ Compare=0\r
+ Compare=1\r
+ Flags=00000011\r
+end\r
+item: Custom Dialog Set\r
+ Name=Welcome\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Welcome\r
+ Title French=Bienvenue\r
+ Title German=Willkommen\r
+ Title Portuguese=Bem-vindo \r
+ Title Spanish=Bienvenido\r
+ Title Italian=Benvenuto\r
+ Title Danish=Velkommen\r
+ Title Dutch=Welkom\r
+ Title Norwegian=Velkommen\r
+ Title Swedish=Välkommen\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Annuller\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=91 22 245 118\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=<<<version.welcome>>>\r
+ end\r
+ end\r
+end\r
+item: Custom Dialog Set\r
+ Name=Display ReadMe\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Read Me File\r
+ Title French=Fichier Lisez-moi\r
+ Title German=Liesmich-Datei\r
+ Title Portuguese=Ficheiro Leia-me\r
+ Title Spanish=Archivo Léeme\r
+ Title Italian=File Leggimi\r
+ Title Danish=Vigtigt fil\r
+ Title Dutch=Leesmij-bestand\r
+ Title Norwegian=Informasjonsfil\r
+ Title Swedish=Läs mig-fil\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=I &Agree >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Slet\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Editbox\r
+ Rectangle=85 11 254 170\r
+ Value=%TEMP%\%READMEFILE%\r
+ Help Context=16711681\r
+ Create Flags=01010000101000000000100000000100\r
+ end\r
+ end\r
+end\r
+item: Custom Dialog Set\r
+ Name=Select Destination Directory\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Choose Destination Location\r
+ Title French=Choisissez la localisation de destination\r
+ Title German=Zielpfad wählen\r
+ Title Portuguese=Escolher Local de Destino\r
+ Title Spanish=Elegir una localización de destino\r
+ Title Italian=Scegli Posizione di Destinazione\r
+ Title Danish=Vælg destinationsmappe\r
+ Title Dutch=Kies doellocatie\r
+ Title Norwegian=Velg målplassering\r
+ Title Swedish=Välj ställe för installationen\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=130 185 172 199\r
+ Variable=DIRECTION\r
+ Value=B\r
+ Create Flags=01010000000000010000000000000000\r
+ Flags=0000000000000001\r
+ Text=< &Back\r
+ Text French=<&Retour\r
+ Text German=<&Zurück\r
+ Text Portuguese=<&Retornar\r
+ Text Spanish=<&Retroceder\r
+ Text Italian=< &Indietro\r
+ Text Danish=<&Tilbage\r
+ Text Dutch=<&Terug\r
+ Text Norwegian=<&Tilbake\r
+ Text Swedish=< &Tillbaka\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Annuller\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=90 10 260 122\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Setup will install %APPTITLE% in the following folder.\r
+ Text=\r
+ Text=To install into a different folder, click Browse, and select another folder. \r
+ Text=\r
+ Text=You can choose not to install %APPTITLE% by clicking Cancel to exit Setup.\r
+ Text French=%APPTITLE% va être installé dans le répertoire ci-dessous\r
+ Text French=\r
+ Text French=Pour l'installer dans un répertoire différent, cliquez sur Parcourir et sélectionnez un autre répertoire\r
+ Text French=\r
+ Text French=Vous pouvez choisir de ne pas installer %APPTITLE% en cliquant sur Annuler pour quitter l'Installation\r
+ Text German=Installation speichert %APPTITLE% im unten angegebenen Ordner:\r
+ Text German=\r
+ Text German=Zur Installation in einem anderen Ordner auf Blättern klicken und einen anderen Ordner wählen.\r
+ Text German=\r
+ Text German=Wenn Sie %APPTITLE% nicht installieren möchten, können Sie durch Klicken auf Abbrechen die Installation beenden.\r
+ Text Portuguese=Configuração instalará %APPTITLE% na seguinte pasta\r
+ Text Portuguese=\r
+ Text Portuguese=Para instalar numa pasta diferente, faça um clique sobre Procurar, e seleccione uma outra pasta.\r
+ Text Portuguese=\r
+ Text Portuguese=Pode escolher não instalar %APPTITLE% clicando no botão Cancelar para sair da Configuração\r
+ Text Spanish=El programa de Configuración instalará %APPTITLE% en la siguiente carpeta.\r
+ Text Spanish=\r
+ Text Spanish=Para instalar en una carpeta diferente, haga un clic en Visualizar, y seleccione otra carpeta.\r
+ Text Spanish=\r
+ Text Spanish=Puede elegir no instalar %APPTITLE% haciendo un clic en Cancelar para salir de Configuración.\r
+ Text Italian=Il programma di installazione installerà %APPTITLE% nella seguente cartella.\r
+ Text Italian=\r
+ Text Italian=Per effettuare l\92installazione in una cartella diversa, fai clic su Sfoglia, e scegli un\92altra cartella.\r
+ Text Italian=\r
+ Text Italian=Puoi scegliere di non installare %APPTITLE% facendo clic su Annulla per uscire dal programma di installazione\r
+ Text Danish=Installationsprogrammet installerer %APPTITLE% i denne mappe.\r
+ Text Danish=\r
+ Text Danish=Man installerer i en anden mappe ved at klikke på Browse og vælge en anden mappe.\r
+ Text Danish=\r
+ Text Danish=Man kan vælge ikke at installere %APPTITLE% ved at klikke på Slet og forlade installationsprogrammet.\r
+ Text Dutch=Het installatieprogramma installeert %APPTITLE% in de volgende directory.\r
+ Text Dutch=\r
+ Text Dutch=Als u het in een andere directory wilt installeren, klik dan op Bladeren en kies een andere locatie.\r
+ Text Dutch=\r
+ Text Dutch=U kunt ervoor kiezen om %APPTITLE% niet te installeren: klik op Annuleren om het installatieprogramma te verlaten.\r
+ Text Norwegian=Oppsett vil installere %APPTITLE% i følgende mappe.\r
+ Text Norwegian=\r
+ Text Norwegian=For å installere i en annen mappe, klikk Bla igjennom og velg en annen mappe.\r
+ Text Norwegian=\r
+ Text Norwegian=Du kan velge å ikke installere %APPTITLE% ved å velge Avbryt for å gå ut av Oppsett.\r
+ Text Swedish=Installationsprogrammet installerar %APPTITLE% i följande mapp.\r
+ Text Swedish=\r
+ Text Swedish=Om du vill att installationen ska göras i en annan mapp, klickar du på Bläddra och väljer en annan mapp.\r
+ Text Swedish=\r
+ Text Swedish=Du kan välja att inte installera %APPTITLE% genom att klicka på Avbryt för att lämna installationsprogrammet.\r
+ end\r
+ item: Static\r
+ Rectangle=90 134 260 162\r
+ Action=1\r
+ Create Flags=01010000000000000000000000000111\r
+ Text=Destination Folder\r
+ Text French=Répertoire de destination\r
+ Text German=Zielordner\r
+ Text Portuguese=Pasta de Destino\r
+ Text Spanish=Carpeta de Destino\r
+ Text Italian=Cartella di destinazione\r
+ Text Danish=Destinationsmappe\r
+ Text Dutch=Doeldirectory\r
+ Text Norwegian=Målmappe\r
+ Text Swedish=Destinationsmapp\r
+ end\r
+ item: Push Button\r
+ Rectangle=213 143 255 157\r
+ Variable=MAINDIR_SAVE\r
+ Value=%MAINDIR%\r
+ Destination Dialog=1\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=B&rowse...\r
+ Text French=P&arcourir\r
+ Text German=B&lättern...\r
+ Text Portuguese=P&rocurar\r
+ Text Spanish=V&isualizar...\r
+ Text Italian=Sfoglia...\r
+ Text Danish=&Gennemse...\r
+ Text Dutch=B&laderen...\r
+ Text Norwegian=Bla igjennom\r
+ Text Swedish=&Bläddra\r
+ end\r
+ item: Static\r
+ Rectangle=95 146 211 157\r
+ Destination Dialog=2\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=%MAINDIR%\r
+ Text French=%MAINDIR%\r
+ Text German=%MAINDIR%\r
+ Text Portuguese=%MAINDIR%\r
+ Text Spanish=%MAINDIR%\r
+ Text Italian=%MAINDIR%\r
+ Text Danish=%MAINDIR%\r
+ Text Dutch=%MAINDIR%\r
+ Text Norwegian=%MAINDIR%\r
+ Text Swedish=%MAINDIR%\r
+ end\r
+ end\r
+ item: Dialog\r
+ Title=Select Destination Directory\r
+ Title French=Choisissez le répertoire de destination\r
+ Title German=Zielverzeichnis wählen\r
+ Title Portuguese=Seleccionar Directório de Destino\r
+ Title Spanish=Seleccione el Directorio de Destino\r
+ Title Italian=Seleziona Directory di destinazione\r
+ Title Danish=Vælg Destinationsbibliotek\r
+ Title Dutch=Kies doeldirectory\r
+ Title Norwegian=Velg målkatalog\r
+ Title Swedish=Välj destinationskalatog\r
+ Width=221\r
+ Height=173\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Listbox\r
+ Rectangle=5 2 160 149\r
+ Variable=MAINDIR\r
+ Create Flags=01010000100000010000000101000000\r
+ Flags=0000110000100010\r
+ Text=%MAINDIR%\r
+ Text French=%MAINDIR%\r
+ Text German=%MAINDIR%\r
+ Text Portuguese=%MAINDIR%\r
+ Text Spanish=%MAINDIR%\r
+ Text Italian=%MAINDIR%\r
+ Text Danish=%MAINDIR%\r
+ Text Dutch=%MAINDIR%\r
+ Text Norwegian=%MAINDIR%\r
+ Text Swedish=%MAINDIR%\r
+ end\r
+ item: Push Button\r
+ Rectangle=167 6 212 21\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=OK\r
+ Text French=OK\r
+ Text German=OK\r
+ Text Portuguese=OK\r
+ Text Spanish=ACEPTAR\r
+ Text Italian=OK\r
+ Text Danish=OK\r
+ Text Dutch=OK\r
+ Text Norwegian=OK\r
+ Text Swedish=OK\r
+ end\r
+ item: Push Button\r
+ Rectangle=167 25 212 40\r
+ Variable=MAINDIR\r
+ Value=%MAINDIR_SAVE%\r
+ Create Flags=01010000000000010000000000000000\r
+ Flags=0000000000000001\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen \r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Slet\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ end\r
+end\r
+item: Custom Dialog Set\r
+ Name=Select Packages\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Select Packages\r
+ Width=271\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=150 187 195 202\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suite >\r
+ Text German=&Weiter >\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ end\r
+ item: Push Button\r
+ Rectangle=105 187 150 202\r
+ Variable=DIRECTION\r
+ Value=B\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=< &Back\r
+ Text French=< &Retour\r
+ Text German=< &Zurück\r
+ Text Spanish=< &Atrás\r
+ Text Italian=< &Indietro\r
+ end\r
+ item: Push Button\r
+ Rectangle=211 187 256 202\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=&Cancel\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Static\r
+ Rectangle=8 180 256 181\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=86 8 258 28\r
+ Create Flags=01010000000000000000000000000000\r
+ Flags=0000000000000001\r
+ Name=Times New Roman\r
+ Font Style=-24 0 0 0 700 255 0 0 0 3 2 1 18\r
+ Text=Select Packages\r
+ Text French=Sélectionner les composants\r
+ Text German=Komponenten auswählen\r
+ Text Spanish=Seleccione componentes\r
+ Text Italian=Selezionare i componenti\r
+ end\r
+ item: Checkbox\r
+ Rectangle=83 62 211 146\r
+ Variable=COMPONENTS LIBS,COMM,OA,OS,PROG,WP,GAMES\r
+ Create Flags=01010000000000010000000000000011\r
+ Flags=0000000000000110\r
+ Text=Libraries\r
+ Text=Communication\r
+ Text=Productivity\r
+ Text=Operating System\r
+ Text=Programming\r
+ Text=Word Processing\r
+ Text=Games and Amusements\r
+ Text=\r
+ end\r
+ item: Static\r
+ Rectangle=194 162 242 172\r
+ Variable=COMPONENTS, LIBS, COMM, OA, OS, PROG, WP, GAMES\r
+ Value=MAINDIR\r
+ Create Flags=01010000000000000000000000000010\r
+ end\r
+ item: Static\r
+ Rectangle=194 153 242 162\r
+ Variable=COMPONENTS, LIBS, COMM, OA, OS, PROG, WP, GAMES\r
+ Create Flags=01010000000000000000000000000010\r
+ end\r
+ item: Static\r
+ Rectangle=107 153 196 164\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Disk Space Required:\r
+ Text French=Espace disque requis :\r
+ Text German=Notwendiger Speicherplatz:\r
+ Text Spanish=Espacio requerido en el disco:\r
+ Text Italian=Spazio su disco necessario:\r
+ end\r
+ item: Static\r
+ Rectangle=107 162 196 172\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Disk Space Remaining:\r
+ Text French=Espace disque disponible :\r
+ Text German=Verbleibender Speicherplatz:\r
+ Text Spanish=Espacio en disco disponible:\r
+ Text Italian=Spazio su disco disponibile:\r
+ end\r
+ item: Static\r
+ Rectangle=80 146 256 175\r
+ Action=1\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=83 30 256 57\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Choose which package categories to install by checking the boxes below. Press the Options buttons to select individual packages.\r
+ Text French=Choisissez les composants que vous voulez installer en cochant les cases ci-dessous.\r
+ Text German=Wählen Sie die zu installierenden Komponenten, indem Sie in die entsprechenden Kästchen klicken.\r
+ Text Spanish=Elija los componentes que desee instalar marcando los cuadros de abajo.\r
+ Text Italian=Scegliere quali componenti installare selezionando le caselle sottostanti.\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 62 254 72\r
+ Variable=LIBS_SAVE\r
+ Value=%LIBS%\r
+ Destination Dialog=1\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 74 254 84\r
+ Variable=COMM_SAVE\r
+ Value=%COMM%\r
+ Destination Dialog=2\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 86 254 96\r
+ Variable=OA_SAVE\r
+ Value=%OA%\r
+ Destination Dialog=3\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 98 254 108\r
+ Variable=OS_SAVE\r
+ Value=%OS%\r
+ Destination Dialog=4\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 110 254 120\r
+ Variable=PROG_SAVE\r
+ Value=%PROG%\r
+ Destination Dialog=5\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 122 254 132\r
+ Variable=WP_SAVE\r
+ Value=%WP%\r
+ Destination Dialog=6\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Push Button\r
+ Rectangle=230 134 254 144\r
+ Variable=GAMES_SAVE\r
+ Value=%GAMES%\r
+ Destination Dialog=7\r
+ Action=2\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Options\r
+ Text French=&Annuler\r
+ Text German=&Abbrechen\r
+ Text Spanish=&Cancelar\r
+ Text Italian=&Annulla\r
+ end\r
+ item: Set Variable\r
+ Variable=COMPONENTS\r
+ Value=X\r
+ Flags=00000001\r
+ end\r
+ end\r
+<<<string.join(map(category_dialog,packages.category_names),"")>>>\r
+end\r
+item: Custom Dialog Set\r
+ Name=Select Program Manager Group\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Select Program Manager Group\r
+ Title French=Sélectionnez le Groupe du Gestionnaire de Programmes\r
+ Title German=Programm-Managergruppe wählen\r
+ Title Portuguese=Seleccionar o Grupo Gestor de Programas\r
+ Title Spanish=Seleccione el Grupo del Administrador del Programa\r
+ Title Italian=Seleziona il gruppo Program Manager\r
+ Title Danish=Vælg Programstyringsgruppen\r
+ Title Dutch=Kies Programmabeheergroep.\r
+ Title Norwegian=Velg Programbehandlingsgruppen\r
+ Title Swedish=Välj grupp i Programhanteraren\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=130 185 172 199\r
+ Variable=DIRECTION\r
+ Value=B\r
+ Create Flags=01010000000000010000000000000000\r
+ Flags=0000000000000001\r
+ Text=< &Back\r
+ Text French=<&Retour\r
+ Text German=<&Zurück\r
+ Text Portuguese=<&Retornar\r
+ Text Spanish=<&Retroceder\r
+ Text Italian=< &Indietro\r
+ Text Danish=<&Back\r
+ Text Dutch=<&Terug\r
+ Text Norwegian=<&Tilbake\r
+ Text Swedish=< &Tillbaka\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Slet\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=90 10 260 38\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=Enter the name of the Program Manager group to add %APPTITLE% icons to:\r
+ Text French=Entrez le nom du groupe du Gestionnaire de Programmes où placer les icônes %APPTITLE% à :\r
+ Text German=Den Namen der Programm-Managergruppe wählen, in der die %APPTITLE%-Symbole gespeichert werden sollen:\r
+ Text Portuguese=Introduzir o nome do Grupo Gestor de Programa para acrescentar os ícones %APPTITLE% para:\r
+ Text Spanish=Introduzca el nombre del grupo del Administrador del Programa para añadir los iconos %APPTITLE para:\r
+ Text Italian=Inserisci il nome del gruppo Program Manager per aggiungere le icone di %APPTITLE% a:\r
+ Text Danish=Indtast navnet på Programstyringsgruppen der skal tilføjes %APPTITLE% elementer:\r
+ Text Dutch=Breng de naam van de programmabeheergroep in waaraan u %APPTITLE%-pictogrammen wilt toevoegen.\r
+ Text Norwegian=Tast inn navnet på programbehandlingsgruppen for å legge %APPTITLE%-ikoner til:\r
+ Text Swedish=Skriv in namnet på den grupp i Programhanteraren där du vill ha ikonerna för %APPTITLE%:\r
+ end\r
+ item: Combobox\r
+ Rectangle=90 42 260 148\r
+ Variable=GROUP\r
+ Create Flags=01010000001000010000001100000001\r
+ Flags=0000000000000001\r
+ Text=%GROUP%\r
+ Text=\r
+ Text French=%GROUP%\r
+ Text French=\r
+ Text German=%GROUP%\r
+ Text German=\r
+ Text Portuguese=%GROUP%\r
+ Text Portuguese=\r
+ Text Spanish=%GROUP%\r
+ Text Spanish=\r
+ Text Italian=%GROUP%\r
+ Text Italian=\r
+ Text Danish=%GROUP%\r
+ Text Danish=\r
+ Text Dutch=%GROUP%\r
+ Text Dutch=\r
+ Text Norwegian=%GROUP%\r
+ Text Norwegian=\r
+ Text Swedish=%GROUP%\r
+ Text Swedish=\r
+ end\r
+ end\r
+end\r
+item: Custom Dialog Set\r
+ Name=Start Installation\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Start Installation\r
+ Title French=Commencer l'installation\r
+ Title German=Installation beginnen\r
+ Title Portuguese=Iniciar Instalação\r
+ Title Spanish=Comenzar la Instalación\r
+ Title Italian=Avvia Installazione\r
+ Title Danish=Start installationen\r
+ Title Dutch=Start de installatie.\r
+ Title Norwegian=Start installeringen\r
+ Title Swedish=Starta installationen\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=172 185 214 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Next >\r
+ Text French=&Suivant>\r
+ Text German=&Weiter>\r
+ Text Portuguese=&Próximo>\r
+ Text Spanish=&Siguiente >\r
+ Text Italian=&Avanti >\r
+ Text Danish=&Næste>\r
+ Text Dutch=&Volgende>\r
+ Text Norwegian=&Neste>\r
+ Text Swedish=&Nästa >\r
+ end\r
+ item: Push Button\r
+ Rectangle=130 185 172 199\r
+ Variable=DIRECTION\r
+ Value=B\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=< &Back\r
+ Text French=<&Retour\r
+ Text German=<&Zurück\r
+ Text Portuguese=<&Retornar\r
+ Text Spanish=<&Retroceder\r
+ Text Italian=< &Indietro\r
+ Text Danish=<&Tilbage\r
+ Text Dutch=<&Terug\r
+ Text Norwegian=<&Tilbake\r
+ Text Swedish=< &Tillbaka\r
+ end\r
+ item: Push Button\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Annuller\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=90 10 260 70\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=You are now ready to install %APPTITLE%.\r
+ Text=\r
+ Text=Press the Next button to begin the installation or the Back button to reenter the installation information.\r
+ Text French=Vous êtes maintenant prêt à installer %APPTITLE%\r
+ Text French=\r
+ Text French=Cliquez sur Suivant pour commencer l'installation ou Retour pour entrer à nouveau les informations d'installation\r
+ Text German=Sie sind jetzt zur Installation von %APPTITLE% bereit.\r
+ Text German=\r
+ Text German=Auf die Schaltfläche Weiter klicken, um mit dem Start der Installation zu beginnen, oder auf die Schaltfläche Zurück, um die Installationsinformationen nochmals aufzurufen.\r
+ Text Portuguese=Está agora pronto para instalar %APPTITLE%\r
+ Text Portuguese=\r
+ Text Portuguese=Pressione o botão Próximo para começar a instalação ou o botão Retornar para introduzir novamente a informação sobre a instalação\r
+ Text Spanish=Ahora estará listo para instalar %APPTITLE%.\r
+ Text Spanish=\r
+ Text Spanish=Pulse el botón de Próximo para comenzar la instalación o el botón Retroceder para volver a introducir la información sobre la instalación.\r
+ Text Italian=Sei pronto ad installare %APPTITLE%.\r
+ Text Italian=\r
+ Text Italian=Premi il tasto Avanti per iniziare l\92installazione o il tasto Indietro per rientrare nuovamente nei dati sull\92installazione\r
+ Text Danish=Du er nu klar til at installere %APPTITLE%.\r
+ Text Danish=\r
+ Text Danish=Klik på Næste for at starte installationen eller på Tilbage for at ændre installationsoplysningerne.\r
+ Text Dutch=U bent nu klaar om %APPTITLE% te installeren.\r
+ Text Dutch=\r
+ Text Dutch=Druk op Volgende om met de installatie te beginnen of op Terug om de installatie-informatie opnieuw in te voeren.\r
+ Text Norwegian=Du er nå klar til å installere %APPTITLE%\r
+ Text Norwegian=\r
+ Text Norwegian=Trykk på Neste-tasten for å starte installeringen, eller Tilbake-tasten for å taste inn installasjonsinformasjonen på nytt.\r
+ Text Swedish=Du är nu redo att installera %APPTITLE%.\r
+ Text Swedish=\r
+ Text Swedish=Tryck på Nästa för att starta installationen eller på Tillbaka för att skriva in installationsinformationen på nytt.\r
+ end\r
+ end\r
+end\r
+item: If/While Statement\r
+ Variable=DISPLAY\r
+ Value=Select Destination Directory\r
+end\r
+item: Set Variable\r
+ Variable=BACKUP\r
+ Value=%MAINDIR%\BACKUP\r
+end\r
+item: End Block\r
+end\r
+item: End Block\r
+end\r
+item: If/While Statement\r
+ Variable=DOBACKUP\r
+ Value=A\r
+end\r
+item: Set Variable\r
+ Variable=BACKUPDIR\r
+ Value=%BACKUP%\r
+end\r
+item: End Block\r
+end\r
+item: Open/Close INSTALL.LOG\r
+end\r
+item: Check Disk Space\r
+ Component=COMPONENTS\r
+end\r
+item: Display Graphic\r
+ Pathname=<<<dirs.source>>>\nt\Wise\xemacs-beta.bmp\r
+ X Position=32784\r
+ Y Position=16\r
+end\r
+item: Include Script\r
+ Pathname=%_WISE_%\INCLUDE\uninstal.wse\r
+end\r
+<<<ifblock("COMPONENTS","X")>>>\r
+<<<string.join(map(lambda x:install_file(x[0],x[1],x[2]),filelist.all),"")>>>\r
+<<<endblock()>>>\r
+<<<map(do_category,packages.category_names)>>>\r
+item: Set Variable\r
+ Variable=COMMON\r
+ Value=%COMMON%\r
+ Flags=00010100\r
+end\r
+item: Set Variable\r
+ Variable=MAINDIR\r
+ Value=%MAINDIR%\r
+ Flags=00010100\r
+end\r
+item: Check Configuration\r
+ Flags=10111011\r
+end\r
+item: Get Registry Key Value\r
+ Variable=STARTUPDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%WIN%\Start Menu\Programs\StartUp\r
+ Value Name=StartUp\r
+ Flags=00000010\r
+end\r
+item: Get Registry Key Value\r
+ Variable=DESKTOPDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%WIN%\Desktop\r
+ Value Name=Desktop\r
+ Flags=00000010\r
+end\r
+item: Get Registry Key Value\r
+ Variable=STARTMENUDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%WIN%\Start Menu\r
+ Value Name=Start Menu\r
+ Flags=00000010\r
+end\r
+item: Get Registry Key Value\r
+ Variable=GROUPDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%WIN%\Start Menu\Programs\r
+ Value Name=Programs\r
+ Flags=00000010\r
+end\r
+item: Get Registry Key Value\r
+ Variable=CSTARTUPDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%STARTUPDIR%\r
+ Value Name=Common Startup\r
+ Flags=00000100\r
+end\r
+item: Get Registry Key Value\r
+ Variable=CDESKTOPDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%DESKTOPDIR%\r
+ Value Name=Common Desktop\r
+ Flags=00000100\r
+end\r
+item: Get Registry Key Value\r
+ Variable=CSTARTMENUDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%STARTMENUDIR%\r
+ Value Name=Common Start Menu\r
+ Flags=00000100\r
+end\r
+item: Get Registry Key Value\r
+ Variable=CGROUPDIR\r
+ Key=Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\r
+ Default=%GROUPDIR%\r
+ Value Name=Common Programs\r
+ Flags=00000100\r
+end\r
+item: Set Variable\r
+ Variable=CGROUP_SAVE\r
+ Value=%GROUP%\r
+end\r
+item: Set Variable\r
+ Variable=GROUP\r
+ Value=%GROUPDIR%\%GROUP%\r
+end\r
+item: Create Shortcut\r
+ Source=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\runemacs.exe\r
+ Destination=%GROUP%\XEmacs.lnk\r
+ Working Directory=\\r
+ Icon Number=0\r
+end\r
+item: Create Shortcut\r
+ Source=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\runemacs.exe\r
+ Destination=%DESKTOPDIR%\XEmacs.lnk\r
+ Working Directory=\\r
+ Icon Number=0\r
+end\r
+item: Else Statement\r
+end\r
+item: Add ProgMan Icon\r
+ Group=%GROUP%\r
+ Icon Name=XEmacs\r
+ Command Line=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\runemacs.exe\r
+ Default Directory=\\r
+ Flags=01000000\r
+end\r
+item: End Block\r
+end\r
+item: Edit Registry\r
+ Total Keys=16\r
+ item: Key\r
+ Key=SOFTWARE\GNU\XEmacs\r
+ New Value=%MAINDIR%\r
+ Value Name=emacs_dir\r
+ Root=2\r
+ end\r
+ item: Key\r
+ Key=SOFTWARE\GNU\XEmacs\r
+ New Value=%MAINDIR%\xemacs-packages\r
+ Value Name=EMACSPACKAGEPATH\r
+ Root=2\r
+ end\r
+ item: Key\r
+ Key=SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\runemacs.exe\r
+ New Value=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\r
+ Value Name=Path\r
+ Root=2\r
+ end\r
+ item: Key\r
+ Key=SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\xemacs.exe\r
+ New Value=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\r
+ Value Name=Path\r
+ Root=2\r
+ end\r
+ item: Key\r
+ Key=.el\r
+ New Value=elfile\r
+ end\r
+ item: Key\r
+ Key=.el\r
+ New Value=text/plain\r
+ Value Name=Content Type\r
+ end\r
+ item: Key\r
+ Key=elfile\r
+ New Value=Emacs lisp\r
+ end\r
+ item: Key\r
+ Key=elfile\r
+ New Value=00 00 01 00\r
+ Value Name=EditFlags\r
+ Data Type=4\r
+ end\r
+ item: Key\r
+ Key=elfile\DefaultIcon\r
+ New Value=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\runemacs.exe,2\r
+ end\r
+ item: Key\r
+ Key=elfile\QuickView\r
+ New Value=*\r
+ end\r
+ item: Key\r
+ Key=elfile\Shell\r
+ New Value=\r
+ end\r
+ item: Key\r
+ Key=elfile\Shell\open\r
+ end\r
+ item: Key\r
+ Key=elfile\Shell\open\command\r
+ New Value=%MAINDIR%\<<<dirs.dst>>>\i386-pc-win32\runemacs.exe "%%1"\r
+ end\r
+ item: Key\r
+ Key=elfile\Shell\open\ddeexec\r
+ New Value=open("%%1")\r
+ end\r
+ item: Key\r
+ Key=elfile\Shell\open\ddeexec\Application\r
+ New Value=XEmacs\r
+ New Value=\r
+ end\r
+ item: Key\r
+ Key=elfile\Shell\open\ddeexec\topic\r
+ New Value=System\r
+ end\r
+end\r
+item: Wizard Block\r
+ Direction Variable=DIRECTION\r
+ Display Variable=DISPLAY\r
+ Bitmap Pathname=<<<dirs.source>>>\nt\Wise\gnu.bmp\r
+ X Position=9\r
+ Y Position=10\r
+ Filler Color=8421440\r
+ Flags=00000011\r
+end\r
+item: Custom Dialog Set\r
+ Name=Finished\r
+ Display Variable=DISPLAY\r
+ item: Dialog\r
+ Title=Installation Complete\r
+ Title French=Installation en cours\r
+ Title German=Installation abgeschlossen\r
+ Title Portuguese=Instalação Completa \r
+ Title Spanish=Se ha completado la Instalación\r
+ Title Italian=Installazione completata\r
+ Title Danish=Installation gennemført\r
+ Title Dutch=Installatie afgerond\r
+ Title Norwegian=Installasjonen er fullført\r
+ Title Swedish=Installationen klar\r
+ Width=280\r
+ Height=224\r
+ Font Name=Helv\r
+ Font Size=8\r
+ item: Push Button\r
+ Rectangle=170 185 212 199\r
+ Variable=DIRECTION\r
+ Value=N\r
+ Create Flags=01010000000000010000000000000001\r
+ Text=&Finish >\r
+ Text French=&Terminer>\r
+ Text German=&Fertigstellen>\r
+ Text Portuguese=&Terminar >\r
+ Text Spanish=&Finalizar>\r
+ Text Italian=&Fine >\r
+ Text Danish=&Afslut >\r
+ Text Dutch=&Klaar>\r
+ Text Norwegian=&Avslutt>\r
+ Text Swedish=&Sluta>\r
+ end\r
+ item: Push Button\r
+ Control Name=CANCEL\r
+ Rectangle=222 185 264 199\r
+ Action=3\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=Cancel\r
+ Text French=Annuler\r
+ Text German=Abbrechen\r
+ Text Portuguese=Cancelar\r
+ Text Spanish=Cancelar\r
+ Text Italian=Annulla\r
+ Text Danish=Annuller\r
+ Text Dutch=Annuleren\r
+ Text Norwegian=Avbryt\r
+ Text Swedish=Avbryt\r
+ end\r
+ item: Static\r
+ Rectangle=9 177 263 178\r
+ Action=3\r
+ Create Flags=01010000000000000000000000000111\r
+ end\r
+ item: Static\r
+ Rectangle=90 10 260 63\r
+ Enabled Color=00000000000000001111111111111111\r
+ Create Flags=01010000000000000000000000000000\r
+ Text=%APPTITLE% has been successfully installed.\r
+ Text=\r
+ Text=\r
+ Text=Press the Finish button to exit this installation.\r
+ Text=\r
+ Text French=L'installation de %APPTITLE% est réussie\r
+ Text French=\r
+ Text French=\r
+ Text French=Cliquez sur Terminer pour quitter cette installation\r
+ Text French=\r
+ Text German=%APPTITLE% wurde erfolgreich installiert.\r
+ Text German=\r
+ Text German=\r
+ Text German=Zum Beenden dieser Installation Fertigstellen anklicken.\r
+ Text German=\r
+ Text Portuguese=%APPTITLE% foi instalado com êxito\r
+ Text Portuguese=\r
+ Text Portuguese=\r
+ Text Portuguese=Pressionar o botão Terminar para sair desta instalação\r
+ Text Portuguese=\r
+ Text Spanish=%APPTITLE% se ha instalado con éxito.\r
+ Text Spanish=\r
+ Text Spanish=\r
+ Text Spanish=Pulse el botón de Finalizar para salir de esta instalación.\r
+ Text Spanish=\r
+ Text Italian=%APPTITLE% è stato installato.\r
+ Text Italian=\r
+ Text Italian=\r
+ Text Italian=Premi il pulsante Fine per uscire dal programma di installazione\r
+ Text Italian=\r
+ Text Danish=%APPTITLE% er nu installeret korrekt.\r
+ Text Danish=\r
+ Text Danish=\r
+ Text Danish=Klik på Afslut for at afslutte installationen.\r
+ Text Danish=\r
+ Text Dutch=%APPTITLE% is met succes geïnstalleerd.\r
+ Text Dutch=\r
+ Text Dutch=\r
+ Text Dutch=Druk op Klaar om deze installatie af te ronden.\r
+ Text Dutch=\r
+ Text Norwegian=Installasjonen av %APPTITLE% er suksessfull.\r
+ Text Norwegian=\r
+ Text Norwegian=\r
+ Text Norwegian=Trykk på Avslutt-tasten for å avslutte denne installasjonen.\r
+ Text Norwegian=\r
+ Text Swedish=Installationen av %APPTITLE% har lyckats.\r
+ Text Swedish=\r
+ Text Swedish=\r
+ Text Swedish=Tryck på Sluta för att gå ur installationsprogrammet.\r
+ Text Swedish=\r
+ end\r
+ item: Push Button\r
+ Control Name=BACK\r
+ Rectangle=128 185 170 199\r
+ Variable=DIRECTION\r
+ Value=B\r
+ Create Flags=01010000000000010000000000000000\r
+ Text=< &Back\r
+ Text French=<&Retour\r
+ Text German=<&Zurück\r
+ Text Portuguese=<&Retornar\r
+ Text Spanish=<&Retroceder\r
+ Text Italian=< &Indietro\r
+ Text Danish=<&Tilbage\r
+ Text Dutch=<&Terug\r
+ Text Norwegian=<&Tilbake\r
+ Text Swedish=< &Tillbaka\r
+ end\r
+ item: Set Control Attribute\r
+ Control Name=BACK\r
+ Operation=1\r
+ end\r
+ item: Set Control Attribute\r
+ Control Name=CANCEL\r
+ Operation=1\r
+ end\r
+ end\r
+end\r
+item: End Block\r
+end\r
+item: New Event\r
+ Name=Cancel\r
+end\r
+item: Include Script\r
+ Pathname=%_WISE_%\INCLUDE\rollback.wse\r
+end\r
projects / chise / xemacs-chise.git.1 / commitdiff
