1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell
35 Interactive Inferior Shell
36 --------------------------
38 To run a subshell interactively with its typescript in an XEmacs
39 buffer, use `M-x shell'. This creates (or reuses) a buffer named
40 `*shell*' and runs a subshell with input coming from and output going
41 to that buffer. That is to say, any "terminal output" from the subshell
42 will go into the buffer, advancing point, and any "terminal input" for
43 the subshell comes from text in the buffer. To give input to the
44 subshell, go to the end of the buffer and type the input, terminated by
47 XEmacs does not wait for the subshell to do anything. You can switch
48 windows or buffers and edit them while the shell is waiting, or while
49 it is running a command. Output from the subshell waits until XEmacs
50 has time to process it; this happens whenever XEmacs is waiting for
51 keyboard input or for time to elapse.
53 To get multiple subshells, change the name of buffer `*shell*' to
54 something different by using `M-x rename-buffer'. The next use of `M-x
55 shell' creates a new buffer `*shell*' with its own subshell. By
56 renaming this buffer as well you can create a third one, and so on.
57 All the subshells run independently and in parallel.
59 The file name used to load the subshell is the value of the variable
60 `explicit-shell-file-name', if that is non-`nil'. Otherwise, the
61 environment variable `ESHELL' is used, or the environment variable
62 `SHELL' if there is no `ESHELL'. If the file name specified is
63 relative, the directories in the list `exec-path' are searched (*note
64 Single Shell Commands: Single Shell.).
66 As soon as the subshell is started, it is sent as input the contents
67 of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME
68 is the name of the file that the shell was loaded from. For example,
69 if you use `csh', the file sent to it is `~/.emacs_csh'.
71 `cd', `pushd', and `popd' commands given to the inferior shell are
72 watched by XEmacs so it can keep the `*shell*' buffer's default
73 directory the same as the shell's working directory. These commands
74 are recognized syntactically by examining lines of input that are sent.
75 If you use aliases for these commands, you can tell XEmacs to
76 recognize them also. For example, if the value of the variable
77 `shell-pushd-regexp' matches the beginning of a shell command line,
78 that line is regarded as a `pushd' command. Change this variable when
79 you add aliases for `pushd'. Likewise, `shell-popd-regexp' and
80 `shell-cd-regexp' are used to recognize commands with the meaning of
83 `M-x shell-resync-dirs' queries the shell and resynchronizes XEmacs'
84 idea of what the current directory stack is. `M-x
85 shell-dirtrack-toggle' turns directory tracking on and off.
87 XEmacs keeps a history of the most recent commands you have typed in
88 the `*shell*' buffer. If you are at the beginning of a shell command
89 line and type <M-p>, the previous shell input is inserted into the
90 buffer before point. Immediately typing <M-p> again deletes that input
91 and inserts the one before it. By repeating <M-p> you can move
92 backward through your commands until you find one you want to repeat.
93 You may then edit the command before typing <RET> if you wish. <M-n>
94 moves forward through the command history, in case you moved backward
95 past the one you wanted while using <M-p>. If you type the first few
96 characters of a previous command and then type <M-p>, the most recent
97 shell input starting with those characters is inserted. This can be
98 very convenient when you are repeating a sequence of shell commands.
99 The variable `input-ring-size' controls how many commands are saved in
100 your input history. The default is 30.
103 File: xemacs.info, Node: Shell Mode, Next: Terminal emulator, Prev: Interactive Shell, Up: Shell
108 The shell buffer uses Shell mode, which defines several special keys
109 attached to the `C-c' prefix. They are chosen to resemble the usual
110 editing and job control characters present in shells that are not under
111 XEmacs, except that you must type `C-c' first. Here is a list of the
112 special key bindings of Shell mode:
115 At end of buffer send line as input; otherwise, copy current line
116 to end of buffer and send it (`send-shell-input'). When a line is
117 copied, any text at the beginning of the line that matches the
118 variable `shell-prompt-pattern' is left out; this variable's value
119 should be a regexp string that matches the prompts that you use in
123 Send end-of-file as input, probably causing the shell or its
124 current subjob to finish (`shell-send-eof').
127 If point is not at the end of the buffer, delete the next
128 character just like most other modes. If point is at the end of
129 the buffer, send end-of-file as input, instead of generating an
130 error as in other modes (`comint-delchar-or-maybe-eof').
133 Kill all text that has yet to be sent as input
134 (`kill-shell-input').
137 Kill a word before point (`backward-kill-word').
140 Interrupt the shell or its current subjob if any
141 (`interrupt-shell-subjob').
144 Stop the shell or its current subjob if any (`stop-shell-subjob').
147 Send quit signal to the shell or its current subjob if any
148 (`quit-shell-subjob').
151 Delete last batch of output from shell (`kill-output-from-shell').
154 Scroll top of last batch of output to top of window
155 (`show-output-from-shell').
158 Copy the previous bunch of shell input and insert it into the
159 buffer before point (`copy-last-shell-input'). No final newline
160 is inserted, and the input copied is not resubmitted until you type
164 Move backward through the input history. Search for a matching
165 command if you have typed the beginning of a command
166 (`comint-previous-input').
169 Move forward through the input history. Useful when you are using
170 <M-p> quickly and go past the desired command
171 (`comint-next-input').
174 Complete the file name preceding point (`comint-dynamic-complete').
177 File: xemacs.info, Node: Terminal emulator, Next: Term Mode, Prev: Shell Mode, Up: Shell
179 Interactive Inferior Shell with Terminal Emulator
180 -------------------------------------------------
182 To run a subshell in a terminal emulator, putting its typescript in
183 an XEmacs buffer, use `M-x term'. This creates (or reuses) a buffer
184 named `*term*' and runs a subshell with input coming from your keyboard
185 and output going to that buffer.
187 All the normal keys that you type are sent without any interpretation
188 by XEmacs directly to the subshell, as "terminal input." Any "echo" of
189 your input is the responsibility of the subshell. (The exception is
190 the terminal escape character, which by default is `C-c'. *note Term
191 Mode::.) Any "terminal output" from the subshell goes into the buffer,
194 Some programs (such as XEmacs itself) need to control the appearance
195 on the terminal screen in detail. They do this by sending special
196 control codes. The exact control codes needed vary from terminal to
197 terminal, but nowadays most terminals and terminal emulators (including
198 xterm) understand the so-called "ANSI escape sequences" (first
199 popularized by the Digital's VT100 family of terminal). The term mode
200 also understands these escape sequences, and for each control code does
201 the appropriate thing to change the buffer so that the appearance of
202 the window will match what it would be on a real terminal. Thus you
203 can actually run XEmacs inside an XEmacs Term window!
205 XEmacs does not wait for the subshell to do anything. You can switch
206 windows or buffers and edit them while the shell is waiting, or while
207 it is running a command. Output from the subshell waits until XEmacs
208 has time to process it; this happens whenever XEmacs is waiting for
209 keyboard input or for time to elapse.
211 To make multiple terminal emulators, rename the buffer `*term*' to
212 something different using `M-x rename-uniquely', just as with Shell
215 The file name used to load the subshell is determined the same way
218 Unlike Shell mode, Term mode does not track the current directory by
219 examining your input. Instead, if you use a programmable shell, you
220 can have it tell Term what the current directory is. This is done
221 automatically by bash for version 1.15 and later.
224 File: xemacs.info, Node: Term Mode, Next: Paging in Term, Prev: Terminal emulator, Up: Shell
229 Term uses Term mode, which has two input modes: In line mode, Term
230 basically acts like Shell mode. *Note Shell Mode::. In Char mode,
231 each character is sent directly to the inferior subshell, except for
232 the Term escape character, normally `C-c'.
234 To switch between line and char mode, use these commands:
235 findex term-char-mode
238 Switch to line mode. Do nothing if already in line mode.
241 Switch to char mode. Do nothing if already in char mode.
243 The following commands are only available in Char mode:
245 Send a literal <C-c> to the sub-shell.
248 A prefix command to conveniently access the global <C-x> commands.
249 For example, `C-c C-x o' invokes the global binding of `C-x o',
250 which is normally `other-window'.
253 File: xemacs.info, Node: Paging in Term, Prev: Term Mode, Up: Shell
255 Paging in the terminal emulator
256 -------------------------------
258 Term mode has a pager feature. When the pager is enabled, term mode
259 will pause at the end of each screenful.
262 Toggles the pager feature: Disables the pager if it is enabled,
263 and vice versa. This works in both line and char modes. If the
264 pager enabled, the mode-line contains the word `page'.
266 If the pager is enabled, and Term receives more than a screenful of
267 output since your last input, Term will enter More break mode. This is
268 indicated by `**MORE**' in the mode-line. Type a `Space' to display
269 the next screenful of output. Type `?' to see your other options. The
270 interface is similar to the Unix `more' program.
273 File: xemacs.info, Node: Narrowing, Next: Hardcopy, Prev: Shell, Up: Top
278 "Narrowing" means focusing in on some portion of the buffer, making
279 the rest temporarily invisible and inaccessible. Cancelling the
280 narrowing and making the entire buffer once again visible is called
281 "widening". The amount of narrowing in effect in a buffer at any time
282 is called the buffer's "restriction".
285 Narrow down to between point and mark (`narrow-to-region').
288 Widen to make the entire buffer visible again (`widen').
290 Narrowing sometimes makes it easier to concentrate on a single
291 subroutine or paragraph by eliminating clutter. It can also be used to
292 restrict the range of operation of a replace command or repeating
293 keyboard macro. The word `Narrow' appears in the mode line whenever
294 narrowing is in effect. When you have narrowed to a part of the
295 buffer, that part appears to be all there is. You can't see the rest,
296 can't move into it (motion commands won't go outside the visible part),
297 and can't change it in any way. However, the invisible text is not
298 gone; if you save the file, it will be saved.
300 The primary narrowing command is `C-x n n' (`narrow-to-region'). It
301 sets the current buffer's restrictions so that the text in the current
302 region remains visible but all text before the region or after the
303 region is invisible. Point and mark do not change.
305 Because narrowing can easily confuse users who do not understand it,
306 `narrow-to-region' is normally a disabled command. Attempting to use
307 this command asks for confirmation and gives you the option of enabling
308 it; once you enable the command, confirmation will no longer be
309 required. *Note Disabling::.
311 To undo narrowing, use `C-x n w' (`widen'). This makes all text in
312 the buffer accessible again.
314 Use the `C-x =' command to get information on what part of the
315 buffer you narrowed down. *Note Position Info::.
318 File: xemacs.info, Node: Hardcopy, Next: Recursive Edit, Prev: Narrowing, Up: Top
323 The XEmacs commands for making hardcopy derive their names from the
324 Unix commands `print' and `lpr'.
327 Print hardcopy of current buffer using Unix command `print'
328 (`lpr -p'). This command adds page headings containing the file
329 name and page number.
332 Print hardcopy of current buffer using Unix command `lpr'. This
333 command does not add page headings.
336 Like `print-buffer', but prints only the current region.
339 Like `lpr-buffer', but prints only the current region.
341 All the hardcopy commands pass extra switches to the `lpr' program
342 based on the value of the variable `lpr-switches'. Its value should be
343 a list of strings, each string a switch starting with `-'. For
344 example, the value could be `("-Pfoo")' to print on printer `foo'.
347 File: xemacs.info, Node: Recursive Edit, Next: Dissociated Press, Prev: Hardcopy, Up: Top
349 Recursive Editing Levels
350 ========================
352 A "recursive edit" is a situation in which you are using XEmacs
353 commands to perform arbitrary editing while in the middle of another
354 XEmacs command. For example, when you type `C-r' inside a
355 `query-replace', you enter a recursive edit in which you can change the
356 current buffer. When you exit from the recursive edit, you go back to
359 "Exiting" a recursive edit means returning to the unfinished
360 command, which continues execution. For example, exiting the recursive
361 edit requested by `C-r' in `query-replace' causes query replacing to
362 resume. Exiting is done with `C-M-c' (`exit-recursive-edit').
364 You can also "abort" a recursive edit. This is like exiting, but
365 also quits the unfinished command immediately. Use the command `C-]'
366 (`abort-recursive-edit') for this. *Note Quitting::.
368 The mode line shows you when you are in a recursive edit by
369 displaying square brackets around the parentheses that always surround
370 the major and minor mode names. Every window's mode line shows the
371 square brackets, since XEmacs as a whole, rather than any particular
372 buffer, is in a recursive edit.
374 It is possible to be in recursive edits within recursive edits. For
375 example, after typing `C-r' in a `query-replace', you might type a
376 command that entered the debugger. In such a case, two or more sets of
377 square brackets appear in the mode line(s). Exiting the inner
378 recursive edit (here with the debugger `c' command) resumes the
379 query-replace command where it called the debugger. After the end of
380 the query-replace command, you would be able to exit the first
381 recursive edit. Aborting exits only one level of recursive edit; it
382 returns to the command level of the previous recursive edit. You can
383 then abort that one as well.
385 The command `M-x top-level' aborts all levels of recursive edits,
386 returning immediately to the top level command reader.
388 The text you edit inside the recursive edit need not be the same text
389 that you were editing at top level. If the command that invokes the
390 recursive edit selects a different buffer first, that is the buffer you
391 will edit recursively. You can switch buffers within the recursive edit
392 in the normal manner (as long as the buffer-switching keys have not been
393 rebound). While you could theoretically do the rest of your editing
394 inside the recursive edit, including visiting files, this could have
395 surprising effects (such as stack overflow) from time to time. It is
396 best if you always exit or abort a recursive edit when you no longer
399 In general, XEmacs tries to avoid using recursive edits. It is
400 usually preferable to allow users to switch among the possible editing
401 modes in any order they like. With recursive edits, the only way to get
402 to another state is to go "back" to the state that the recursive edit
406 File: xemacs.info, Node: Dissociated Press, Next: CONX, Prev: Recursive Edit, Up: Top
411 `M-x dissociated-press' is a command for scrambling a file of text
412 either word by word or character by character. Starting from a buffer
413 of straight English, it produces extremely amusing output. The input
414 comes from the current XEmacs buffer. Dissociated Press writes its
415 output in a buffer named `*Dissociation*', and redisplays that buffer
416 after every couple of lines (approximately) to facilitate reading it.
418 `dissociated-press' asks every so often whether to continue
419 operating. Answer `n' to stop it. You can also stop at any time by
420 typing `C-g'. The dissociation output remains in the `*Dissociation*'
421 buffer for you to copy elsewhere if you wish.
423 Dissociated Press operates by jumping at random from one point in the
424 buffer to another. In order to produce plausible output rather than
425 gibberish, it insists on a certain amount of overlap between the end of
426 one run of consecutive words or characters and the start of the next.
427 That is, if it has just printed out `president' and then decides to
428 jump to a different point in the file, it might spot the `ent' in
429 `pentagon' and continue from there, producing `presidentagon'. Long
430 sample texts produce the best results.
432 A positive argument to `M-x dissociated-press' tells it to operate
433 character by character, and specifies the number of overlap characters.
434 A negative argument tells it to operate word by word and specifies the
435 number of overlap words. In this mode, whole words are treated as the
436 elements to be permuted, rather than characters. No argument is
437 equivalent to an argument of two. For your againformation, the output
438 goes only into the buffer `*Dissociation*'. The buffer you start with
441 Dissociated Press produces nearly the same results as a Markov chain
442 based on a frequency table constructed from the sample text. It is,
443 however, an independent, ignoriginal invention. Dissociated Press
444 techniquitously copies several consecutive characters from the sample
445 between random choices, whereas a Markov chain would choose randomly for
446 each word or character. This makes for more plausible sounding results
449 It is a mustatement that too much use of Dissociated Press can be a
450 developediment to your real work. Sometimes to the point of outragedy.
451 And keep dissociwords out of your documentation, if you want it to be
452 well userenced and properbose. Have fun. Your buggestions are welcome.
455 File: xemacs.info, Node: CONX, Next: Amusements, Prev: Dissociated Press, Up: Top
460 Besides producing a file of scrambled text with Dissociated Press,
461 you can generate random sentences by using CONX.
464 Generate random sentences in the `*conx*' buffer.
467 Absorb the text in the current buffer into the `conx' database.
470 Forget the current word-frequency tree.
473 Load a `conx' database that has been previously saved with `M-x
477 Absorb the text in the current buffer into the `conx' database.
480 Save the current `conx' database to a file for future retrieval.
482 Copy text from a buffer using `M-x conx-buffer' or `M-x conx-region'
483 and then type `M-x conx'. Output is continuously generated until you
484 type <^G>. You can save the `conx' database to a file with `M-x
485 conx-save', which you can retrieve with `M-x conx-load'. To clear the
486 database, use `M-x conx-init'.
489 File: xemacs.info, Node: Amusements, Next: Emulation, Prev: CONX, Up: Top
494 If you are a little bit bored, you can try `M-x hanoi'. If you are
495 considerably bored, give it a numeric argument. If you are very, very
496 bored, try an argument of 9. Sit back and watch.
498 When you are frustrated, try the famous Eliza program. Just do `M-x
499 doctor'. End each input by typing `RET' twice.
501 When you are feeling strange, type `M-x yow'.
504 File: xemacs.info, Node: Emulation, Next: Customization, Prev: Amusements, Up: Top
509 XEmacs can be programmed to emulate (more or less) most other
510 editors. Standard facilities can emulate these:
512 Viper (a vi emulator)
513 In XEmacs, Viper is the preferred emulation of vi within XEmacs.
514 Viper is designed to allow you to take advantage of the best
515 features of XEmacs while still doing your basic editing in a
516 familiar, vi-like fashion. Viper provides various different
517 levels of vi emulation, from a quite complete emulation that
518 allows almost no access to native XEmacs commands, to an "expert"
519 mode that combines the most useful vi commands with the most
520 useful XEmacs commands.
522 To start Viper, put the command
526 in your init file. *Note Init File::.
528 Viper comes with a separate manual that is provided standard with
529 the XEmacs distribution.
532 Turn on EDT emulation with `M-x edt-emulation-on'. `M-x
533 edt-emulation-off' restores normal Emacs command bindings.
535 Most of the EDT emulation commands are keypad keys, and most
536 standard Emacs key bindings are still available. The EDT
537 emulation rebindings are done in the global keymap, so there is no
538 problem switching buffers or major modes while in EDT emulation.
541 Turn on emulation of Gosling Emacs (aka Unipress Emacs) with `M-x
542 set-gosmacs-bindings'. This redefines many keys, mostly on the
543 `C-x' and `ESC' prefixes, to work as they do in Gosmacs. `M-x
544 set-gnu-bindings' returns to normal XEmacs by rebinding the same
545 keys to the definitions they had at the time `M-x
546 set-gosmacs-bindings' was done.
548 It is also possible to run Mocklisp code written for Gosling Emacs.
552 File: xemacs.info, Node: Customization, Next: Quitting, Prev: Emulation, Up: Top
557 This chapter talks about various topics relevant to adapting the
558 behavior of Emacs in minor ways.
560 All kinds of customization affect only the particular Emacs job that
561 you do them in. They are completely lost when you kill the Emacs job,
562 and have no effect on other Emacs jobs you may run at the same time or
563 later. The only way an Emacs job can affect anything outside of it is
564 by writing a file; in particular, the only way to make a customization
565 `permanent' is to put something in your init file or other appropriate
566 file to do the customization in each session. *Note Init File::.
570 * Minor Modes:: Each minor mode is one feature you can turn on
571 independently of any others.
572 * Variables:: Many Emacs commands examine Emacs variables
573 to decide what to do; by setting variables,
574 you can control their functioning.
575 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
576 to be replayed with a single command.
577 * Key Bindings:: The keymaps say what command each key runs.
578 By changing them, you can "redefine keys".
579 * Syntax:: The syntax table controls how words and expressions
581 * Init File:: How to write common customizations in the init file.
582 * Audible Bell:: Changing how Emacs sounds the bell.
583 * Faces:: Changing the fonts and colors of a region of text.
584 * Frame Components:: Controlling the presence and positions of the
585 menubar, toolbars, and gutters.
586 * X Resources:: X resources controlling various aspects of the
590 File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization
595 Minor modes are options which you can use or not. For example, Auto
596 Fill mode is a minor mode in which <SPC> breaks lines between words as
597 you type. All the minor modes are independent of each other and of the
598 selected major mode. Most minor modes inform you in the mode line when
599 they are on; for example, `Fill' in the mode line means that Auto Fill
602 Append `-mode' to the name of a minor mode to get the name of a
603 command function that turns the mode on or off. Thus, the command to
604 enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These
605 commands are usually invoked with `M-x', but you can bind keys to them
606 if you wish. With no argument, the function turns the mode on if it was
607 off and off if it was on. This is known as "toggling". A positive
608 argument always turns the mode on, and an explicit zero argument or a
609 negative argument always turns it off.
611 Auto Fill mode allows you to enter filled text without breaking lines
612 explicitly. Emacs inserts newlines as necessary to prevent lines from
613 becoming too long. *Note Filling::.
615 Overwrite mode causes ordinary printing characters to replace
616 existing text instead of moving it to the right. For example, if point
617 is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite
618 mode, it changes to `FOOGAR', instead of `FOOGBAR'.
620 Abbrev mode allows you to define abbreviations that automatically
621 expand as you type them. For example, `amd' might expand to `abbrev
622 mode'. *Note Abbrevs::, for full information.
625 File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization
630 A "variable" is a Lisp symbol which has a value. Variable names can
631 contain any characters, but by convention they are words separated by
632 hyphens. A variable can also have a documentation string, which
633 describes what kind of value it should have and how the value will be
636 Lisp allows any variable to have any kind of value, but most
637 variables that Emacs uses require a value of a certain type. Often the
638 value has to be a string or a number. Sometimes we say that a certain
639 feature is turned on if a variable is "non-`nil'," meaning that if the
640 variable's value is `nil', the feature is off, but the feature is on
641 for any other value. The conventional value to turn on the
642 feature--since you have to pick one particular value when you set the
645 Emacs uses many Lisp variables for internal recordkeeping, as any
646 Lisp program must, but the most interesting variables for you are the
647 ones that exist for the sake of customization. Emacs does not
648 (usually) change the values of these variables; instead, you set the
649 values, and thereby alter and control the behavior of certain Emacs
650 commands. These variables are called "options". Most options are
651 documented in this manual and appear in the Variable Index (*note
654 One example of a variable which is an option is `fill-column', which
655 specifies the position of the right margin (as a number of characters
656 from the left margin) to be used by the fill commands (*note Filling::).
660 * Examining:: Examining or setting one variable's value.
661 * Easy Customization:: Convenient and easy customization of variables.
662 * Edit Options:: Examining or editing list of all variables' values.
663 * Locals:: Per-buffer values of variables.
664 * File Variables:: How files can specify variable values.
667 File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables
669 Examining and Setting Variables
670 -------------------------------
673 `M-x describe-variable'
674 Print the value and documentation of a variable.
677 Change the value of a variable.
679 To examine the value of a single variable, use `C-h v'
680 (`describe-variable'), which reads a variable name using the
681 minibuffer, with completion. It prints both the value and the
682 documentation of the variable.
684 C-h v fill-column <RET>
686 prints something like:
688 fill-column's value is 75
691 *Column beyond which automatic line-wrapping should happen.
692 Automatically becomes local when set in any fashion.
694 The star at the beginning of the documentation indicates that this
695 variable is an option. `C-h v' is not restricted to options; it allows
698 If you know which option you want to set, you can use `M-x
699 set-variable' to set it. This prompts for the variable name in the
700 minibuffer (with completion), and then prompts for a Lisp expression
701 for the new value using the minibuffer a second time. For example,
703 M-x set-variable <RET> fill-column <RET> 75 <RET>
705 sets `fill-column' to 75, as if you had executed the Lisp expression
706 `(setq fill-column 75)'.
708 Setting variables in this way, like all means of customizing Emacs
709 except where explicitly stated, affects only the current Emacs session.
712 File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables
714 Easy Customization Interface
715 ----------------------------
717 A convenient way to find the user option variables that you want to
718 change, and then change them, is with `M-x customize'. This command
719 creates a "customization buffer" with which you can browse through the
720 Emacs user options in a logically organized structure, then edit and
721 set their values. You can also use the customization buffer to save
722 settings permanently. (Not all Emacs user options are included in this
723 structure as of yet, but we are adding the rest.)
727 * Groups: Customization Groups.
728 How options are classified in a structure.
729 * Changing an Option:: How to edit a value and set an option.
730 * Face Customization:: How to edit the attributes of a face.
731 * Specific Customization:: Making a customization buffer for specific
732 options, faces, or groups.
735 File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization
740 For customization purposes, user options are organized into "groups"
741 to help you find them. Groups are collected into bigger groups, all
742 the way up to a master group called `Emacs'.
744 `M-x customize' creates a customization buffer that shows the
745 top-level `Emacs' group and the second-level groups immediately under
746 it. It looks like this, in part:
748 /- Emacs group: ---------------------------------------------------\
749 [State]: visible group members are all at standard settings.
750 Customization of the One True Editor.
754 Basic text editing facilities.
756 [Open] External group
757 Interfacing to external utilities.
759 MORE SECOND-LEVEL GROUPS
761 \- Emacs group end ------------------------------------------------/
763 This says that the buffer displays the contents of the `Emacs' group.
764 The other groups are listed because they are its contents. But they
765 are listed differently, without indentation and dashes, because _their_
766 contents are not included. Each group has a single-line documentation
767 string; the `Emacs' group also has a `[State]' line.
769 Most of the text in the customization buffer is read-only, but it
770 typically includes some "editable fields" that you can edit. There are
771 also "active fields"; this means a field that does something when you
772 "invoke" it. To invoke an active field, either click on it with
773 `Mouse-1', or move point to it and type <RET>.
775 For example, the phrase `[Open]' that appears in a second-level
776 group is an active field. Invoking the `[Open]' field for a group
777 opens up a new customization buffer, which shows that group and its
778 contents. This field is a kind of hypertext link to another group.
780 The `Emacs' group does not include any user options itself, but
781 other groups do. By examining various groups, you will eventually find
782 the options and faces that belong to the feature you are interested in
783 customizing. Then you can use the customization buffer to set them.
785 You can view the structure of customization groups on a larger scale
786 with `M-x customize-browse'. This command creates a special kind of
787 customization buffer which shows only the names of the groups (and
788 options and faces), and their structure.
790 In this buffer, you can show the contents of a group by invoking
791 `[+]'. When the group contents are visible, this button changes to
792 `[-]'; invoking that hides the group contents.
794 Each group, option or face name in this buffer has an active field
795 which says `[Group]', `[Option]' or `[Face]'. Invoking that active
796 field creates an ordinary customization buffer showing just that group
797 and its contents, just that option, or just that face. This is the way
801 File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization
806 Here is an example of what a user option looks like in the
807 customization buffer:
809 Kill Ring Max: [Hide] 30
810 [State]: this option is unchanged from its standard setting.
811 Maximum length of kill ring before oldest elements are thrown away.
813 The text following `[Hide]', `30' in this case, indicates the
814 current value of the option. If you see `[Show]' instead of `[Hide]',
815 it means that the value is hidden; the customization buffer initially
816 hides values that take up several lines. Invoke `[Show]' to show the
819 The line after the option name indicates the "customization state"
820 of the option: in the example above, it says you have not changed the
821 option yet. The word `[State]' at the beginning of this line is
822 active; you can get a menu of various operations by invoking it with
823 `Mouse-1' or <RET>. These operations are essential for customizing the
826 The line after the `[State]' line displays the beginning of the
827 option's documentation string. If there are more lines of
828 documentation, this line ends with `[More]'; invoke this to show the
829 full documentation string.
831 To enter a new value for `Kill Ring Max', move point to the value
832 and edit it textually. For example, you can type `M-d', then insert
835 When you begin to alter the text, you will see the `[State]' line
836 change to say that you have edited the value:
838 [State]: you have edited the value as text, but not set the option.
840 Editing the value does not actually set the option variable. To do
841 that, you must "set" the option. To do this, invoke the word `[State]'
842 and choose `Set for Current Session'.
844 The state of the option changes visibly when you set it:
846 [State]: you have set this option, but not saved it for future sessions.
848 You don't have to worry about specifying a value that is not valid;
849 setting the option checks for validity and will not really install an
852 While editing a value or field that is a file name, directory name,
853 command name, or anything else for which completion is defined, you can
854 type `M-<TAB>' (`widget-complete') to do completion.
856 Some options have a small fixed set of possible legitimate values.
857 These options don't let you edit the value textually. Instead, an
858 active field `[Value Menu]' appears before the value; invoke this field
859 to edit the value. For a boolean "on or off" value, the active field
860 says `[Toggle]', and it changes to the other value. `[Value Menu]' and
861 `[Toggle]' edit the buffer; the changes take effect when you use the
862 `Set for Current Session' operation.
864 Some options have values with complex structure. For example, the
865 value of `load-path' is a list of directories. Here is how it appears
866 in the customization buffer:
869 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
870 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
871 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
872 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
873 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
874 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
876 [State]: this item has been changed outside the customization buffer.
877 List of directories to search for files to load....
879 Each directory in the list appears on a separate line, and each line has
880 several editable or active fields.
882 You can edit any of the directory names. To delete a directory from
883 the list, invoke `[DEL]' on that line. To insert a new directory in
884 the list, invoke `[INS]' at the point where you want to insert it.
886 You can also invoke `[Current dir?]' to switch between including a
887 specific named directory in the path, and including `nil' in the path.
888 (`nil' in a search path means "try the current directory.")
890 Two special commands, <TAB> and `S-<TAB>', are useful for moving
891 through the customization buffer. <TAB> (`widget-forward') moves
892 forward to the next active or editable field; `S-<TAB>'
893 (`widget-backward') moves backward to the previous active or editable
896 Typing <RET> on an editable field also moves forward, just like
897 <TAB>. The reason for this is that people have a tendency to type
898 <RET> when they are finished editing a field. If you have occasion to
899 insert a newline in an editable field, use `C-o' or `C-q C-j',
901 Setting the option changes its value in the current Emacs session;
902 "saving" the value changes it for future sessions as well. This works
903 by writing code into your init file so as to set the option variable
904 again each time you start Emacs. *Note Init File::. To save the
905 option, invoke `[State]' and select the `Save for Future Sessions'
908 You can also restore the option to its standard value by invoking
909 `[State]' and selecting the `Reset' operation. There are actually
910 three reset operations:
913 If you have made some modifications and not yet set the option,
914 this restores the text in the customization buffer to match the
918 This restores the value of the option to the last saved value, and
919 updates the text accordingly.
921 `Reset to Standard Settings'
922 This sets the option to its standard value, and updates the text
923 accordingly. This also eliminates any saved value for the option,
924 so that you will get the standard value in future Emacs sessions.
926 The state of a group indicates whether anything in that group has
927 been edited, set or saved. You can select `Set for Current Session',
928 `Save for Future Sessions' and the various kinds of `Reset' operation
929 for the group; these operations on the group apply to all options in
930 the group and its subgroups.
932 Near the top of the customization buffer there are two lines
933 containing several active fields:
935 [Set] [Save] [Reset] [Done]
937 Invoking `[Done]' buries this customization buffer. Each of the other
938 fields performs an operation--set, save or reset--on each of the items
939 in the buffer that could meaningfully be set, saved or reset.
942 File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization
947 In addition to user options, some customization groups also include
948 faces. When you show the contents of a group, both the user options and
949 the faces in the group appear in the customization buffer. Here is an
950 example of how a face looks:
952 Custom Changed Face: (sample)
953 [State]: this face is unchanged from its standard setting.
954 Face used when the customize item has been changed.
955 Parent groups: [Custom Magic Faces]
956 Attributes: [ ] Bold: [Toggle] off (nil)
957 [ ] Italic: [Toggle] off (nil)
958 [ ] Underline: [Toggle] off (nil)
959 [ ] Foreground: white (sample)
960 [ ] Background: blue (sample)
961 [ ] Inverse: [Toggle] off (nil)
967 Each face attribute has its own line. The `[X]' field before the
968 attribute name indicates whether the attribute is "enabled"; `X' means
969 that it is. You can enable or disable the attribute by invoking that
970 field. When the attribute is enabled, you can change the attribute
971 value in the usual ways.
973 Setting, saving and resetting a face work like the same operations
974 for options (*note Changing an Option::).
976 A face can specify different appearances for different types of
977 display. For example, a face can make text red on a color display, but
978 use a bold font on a monochrome display. To specify multiple
979 appearances for a face, select `Show Display Types' in the menu you get
980 from invoking `[State]'.
983 File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization
985 Customizing Specific Items
986 ..........................
988 Instead of finding the options you want to change by moving down
989 through the structure of groups, you can specify the particular option,
990 face or group that you want to customize.
992 `M-x customize-option <RET> OPTION <RET>'
993 Set up a customization buffer with just one option, OPTION.
995 `M-x customize-face <RET> FACE <RET>'
996 Set up a customization buffer with just one face, FACE.
998 `M-x customize-group <RET> GROUP <RET>'
999 Set up a customization buffer with just one group, GROUP.
1001 `M-x customize-apropos <RET> REGEXP <RET>'
1002 Set up a customization buffer with all the options, faces and
1003 groups that match REGEXP.
1005 `M-x customize-saved'
1006 Set up a customization buffer containing all options and faces
1007 that you have saved with customization buffers.
1009 `M-x customize-customized'
1010 Set up a customization buffer containing all options and faces
1011 that you have customized but not saved.
1013 If you want to alter a particular user option variable with the
1014 customization buffer, and you know its name, you can use the command
1015 `M-x customize-option' and specify the option name. This sets up the
1016 customization buffer with just one option--the one that you asked for.
1017 Editing, setting and saving the value work as described above, but only
1018 for the specified option.
1020 Likewise, you can modify a specific face, chosen by name, using `M-x
1023 You can also set up the customization buffer with a specific group,
1024 using `M-x customize-group'. The immediate contents of the chosen
1025 group, including option variables, faces, and other groups, all appear
1026 as well. However, these subgroups' own contents start out hidden. You
1027 can show their contents in the usual way, by invoking `[Show]'.
1029 To control more precisely what to customize, you can use `M-x
1030 customize-apropos'. You specify a regular expression as argument; then
1031 all options, faces and groups whose names match this regular expression
1032 are set up in the customization buffer. If you specify an empty regular
1033 expression, this includes _all_ groups, options and faces in the
1034 customization buffer (but that takes a long time).
1036 If you change option values and then decide the change was a mistake,
1037 you can use two special commands to revisit your previous changes. Use
1038 `customize-saved' to look at the options and faces that you have saved.
1039 Use `M-x customize-customized' to look at the options and faces that
1040 you have set but not saved.
1043 File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables
1045 Editing Variable Values
1046 -----------------------
1049 Display a buffer listing names, values, and documentation of all
1053 Change option values by editing a list of options.
1055 `M-x list-options' displays a list of all Emacs option variables in
1056 an Emacs buffer named `*List Options*'. Each option is shown with its
1057 documentation and its current value. Here is what a portion of it might
1061 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
1062 *List of directories to search programs to run in subprocesses.
1063 Each element is a string (directory name)
1064 or nil (try the default directory).
1068 *Column beyond which automatic line-wrapping should happen.
1069 Automatically becomes local when set in any fashion.
1072 `M-x edit-options' goes one step further and immediately selects the
1073 `*List Options*' buffer; this buffer uses the major mode Options mode,
1074 which provides commands that allow you to point at an option and change
1078 Set the variable point is in or near to a new value read using the
1082 Toggle the variable point is in or near: if the value was `nil',
1083 it becomes `t'; otherwise it becomes `nil'.
1086 Set the variable point is in or near to `t'.
1089 Set the variable point is in or near to `nil'.
1093 Move to the next or previous variable.
1096 File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables
1101 `M-x make-local-variable'
1102 Make a variable have a local value in the current buffer.
1104 `M-x kill-local-variable'
1105 Make a variable use its global value in the current buffer.
1107 `M-x make-variable-buffer-local'
1108 Mark a variable so that setting it will make it local to the
1109 buffer that is current at that time.
1111 You can make any variable "local" to a specific Emacs buffer. This
1112 means that the variable's value in that buffer is independent of its
1113 value in other buffers. A few variables are always local in every
1114 buffer. All other Emacs variables have a "global" value which is in
1115 effect in all buffers that have not made the variable local.
1117 Major modes always make the variables they set local to the buffer.
1118 This is why changing major modes in one buffer has no effect on other
1121 `M-x make-local-variable' reads the name of a variable and makes it
1122 local to the current buffer. Further changes in this buffer will not
1123 affect others, and changes in the global value will not affect this
1126 `M-x make-variable-buffer-local' reads the name of a variable and
1127 changes the future behavior of the variable so that it automatically
1128 becomes local when it is set. More precisely, once you have marked a
1129 variable in this way, the usual ways of setting the variable will
1130 automatically invoke `make-local-variable' first. We call such
1131 variables "per-buffer" variables.
1133 Some important variables have been marked per-buffer already. They
1134 include `abbrev-mode', `auto-fill-function', `case-fold-search',
1135 `comment-column', `ctl-arrow', `fill-column', `fill-prefix',
1136 `indent-tabs-mode', `left-margin',
1137 `mode-line-format', `overwrite-mode', `selective-display-ellipses',
1138 `selective-display', `tab-width', and `truncate-lines'. Some other
1139 variables are always local in every buffer, but they are used for
1142 Note: the variable `auto-fill-function' was formerly named
1145 If you want a variable to cease to be local to the current buffer,
1146 call `M-x kill-local-variable' and provide the name of a variable to
1147 the prompt. The global value of the variable is again in effect in
1148 this buffer. Setting the major mode kills all the local variables of
1151 To set the global value of a variable, regardless of whether the
1152 variable has a local value in the current buffer, you can use the Lisp
1153 function `setq-default'. It works like `setq'. If there is a local
1154 value in the current buffer, the local value is not affected by
1155 `setq-default'; thus, the new global value may not be visible until you
1156 switch to another buffer, as in the case of:
1158 (setq-default fill-column 75)
1160 `setq-default' is the only way to set the global value of a variable
1161 that has been marked with `make-variable-buffer-local'.
1163 Programs can look at a variable's default value with `default-value'.
1164 This function takes a symbol as an argument and returns its default
1165 value. The argument is evaluated; usually you must quote it
1166 explicitly, as in the case of:
1168 (default-value 'fill-column)