translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings
+File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
-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.
-
-\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.
+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: 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.
+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: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File
-
-Init File Examples
-------------------
+File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
- Here are some examples of doing certain commonly desired things with
-Lisp expressions:
+CONX
+====
- * Make <TAB> in C mode just insert a tab if point is in the middle
- of a line.
+ Besides producing a file of scrambled text with Dissociated Press,
+you can generate random sentences by using CONX.
- (setq c-tab-always-indent nil)
+`M-x conx'
+ Generate random sentences in the `*conx*' buffer.
- Here we have a variable whose value is normally `t' for `true' and
- the alternative is `nil' for `false'.
+`M-x conx-buffer'
+ Absorb the text in the current buffer into the `conx' database.
- * Make searches case sensitive by default (in all buffers that do not
- override this).
+`M-x conx-init'
+ Forget the current word-frequency tree.
- (setq-default case-fold-search nil)
+`M-x conx-load'
+ Load a `conx' database that has been previously saved with `M-x
+ conx-save'.
- 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.
+`M-x conx-region'
+ Absorb the text in the current buffer into the `conx' database.
- * Make Text mode the default mode for new buffers.
+`M-x conx-save'
+ Save the current `conx' database to a file for future retrieval.
- (setq default-major-mode 'text-mode)
+ 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'.
- 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.
+\1f
+File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
- (load "~/foo.elc")
+Other Amusements
+================
- Here an absolute file name is used, so no searching is done.
+ 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.
- * Rebind the key `C-x l' to run the function `make-symbolic-link'.
+ When you are frustrated, try the famous Eliza program. Just do `M-x
+doctor'. End each input by typing `RET' twice.
- (global-set-key "\C-xl" 'make-symbolic-link)
+ When you are feeling strange, type `M-x yow'.
- or
+\1f
+File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
- (define-key global-map "\C-xl" 'make-symbolic-link)
+Emulation
+=========
- Note once again the single-quote used to refer to the symbol
- `make-symbolic-link' instead of its value as a variable.
+ XEmacs can be programmed to emulate (more or less) most other
+editors. Standard facilities can emulate these:
- * Do the same thing for C mode only.
+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.
- (define-key c-mode-map "\C-xl" 'make-symbolic-link)
+ To start Viper, put the command
- * Bind the function key <F1> to a command in C mode. Note that the
- names of function keys must be lower case.
+ (viper-mode)
- (define-key c-mode-map 'f1 'make-symbolic-link)
+ in your init file. *Note Init File::.
- * Bind the shifted version of <F1> to a command.
+ Viper comes with a separate manual that is provided standard with
+ the XEmacs distribution.
- (define-key c-mode-map '(shift f1) 'make-symbolic-link)
+EDT (DEC VMS editor)
+ Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
+ edt-emulation-off' restores normal Emacs command bindings.
- * Redefine all keys which now run `next-line' in Fundamental mode to
- run `forward-line' instead.
+ 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.
- (substitute-key-definition 'next-line 'forward-line
- global-map)
+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.
- * Make `C-x C-v' undefined.
+ It is also possible to run Mocklisp code written for Gosling Emacs.
+ *Note Mocklisp::.
- (global-unset-key "\C-x\C-v")
+\1f
+File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
- 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.
+Customization
+*************
- * Make `$' have the syntax of punctuation in Text mode. Note the
- use of a character constant for `$'.
+ This chapter talks about various topics relevant to adapting the
+behavior of Emacs in minor ways.
- (modify-syntax-entry ?\$ "." text-mode-syntax-table)
+ 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 init file or other appropriate
+file to do the customization in each session. *Note Init File::.
- * Enable the use of the command `eval-expression' without
- confirmation.
+* Menu:
- (put 'eval-expression 'disabled nil)
+* 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 init file.
+* Audible Bell:: Changing how Emacs sounds the bell.
+* Faces:: Changing the fonts and colors of a region of text.
+* Frame Components:: Controlling the presence and positions of the
+ menubar, toolbars, and gutters.
+* X Resources:: X resources controlling various aspects of the
+ behavior of XEmacs.
\1f
-File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File
+File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
-Terminal-Specific Initialization
---------------------------------
+Minor Modes
+===========
- 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.
+ 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: 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.
+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::).
- 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'
+* Menu:
-`yes-or-no-p'
- You type something other than `yes' or `no'
+* 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: Faces, Next: X Resources, Prev: Audible Bell, Up: Customization
+File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
-Faces
-=====
+Examining and Setting Variables
+-------------------------------
- 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.
+`C-h v'
+`M-x describe-variable'
+ Print the value and documentation of a variable.
- The display attributes of faces may be specified either in Lisp or
-through the X resource manager.
+`M-x set-variable'
+ Change the value of a variable.
-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.
+ 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.
-\1f
-File: xemacs.info, Node: X Resources, Prev: Faces, Up: Customization
+ C-h v fill-column <RET>
-X Resources
-===========
+prints something like:
- 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.
+ fill-column's value is 75
+
+ Documentation:
+ *Column beyond which automatic line-wrapping should happen.
+ Automatically becomes local when set in any fashion.
- Starting with XEmacs 21, XEmacs uses the class `XEmacs' if it finds
-any XEmacs resources in the resource database when the X connection is
-initialized. Otherwise, it will use the class `Emacs' for backwards
-compatibility. The variable X-EMACS-APPLICATION-CLASS may be consulted
-to determine the application class being used.
+The 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.
- The examples in this section assume the application class is `Emacs'.
+ 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,
- 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.
+ M-x set-variable <RET> fill-column <RET> 75 <RET>
- You can specify resources for all frames with the syntax:
+sets `fill-column' to 75, as if you had executed the Lisp expression
+`(setq fill-column 75)'.
- Emacs*parameter: value
+ Setting variables in this way, like all means of customizing Emacs
+except where explicitly stated, affects only the current Emacs session.
-or
-
- Emacs*EmacsFrame.parameter:value
+\1f
+File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
-You can specify resources for a particular frame with the syntax:
+Easy Customization Interface
+----------------------------
- Emacs*FRAME-NAME.parameter: value
+ 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:
-* 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.
+* 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: 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:
+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.
- Emacs*EmacsFrame.geometry: 80x55
+\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 init file so as to set the option variable
+again each time you start Emacs. *Note Init File::. 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.
-To set the geometry of a particular frame named `fred', do this:
+\1f
+File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
- Emacs*fred.geometry: 80x55
+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]'.
-Important! Do not use the following syntax:
+\1f
+File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
- Emacs*geometry: 80x55
+Customizing Specific Items
+..........................
-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.
+ 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.
- As a special case, this geometry specification also works (and sets
-the default size of all Emacs frames to 80 columns by 55 lines):
+`M-x customize-option <RET> OPTION <RET>'
+ Set up a customization buffer with just one option, OPTION.
- Emacs.geometry: 80x55
+`M-x customize-face <RET> FACE <RET>'
+ Set up a customization buffer with just one face, FACE.
-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.
+`M-x customize-group <RET> GROUP <RET>'
+ Set up a customization buffer with just one group, GROUP.
- The `-geometry' command-line argument sets only the geometry of the
-initial frame created by Emacs.
+`M-x customize-apropos <RET> REGEXP <RET>'
+ Set up a customization buffer with all the options, faces and
+ groups that match REGEXP.
- A more complete explanation of geometry-handling is
+`M-x customize-saved'
+ Set up a customization buffer containing all options and faces
+ that you have saved with customization buffers.
- * The `-geometry' command-line option sets the `Emacs.geometry'
- resource, that is, the geometry of the ApplicationShell.
+`M-x customize-customized'
+ Set up a customization buffer containing all options and faces
+ that you have customized but not saved.
- * 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.
+ 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.
- * For subsequent frames, the order is reversed: First the frame, and
- then the ApplicationShell.
+ Likewise, you can modify a specific face, chosen by name, using `M-x
+customize-face'.
- * 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.
+ 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]'.
- * For subsequent frames, the position is taken only from the frame,
- and never from the ApplicationShell.
+ 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).
- 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.
+ 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: Iconic Resources, Next: Resource List, Prev: Geometry Resources, Up: X Resources
-
-Iconic Resources
-----------------
-
- Analogous to `-geometry', the `-iconic' command-line option sets the
-iconic flag of the ApplicationShell (`Emacs.iconic') and always applies
-to the first frame created regardless of its name. However, it is
-possible to set the iconic flag on particular frames (by name) by using
-the `Emacs*FRAME-NAME.iconic' resource.
+File: xemacs.info, Node: 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: 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'.
+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: 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
+File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables
- 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.
+Local Variables in Files
+------------------------
-`italic'
- If this is not specified in the resource database, Emacs tries to
- find an italic version of the font of the default face.
+ A file can contain a "local variables list", which specifies the
+values to use for certain Emacs variables when that file is edited.
+Visiting the file checks for a local variables list and makes each
+variable in the list local to the buffer in which the file is visited,
+with the value specified in the file.
+
+ A local variables list goes near the end of the file, in the last
+page. (It is often best to put it on a page by itself.) The local
+variables list starts with a line containing the string `Local
+Variables:', and ends with a line containing the string `End:'. In
+between come the variable names and values, one set per line, as
+`VARIABLE: VALUE'. The VALUEs are not evaluated; they are used
+literally.
+
+ The line which starts the local variables list does not have to say
+just `Local Variables:'. If there is other text before `Local
+Variables:', that text is called the "prefix", and if there is other
+text after, that is called the "suffix". If a prefix or suffix are
+present, each entry in the local variables list should have the prefix
+before it and the suffix after it. This includes the `End:' line. The
+prefix and suffix are included to disguise the local variables list as
+a comment so the compiler or text formatter will ignore it. If you do
+not need to disguise the local variables list as a comment in this way,
+there is no need to include a prefix or a suffix.
+
+ Two "variable" names are special in a local variables list: a value
+for the variable `mode' sets the major mode, and a value for the
+variable `eval' is simply evaluated as an expression and the value is
+ignored. These are not real variables; setting them in any other
+context does not have the same effect. If `mode' is used in a local
+variables list, it should be the first entry in the list.
+
+ Here is an example of a local variables list:
+ ;;; Local Variables: ***
+ ;;; mode:lisp ***
+ ;;; comment-column:0 ***
+ ;;; comment-start: ";;; " ***
+ ;;; comment-end:"***" ***
+ ;;; End: ***
+
+ Note that the prefix is `;;; ' and the suffix is ` ***'. Note also
+that comments in the file begin with and end with the same strings.
+Presumably the file contains code in a language which is enough like
+Lisp for Lisp mode to be useful but in which comments start and end
+differently. The prefix and suffix are used in the local variables
+list to make the list look like several lines of comments when the
+compiler or interpreter for that language reads the file.
+
+ The start of the local variables list must be no more than 3000
+characters from the end of the file, and must be in the last page if the
+file is divided into pages. Otherwise, Emacs will not notice it is
+there. The purpose is twofold: a stray `Local Variables:' not in the
+last page does not confuse Emacs, and Emacs never needs to search a
+long file that contains no page markers and has no local variables list.
+
+ You may be tempted to turn on Auto Fill mode with a local variable
+list. That is inappropriate. Whether you use Auto Fill mode or not is
+a matter of personal taste, not a matter of the contents of particular
+files. If you want to use Auto Fill, set up major mode hooks with your
+init file to turn it on (when appropriate) for you alone (*note Init
+File::). Don't try to use a local variable list that would impose your
+taste on everyone working with the file.
+
+ XEmacs allows you to specify local variables in the first line of a
+file, in addition to specifying them in the `Local Variables' section
+at the end of a file.
+
+ If the first line of a file contains two occurrences of ``-*-'',
+XEmacs uses the information between them to determine what the major
+mode and variable settings should be. For example, these are all legal:
+
+ ;;; -*- mode: emacs-lisp -*-
+ ;;; -*- mode: postscript; version-control: never -*-
+ ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
+
+ For historical reasons, the syntax ``-*- modename -*-'' is allowed
+as well; for example, you can use:
+
+ ;;; -*- emacs-lisp -*-
+
+ The variable `enable-local-variables' controls the use of local
+variables lists in files you visit. The value can be `t', `nil', or
+something else. A value of `t' means local variables lists are obeyed;
+`nil' means they are ignored; anything else means query.
+
+ The command `M-x normal-mode' always obeys local variables lists and
+ignores this variable.
-`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.
+\1f
+File: xemacs.info, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization
-`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.
+Keyboard Macros
+===============
-`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.
+ 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.
-`left-margin'
-`right-margin'
- These are the faces that the left and right annotation margins are
- displayed in.
+`C-x ('
+ Start defining a keyboard macro (`start-kbd-macro').
-`zmacs-region'
- This is the face that mouse selections are displayed in.
+`C-x )'
+ End the definition of a keyboard macro (`end-kbd-macro').
-`isearch'
- This is the face that the matched text being searched for is
- displayed in.
+`C-x e'
+ Execute the most recent keyboard macro (`call-last-kbd-macro').
-`info-node'
- This is the face of info menu items. If unspecified, it is copied
- from `bold-italic'.
+`C-u C-x ('
+ Re-execute last keyboard macro, then add more keys to its
+ definition.
-`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.)
+`C-x q'
+ When this point is reached during macro execution, ask for
+ confirmation (`kbd-macro-query').
- 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.
+`M-x name-last-kbd-macro'
+ Give a command name (for the duration of the session) to the most
+ recently defined keyboard macro.
- 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
+`M-x insert-kbd-macro'
+ Insert in the buffer a keyboard macro's definition, as Lisp code.
- *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+ 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.
-If you use any of the other, less strict font name formats, some of
-which look like
+ 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.
- lucidasanstypewriter-12
- fixed
- 9x13
+* Menu:
- 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)'.
+* 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: Widgets, Next: Menubar Resources, Prev: Face Resources, Up: X Resources
+File: xemacs.info, Node: Basic Kbd Macro, Next: Save Kbd Macro, Up: Keyboard Macros
-Widgets
--------
+Basic Use
+---------
- 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:
+ 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.
- 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
+ For example,
-Menubar Resources
------------------
+ C-x ( M-f foo C-x )
- 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.
+defines a macro to move forward a word and then insert `foo'.
- If Emacs was compiled to use only the Motif-lookalike menu widgets,
-then one way to specify the font of the menubar would be
+ 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').
- Emacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
+ 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.
- If the Motif library is being used, then one would have to use
+ 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.
- 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.
+ 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: Quitting, Next: Lossage, Prev: Customization, Up: Top
-
-Quitting and Aborting
-=====================
-
-`C-g'
- Quit. Cancel running or partially typed command.
-
-`C-]'
- Abort innermost recursive editing level and cancel the command
- which invoked it (`abort-recursive-edit').
-
-`M-x top-level'
- Abort all recursive editing levels that are currently executing.
-
-`C-x u'
- Cancel an already-executed command, usually (`undo').
-
- There are two ways of cancelling commands which are not finished
-executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
-top-level'. Quitting is cancelling a partially typed command or one
-which is already running. Aborting is getting out of a recursive
-editing level and cancelling the command that invoked the recursive
-edit.
-
- Quitting with `C-g' is used for getting rid of a partially typed
-command or a numeric argument that you don't want. It also stops a
-running command in the middle in a relatively safe way, so you can use
-it if you accidentally start executing a command that takes a long
-time. In particular, it is safe to quit out of killing; either your
-text will ALL still be there, or it will ALL be in the kill ring (or
-maybe both). Quitting an incremental search does special things
-documented under searching; in general, it may take two successive
-`C-g' characters to get out of a search. `C-g' works by setting the
-variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
-checks this variable frequently and quits if it is non-`nil'. `C-g' is
-only actually executed as a command if it is typed while Emacs is
-waiting for input.
-
- If you quit twice in a row before the first `C-g' is recognized, you
-activate the "emergency escape" feature and return to the shell. *Note
-Emergency Escape::.
-
- You can use `C-]' (`abort-recursive-edit') to get out of a recursive
-editing level and cancel the command which invoked it. Quitting with
-`C-g' does not do this, and could not do this because it is used to
-cancel a partially typed command within the recursive editing level.
-Both operations are useful. For example, if you are in the Emacs
-debugger (*note Lisp Debug::) and have typed `C-u 8' to enter a numeric
-argument, you can cancel that argument with `C-g' and remain in the
-debugger.
-
- The command `M-x top-level' is equivalent to "enough" `C-]' commands
-to get you out of all the levels of recursive edits that you are in.
-`C-]' only gets you out one level at a time, but `M-x top-level' goes
-out all levels at once. Both `C-]' and `M-x top-level' are like all
-other commands and unlike `C-g' in that they are effective only when
-Emacs is ready for a command. `C-]' is an ordinary key and has its
-meaning only because of its binding in the keymap. *Note Recursive
-Edit::.
-
- `C-x u' (`undo') is not strictly speaking a way of cancelling a
-command, but you can think of it as cancelling a command already
-finished executing. *Note Undo::.
+File: xemacs.info, Node: 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 (*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: 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.
+File: xemacs.info, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros
-* Menu:
+Executing Macros With Variations
+--------------------------------
-* 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.
+ 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: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage
-
-Recursive Editing Levels
-------------------------
+File: xemacs.info, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization
- Recursive editing levels are important and useful features of Emacs,
-but they can seem like malfunctions to the user who does not understand
-them.
+Customizing Key Bindings
+========================
- 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::.
+ This section deals with the "keymaps" that define the bindings
+between keys and functions, and shows how you can customize these
+bindings.
-\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.
+ 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.
-\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.
+* Menu:
- 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::.
+* 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.