1 This is ../info/xemacs.info, produced by makeinfo version 4.0b 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: Position Info, Next: Arguments, Prev: Continuation Lines, Up: Basic
35 Cursor Position Information
36 ===========================
38 If you are accustomed to other display editors, you may be surprised
39 that Emacs does not always display the page number or line number of
40 point in the mode line. In Emacs, this information is only rarely
41 needed, and a number of commands are available to compute and print it.
42 Since text is stored in a way that makes it difficult to compute the
43 information, it is not displayed all the time.
46 Print page number of point, and line number within page.
49 Print line number of point in the buffer.
51 `M-x line-number-mode'
52 Toggle automatic display of current line number.
55 Print number of lines and characters in the current region
56 (`count-lines-region'). *Note Mark::, for information about the
60 Print character code of character after point, character position
61 of point, and column of point (`what-cursor-position').
63 There are several commands for printing line numbers:
65 * `M-x what-line' counts lines from the beginning of the file and
66 prints the line number point is on. The first line of the file is
67 line number 1. You can use these numbers as arguments to `M-x
70 * `M-x what-page' counts pages from the beginning of the file, and
71 counts lines within the page, printing both of them. *Note
72 Pages::, for the command `C-x l', which counts the lines in the
75 * `M-=' (`count-lines-region') prints the number of lines in the
76 region (*note Mark::). *Note Pages::, for the command `C-x l'
77 which counts the lines in the
79 The command `C-x =' (`what-cursor-position') can be used to find out
80 the column that the cursor is in, and other miscellaneous information
81 about point. It prints a line in the echo area that looks like this:
83 Char: c (0143, 99, 0x63) point=18862 of 24800(76%) column 53
85 (In fact, this is the output produced when point is before `column 53'
88 The four values after `Char:' describe the character that follows
89 point, first by showing it and then by giving its character code in
90 octal, decimal and hex.
92 `point=' is followed by the position of point expressed as a
93 character count. The front of the buffer counts as position 1, one
94 character later as 2, and so on. The next, larger number is the total
95 number of characters in the buffer. Afterward in parentheses comes the
96 position expressed as a percentage of the total size.
98 `column' is followed by the horizontal position of point, in columns
99 from the left edge of the window.
101 If the buffer has been narrowed, making some of the text at the
102 beginning and the end temporarily invisible, `C-x =' prints additional
103 text describing the current visible range. For example, it might say:
105 Char: c (0143, 99, 0x63) point=19674 of 24575(80%) <19591 - 19703> column 69
107 where the two extra numbers give the smallest and largest character
108 position that point is allowed to assume. The characters between those
109 two positions are the visible ones. *Note Narrowing::.
111 If point is at the end of the buffer (or the end of the visible
112 part), `C-x =' omits any description of the character after point. The
115 point=563026 of 563025(100%) column 0
118 File: xemacs.info, Node: Arguments, Prev: Position Info, Up: Basic
123 In mathematics and computer usage, the word "argument" means "data
124 provided to a function or operation." Any Emacs command can be given a
125 "numeric argument" (also called a "prefix argument"). Some commands
126 interpret the argument as a repetition count. For example, giving an
127 argument of ten to the key `C-f' (the command `forward-char', move
128 forward one character) moves forward ten characters. With these
129 commands, no argument is equivalent to an argument of one. Negative
130 arguments are allowed. Often they tell a command to move or act in
131 the opposite direction.
133 If your keyboard has a <META> key (labelled with a diamond on
134 Sun-type keyboards and labelled `Alt' on some other keyboards), the
135 easiest way to specify a numeric argument is to type digits and/or a
136 minus sign while holding down the <META> key. For example,
139 would move down five lines. The characters `Meta-1', `Meta-2', and so
140 on, as well as `Meta--', do this because they are keys bound to
141 commands (`digit-argument' and `negative-argument') that are defined to
142 contribute to an argument for the next command. Digits and `-'
143 modified with Control, or Control and Meta, also specify numeric
146 Another way of specifying an argument is to use the `C-u'
147 (`universal-argument') command followed by the digits of the argument.
148 With `C-u', you can type the argument digits without holding down
149 modifier keys; `C-u' works on all terminals. To type a negative
150 argument, type a minus sign after `C-u'. Just a minus sign without
151 digits normally means -1.
153 `C-u' followed by a character which is neither a digit nor a minus
154 sign has the special meaning of "multiply by four". It multiplies the
155 argument for the next command by four. `C-u' twice multiplies it by
156 sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This
157 is a good way to move forward "fast", since it moves about 1/5 of a line
158 in the usual size frame. Other useful combinations are `C-u C-n', `C-u
159 C-u C-n' (move down a good fraction of a frame), `C-u C-u C-o' (make "a
160 lot" of blank lines), and `C-u C-k' (kill four lines).
162 Some commands care only about whether there is an argument and not
163 about its value. For example, the command `M-q' (`fill-paragraph') with
164 no argument fills text; with an argument, it justifies the text as well.
165 (*Note Filling::, for more information on `M-q'.) Just `C-u' is a
166 handy way of providing an argument for such commands.
168 Some commands use the value of the argument as a repeat count, but do
169 something peculiar when there is no argument. For example, the command
170 `C-k' (`kill-line') with argument N kills N lines, including their
171 terminating newlines. But `C-k' with no argument is special: it kills
172 the text up to the next newline, or, if point is right at the end of
173 the line, it kills the newline itself. Thus, two `C-k' commands with
174 no arguments can kill a non-blank line, just like `C-k' with an
175 argument of one. (*Note Killing::, for more information on `C-k'.)
177 A few commands treat a plain `C-u' differently from an ordinary
178 argument. A few others may treat an argument of just a minus sign
179 differently from an argument of -1. These unusual cases are described
180 when they come up; they are always for reasons of convenience of use of
181 the individual command.
183 You can use a numeric argument to insert multiple copies of a
184 character. This is straightforward unless the character is a digit; for
185 example, `C-u 6 4 a' inserts 64 copies of the character `a'. But this
186 does not work for inserting digits; `C-u 6 4 1' specifies an argument
187 of 641, rather than inserting anything. To separate the digit to
188 insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
189 1' does insert 64 copies of the character `1'.
191 We use the term "prefix argument" as well as "numeric argument" to
192 emphasize that you type the argument before the command, and to
193 distinguish these arguments from minibuffer arguments that come after
197 File: xemacs.info, Node: Undo, Next: Minibuffer, Prev: Basic, Up: Top
202 Emacs allows you to undo all changes you make to the text of a
203 buffer, up to a certain amount of change (8000 characters). Each
204 buffer records changes individually, and the undo command always
205 applies to the current buffer. Usually each editing command makes a
206 separate entry in the undo records, but some commands such as
207 `query-replace' make many entries, and very simple commands such as
208 self-inserting characters are often grouped to make undoing less
212 Undo one batch of changes (usually, one command's worth) (`undo').
217 The command `C-x u' or `C-_' allows you to undo changes. The first
218 time you give this command, it undoes the last change. Point moves to
219 the text affected by the undo, so you can see what was undone.
221 Consecutive repetitions of the `C-_' or `C-x u' commands undo
222 earlier and earlier changes, back to the limit of what has been
223 recorded. If all recorded changes have already been undone, the undo
224 command prints an error message and does nothing.
226 Any command other than an undo command breaks the sequence of undo
227 commands. Starting at this moment, the previous undo commands are
228 considered ordinary changes that can themselves be undone. Thus, you
229 can redo changes you have undone by typing `C-f' or any other command
230 that have no important effect, and then using more undo commands.
232 If you notice that a buffer has been modified accidentally, the
233 easiest way to recover is to type `C-_' repeatedly until the stars
234 disappear from the front of the mode line. When that happens, all the
235 modifications you made have been canceled. If you do not remember
236 whether you changed the buffer deliberately, type `C-_' once. When you
237 see Emacs undo the last change you made, you probably remember why you
238 made it. If the change was an accident, leave it undone. If it was
239 deliberate, redo the change as described in the preceding paragraph.
241 Whenever an undo command makes the stars disappear from the mode
242 line, the buffer contents is the same as it was when the file was last
245 Not all buffers record undo information. Buffers whose names start
246 with spaces don't; these buffers are used internally by Emacs and its
247 extensions to hold text that users don't normally look at or edit.
248 Minibuffers, help buffers, and documentation buffers also don't record
251 Emacs can remember at most 8000 or so characters of deleted or
252 modified text in any one buffer for reinsertion by the undo command.
253 There is also a limit on the number of individual insert, delete, or
254 change actions that Emacs can remember.
256 There are two keys to run the `undo' command, `C-x u' and `C-_',
257 because on some keyboards, it is not obvious how to type `C-_'. `C-x u'
258 is an alternative you can type in the same fashion on any terminal.
261 File: xemacs.info, Node: Minibuffer, Next: M-x, Prev: Undo, Up: Top
266 The "minibuffer" is the facility used by XEmacs commands to read
267 arguments more complicated than a single number. Minibuffer arguments
268 can be file names, buffer names, Lisp function names, XEmacs command
269 names, Lisp expressions, and many other things, depending on the command
270 reading the argument. You can use the usual XEmacs editing commands in
271 the minibuffer to edit the argument text.
273 When the minibuffer is in use, it appears in the echo area, and the
274 cursor moves there. The beginning of the minibuffer line displays a
275 "prompt" which says what kind of input you should supply and how it
276 will be used. Often this prompt is derived from the name of the command
277 that the argument is for. The prompt normally ends with a colon.
279 Sometimes a "default argument" appears in parentheses after the
280 colon; it, too, is part of the prompt. The default is used as the
281 argument value if you enter an empty argument (e.g., by just typing
282 <RET>). For example, commands that read buffer names always show a
283 default, which is the name of the buffer that will be used if you type
286 The simplest way to enter a minibuffer argument is to type the text
287 you want, terminated by <RET> which exits the minibuffer. You can
288 cancel the command that wants the argument, and get out of the
289 minibuffer, by typing `C-g'.
291 Since the minibuffer uses the screen space of the echo area, it can
292 conflict with other ways XEmacs customarily uses the echo area. Here is
293 how XEmacs handles such conflicts:
295 * If a command gets an error while you are in the minibuffer, this
296 does not cancel the minibuffer. However, the echo area is needed
297 for the error message and therefore the minibuffer itself is
298 hidden for a while. It comes back after a few seconds, or as soon
299 as you type anything.
301 * If in the minibuffer you use a command whose purpose is to print a
302 message in the echo area, such as `C-x =', the message is printed
303 normally, and the minibuffer is hidden for a while. It comes back
304 after a few seconds, or as soon as you type anything.
306 * Echoing of keystrokes does not take place while the minibuffer is
311 * File: Minibuffer File. Entering file names with the minibuffer.
312 * Edit: Minibuffer Edit. How to edit in the minibuffer.
313 * Completion:: An abbreviation facility for minibuffer input.
314 * Minibuffer History:: Reusing recent minibuffer arguments.
315 * Repetition:: Re-executing commands that used the minibuffer.
318 File: xemacs.info, Node: Minibuffer File, Next: Minibuffer Edit, Prev: Minibuffer, Up: Minibuffer
320 Minibuffers for File Names
321 ==========================
323 Sometimes the minibuffer starts out with text in it. For example,
324 when you are supposed to give a file name, the minibuffer starts out
325 containing the "default directory", which ends with a slash. This is
326 to inform you which directory the file will be found in if you do not
329 For example, the minibuffer might start out with these contents:
331 Find File: /u2/emacs/src/
333 where `Find File: ' is the prompt. Typing `buffer.c' specifies the
334 file `/u2/emacs/src/buffer.c'. To find files in nearby directories,
335 use `..'; thus, if you type `../lisp/simple.el', you will get the file
336 named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with
337 `M-<DEL>' the directory names you don't want (*note Words::).
339 If you don't want any of the default, you can kill it with `C-a
340 C-k'. But you don't need to kill the default; you can simply ignore it.
341 Insert an absolute file name, one starting with a slash or a tilde,
342 after the default directory. For example, to specify the file
343 `/etc/termcap', just insert that name, giving these minibuffer contents:
345 Find File: /u2/emacs/src//etc/termcap
347 XEmacs gives a special meaning to a double slash (which is not normally
348 a useful thing to write): it means, "ignore everything before the
349 second slash in the pair." Thus, `/u2/emacs/src/' is ignored in the
350 example above, and you get the file `/etc/termcap'.
352 If you set `insert-default-directory' to `nil', the default
353 directory is not inserted in the minibuffer. This way, the minibuffer
354 starts out empty. But the name you type, if relative, is still
355 interpreted with respect to the same default directory.
358 File: xemacs.info, Node: Minibuffer Edit, Next: Completion, Prev: Minibuffer File, Up: Minibuffer
360 Editing in the Minibuffer
361 =========================
363 The minibuffer is an XEmacs buffer (albeit a peculiar one), and the
364 usual XEmacs commands are available for editing the text of an argument
367 Since <RET> in the minibuffer is defined to exit the minibuffer, you
368 can't use it to insert a newline in the minibuffer. To do that, type
369 `C-o' or `C-q C-j'. (Recall that a newline is really the character
372 The minibuffer has its own window which always has space on the
373 screen but acts as if it were not there when the minibuffer is not in
374 use. When the minibuffer is in use, its window is just like the
375 others; you can switch to another window with `C-x o', edit text in
376 other windows and perhaps even visit more files, before returning to the
377 minibuffer to submit the argument. You can kill text in another window,
378 return to the minibuffer window, and then yank the text to use it in the
379 argument. *Note Windows::.
381 There are some restrictions on the use of the minibuffer window,
382 however. You cannot switch buffers in it--the minibuffer and its
383 window are permanently attached. Also, you cannot split or kill the
384 minibuffer window. But you can make it taller in the normal fashion with
385 `C-x ^'. If you enable Resize-Minibuffer mode, then the minibuffer
386 window expands vertically as necessary to hold the text that you put in
387 the minibuffer. Use `M-x resize-minibuffer-mode' to enable or disable
388 this minor mode (*note Minor Modes::).
390 If while in the minibuffer you issue a command that displays help
391 text of any sort in another window, you can use the `C-M-v' command
392 while in the minibuffer to scroll the help text. This lasts until you
393 exit the minibuffer. This feature is especially useful if a completing
394 minibuffer gives you a list of possible completions. *Note Other
397 If the variable `minibuffer-confirm-incomplete' is `t', you are
398 asked for confirmation if there is no known completion for the text you
399 typed. For example, if you attempted to visit a non-existent file, the
400 minibuffer might read:
401 Find File: chocolate_bar.c [no completions, confirm]
402 If you press `Return' again, that confirms the filename. Otherwise,
403 you can continue editing it.
405 XEmacs supports recursive use of the minibuffer. However, it is easy
406 to do this by accident (because of autorepeating keyboards, for example)
407 and get confused. Therefore, most XEmacs commands that use the
408 minibuffer refuse to operate if the minibuffer window is selected. If
409 the minibuffer is active but you have switched to a different window,
410 recursive use of the minibuffer is allowed--if you know enough to try
411 to do this, you probably will not get confused.
413 If you set the variable `enable-recursive-minibuffers' to a
414 non-`nil', recursive use of the minibuffer is always allowed.
417 File: xemacs.info, Node: Completion, Next: Minibuffer History, Prev: Minibuffer Edit, Up: Minibuffer
422 For certain kinds of arguments, you can use "completion" to enter
423 the argument value. Completion means that you type part of the
424 argument, then XEmacs visibly fills in the rest, or as much as can be
425 determined from the part you have typed.
427 When completion is available, certain keys--<TAB>, <RET>, and
428 <SPC>--are rebound to complete the text present in the minibuffer into
429 a longer string that it stands for, by matching it against a set of
430 "completion alternatives" provided by the command reading the argument.
431 `?' is defined to display a list of possible completions of what you
434 For example, when `M-x' uses the minibuffer to read the name of a
435 command, it provides a list of all available XEmacs command names to
436 complete against. The completion keys match the text in the minibuffer
437 against all the command names, find any additional name characters
438 implied by the ones already present in the minibuffer, and add those
439 characters to the ones you have given. This is what makes it possible
440 to type `M-x inse <SPC> b <RET>' instead of `M-x insert-buffer <RET>'
443 Case is normally significant in completion because it is significant
444 in most of the names that you can complete (buffer names, file names and
445 command names). Thus, `fo' does not complete to `Foo'. When you are
446 completing a name in which case does not matter, case may be ignored
447 for completion's sake if specified by program.
449 When a completion list is displayed, the completions will highlight
450 as you move the mouse over them. Clicking the middle mouse button on
451 any highlighted completion will "select" it just as if you had typed it
456 * Example: Completion Example.
457 * Commands: Completion Commands.
458 * Strict Completion::
459 * Options: Completion Options.
462 File: xemacs.info, Node: Completion Example, Next: Completion Commands, Prev: Completion, Up: Completion
467 A concrete example may help here. If you type `M-x au <TAB>', the
468 <TAB> looks for alternatives (in this case, command names) that start
469 with `au'. There are several, including `auto-fill-mode' and
470 `auto-save-mode'--but they are all the same as far as `auto', so the
471 `au' in the minibuffer changes to `auto'.
473 If you type <TAB> again immediately, there are multiple
474 possibilities for the very next character--it could be any of `c-'--so
475 no more characters are added; instead, <TAB> displays a list of all
476 possible completions in another window.
478 If you go on to type `-f <TAB>', this <TAB> sees `auto-f'. The only
479 command name starting this way is `auto-fill-mode', so completion fills
480 in the rest of that. You now have `auto-fill-mode' in the minibuffer
481 after typing just `au <TAB> f <TAB>'. Note that <TAB> has this effect
482 because in the minibuffer it is bound to the command
483 `minibuffer-complete' when completion is available.
486 File: xemacs.info, Node: Completion Commands, Next: Strict Completion, Prev: Completion Example, Up: Completion
491 Here is a list of the completion commands defined in the minibuffer
492 when completion is available.
495 Complete the text in the minibuffer as much as possible
496 (`minibuffer-complete').
499 Complete the minibuffer text, but don't go beyond one word
500 (`minibuffer-complete-word').
503 Submit the text in the minibuffer as the argument, possibly
504 completing first as described below
505 (`minibuffer-complete-and-exit').
508 Print a list of all possible completions of the text in the
509 minibuffer (`minibuffer-list-completions').
512 Select the highlighted text under the mouse as a minibuffer
513 response. When the minibuffer is being used to prompt the user
514 for a completion, any valid completions which are visible on the
515 screen will be highlighted when the mouse moves over them.
516 Clicking <button2> will select the highlighted completion and exit
517 the minibuffer. (`minibuf-select-highlighted-completion').
519 <SPC> completes much like <TAB>, but never goes beyond the next
520 hyphen or space. If you have `auto-f' in the minibuffer and type
521 <SPC>, it finds that the completion is `auto-fill-mode', but it stops
522 completing after `fill-'. This gives `auto-fill-'. Another <SPC> at
523 this point completes all the way to `auto-fill-mode'. <SPC> in the
524 minibuffer when completion is available runs the command
525 `minibuffer-complete-word'.
527 Here are some commands you can use to choose a completion from a
528 window that displays a list of completions:
531 Clicking mouse button 2 on a completion in the list of possible
532 completions chooses that completion (`mouse-choose-completion').
533 You normally use this command while point is in the minibuffer;
534 but you must click in the list of completions, not in the
539 Typing <PRIOR> or `M-v', while in the minibuffer, selects the
540 window showing the completion list buffer
541 (`switch-to-completions'). This paves the way for using the
542 commands below. (Selecting that window in the usual ways has the
543 same effect, but this way is more convenient.)
546 Typing <RET> _in the completion list buffer_ chooses the
547 completion that point is in or next to (`choose-completion'). To
548 use this command, you must first switch windows to the window that
549 shows the list of completions.
554 Typing the right-arrow key <RIGHT>, <TAB> or `C-f' _in the
555 completion list buffer_ moves point to the following completion
556 (`next-list-mode-item').
560 Typing the left-arrow key <LEFT> or `C-b' _in the completion list
561 buffer_ moves point toward the beginning of the buffer, to the
562 previous completion (`previous-list-mode-item').
565 File: xemacs.info, Node: Strict Completion, Next: Completion Options, Prev: Completion Commands, Up: Completion
570 There are three different ways that <RET> can work in completing
571 minibuffers, depending on how the argument will be used.
573 * "Strict" completion is used when it is meaningless to give any
574 argument except one of the known alternatives. For example, when
575 `C-x k' reads the name of a buffer to kill, it is meaningless to
576 give anything but the name of an existing buffer. In strict
577 completion, <RET> refuses to exit if the text in the minibuffer
578 does not complete to an exact match.
580 * "Cautious" completion is similar to strict completion, except that
581 <RET> exits only if the text was an exact match already, not
582 needing completion. If the text is not an exact match, <RET> does
583 not exit, but it does complete the text. If it completes to an
584 exact match, a second <RET> will exit.
586 Cautious completion is used for reading file names for files that
589 * "Permissive" completion is used when any string whatever is
590 meaningful, and the list of completion alternatives is just a
591 guide. For example, when `C-x C-f' reads the name of a file to
592 visit, any file name is allowed, in case you want to create a
593 file. In permissive completion, <RET> takes the text in the
594 minibuffer exactly as given, without completing it.
596 The completion commands display a list of all possible completions in
597 a window whenever there is more than one possibility for the very next
598 character. Also, typing `?' explicitly requests such a list. If the
599 list of completions is long, you can scroll it with `C-M-v' (*note
603 File: xemacs.info, Node: Completion Options, Prev: Strict Completion, Up: Completion
608 When completion is done on file names, certain file names are usually
609 ignored. The variable `completion-ignored-extensions' contains a list
610 of strings; a file whose name ends in any of those strings is ignored
611 as a possible completion. The standard value of this variable has
612 several elements including `".o"', `".elc"', `".dvi"' and `"~"'. The
613 effect is that, for example, `foo' can complete to `foo.c' even though
614 `foo.o' exists as well. However, if _all_ the possible completions end
615 in "ignored" strings, then they are not ignored. Ignored extensions do
616 not apply to lists of completions--those always mention all possible
619 If a completion command finds the next character is undetermined, it
620 automatically displays a list of all possible completions. If the
621 variable `completion-auto-help' is set to `nil', this does not happen,
622 and you must type `?' to display the possible completions.
624 If the variable `minibuffer-confirm-incomplete' is set to `t', then
625 in contexts where `completing-read' allows answers that are not valid
626 completions, an extra <RET> must be typed to confirm the response.
627 This is helpful for catching typos.
629 Icomplete mode presents a constantly-updated display that tells you
630 what completions are available for the text you've entered so far. The
631 command to enable or disable this minor mode is `M-x icomplete-mode'.
634 File: xemacs.info, Node: Minibuffer History, Next: Repetition, Prev: Completion, Up: Minibuffer
639 Every argument that you enter with the minibuffer is saved on a
640 "minibuffer history list" so that you can use it again later in another
641 argument. Special commands load the text of an earlier argument in the
642 minibuffer. They discard the old minibuffer contents, so you can think
643 of them as moving through the history of previous arguments.
647 Move to the next earlier argument string saved in the minibuffer
648 history (`previous-history-element').
652 Move to the next later argument string saved in the minibuffer
653 history (`next-history-element').
656 Move to an earlier saved argument in the minibuffer history that
657 has a match for REGEXP (`previous-matching-history-element').
660 Move to a later saved argument in the minibuffer history that has a
661 match for REGEXP (`next-matching-history-element').
663 The simplest way to reuse the saved arguments in the history list is
664 to move through the history list one element at a time. While in the
665 minibuffer, use `M-p' or up-arrow (`previous-history-element') to "move
666 to" the next earlier minibuffer input, and use `M-n' or down-arrow
667 (`next-history-element') to "move to" the next later input.
669 The previous input that you fetch from the history entirely replaces
670 the contents of the minibuffer. To use it as the argument, exit the
671 minibuffer as usual with <RET>. You can also edit the text before you
672 reuse it; this does not change the history element that you "moved" to,
673 but your new argument does go at the end of the history list in its own
676 For many minibuffer arguments there is a "default" value. In some
677 cases, the minibuffer history commands know the default value. Then you
678 can insert the default value into the minibuffer as text by using `M-n'
679 to move "into the future" in the history.
681 There are also commands to search forward or backward through the
682 history; they search for history elements that match a regular
683 expression that you specify with the minibuffer. `M-r'
684 (`previous-matching-history-element') searches older elements in the
685 history, while `M-s' (`next-matching-history-element') searches newer
686 elements. By special dispensation, these commands can use the
687 minibuffer to read their arguments even though you are already in the
688 minibuffer when you issue them. As with incremental searching, an
689 uppercase letter in the regular expression makes the search
690 case-sensitive (*note Search Case::).
692 All uses of the minibuffer record your input on a history list, but
693 there are separate history lists for different kinds of arguments. For
694 example, there is a list for file names, used by all the commands that
697 There are several other very specific history lists, including one
698 for command names read by `M-x', one for buffer names, one for arguments
699 of commands like `query-replace', and one for compilation commands read
700 by `compile'. Finally, there is one "miscellaneous" history list that
701 most minibuffer arguments use.
704 File: xemacs.info, Node: Repetition, Prev: Minibuffer History, Up: Minibuffer
706 Repeating Minibuffer Commands
707 =============================
709 Every command that uses the minibuffer at least once is recorded on a
710 special history list, together with the values of its arguments, so that
711 you can repeat the entire command. In particular, every use of `M-x'
712 is recorded there, since `M-x' uses the minibuffer to read the command
716 Re-execute a recent minibuffer command (`repeat-complex-command').
719 Within `C-x <ESC> <ESC>', move to previous recorded command
720 (`previous-history-element').
723 Within `C-x <ESC> <ESC>', move to the next (more recent) recorded
724 command (`next-history-element').
726 `M-x list-command-history'
727 Display the entire command history, showing all the commands `C-x
728 <ESC> <ESC>' can repeat, most recent first.
730 `C-x <ESC> <ESC>' is used to re-execute a recent minibuffer-using
731 command. With no argument, it repeats the last such command. A
732 numeric argument specifies which command to repeat; one means the last
733 one, and larger numbers specify earlier ones.
735 `C-x <ESC> <ESC>' works by turning the previous command into a Lisp
736 expression and then entering a minibuffer initialized with the text for
737 that expression. If you type just <RET>, the command is repeated as
738 before. You can also change the command by editing the Lisp
739 expression. Whatever expression you finally submit is what will be
740 executed. The repeated command is added to the front of the command
741 history unless it is identical to the most recently executed command
744 Even if you don't understand Lisp syntax, it will probably be obvious
745 which command is displayed for repetition. If you do not change the
746 text, you can be sure the command will repeat exactly as before.
748 If you are in the minibuffer for `C-x <ESC> <ESC>' and the command
749 shown to you is not the one you want to repeat, you can move around the
750 list of previous commands using `M-n' and `M-p'. `M-p' replaces the
751 contents of the minibuffer with the next earlier recorded command, and
752 `M-n' replaces it with the next later command. After finding the
753 desired previous command, you can edit its expression and then resubmit
754 it by typing <RET>. Any editing you have done on the command to be
755 repeated is lost if you use `M-n' or `M-p'.
757 `M-n' and `M-p' are specially defined within `C-x <ESC> <ESC>' to
758 run the commands `previous-history-element' and `next-history-element'.
760 The list of previous commands using the minibuffer is stored as a
761 Lisp list in the variable `command-history'. Each element of the list
762 is a Lisp expression which describes one command and its arguments.
763 Lisp programs can reexecute a command by feeding the corresponding
764 `command-history' element to `eval'.
767 File: xemacs.info, Node: M-x, Next: Help, Prev: Minibuffer, Up: Top
769 Running Commands by Name
770 ************************
772 The Emacs commands that are used often or that must be quick to type
773 are bound to keys--short sequences of characters--for convenient use.
774 Other Emacs commands that are used more rarely are not bound to keys;
775 to run them, you must refer to them by name.
777 A command name consists, by convention, of one or more words,
778 separated by hyphens: for example, `auto-fill-mode' or `manual-entry'.
779 The use of English words makes the command name easier to remember than
780 a key made up of obscure characters, even though it results in more
781 characters to type. You can run any command by name, even if it can be
784 To run a command by name, start with `M-x', then type the command
785 name, and finish with <RET>. `M-x' uses the minibuffer to read the
786 command name. <RET> exits the minibuffer and runs the command.
788 Emacs uses the minibuffer for reading input for many different
789 purposes; on this occasion, the string `M-x' is displayed at the
790 beginning of the minibuffer as a "prompt" to remind you that your input
791 should be the name of a command to be run. *Note Minibuffer::, for
792 full information on the features of the minibuffer.
794 You can use completion to enter a command name. For example, to
795 invoke the command `forward-char', type:
797 M-x forward-char <RET>
801 After you type in `M-x fo TAB' emacs will give you a possible list of
802 completions from which you can choose. Note that `forward-char' is the
803 same command that you invoke with the key `C-f'. You can call any
804 command (interactively callable function) defined in Emacs by its name
805 using `M-x' regardless of whether or not any keys are bound to it.
807 If you type `C-g' while Emacs reads the command name, you cancel the
808 `M-x' command and get out of the minibuffer, ending up at top level.
810 To pass a numeric argument to a command you are invoking with `M-x',
811 specify the numeric argument before the `M-x'. `M-x' passes the
812 argument along to the function that it calls. The argument value
813 appears in the prompt while the command name is being read.
815 You can use the command `M-x interactive' to specify a way of
816 parsing arguments for interactive use of a function. For example,
819 (defun foo (arg) "Doc string" (interactive "p") ...use arg...)
821 to make `arg' be the prefix argument when `foo' is called as a
822 command. The call to `interactive' is actually a declaration rather
823 than a function; it tells `call-interactively' how to read arguments to
824 pass to the function. When actually called, `interactive' returns
827 The argument of INTERACTIVE is usually a string containing a code
828 letter followed by a prompt. Some code letters do not use I/O to get
829 the argument and do not need prompts. To prompt for multiple arguments,
830 you must provide a code letter, its prompt, a newline, and another code
831 letter, and so forth. If the argument is not a string, it is evaluated
832 to get a list of arguments to pass to the function. If you do not
833 provide an argument to `interactive', no arguments are passed when
834 calling interactively.
836 Available code letters are:
839 Function name: symbol with a function definition
842 Name of existing buffer
845 Name of buffer, possibly nonexistent
851 Command name: symbol with interactive function definition
854 Value of point as number (does not do I/O)
866 Possibly nonexistent file name
869 Key sequence (string)
872 Value of mark as number (does not do I/O)
875 Number read using minibuffer
878 Prefix arg converted to number, or if none, do like code `n'
881 Prefix arg converted to number (does not do I/O)
884 Prefix arg in raw form (does not do I/O)
887 Region: point and mark as two numeric arguments, smallest first
897 Variable name: symbol that is `user-variable-p'
900 Lisp expression read but not evaluated
903 Lisp expression read and evaluated
905 In addition, if the string begins with `*', an error is signaled if
906 the buffer is read-only. This happens before reading any arguments.
907 If the string begins with `@', the window the mouse is over is selected
908 before anything else is done. You may use both `@' and `*'; they are
909 processed in the order that they appear.
911 Normally, when describing a command that is run by name, we omit the
912 <RET> that is needed to terminate the name. Thus we may refer to `M-x
913 auto-fill-mode' rather than `M-x auto-fill-mode' <RET>. We mention the
914 <RET> only when it is necessary to emphasize its presence, for example,
915 when describing a sequence of input that contains a command name and
916 arguments that follow it.
918 `M-x' is defined to run the command `execute-extended-command',
919 which is responsible for reading the name of another command and
923 File: xemacs.info, Node: Help, Next: Mark, Prev: M-x, Up: Top
928 XEmacs provides extensive help features accessible through a single
929 character, `C-h'. `C-h' is a prefix key that is used only for
930 documentation-printing commands. The characters that you can type after
931 `C-h' are called "help options". One help option is `C-h'; that is how
932 you ask for help about using `C-h'. To cancel, type `C-g'. The
933 function key <F1> is equivalent to `C-h'.
935 `C-h C-h' (`help-for-help') displays a list of the possible help
936 options, and then asks you to type the desired option. It prompts with
939 A B C F I K L M N P S T V W C-c C-d C-f C-i C-k C-n C-w; ? for more help:
941 You should type one of those characters.
943 Typing a third `C-h' displays a description of what the options mean;
944 Emacs still waits for you to type an option. To cancel, type `C-g'.
946 Most help buffers use a special major mode, Help mode, which lets you
947 scroll conveniently with <SPC> and <DEL> or <BS>.
951 * Help Summary:: Brief list of all Help commands.
952 * Key Help:: Asking what a key does in XEmacs.
953 * Name Help:: Asking about a command, variable or function name.
954 * Apropos:: Asking what pertains to a given topic.
955 * Library Keywords:: Finding Lisp libraries by keywords (topics).
956 * Help Mode:: Special features of Help mode and Help buffers.
957 * Misc Help:: Other help commands.
960 File: xemacs.info, Node: Help Summary, Next: Key Help, Prev: Help, Up: Help
965 Here is a summary of the defined help commands.
968 Display a list of functions and variables whose names match REGEXP
972 Show all commands whose names contain matches for REGEXP
976 Display a table of all key bindings currently in effect, with local
977 bindings of the current major mode first, followed by all global
978 bindings (`describe-bindings').
981 Print the name of the command that KEY runs
982 (`describe-key-briefly'). Here `c' stands for `character'. For
983 more extensive information on KEY, use `C-h k'.
985 `C-h d FUNCTION <RET>'
986 `C-h f FUNCTION <RET>'
987 Display documentation on the Lisp function named FUNCTION
988 (`describe-function'). Since commands are Lisp functions, a
989 command name may be used.
992 Run Info, the program for browsing documentation files (`info').
993 The complete XEmacs manual is available online in Info.
996 Display the name and documentation of the command that KEY runs
1000 Display a description of the last 100 characters you typed
1004 Display documentation of the current major mode (`describe-mode').
1008 Display documentation of XEmacs changes, most recent first
1009 (`view-emacs-news').
1012 Find packages by topic keyword (`finder-by-keyword').
1015 Display a table of all mouse bindings currently in effect now, with
1016 local bindings of the current major mode first, followed by all
1017 global bindings (`describe-pointer').
1020 Display current contents of the syntax table, plus an explanation
1021 of what they mean (`describe-syntax'). *Note Syntax::.
1024 Enter the XEmacs interactive tutorial (`help-with-tutorial').
1027 Display the documentation of the Lisp variable VAR
1028 (`describe-variable').
1030 `C-h w COMMAND <RET>'
1031 Print which keys run the command named COMMAND (`where-is').
1034 Display info on how to deal with Beta versions of XEmacs
1038 Select customization buffer for GROUP (`customize').
1041 View the local copy of the XEmacs FAQ (`xemacs-local-faq').
1043 `C-h C-i FILE <RET>'
1044 Read Info file FILE with Info browser (`Info-query').
1046 `C-h C-c COMMAND <RET>'
1047 Look up an Emacs command COMMAND in the Emacs manual in the Info
1048 system (`Info-goto-emacs-command-node').
1050 `C-h C-f FUNCTION <RET>'
1051 Look up an Emacs Lisp function FUNCTION in the Elisp manual in the
1052 Info system (`Info-elisp-ref').
1055 File: xemacs.info, Node: Key Help, Next: Name Help, Prev: Help Summary, Up: Help
1057 Documentation for a Key
1058 =======================
1060 The most basic `C-h' options are `C-h c' (`describe-key-briefly')
1061 and `C-h k' (`describe-key'). `C-h c KEY' prints in the echo area the
1062 name of the command that KEY is bound to. For example, `C-h c C-f'
1063 prints `forward-char'. Since command names are chosen to describe what
1064 the commands do, this is a good way to get a very brief description of
1067 `C-h k KEY' is similar to `C-h c' but gives more information. It
1068 displays the documentation string of the function KEY is bound to as
1069 well as its name. KEY is a string or vector of events. When called
1070 interactively, KEY may also be a menu selection. This information does
1071 not usually fit into the echo area, so a window is used for the display.
1073 `C-h c' and `C-h k' work for any sort of key sequences, including
1074 function keys and mouse events.
1077 File: xemacs.info, Node: Name Help, Next: Apropos, Prev: Key Help, Up: Help
1079 Help by Command or Variable Name
1080 ================================
1082 `C-h f' (`describe-function') reads the name of a Lisp function
1083 using the minibuffer, then displays that function's documentation
1084 string in a window. Since commands are Lisp functions, you can use the
1085 argument FUNCTION to get the documentation of a command that you know
1086 by name. For example,
1088 C-h f auto-fill-mode <RET>
1090 displays the documentation for `auto-fill-mode'. Using `C-h f' is the
1091 only way to see the documentation of a command that is not bound to any
1092 key, that is, a command you would normally call using `M-x'. If the
1093 variable `describe-function-show-arglist' is `t', `describe-function'
1094 shows its arglist if the FUNCTION is not an autoload function.
1096 `C-h f' is also useful for Lisp functions that you are planning to
1097 use in a Lisp program. For example, if you have just written the
1098 expression `(make-vector len)' and want to make sure you are using
1099 `make-vector' properly, type `C-h f make-vector <RET>'. Because `C-h
1100 f' allows all function names, not just command names, you may find that
1101 some of your favorite abbreviations that work in `M-x' don't work in
1102 `C-h f'. An abbreviation may be unique among command names, yet fail
1103 to be unique when other function names are allowed.
1105 The function name for `C-h f' to describe has a default which is
1106 used if you type <RET> leaving the minibuffer empty. The default is
1107 the function called by the innermost Lisp expression in the buffer
1108 around point, _provided_ that is a valid, defined Lisp function name.
1109 For example, if point is located following the text `(make-vector (car
1110 x)', the innermost list containing point is the one that starts with
1111 `(make-vector', so the default is to describe the function
1114 `C-h f' is often useful just to verify that you have the right
1115 spelling for the function name. If `C-h f' mentions a name from the
1116 buffer as the default, that name must be defined as a Lisp function. If
1117 that is all you want to know, just type `C-g' to cancel the `C-h f'
1118 command, then go on editing.
1120 `C-h w COMMAND <RET>' (`where-is') tells you what keys are bound to
1121 COMMAND. It prints a list of the keys in the echo area. Alternatively,
1122 it informs you that a command is not bound to any keys, which implies
1123 that you must use `M-x' to call the command.
1125 `C-h v' (`describe-variable') is like `C-h f' but describes Lisp
1126 variables instead of Lisp functions. Its default is the Lisp symbol
1127 around or before point, if that is the name of a known Lisp variable.
1131 File: xemacs.info, Node: Apropos, Next: Library Keywords, Prev: Name Help, Up: Help
1137 Show only symbols that are names of commands (`command-apropos').
1139 `M-x apropos REGEXP'
1140 Show all symbols whose names contain matches for REGEXP.
1142 A more sophisticated sort of question to ask is, "What are the
1143 commands for working with files?" To ask this question, type `C-h a
1144 file <RET>', which displays a list of all command names that contain
1145 `file', including `copy-file', `find-file', and so on. With each
1146 command name appears a brief description of how to use the command, and
1147 what keys you can currently invoke it with. For example, it would say
1148 that you can invoke `find-file' by typing `C-x C-f'. The `A' in `C-h
1149 A' stands for `Apropos'; `C-h A' runs the command `command-apropos'.
1150 This command normally checks only commands (interactive functions); if
1151 you specify a prefix argument, it checks noninteractive functions as
1154 Because `C-h A' looks only for functions whose names contain the
1155 string you specify, you must use ingenuity in choosing the string. If
1156 you are looking for commands for killing backwards and `C-h a
1157 kill-backwards <RET>' doesn't reveal any, don't give up. Try just
1158 `kill', or just `backwards', or just `back'. Be persistent. Pretend
1159 you are playing Adventure. Also note that you can use a regular
1160 expression as the argument, for more flexibility (*note Regexps::).
1162 Here is a set of arguments to give to `C-h a' that covers many
1163 classes of XEmacs commands, since there are strong conventions for
1164 naming the standard XEmacs commands. By giving you a feel for the
1165 naming conventions, this set should also serve to aid you in developing
1166 a technique for picking `apropos' strings.
1168 char, line, word, sentence, paragraph, region, page, sexp, list,
1169 defun, rect, buffer, frame, window, face, file, dir, register,
1170 mode, beginning, end, forward, backward, next, previous, up, down,
1171 search, goto, kill, delete, mark, insert, yank, fill, indent,
1172 case, change, set, what, list, find, view, describe, default.
1174 To list all Lisp symbols that contain a match for a regexp, not just
1175 the ones that are defined as commands, use the command `M-x apropos'
1176 instead of `C-h A'. This command does not check key bindings by
1177 default; specify a numeric argument if you want it to check them.
1179 The `apropos-documentation' command is like `apropos' except that it
1180 searches documentation strings for matches for the specified regular
1183 The `apropos-value' command is like `apropos' except that it
1184 searches symbols' values for matches for the specified regular
1185 expression. This command does not check function definitions or
1186 property lists by default; specify a numeric argument if you want it to
1189 If the variable `apropos-do-all' is non-`nil', the commands above
1190 all behave as if they had been given a prefix argument.
1192 If you want more information about a function definition, variable or
1193 symbol property listed in the Apropos buffer, you can click on it with
1194 `Mouse-2' or move there and type <RET>.