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: Mode Line, Next: XEmacs under X, Prev: Echo Area, Up: Frame
38 Each text window's last line is a "mode line" which describes what is
39 going on in that window. When there is only one text window, the mode
40 line appears right above the echo area. The mode line is in inverse
41 video if the terminal supports that, starts and ends with dashes, and
42 contains text like `XEmacs: SOMETHING'.
44 If a mode line has something else in place of `XEmacs: SOMETHING',
45 the window above it is in a special subsystem such as Dired. The mode
46 line then indicates the status of the subsystem.
48 Normally, the mode line has the following appearance:
50 --CH-XEmacs: BUF (MAJOR MINOR)----POS------
52 This gives information about the buffer being displayed in the window:
53 the buffer's name, what major and minor modes are in use, whether the
54 buffer's text has been changed, and how far down the buffer you are
57 CH contains two stars (`**') if the text in the buffer has been
58 edited (the buffer is "modified"), or two dashes (`--') if the buffer
59 has not been edited. Exception: for a read-only buffer, it is `%%'.
61 BUF is the name of the window's chosen "buffer". The chosen buffer
62 in the selected window (the window that the cursor is in) is also
63 XEmacs's selected buffer, the buffer in which editing takes place. When
64 we speak of what some command does to "the buffer", we mean the
65 currently selected buffer. *Note Buffers::.
67 POS tells you whether there is additional text above the top of the
68 screen or below the bottom. If your file is small and it is completely
69 visible on the screen, POS is `All'. Otherwise, POS is `Top' if you
70 are looking at the beginning of the file, `Bot' if you are looking at
71 the end of the file, or `NN%', where NN is the percentage of the file
72 above the top of the screen.
74 MAJOR is the name of the "major mode" in effect in the buffer. At
75 any time, each buffer is in one and only one major mode. The available
76 major modes include Fundamental mode (the least specialized), Text
77 mode, Lisp mode, and C mode. *Note Major Modes::, for details on how
78 the modes differ and how you select one.
80 MINOR is a list of some of the "minor modes" that are turned on in
81 the window's chosen buffer. For example, `Fill' means that Auto Fill
82 mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means
83 that Overwrite mode is on. *Note Minor Modes::, for more information.
84 `Narrow' means that the buffer being displayed has editing restricted
85 to only a portion of its text. This is not really a minor mode, but is
86 like one. *Note Narrowing::. `Def' means that a keyboard macro is
87 being defined. *Note Keyboard Macros::.
89 Some buffers display additional information after the minor modes.
90 For example, Rmail buffers display the current message number and the
91 total number of messages. Compilation buffers and Shell mode display
92 the status of the subprocess.
94 If XEmacs is currently inside a recursive editing level, square
95 brackets (`[...]') appear around the parentheses that surround the
96 modes. If XEmacs is in one recursive editing level within another,
97 double square brackets appear, and so on. Since information on
98 recursive editing applies to XEmacs in general and not to any one
99 buffer, the square brackets appear in every mode line on the screen or
100 not in any of them. *Note Recursive Edit::.
102 XEmacs can optionally display the time and system load in all mode
103 lines. To enable this feature, type `M-x display-time'. The
104 information added to the mode line usually appears after the file name,
105 before the mode names and their parentheses. It looks like this:
109 (Some fields may be missing if your operating system cannot support
110 them.) HH and MM are the hour and minute, followed always by `am' or
111 `pm'. L.LL is the average number of running processes in the whole
112 system recently. D is an approximate index of the ratio of disk
113 activity to CPU activity for all users.
115 The word `Mail' appears after the load level if there is mail for
116 you that you have not read yet.
118 Customization note: the variable `mode-line-inverse-video' controls
119 whether the mode line is displayed in inverse video (assuming the
120 terminal supports it); `nil' means no inverse video. The default is
121 `t'. For X frames, simply set the foreground and background colors
125 File: xemacs.info, Node: XEmacs under X, Prev: Mode Line, Up: Frame
127 Using XEmacs Under the X Window System
128 ======================================
130 XEmacs can be used with the X Window System and a window manager like
131 MWM or TWM. In that case, the X window manager opens, closes, and
132 resizes XEmacs frames. You use the window manager's mouse gestures to
133 perform the operations. Consult your window manager guide or reference
134 manual for information on manipulating X windows.
136 When you are working under X, each X window (that is, each XEmacs
137 frame) has a menu bar for mouse-controlled operations (*note Pull-down
140 XEmacs under X is also a multi-frame XEmacs. You can use the New
141 Frame menu item from the File menu to create a new XEmacs frame in a
142 new X window from the same process. The different frames will share the
143 same buffer list, but you can look at different buffers in the different
146 The function `find-file-other-frame' is just like `find-file', but
147 creates a new frame to display the buffer in first. This is normally
148 bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
151 The function `switch-to-buffer-other-frame' is just like
152 `switch-to-buffer', but creates a new frame to display the buffer in
153 first. This is normally bound to `C-x 5 b'.
155 You can specify a different default frame size other than the one
156 provided. Use the variable `default-frame-alist', which is an alist of
157 default values for frame creation other than the first one. These may
158 be set in your init file, like this:
160 (setq default-frame-alist '((width . 80) (height . 55)))
162 For values specific to the first XEmacs frame, you must use X
163 resources. The variable `x-frame-defaults' takes an alist of default
164 frame creation parameters for X window frames. These override what is
165 specified in `~/.Xdefaults' but are overridden by the arguments to the
166 particular call to `x-create-frame'.
168 When you create a new frame, the variable `create-frame-hook' is
169 called with one argument, the frame just created.
171 If you want to close one or more of the X windows you created using
172 New Frame, use the Delete Frame menu item from the File menu.
174 If you are working with multiple frames, some special information
176 * Two variables, `frame-title-format' and `frame-icon-title-format'
177 determine the title of the frame and the title of the icon that
178 results if you shrink the frame.
180 * The variables `auto-lower-frame' and `auto-raise-frame' position a
181 frame. If true, `auto-lower-frame' lowers a frame to the bottom
182 when it is no longer selected. If true, `auto-raise-frame' raises
183 a frame to the top when it is selected. Under X, most
184 ICCCM-compliant window managers will have options to do this for
185 you, but these variables are provided in case you are using a
186 broken window manager.
188 * There is a new frame/modeline format directive, %S, which expands
189 to the name of the current frame (a frame's name is distinct from
190 its title; the name is used for resource lookup, among other
191 things, and the title is simply what appears above the window.)
194 File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
196 Keystrokes, Key Sequences, and Key Bindings
197 *******************************************
201 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
202 * Representing Keystrokes:: Using lists of modifiers and keysyms to
203 represent keystrokes.
204 * Key Sequences:: Combine key strokes into key sequences you can
206 * String Key Sequences:: Available for upward compatibility.
207 * Meta Key:: Using <ESC> to represent <Meta>
208 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
209 * Character Representation:: How characters appear in Emacs buffers.
210 * Commands:: How commands are bound to key sequences.
213 File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
215 Keystrokes as Building Blocks of Key Sequences
216 ==============================================
218 Earlier versions of Emacs used only the ASCII character set, which
219 defines 128 different character codes. Some of these codes are
220 assigned graphic symbols like `a' and `='; the rest are control
221 characters, such as `Control-a' (also called `C-a'). `C-a' means you
222 hold down the <CTRL> key and then press `a'.
224 Keybindings in XEmacs are not restricted to the set of keystrokes
225 that can be represented in ASCII. XEmacs can tell the difference
226 between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
228 A keystroke is like a piano chord: you get it by simultaneously
229 striking several keys. To be more precise, a keystroke consists of a
230 possibly empty set of modifiers followed by a single "keysym". The set
231 of modifiers is small; it consists of `Control', `Meta', `Super',
232 `Hyper', and `Shift'.
234 The rest of the keys on your keyboard, along with the mouse buttons,
235 make up the set of keysyms. A keysym is usually what is printed on the
236 keys on your keyboard. Here is a table of some of the symbolic names
254 upstroke on the left mouse button
257 upstroke on the middle mouse button
260 upstroke on the right mouse button
265 Use the variable `keyboard-translate-table' only if you are on a
266 dumb tty, as it cannot handle input that cannot be represented as ASCII.
267 The value of this variable is a string used as a translate table for
268 keyboard input or `nil'. Each character is looked up in this string
269 and the contents used instead. If the string is of length `n',
270 character codes `N' and up are untranslated. If you are running Emacs
271 under X, you should do the translations with the `xmodmap' program
275 File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
277 Representing Keystrokes
278 -----------------------
280 XEmacs represents keystrokes as lists. Each list consists of an
281 arbitrary combination of modifiers followed by a single keysym at the
282 end of the list. If the keysym corresponds to an ASCII character, you
283 can use its character code. (A keystroke may also be represented by an
284 event object, as returned by the `read-key-sequence' function;
285 non-programmers need not worry about this.)
287 The following table gives some examples of how to list
288 representations for keystrokes. Each list consists of sets of
289 modifiers followed by keysyms:
292 Pressing <CTRL> and `a' simultaneously.
295 Another way of writing the keystroke `C-a'.
298 Yet another way of writing the keystroke `C-a'.
301 Pressing the <BREAK> key.
303 `(control meta button2up)'
304 Release the middle mouse button, while pressing <CTRL> and <META>.
305 Note: As you define keystrokes, you can use the `shift' key only as a
306 modifier with characters that do not have a second keysym on the same
307 key, such as `backspace' and `tab'. It is an error to define a
308 keystroke using the <shift> modifier with keysyms such as `a' and `='.
309 The correct forms are `A' and `+'.
312 File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
314 Representing Key Sequences
315 --------------------------
317 A "complete key sequence" is a sequence of keystrokes that Emacs
318 understands as a unit. Key sequences are significant because you can
319 bind them to commands. Note that not all sequences of keystrokes are
320 possible key sequences. In particular, the initial keystrokes in a key
321 sequence must make up a "prefix key sequence".
323 Emacs represents a key sequence as a vector of keystrokes. Thus, the
324 schematic representation of a complete key sequence is as follows:
326 [(modifier .. modifer keysym) ... (modifier .. modifier keysym)]
328 Here are some examples of complete key sequences:
330 `[(control c) (control a)]'
331 Typing `C-c' followed by `C-a'
333 `[(control c) (control 65)]'
334 Typing `C-c' followed by `C-a'. (Using the ASCII code for the
337 `[(control c) (break)]'
338 Typing `C-c' followed by the `break' character.
340 A "prefix key sequence" is the beginning of a series of longer
341 sequences that are valid key sequences; adding any single keystroke to
342 the end of a prefix results in a valid key sequence. For example,
343 `control-x' is standardly defined as a prefix. Thus there is a
344 two-character key sequence starting with `C-x' for each valid
345 keystroke, giving numerous possibilities. Here are some samples:
347 * `[(control x) (c)]'
349 * `[(control x) (control c)]'
351 Adding one character to a prefix key does not have to form a complete
352 key. It could make another, longer prefix. For example, `[(control x)
353 (\4)]' is itself a prefix that leads to any number of different
354 three-character keys, including `[(control x) (\4) (f)]', `[(control x)
355 (\4) (b)]' and so on. It would be possible to define one of those
356 three-character sequences as a prefix, creating a series of
357 four-character keys, but we did not define any of them this way.
359 By contrast, the two-character sequence `[(control f) (control k)]'
360 is not a key, because the `(control f)' is a complete key sequence in
361 itself. You cannot give `[(control f (control k)]' an independent
362 meaning as a command while `(control f)' is a complete sequence,
363 because Emacs would understand <C-f C-k> as two commands.
365 The predefined prefix key sequences in Emacs are `(control c)',
366 `(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
367 can customize Emacs and could make new prefix keys or eliminate the
368 default key sequences. *Note Key Bindings::. For example, if you
369 redefine `(control f)' as a prefix, `[(control f) (control k)]'
370 automatically becomes a valid key sequence (complete, unless you define
371 it as a prefix as well). Conversely, if you remove the prefix
372 definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
373 `[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
375 Note that the above paragraphs uses \4 instead of simply 4, because
376 \4 is the symbol whose name is "4", and plain 4 is the integer 4, which
377 would have been interpreted as the ASCII value. Another way of
378 representing the symbol whose name is "4" is to write ?4, which would be
379 interpreted as the number 52, which is the ASCII code for the character
380 "4". We could therefore actually have written 52 directly, but that is
384 File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
389 For backward compatibility, you may also represent a key sequence
390 using strings. For example, we have the following equivalent
394 `[(control c) (control c)]'
400 File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
402 Assignment of the <META> Key
403 ----------------------------
405 Not all terminals have the complete set of modifiers. Terminals
406 that have a <Meta> key allow you to type Meta characters by just
407 holding that key down. To type `Meta-a', hold down <META> and press
408 `a'. On those terminals, the <META> key works like the <SHIFT> key.
409 Such a key is not always labeled <META>, however, as this function is
410 often a special option for a key with some other primary purpose.
412 If there is no <META> key, you can still type Meta characters using
413 two-character sequences starting with <ESC>. To enter `M-a', you could
414 type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
415 allowed on terminals with Meta keys, too, in case you have formed a
418 If you are running under X and do not have a <META> key, it is
419 possible to reconfigure some other key to be a <META> key. *Note Super
422 Emacs believes the terminal has a <META> key if the variable
423 `meta-flag' is non-`nil'. Normally this is set automatically according
424 to the termcap entry for your terminal type. However, sometimes the
425 termcap entry is wrong, and then it is useful to set this variable
426 yourself. *Note Variables::, for how to do this.
428 Note: If you are running under the X window system, the setting of
429 the `meta-flag' variable is irrelevant.
432 File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
434 Assignment of the <SUPER> and <HYPER> Keys
435 ------------------------------------------
437 Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
438 keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
439 to bind keys to sequences using `super' and `hyper'. You can use the
440 `xmodmap' program to do this.
442 For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
445 Create a file called `~/.xmodmap'. In this file, place the lines
447 remove Lock = Caps_Lock
448 keysym Caps_Lock = Super_L
451 The first line says that the key that is currently called `Caps_Lock'
452 should no longer behave as a "lock" key. The second line says that
453 this should now be called `Super_L' instead. The third line says that
454 the key called `Super_L' should be a modifier key, which produces the
457 To create a <META> or <HYPER> key instead of a <SUPER> key, replace
458 the word `Super' above with `Meta' or `Hyper'.
460 Just after you start up X, execute the command `xmodmap /.xmodmap'.
461 You can add this command to the appropriate initialization file to have
462 the command executed automatically.
464 If you have problems, see the documentation for the `xmodmap'
465 program. The X keyboard model is quite complicated, and explaining it
466 is beyond the scope of this manual. However, we reprint the following
467 description from the X Protocol document for your convenience:
469 A list of keysyms is associated with each keycode. If that list
470 (ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
471 list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
472 the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
473 `K1 K2', then the list is treated as if it were the list ```K1 K2 K1
474 K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
475 of keysyms `K1 K2 K3', then the list is treated as if it were the list
476 ```K1 K2 K3 NoSymbol'''.
478 The first four elements of the list are split into two groups of
479 keysyms. Group 1 contains the first and second keysyms; Group 2 contains
480 third and fourth keysyms. Within each group, if the second element of
481 the group is NoSymbol, then the group should be treated as if the second
482 element were the same as the first element, except when the first
483 element is an alphabetic keysym `K' for which both lowercase and
484 uppercase forms are defined. In that case, the group should be treated
485 as if the first element were the lowercase form of `K' and the second
486 element were the uppercase form of `K'.
488 The standard rules for obtaining a keysym from a KeyPress event make
489 use of only the Group 1 and Group 2 keysyms; no interpretation of other
490 keysyms in the list is given here. (That is, the last four keysyms are
493 Which group to use is determined by modifier state. Switching between
494 groups is controlled by the keysym named `Mode_switch'. Attach that
495 keysym to some keycode and attach that keycode to any one of the
496 modifiers Mod1 through Mod5. This modifier is called the "group
497 modifier". For any keycode, Group 1 is used when the group modifier is
498 off, and Group 2 is used when the group modifier is on.
500 Within a group, which keysym to use is also determined by modifier
501 state. The first keysym is used when the `Shift' and `Lock' modifiers
502 are off. The second keysym is used when the `Shift' modifier is on, or
503 when the `Lock' modifier is on and the second keysym is uppercase
504 alphabetic, or when the `Lock' modifier is on and is interpreted as
505 `ShiftLock'. Otherwise, when the `Lock' modifier is on and is
506 interpreted as `CapsLock', the state of the `Shift' modifier is applied
507 first to select a keysym, but if that keysym is lower-case alphabetic,
508 then the corresponding upper-case keysym is used instead.
510 In addition to the above information on keysyms, we also provide the
511 following description of modifier mapping from the InterClient
512 Communications Conventions Manual:
514 X11 supports 8 modifier bits, of which 3 are pre-assigned to
515 `Shift', `Lock', and `Control'. Each modifier bit is controlled by the
516 state of a set of keys, and these sets are specified in a table
517 accessed by `GetModifierMapping()' and `SetModifierMapping()'.
519 A client needing to use one of the pre-assigned modifiers should
520 assume that the modifier table has been set up correctly to control
521 these modifiers. The `Lock' modifier should be interpreted as `Caps
522 Lock' or `Shift Lock' according to whether the keycodes in its
523 controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
525 Clients should determine the meaning of a modifier bit from the
526 keysyms being used to control it.
528 A client needing to use an extra modifier, for example `Meta',
531 1. Scan the existing modifier mappings.
533 1. If it finds a modifier that contains a keycode whose set of
534 keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
537 2. If there is no existing modifier controlled by `XK_Meta_L' or
538 `XK_Meta_R', it should select an unused modifier bit (one with
539 an empty controlling set) and:
541 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
542 that keycode to the set for the chosen modifier, and then:
544 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
545 add that keycode to the set for the chosen modifier, and then:
547 2. If the controlling set is still empty, interact with the user
548 to select one or more keys to be `Meta'.
550 3. If there are no unused modifier bits, ask the user to take
553 This means that the `Mod1' modifier does not necessarily mean
554 `Meta', although some applications (such as twm and emacs 18) assume
555 that. Any of the five unassigned modifier bits could mean `Meta'; what
556 matters is that a modifier bit is generated by a keycode which is bound
557 to the keysym `Meta_L' or `Meta_R'.
559 Therefore, if you want to make a <META> key, the right way is to
560 make the keycode in question generate both a `Meta' keysym and some
561 previously-unassigned modifier bit.
564 File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
566 Representation of Characters
567 ============================
569 This section briefly discusses how characters are represented in
570 Emacs buffers. *Note Key Sequences::, for information on representing
571 key sequences to create key bindings.
573 ASCII graphic characters in Emacs buffers are displayed with their
574 graphics. <LFD> is the same as a newline character; it is displayed by
575 starting a new line. <TAB> is displayed by moving to the next tab stop
576 column (usually every 8 spaces). Other control characters are
577 displayed as a caret (`^') followed by the non-control version of the
578 character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
579 and up are displayed with octal escape sequences; thus, character code
580 243 (octal), also called `M-#' when used as an input character, is
583 The variable `ctl-arrow' may be used to alter this behavior. *Note
587 File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
592 This manual is full of passages that tell you what particular keys
593 do. But Emacs does not assign meanings to keys directly. Instead,
594 Emacs assigns meanings to "functions", and then gives keys their
595 meanings by "binding" them to functions.
597 A function is a Lisp object that can be executed as a program.
598 Usually it is a Lisp symbol that has been given a function definition;
599 every symbol has a name, usually made of a few English words separated
600 by dashes, such as `next-line' or `forward-word'. It also has a
601 "definition", which is a Lisp program. Only some functions can be the
602 bindings of keys; these are functions whose definitions use
603 `interactive' to specify how to call them interactively. Such
604 functions are called "commands", and their names are "command names".
605 More information on this subject will appear in the XEmacs Lisp
608 The bindings between keys and functions are recorded in various
609 tables called "keymaps". *Note Key Bindings::, for more information on
610 key sequences you can bind commands to. *Note Keymaps::, for
611 information on creating keymaps.
613 When we say "`C-n' moves down vertically one line" we are glossing
614 over a distinction that is irrelevant in ordinary use but is vital in
615 understanding how to customize Emacs. The function `next-line' is
616 programmed to move down vertically. `C-n' has this effect because it
617 is bound to that function. If you rebind `C-n' to the function
618 `forward-word' then `C-n' will move forward by words instead.
619 Rebinding keys is a common method of customization.
621 The rest of this manual usually ignores this subtlety to keep things
622 simple. To give the customizer the information needed, we often state
623 the name of the command that really does the work in parentheses after
624 mentioning the key that runs it. For example, we will say that "The
625 command `C-n' (`next-line') moves point vertically down," meaning that
626 `next-line' is a command that moves vertically down and `C-n' is a key
627 that is standardly bound to it.
629 While we are on the subject of information for customization only,
630 it's a good time to tell you about "variables". Often the description
631 of a command will say, "To change this, set the variable `mumble-foo'."
632 A variable is a name used to remember a value. Most of the variables
633 documented in this manual exist just to facilitate customization: some
634 command or other part of Emacs uses the variable and behaves
635 differently depending on its setting. Until you are interested in
636 customizing, you can ignore the information about variables. When you
637 are ready to be interested, read the basic information on variables, and
638 then the information on individual variables will make sense. *Note
642 File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
644 XEmacs Pull-down Menus
645 ======================
647 If you are running XEmacs under X, a menu bar on top of the Emacs
648 frame provides access to pull-down menus of file, edit, and
649 help-related commands. The menus provide convenient shortcuts and an
650 easy interface for novice users. They do not provide additions to the
651 functionality available via key commands; you can still invoke commands
652 from the keyboard as in previous versions of Emacs.
655 Perform file and buffer-related operations, such as opening and
656 closing files, saving and printing buffers, as well as exiting
660 Perform standard editing operations, such as cutting, copying,
661 pasting, and killing selected text.
664 Access to sub-applications implemented within XEmacs, such as the
665 mail reader, the World Wide Web browser, the spell-checker, and
666 the calendar program.
669 Control various options regarding the way XEmacs works, such as
670 controlling which elements of the frame are visible, selecting the
671 fonts to be used for text, specifying whether searches are
675 Present a menu of buffers for selection as well as the option to
676 display a buffer list.
679 Perform various actions designed to automate software development
680 and similar technical work, such as searching through many files,
681 compiling a program, and comparing or merging two or three files.
684 Access to Emacs Info.
686 There are two ways of selecting an item from a pull-down menu:
688 * Select an item in the menu bar by moving the cursor over it and
689 click the left mouse-button. Then move the cursor over the menu
690 item you want to choose and click left again.
692 * Select an item in the menu bar by moving the cursor over it and
693 click and hold the left mouse-button. With the mouse-button
694 depressed, move the cursor over the menu item you want, then
695 release it to make your selection.
697 If a command in the pull-down menu is not applicable in a given
698 situation, the command is disabled and its name appears faded. You
699 cannot invoke items that are faded. For example, many commands on the
700 Edit menu appear faded until you select text on which they are to
701 operate; after you select a block of text, edit commands are enabled.
702 *Note Mouse Selection::, for information on using the mouse to select
703 text. *Note Using X Selections::, for related information.
705 There are also `M-x' equivalents for each menu item. To find the
706 equivalent for any left-button menu item, do the following:
708 1. Type `C-h k' to get the `Describe Key' prompt.
710 2. Select the menu item and click.
712 Emacs displays the function associated with the menu item in a
713 separate window, usually together with some documentation.
717 * File Menu:: Items on the File menu.
718 * Edit Menu:: Items on the Edit menu.
719 * Apps Menu:: Items on the Apps menu.
720 * Options Menu:: Items on the Options menu.
721 * Buffers Menu:: Information about the Buffers menu.
722 * Tools Menu:: Items on the Tools menu.
723 * Help Menu:: Items on the Help menu.
724 * Menu Customization:: Adding and removing menu items and related
728 File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
733 The File menu bar item contains the items New Frame, Open File...,
734 Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
735 Frame, Kill Buffer and Exit Emacs on the pull-down menu. If you select
736 a menu item, Emacs executes the equivalent command.
738 Open File, New Frame...
739 Prompts you for a filename and loads that file into a new buffer
740 in a new Emacs frame, that is, a new X window running under the
741 same Emacs process. You can remove the frame using the Delete
742 Frame menu item. When you remove the last frame, you exit Emacs
743 and are prompted for confirmation.
746 Prompts you for a filename and loads that file into a new buffer.
747 Open File... is equivalent to the Emacs command `find-file' (`C-x
751 Prompts you for a filename and inserts the contents of that file
752 into the current buffer. The file associated with the current
753 buffer is not changed by this command. This is equivalent to the
754 Emacs command `insert-file' (`C-x i').
757 Writes and saves the current Emacs buffer as the latest version of
758 the current visited file. Save Buffer is equivalent to the Emacs
759 command `save-buffer' (`C-x C-s').
762 Writes and saves the current Emacs buffer to the filename you
763 specify. Save Buffer As... is equivalent to the Emacs command
764 `write-file' (`C-x C-w').
767 Restores the last saved version of the file to the current buffer.
768 When you edit a buffer containing a text file, you must save the
769 buffer before your changes become effective. Use Revert Buffer if
770 you do not want to keep the changes you have made in the buffer.
771 Revert Buffer is equivalent to the Emacs command `revert-file'
772 (`M-x revert-buffer').
775 Kills the current buffer, prompting you first if there are unsaved
776 changes. This is roughly equivalent to the Emacs command
777 `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
778 name of a buffer to kill.
781 Prints a hardcopy of the current buffer. Equivalent to the Emacs
782 command `print-buffer' (`M-x print-buffer').
785 Creates a new Emacs frame displaying the `*scratch*' buffer. This
786 is like the Open File, New Frame... menu item, except that it does
787 not prompt for or load a file.
790 Allows you to close all but one of the frames created by New Frame.
791 If you created several Emacs frames belonging to the same Emacs
792 process, you can close all but one of them. When you attempt to
793 close the last frame, Emacs informs you that you are attempting to
794 delete the last frame. You have to choose Exit Emacs for that.
797 Divides the current window on the current frame into two
798 equal-sized windows, both displaying the same buffer. Equivalent
799 to the Emacs command `split-window-vertically' (`C-x 2').
802 If the frame is divided into multiple windows, this removes all
803 windows other than the selected one. Equivalent to the Emacs
804 command `delete-other-windows' (`C-x 1').
806 Un-split (Keep Others)
807 If the frame is divided into multiple windows, this removes the
808 selected window from the frame, giving the space back to one of the
809 other windows. Equivalent to the Emacs command `delete-window'
813 Shuts down (kills) the Emacs process. Equivalent to the Emacs
814 command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
815 Emacs process, the system asks which unsaved buffers to save by
816 going through the list of all buffers in that Emacs process.
819 File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
824 The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
825 Clear menu items. When you select a menu item, Emacs executes the
826 equivalent command. Most commands on the Edit menu work on a block of
827 text, the X selection. They appear faded until you select a block of
828 text (activate a region) with the mouse. *Note Using X Selections::,
829 *note Killing::, and *note Yanking:: for more information.
832 Undoes the previous command. Undo is equivalent to the Emacs
833 command `undo' (`C-x u').
836 Removes the selected text block from the current buffer, makes it
837 the X clipboard selection, and places it in the kill ring. Before
838 executing this command, you have to select a region using Emacs
839 region selection commands or with the mouse.
842 Makes a selected text block the X clipboard selection, and places
843 it in the kill ring. You can select text using one of the Emacs
844 region selection commands or by selecting a text region with the
848 Inserts the current value of the X clipboard selection in the
849 current buffer. Note that this is not necessarily the same as the
850 Emacs `yank' command, because the Emacs kill ring and the X
851 clipboard selection are not the same thing. You can paste in text
852 you have placed in the clipboard using Copy or Cut. You can also
853 use Paste to insert text that was pasted into the clipboard from
857 Removes the selected text block from the current buffer but does
858 not place it in the kill ring or the X clipboard selection.
860 Start Macro Recording
861 After selecting this, Emacs will remember every keystroke you type
862 until End Macro Recording is selected. This is the same as the
863 Emacs command `start-kbd-macro' (`C-x (').
866 Selecting this tells emacs to stop remembering your keystrokes.
867 This is the same as the Emacs command `end-kbd-macro' (`C-x )').
870 Selecting this item will cause emacs to re-interpret all of the
871 keystrokes which were saved between selections of the Start Macro
872 Recording and End Macro Recording menu items. This is the same as
873 the Emacs command `call-last-kbd-macro' (`C-x e').
876 File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
881 The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
882 (MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
883 Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
884 When you select a menu item, Emacs executes the equivalent command.
885 For some of the menu items, there are sub-menus which you will need to
889 File: xemacs.info, Node: Options Menu, Next: Buffers Menu, Prev: Apps Menu, Up: Pull-down Menus
894 The Options pull-down menu contains the Read Only, Case Sensitive
895 Search, Overstrike, Auto Delete Selection, Teach Extended Commands,
896 Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers
897 Menu Length..., Buffers Sub-Menus and Save Options menu items. When
898 you select a menu item, Emacs executes the equivalent command. For
899 some of the menu items, there are sub-menus which you will need to
903 Selecting this item will cause the buffer to visit the file in a
904 read-only mode. Changes to the file will not be allowed. This is
905 equivalent to the Emacs command `toggle-read-only' (`C-x C-q').
907 Case Sensitive Search
908 Selecting this item will cause searches to be case-sensitive. If
909 its not selected then searches will ignore case. This option is
913 After selecting this item, when you type letters they will replace
914 existing text on a one-to-one basis, rather than pushing it to the
915 right. At the end of a line, such characters extend the line.
916 Before a tab, such characters insert until the tab is filled in.
917 This is the same as Emacs command `quoted-insert' (`C-q').
919 Auto Delete Selection
920 Selecting this item will cause automatic deletion of the selected
921 region. The typed text will replace the selection if the selection
922 is active (i.e. if its highlighted). If the option is not selected
923 then the typed text is just inserted at the point.
925 Teach Extended Commands
926 After you select this item, any time you execute a command with
927 `M-x'which has a shorter keybinding, you will be shown the
928 alternate binding before the command executes.
931 You can customize your `.emacs' file to include the font-lock mode
932 so that when you select this item, the comments will be displayed
933 in one face, strings in another, reserved words in another, and so
934 on. When Fonts is selected, different parts of the program will
935 appear in different Fonts. When Colors is selected, then the
936 program will be displayed in different colors. Selecting None
937 causes the program to appear in just one Font and Color. Selecting
938 Less resets the Fonts and Colors to a fast, minimal set of
939 decorations. Selecting More resets the Fonts and Colors to a larger
940 set of decorations. For example, if Less is selected (which is the
941 default setting) then you might have all comments in green color.
942 Whereas, if More is selected then a function name in the comments
943 themselves might appear in a different Color or Font.
946 After selecting Blink from this item, if you place the cursor on a
947 parenthesis, the matching parenthesis will blink. If you select
948 Highlight and place the cursor on a parenthesis, the whole
949 expression of the parenthesis under the cursor will be highlighted.
950 Selecting None will turn off the options (regarding Paren
951 Highlighting) which you had selected earlier.
954 You can select any Font for your program by choosing from one of
958 You can select any size ranging from 2 to 24 by selecting the
962 You can choose either Bold or Medium for the weight.
964 Buffers Menu Length...
965 Prompts you for the number of buffers to display. Then it will
966 display that number of most recently selected buffers.
969 After selection of this item the Buffers menu will contain several
970 commands, as submenus of each buffer line. If this item is
971 unselected, then there are no submenus for each buffer line, the
972 only command available will be selecting that buffer.
975 Selecting this item will save the current settings of your Options
976 menu to your `.emacs' file.
979 File: xemacs.info, Node: Buffers Menu, Next: Tools Menu, Prev: Options Menu, Up: Pull-down Menus
984 The Buffers menu provides a selection of up to ten buffers and the
985 item List All Buffers, which provides a Buffer List. *Note List
986 Buffers::, for more information.
989 File: xemacs.info, Node: Tools Menu, Next: Help Menu, Prev: Buffers Menu, Up: Pull-down Menus
994 The Tools pull-down menu contains the Grep..., Compile..., Shell
995 Command..., Shell Command on Region..., Debug(GDB)... and
996 Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags
997 sub-menus. When you select a menu item, Emacs executes the equivalent
998 command. For some of the menu items, there are sub-menus which you
1002 File: xemacs.info, Node: Help Menu, Next: Menu Customization, Prev: Tools Menu, Up: Pull-down Menus
1007 The Help Menu gives you access to Emacs Info and provides a menu
1008 equivalent for each of the choices you have when using `C-h'. *Note
1009 Help::, for more information.
1011 The Help menu also gives access to UNIX online manual pages via the
1012 UNIX Manual Page option.
1015 File: xemacs.info, Node: Menu Customization, Prev: Help Menu, Up: Pull-down Menus
1017 Customizing XEmacs Menus
1018 ------------------------
1020 You can customize any of the pull-down menus by adding or removing
1021 menu items and disabling or enabling existing menu items.
1023 The following functions are available:
1024 `add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)'
1025 Add a menu to the menu bar or one of its submenus.
1027 `add-menu-item: (MENU-PATH ITEM-NAME FUNCTION'
1028 ENABLED-P &optional BEFORE) Add a menu item to a menu, creating
1029 the menu first if necessary.
1031 `delete-menu-item: (PATH)'
1032 Remove the menu item defined by PATH from the menu hierarchy.
1034 `disable-menu-item: (PATH)'
1035 Disable the specified menu item.
1037 `enable-menu-item: (PATH)'
1038 Enable the specified previously disabled menu item.
1040 `relabel-menu-item: (PATH NEW-NAME)'
1041 Change the string of the menu item specified by PATH to NEW-NAME.
1043 Use the function `add-menu' to add a new menu or submenu. If a menu
1044 or submenu of the given name exists already, it is changed.
1046 MENU-PATH identifies the menu under which the new menu should be
1047 inserted. It is a list of strings; for example, `("File")' names the
1048 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
1049 File. If MENU-PATH is `nil', the menu is added to the menu bar itself.
1051 MENU-NAME is the string naming the menu to be added.
1053 MENU-ITEMS is a list of menu item descriptions. Each menu item
1054 should be a vector of three elements:
1056 * A string, which is the name of the menu item
1058 * A symbol naming a command, or a form to evaluate
1060 * `t' or `nil' to indicate whether the item is selectable
1062 The optional argument BEFORE is the name of the menu before which
1063 the new menu or submenu should be added. If the menu is already
1064 present, it is not moved.
1066 The function `add-menu-item' adds a menu item to the specified menu,
1067 creating the menu first if necessary. If the named item already
1068 exists, the menu remains unchanged.
1070 MENU-PATH identifies the menu into which the new menu item should be
1071 inserted. It is a list of strings; for example, `("File")' names the
1072 top-level File menu. `("File" "Foo")' names a hypothetical submenu of
1075 ITEM-NAME is the string naming the menu item to add.
1077 FUNCTION is the command to invoke when this menu item is selected.
1078 If it is a symbol, it is invoked with `call-interactively', in the same
1079 way that functions bound to keys are invoked. If it is a list, the
1080 list is simply evaluated.
1082 ENABLED-P controls whether the item is selectable or not. It should
1083 be `t', `nil', or a form to evaluate to decide. This form will be
1084 evaluated just before the menu is displayed, and the menu item will be
1085 selectable if that form returns non-`nil'.
1087 For example, to make the `rename-file' command available from the
1088 File menu, use the following code:
1090 (add-menu-item '("File") "Rename File" 'rename-file t)
1092 To add a submenu of file management commands using a File Management
1093 item, use the following code:
1095 (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
1096 (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
1097 (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
1099 The optional BEFORE argument is the name of a menu item before which
1100 the new item should be added. If the item is already present, it is
1103 To remove a specified menu item from the menu hierarchy, use
1106 PATH is a list of strings that identify the position of the menu
1107 item in the menu hierarchy. `("File" "Save")' means the menu item
1108 called Save under the top level File menu. `("Menu" "Foo" "Item")'
1109 means the menu item called Item under the Foo submenu of Menu.
1111 To disable a menu item, use `disable-menu-item'. The disabled menu
1112 item is grayed and can no longer be selected. To make the item
1113 selectable again, use `enable-menu-item'. `disable-menu-item' and
1114 `enable-menu-item' both have the argument PATH.
1116 To change the string of the specified menu item, use
1117 `relabel-menu-item'. This function also takes the argument PATH.
1119 NEW-NAME is the string to which the menu item will be changed.
1122 File: xemacs.info, Node: Entering Emacs, Next: Exiting, Prev: Pull-down Menus, Up: Top
1124 Entering and Exiting Emacs
1125 **************************
1127 The usual way to invoke XEmacs is to type `xemacs <RET>' at the
1128 shell. XEmacs clears the screen and then displays an initial advisory
1129 message and copyright notice. You can begin typing XEmacs commands
1130 immediately afterward.
1132 Some operating systems insist on discarding all type-ahead when
1133 XEmacs starts up; they give XEmacs no way to prevent this. Therefore,
1134 it is advisable to wait until XEmacs clears the screen before typing
1135 your first editing command.
1137 If you run XEmacs from a shell window under the X Window System, run
1138 it in the background with `xemacs&'. This way, XEmacs does not tie up
1139 the shell window, so you can use that to run other shell commands while
1140 XEmacs operates its own X windows. You can begin typing XEmacs commands
1141 as soon as you direct your keyboard input to the XEmacs frame.
1143 Before Emacs reads the first command, you have not had a chance to
1144 give a command to specify a file to edit. Since Emacs must always have
1145 a current buffer for editing, it presents a buffer, by default, a buffer
1146 named `*scratch*'. The buffer is in Lisp Interaction mode; you can use
1147 it to type Lisp expressions and evaluate them, or you can ignore that
1148 capability and simply doodle. (You can specify a different major mode
1149 for this buffer by setting the variable `initial-major-mode' in your
1150 init file. *Note Init File::.)
1152 It is possible to specify files to be visited, Lisp files to be
1153 loaded, and functions to be called, by giving Emacs arguments in the
1154 shell command line. *Note Command Switches::. But we don't recommend
1155 doing this. The feature exists mainly for compatibility with other
1158 Many other editors are designed to be started afresh each time you
1159 want to edit. You edit one file and then exit the editor. The next
1160 time you want to edit either another file or the same one, you must run
1161 the editor again. With these editors, it makes sense to use a
1162 command-line argument to say which file to edit.
1164 But starting a new Emacs each time you want to edit a different file
1165 does not make sense. For one thing, this would be annoyingly slow. For
1166 another, this would fail to take advantage of Emacs's ability to visit
1167 more than one file in a single editing session. And it would lose the
1168 other accumulated context, such as registers, undo history, and the mark
1171 The recommended way to use XEmacs is to start it only once, just
1172 after you log in, and do all your editing in the same Emacs session.
1173 Each time you want to edit a different file, you visit it with the
1174 existing Emacs, which eventually comes to have many files in it ready
1175 for editing. Usually you do not kill the Emacs until you are about to
1176 log out. *Note Files::, for more information on visiting more than one