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: Mode Line, Next: GUI Components, 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: GUI Components, Next: XEmacs under X, Prev: Mode Line, Up: Frame
130 When executed in a graphical windowing environment such as the X
131 Window System or Microsoft Windows, XEmacs displays several graphical
132 user interface components such as scrollbars, menubars, toolbars, and
133 gutters. By default there is a vertical scrollbar at the right of each
134 frame, and at the top of the frame there is a menubar, a toolbar, and a
135 gutter, in that order. Gutters can contain any of several widgets, but
136 the default configuration puts a set of "notebook tabs" which you can
137 use as a shortcut for selecting any of several related buffers in a
138 given frame. Operating the GUI components is "obvious": click on the
139 menubar to pull down a menu, on a button in the toolbar to invoke a
140 function, and on a tab in the gutter to switch buffers.
144 * Menubar Basics:: How XEmacs uses the menubar.
145 * Scrollbar Basics:: How XEmacs uses scrollbars.
146 * Mode Line Basics:: How XEmacs uses modelines.
147 * Toolbar Basics:: How XEmacs uses toolbars.
148 * Gutter Basics:: How XEmacs uses gutters.
149 * Inhibiting:: What if you don't like GUI?
150 * Customizing:: Position, orientation, and appearance of GUI objects.
153 File: xemacs.info, Node: Menubar Basics, Next: Scrollbar Basics, Up: GUI Components
158 The XEmacs menubar is intended to be conformant to the usual
159 conventions for menubars, although conformance is not yet perfect. The
160 menu at the extreme right is the `Help' menu, which should always be
161 available. It provides access to all the XEmacs help facilities
162 available through `C-h', as well as samples of various configuration
163 files like `~/.Xdefaults' and `~/.emacs'. At the extreme left is the
164 `Files' menu, which provides the usual file reading, writing, and
165 printing operations, as well as operations like revert buffer from most
166 recent save. The next menu from the left is the `Edit' menu, which
167 provides the `Undo' operation as well as cutting and pasting,
168 searching, and keyboard macro definition and execution.
170 XEmacs provides a very dynamic environment, and the Lisp language
171 makes for highly flexible applications. The menubar reflects this:
172 many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
173 determined by the current state of XEmacs, and most major modes and many
174 minor modes add items to menus and even whole menus to the menubar. In
175 fact, some applications like w3.el and VM provide so many menus that
176 they define a whole new menubar and add a button that allows convenient
177 switching between the "XEmacs menubar" and the "application menubar".
178 Such applications normally bind themselves to a particular frame, and
179 this switching only takes place on frames where such an application is
180 active (ie, the current window of the frame is displaying a buffer in
181 the appropriate major mode).
183 Other menus which are typically available are the `Options',
184 `Tools', `Buffers', `Apps', and `Mule' menus. For detailed
185 descriptions of these menus, *Note Pull-down Menus::. (In 21.2
186 XEmacsen, the `Mule' menu will be moved under `Options'.)
189 File: xemacs.info, Node: Scrollbar Basics, Next: Mode Line Basics, Prev: Menubar Basics, Up: GUI Components
194 XEmacs scrollbars provide the usual interface. Arrow buttons at
195 either end allow for line by line scrolling, including autorepeat.
196 Clicking in the scrollbar itself provides scrolling by windowsfull,
197 depending on which side of the slider is clicked. The slider itself
198 may be dragged for smooth scrolling.
200 The position of the slider corresponds to the position of the window
201 in the buffer. In particular, the length of the slider is proportional
202 to the fraction of the buffer which appears in the window.
204 The presence of the scrollbars is under control of the application or
205 may be customized by the user. By default a vertical scrollbar is
206 present in all windows (except the minibuffer), and there is no
207 horizontal scrollbar.
210 File: xemacs.info, Node: Mode Line Basics, Next: Toolbar Basics, Prev: Scrollbar Basics, Up: GUI Components
215 When used in a windowing system, the XEmacs modelines can be dragged
216 vertically. The effect is to resize the windows above and below the
217 modeline (this includes the minibuffer window).
219 Additionally, a modeline can be dragged horizontally, in which case
220 it scrolls its own text. This behavior is not enabled by default
221 because it could be considered as disturbing when dragging vertically.
222 When this behavior is enabled, the modeline's text can be dragged
223 either in the same direction as the mouse, or in the opposite sense,
224 making the modeline act as a scrollbar for its own text.
226 You can select the behavior you want from the `Display' submenu of
230 File: xemacs.info, Node: Toolbar Basics, Next: Gutter Basics, Prev: Mode Line Basics, Up: GUI Components
235 XEmacs has a default toolbar which provides shortcuts for some of the
236 commonly used operations (such as opening files) and applications (such
237 as the Info manual reader). Operations which require arguments will pop
238 up dialogs to get them.
240 The position of the default toolbar can be customized. Also, several
241 toolbars may be present simultaneously (in different positions). VM,
242 for example, provides an application toolbar which shortcuts for
243 mail-specific operations like sending, saving, and deleting messages.
246 File: xemacs.info, Node: Gutter Basics, Next: Inhibiting, Prev: Toolbar Basics, Up: GUI Components
251 Gutters are the most flexible of the GUI components described in this
252 section. In theory, the other GUI components could be implemented by
253 customizing a gutter, but in practice the other components were
254 introduced earlier and have their own special implementations. Gutters
255 tend to be more transient than the other components. Buffer tabs, for
256 example, change every time the selected buffer in the frame changes.
257 And for progress gauges a gutter to contain the gauge is typically
258 created on the fly when needed, then destroyed when the operation whose
259 staus is being displayed is completed.
261 Buffer tabs, having somewhat complex behavior, deserve a closer look.
262 By default, a row of buffer tabs is displayed at the top of every frame.
263 (The tabs could be placed in the bottom gutter, but would be oriented
264 the same way and look rather odd. The horizontal orientation makes
265 putting them in a side gutter utterly impractical.) The buffer
266 displayed in the current window of a frame can be changed to a specific
267 buffer by clicking [mouse-1] on the corresponding tab in the gutter.
269 Each tab contains the name of its buffer. The tab for the current
270 buffer in each frame is displayed in raised relief. The list of buffers
271 chosen for display in the buffer tab row is derived by filtering the
272 buffer list (like the `Buffers' menu). The list starts out with all
273 existing buffers, with more recently selected buffers coming earlier in
276 Then "uninteresting" buffers, like internal XEmacs buffers, the
277 `*Message Log*' buffer, and so on are deleted from the list. Next, the
278 frame's selected buffer is determined. Buffers with a different major
279 mode from the selected buffer are removed from the list. Finally, if
280 the list is too long, the least recently used buffers are deleted from
281 the list. By default up to 6 most recently used buffers with the same
282 mode are displayed on tabs in the gutter.
285 File: xemacs.info, Node: Inhibiting, Next: Customizing, Prev: Gutter Basics, Up: GUI Components
287 Inhibiting Display of GUI Components
288 ====================================
290 Use of GUI facilities is a personal thing. Almost everyone agrees
291 that drawing via keyboard-based "turtle graphics" is acceptable to
292 hardly anyone if a mouse is available, but conversely emulating a
293 keyboard with a screenful of buttons is a painful experience. But
294 between those extremes the complete novice will require a fair amount
295 of time before toolbars and menus become dispensable, but many an
296 "Ancien Haquer" sees them as a complete waste of precious frame space
297 that could be filled with text.
299 Display of all of the GUI components created by XEmacs can be
300 inhibited through the use of Customize. Customize can be accessed
301 through `Options | Customize' in the menu bar, or via `M-x customize'.
302 Then navigate through the Customize tree to `Emacs | Environment'.
303 Scrollbar and toolbar visibility is controlled via the `Display' group,
304 options `Scrollbars visible' and `Toolbar visible' respectively.
305 Gutter visibility is controlled by group `Gutter', option `Visible'.
307 Or they can be controlled directly by `M-x customize-variable', by
308 changing the values of the variables `menubar-visible-p',
309 `scrollbars-visible-p', `toolbar-visible-p', or
310 `gutter-buffers-tab-visible-p' respectively. (The strange form of the
311 last variable is due to the fact that gutters are often used to display
312 transient widgets like progress gauges, which you probably don't want
313 to inhibit. It is more likely that you want to inhibit the default
314 display of the buffers tab widget, which is what that variable controls.
315 This interface is subject to change depending on developer experience
318 Control of frame configuration can controlled automatically
319 according to various parameters such as buffer or frame because these
320 are "specifiers" *Note Specifiers: (lispref)Specifiers. Using these
321 features requires programming in Lisp; Customize is not yet that
322 sophisticated. Also, components that appear in various positions and
323 orientations can have display suppressed according to position. `C-h a
324 visible-p' gives a list of variables which can be customized. E.g., to
325 control the visibility of specifically the left-side toolbar only,
326 customize `left-toolbar-visible-p'.
329 File: xemacs.info, Node: Customizing, Prev: Inhibiting, Up: GUI Components
331 Changing the Position, Orientation, and Appearance of GUI Components
332 ====================================================================
334 #### Not documented yet.
337 File: xemacs.info, Node: XEmacs under X, Next: XEmacs under MS Windows, Prev: GUI Components, Up: Frame
339 Using XEmacs Under the X Window System
340 ======================================
342 XEmacs can be used with the X Window System and a window manager like
343 MWM or TWM. In that case, the X window manager opens, closes, and
344 resizes XEmacs frames. You use the window manager's mouse gestures to
345 perform the operations. Consult your window manager guide or reference
346 manual for information on manipulating X windows.
348 When you are working under X, each X window (that is, each XEmacs
349 frame) has a menu bar for mouse-controlled operations (*note Pull-down
352 XEmacs under X is also a multi-frame XEmacs. You can use the New
353 Frame menu item from the File menu to create a new XEmacs frame in a
354 new X window from the same process. The different frames will share the
355 same buffer list, but you can look at different buffers in the different
358 The function `find-file-other-frame' is just like `find-file', but
359 creates a new frame to display the buffer in first. This is normally
360 bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
363 The function `switch-to-buffer-other-frame' is just like
364 `switch-to-buffer', but creates a new frame to display the buffer in
365 first. This is normally bound to `C-x 5 b'.
367 You can specify a different default frame size other than the one
368 provided. Use the variable `default-frame-alist', which is an alist of
369 default values for frame creation other than the first one. These may
370 be set in your init file, like this:
372 (setq default-frame-alist '((width . 80) (height . 55)))
374 For values specific to the first XEmacs frame, you must use X
375 resources. The variable `x-frame-defaults' takes an alist of default
376 frame creation parameters for X window frames. These override what is
377 specified in `~/.Xdefaults' but are overridden by the arguments to the
378 particular call to `x-create-frame'.
380 When you create a new frame, the variable `create-frame-hook' is
381 called with one argument, the frame just created.
383 If you want to close one or more of the X windows you created using
384 New Frame, use the Delete Frame menu item from the File menu.
386 If you are working with multiple frames, some special information
388 * Two variables, `frame-title-format' and `frame-icon-title-format'
389 determine the title of the frame and the title of the icon that
390 results if you shrink the frame.
392 * The variables `auto-lower-frame' and `auto-raise-frame' position a
393 frame. If true, `auto-lower-frame' lowers a frame to the bottom
394 when it is no longer selected. If true, `auto-raise-frame' raises
395 a frame to the top when it is selected. Under X, most
396 ICCCM-compliant window managers will have options to do this for
397 you, but these variables are provided in case you are using a
398 broken window manager.
400 * There is a new frame/modeline format directive, %S, which expands
401 to the name of the current frame (a frame's name is distinct from
402 its title; the name is used for resource lookup, among other
403 things, and the title is simply what appears above the window.)
406 File: xemacs.info, Node: XEmacs under MS Windows, Prev: XEmacs under X, Up: Frame
408 Using XEmacs Under Microsoft Windows
409 ====================================
411 Use of XEmacs under MS Windows is not separately documented here, but
412 most operations available under the X Window System are also available
415 Where possible, native MS Windows GUI components and capabilities are
419 File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
421 Keystrokes, Key Sequences, and Key Bindings
422 *******************************************
426 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
427 * Representing Keystrokes:: Using lists of modifiers and keysyms to
428 represent keystrokes.
429 * Key Sequences:: Combine key strokes into key sequences you can
431 * String Key Sequences:: Available for upward compatibility.
432 * Meta Key:: Using <ESC> to represent <Meta>
433 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
434 * Character Representation:: How characters appear in Emacs buffers.
435 * Commands:: How commands are bound to key sequences.
438 File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
440 Keystrokes as Building Blocks of Key Sequences
441 ==============================================
443 Earlier versions of Emacs used only the ASCII character set, which
444 defines 128 different character codes. Some of these codes are
445 assigned graphic symbols like `a' and `='; the rest are control
446 characters, such as `Control-a' (also called `C-a'). `C-a' means you
447 hold down the <CTRL> key and then press `a'.
449 Keybindings in XEmacs are not restricted to the set of keystrokes
450 that can be represented in ASCII. XEmacs can tell the difference
451 between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
453 A keystroke is like a piano chord: you get it by simultaneously
454 striking several keys. To be more precise, a keystroke consists of a
455 possibly empty set of modifiers followed by a single "keysym". The set
456 of modifiers is small; it consists of `Control', `Meta', `Super',
457 `Hyper', and `Shift'.
459 The rest of the keys on your keyboard, along with the mouse buttons,
460 make up the set of keysyms. A keysym is usually what is printed on the
461 keys on your keyboard. Here is a table of some of the symbolic names
479 upstroke on the left mouse button
482 upstroke on the middle mouse button
485 upstroke on the right mouse button
490 Use the variable `keyboard-translate-table' only if you are on a
491 dumb tty, as it cannot handle input that cannot be represented as ASCII.
492 The value of this variable is a string used as a translate table for
493 keyboard input or `nil'. Each character is looked up in this string
494 and the contents used instead. If the string is of length `n',
495 character codes `N' and up are untranslated. If you are running Emacs
496 under X, you should do the translations with the `xmodmap' program
500 File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
502 Representing Keystrokes
503 -----------------------
505 XEmacs represents keystrokes as lists. Each list consists of an
506 arbitrary combination of modifiers followed by a single keysym at the
507 end of the list. If the keysym corresponds to an ASCII character, you
508 can use its character code. (A keystroke may also be represented by an
509 event object, as returned by the `read-key-sequence' function;
510 non-programmers need not worry about this.)
512 The following table gives some examples of how to list
513 representations for keystrokes. Each list consists of sets of
514 modifiers followed by keysyms:
517 Pressing <CTRL> and `a' simultaneously.
520 Another way of writing the keystroke `C-a'.
523 Yet another way of writing the keystroke `C-a'.
526 Pressing the <BREAK> key.
528 `(control meta button2up)'
529 Release the middle mouse button, while pressing <CTRL> and <META>.
530 Note: As you define keystrokes, you can use the `shift' key only as a
531 modifier with characters that do not have a second keysym on the same
532 key, such as `backspace' and `tab'. It is an error to define a
533 keystroke using the <shift> modifier with keysyms such as `a' and `='.
534 The correct forms are `A' and `+'.
537 File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
539 Representing Key Sequences
540 --------------------------
542 A "complete key sequence" is a sequence of keystrokes that Emacs
543 understands as a unit. Key sequences are significant because you can
544 bind them to commands. Note that not all sequences of keystrokes are
545 possible key sequences. In particular, the initial keystrokes in a key
546 sequence must make up a "prefix key sequence".
548 Emacs represents a key sequence as a vector of keystrokes. Thus, the
549 schematic representation of a complete key sequence is as follows:
551 [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
553 Here are some examples of complete key sequences:
555 `[(control c) (control a)]'
556 Typing `C-c' followed by `C-a'
558 `[(control c) (control 65)]'
559 Typing `C-c' followed by `C-a'. (Using the ASCII code for the
562 `[(control c) (break)]'
563 Typing `C-c' followed by the `break' character.
565 A "prefix key sequence" is the beginning of a series of longer
566 sequences that are valid key sequences; adding any single keystroke to
567 the end of a prefix results in a valid key sequence. For example,
568 `control-x' is standardly defined as a prefix. Thus there is a
569 two-character key sequence starting with `C-x' for each valid
570 keystroke, giving numerous possibilities. Here are some samples:
572 * `[(control x) (c)]'
574 * `[(control x) (control c)]'
576 Adding one character to a prefix key does not have to form a complete
577 key. It could make another, longer prefix. For example, `[(control x)
578 (\4)]' is itself a prefix that leads to any number of different
579 three-character keys, including `[(control x) (\4) (f)]', `[(control x)
580 (\4) (b)]' and so on. It would be possible to define one of those
581 three-character sequences as a prefix, creating a series of
582 four-character keys, but we did not define any of them this way.
584 By contrast, the two-character sequence `[(control f) (control k)]'
585 is not a key, because the `(control f)' is a complete key sequence in
586 itself. You cannot give `[(control f (control k)]' an independent
587 meaning as a command while `(control f)' is a complete sequence,
588 because Emacs would understand <C-f C-k> as two commands.
590 The predefined prefix key sequences in Emacs are `(control c)',
591 `(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
592 can customize Emacs and could make new prefix keys or eliminate the
593 default key sequences. *Note Key Bindings::. For example, if you
594 redefine `(control f)' as a prefix, `[(control f) (control k)]'
595 automatically becomes a valid key sequence (complete, unless you define
596 it as a prefix as well). Conversely, if you remove the prefix
597 definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
598 `[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
600 Note that the above paragraphs uses \4 instead of simply 4, because
601 \4 is the symbol whose name is "4", and plain 4 is the integer 4, which
602 would have been interpreted as the ASCII value. Another way of
603 representing the symbol whose name is "4" is to write ?4, which would be
604 interpreted as the number 52, which is the ASCII code for the character
605 "4". We could therefore actually have written 52 directly, but that is
609 File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
614 For backward compatibility, you may also represent a key sequence
615 using strings. For example, we have the following equivalent
619 `[(control c) (control c)]'
625 File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
627 Assignment of the <META> Key
628 ----------------------------
630 Not all terminals have the complete set of modifiers. Terminals
631 that have a <Meta> key allow you to type Meta characters by just
632 holding that key down. To type `Meta-a', hold down <META> and press
633 `a'. On those terminals, the <META> key works like the <SHIFT> key.
634 Such a key is not always labeled <META>, however, as this function is
635 often a special option for a key with some other primary purpose.
637 If there is no <META> key, you can still type Meta characters using
638 two-character sequences starting with <ESC>. To enter `M-a', you could
639 type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
640 allowed on terminals with Meta keys, too, in case you have formed a
643 If you are running under X and do not have a <META> key, it is
644 possible to reconfigure some other key to be a <META> key. *Note Super
647 Emacs believes the terminal has a <META> key if the variable
648 `meta-flag' is non-`nil'. Normally this is set automatically according
649 to the termcap entry for your terminal type. However, sometimes the
650 termcap entry is wrong, and then it is useful to set this variable
651 yourself. *Note Variables::, for how to do this.
653 Note: If you are running under the X window system, the setting of
654 the `meta-flag' variable is irrelevant.
657 File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
659 Assignment of the <SUPER> and <HYPER> Keys
660 ------------------------------------------
662 Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
663 keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
664 to bind keys to sequences using `super' and `hyper'. You can use the
665 `xmodmap' program to do this.
667 For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
670 Create a file called `~/.xmodmap'. In this file, place the lines
672 remove Lock = Caps_Lock
673 keysym Caps_Lock = Super_L
676 The first line says that the key that is currently called `Caps_Lock'
677 should no longer behave as a "lock" key. The second line says that
678 this should now be called `Super_L' instead. The third line says that
679 the key called `Super_L' should be a modifier key, which produces the
682 To create a <META> or <HYPER> key instead of a <SUPER> key, replace
683 the word `Super' above with `Meta' or `Hyper'.
685 Just after you start up X, execute the command `xmodmap /.xmodmap'.
686 You can add this command to the appropriate initialization file to have
687 the command executed automatically.
689 If you have problems, see the documentation for the `xmodmap'
690 program. The X keyboard model is quite complicated, and explaining it
691 is beyond the scope of this manual. However, we reprint the following
692 description from the X Protocol document for your convenience:
694 A list of keysyms is associated with each keycode. If that list
695 (ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
696 list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
697 the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
698 `K1 K2', then the list is treated as if it were the list ```K1 K2 K1
699 K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
700 of keysyms `K1 K2 K3', then the list is treated as if it were the list
701 ```K1 K2 K3 NoSymbol'''.
703 The first four elements of the list are split into two groups of
704 keysyms. Group 1 contains the first and second keysyms; Group 2 contains
705 third and fourth keysyms. Within each group, if the second element of
706 the group is NoSymbol, then the group should be treated as if the second
707 element were the same as the first element, except when the first
708 element is an alphabetic keysym `K' for which both lowercase and
709 uppercase forms are defined. In that case, the group should be treated
710 as if the first element were the lowercase form of `K' and the second
711 element were the uppercase form of `K'.
713 The standard rules for obtaining a keysym from a KeyPress event make
714 use of only the Group 1 and Group 2 keysyms; no interpretation of other
715 keysyms in the list is given here. (That is, the last four keysyms are
718 Which group to use is determined by modifier state. Switching between
719 groups is controlled by the keysym named `Mode_switch'. Attach that
720 keysym to some keycode and attach that keycode to any one of the
721 modifiers Mod1 through Mod5. This modifier is called the "group
722 modifier". For any keycode, Group 1 is used when the group modifier is
723 off, and Group 2 is used when the group modifier is on.
725 Within a group, which keysym to use is also determined by modifier
726 state. The first keysym is used when the `Shift' and `Lock' modifiers
727 are off. The second keysym is used when the `Shift' modifier is on, or
728 when the `Lock' modifier is on and the second keysym is uppercase
729 alphabetic, or when the `Lock' modifier is on and is interpreted as
730 `ShiftLock'. Otherwise, when the `Lock' modifier is on and is
731 interpreted as `CapsLock', the state of the `Shift' modifier is applied
732 first to select a keysym, but if that keysym is lower-case alphabetic,
733 then the corresponding upper-case keysym is used instead.
735 In addition to the above information on keysyms, we also provide the
736 following description of modifier mapping from the InterClient
737 Communications Conventions Manual:
739 X11 supports 8 modifier bits, of which 3 are pre-assigned to
740 `Shift', `Lock', and `Control'. Each modifier bit is controlled by the
741 state of a set of keys, and these sets are specified in a table
742 accessed by `GetModifierMapping()' and `SetModifierMapping()'.
744 A client needing to use one of the pre-assigned modifiers should
745 assume that the modifier table has been set up correctly to control
746 these modifiers. The `Lock' modifier should be interpreted as `Caps
747 Lock' or `Shift Lock' according to whether the keycodes in its
748 controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
750 Clients should determine the meaning of a modifier bit from the
751 keysyms being used to control it.
753 A client needing to use an extra modifier, for example `Meta',
756 1. Scan the existing modifier mappings.
758 1. If it finds a modifier that contains a keycode whose set of
759 keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
762 2. If there is no existing modifier controlled by `XK_Meta_L' or
763 `XK_Meta_R', it should select an unused modifier bit (one with
764 an empty controlling set) and:
766 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
767 that keycode to the set for the chosen modifier, and then:
769 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
770 add that keycode to the set for the chosen modifier, and then:
772 2. If the controlling set is still empty, interact with the user
773 to select one or more keys to be `Meta'.
775 3. If there are no unused modifier bits, ask the user to take
778 This means that the `Mod1' modifier does not necessarily mean
779 `Meta', although some applications (such as twm and emacs 18) assume
780 that. Any of the five unassigned modifier bits could mean `Meta'; what
781 matters is that a modifier bit is generated by a keycode which is bound
782 to the keysym `Meta_L' or `Meta_R'.
784 Therefore, if you want to make a <META> key, the right way is to
785 make the keycode in question generate both a `Meta' keysym and some
786 previously-unassigned modifier bit.
789 File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
791 Representation of Characters
792 ============================
794 This section briefly discusses how characters are represented in
795 Emacs buffers. *Note Key Sequences::, for information on representing
796 key sequences to create key bindings.
798 ASCII graphic characters in Emacs buffers are displayed with their
799 graphics. <LFD> is the same as a newline character; it is displayed by
800 starting a new line. <TAB> is displayed by moving to the next tab stop
801 column (usually every 8 spaces). Other control characters are
802 displayed as a caret (`^') followed by the non-control version of the
803 character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
804 and up are displayed with octal escape sequences; thus, character code
805 243 (octal), also called `M-#' when used as an input character, is
808 The variable `ctl-arrow' may be used to alter this behavior. *Note
812 File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
817 This manual is full of passages that tell you what particular keys
818 do. But Emacs does not assign meanings to keys directly. Instead,
819 Emacs assigns meanings to "functions", and then gives keys their
820 meanings by "binding" them to functions.
822 A function is a Lisp object that can be executed as a program.
823 Usually it is a Lisp symbol that has been given a function definition;
824 every symbol has a name, usually made of a few English words separated
825 by dashes, such as `next-line' or `forward-word'. It also has a
826 "definition", which is a Lisp program. Only some functions can be the
827 bindings of keys; these are functions whose definitions use
828 `interactive' to specify how to call them interactively. Such
829 functions are called "commands", and their names are "command names".
830 More information on this subject will appear in the XEmacs Lisp
833 The bindings between keys and functions are recorded in various
834 tables called "keymaps". *Note Key Bindings::, for more information on
835 key sequences you can bind commands to. *Note Keymaps::, for
836 information on creating keymaps.
838 When we say "`C-n' moves down vertically one line" we are glossing
839 over a distinction that is irrelevant in ordinary use but is vital in
840 understanding how to customize Emacs. The function `next-line' is
841 programmed to move down vertically. `C-n' has this effect because it
842 is bound to that function. If you rebind `C-n' to the function
843 `forward-word' then `C-n' will move forward by words instead.
844 Rebinding keys is a common method of customization.
846 The rest of this manual usually ignores this subtlety to keep things
847 simple. To give the customizer the information needed, we often state
848 the name of the command that really does the work in parentheses after
849 mentioning the key that runs it. For example, we will say that "The
850 command `C-n' (`next-line') moves point vertically down," meaning that
851 `next-line' is a command that moves vertically down and `C-n' is a key
852 that is standardly bound to it.
854 While we are on the subject of information for customization only,
855 it's a good time to tell you about "variables". Often the description
856 of a command will say, "To change this, set the variable `mumble-foo'."
857 A variable is a name used to remember a value. Most of the variables
858 documented in this manual exist just to facilitate customization: some
859 command or other part of Emacs uses the variable and behaves
860 differently depending on its setting. Until you are interested in
861 customizing, you can ignore the information about variables. When you
862 are ready to be interested, read the basic information on variables, and
863 then the information on individual variables will make sense. *Note
867 File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
869 XEmacs Pull-down Menus
870 ======================
872 If you are running XEmacs under X, a menu bar on top of the Emacs
873 frame provides access to pull-down menus of file, edit, and
874 help-related commands. The menus provide convenient shortcuts and an
875 easy interface for novice users. They do not provide additions to the
876 functionality available via key commands; you can still invoke commands
877 from the keyboard as in previous versions of Emacs.
880 Perform file and buffer-related operations, such as opening and
881 closing files, saving and printing buffers, as well as exiting
885 Perform standard editing operations, such as cutting, copying,
886 pasting, and killing selected text.
889 Access to sub-applications implemented within XEmacs, such as the
890 mail reader, the World Wide Web browser, the spell-checker, and
891 the calendar program.
894 Control various options regarding the way XEmacs works, such as
895 controlling which elements of the frame are visible, selecting the
896 fonts to be used for text, specifying whether searches are
900 Present a menu of buffers for selection as well as the option to
901 display a buffer list.
904 Perform various actions designed to automate software development
905 and similar technical work, such as searching through many files,
906 compiling a program, and comparing or merging two or three files.
909 Access to Emacs Info.
911 There are two ways of selecting an item from a pull-down menu:
913 * Select an item in the menu bar by moving the cursor over it and
914 click the left mouse-button. Then move the cursor over the menu
915 item you want to choose and click left again.
917 * Select an item in the menu bar by moving the cursor over it and
918 click and hold the left mouse-button. With the mouse-button
919 depressed, move the cursor over the menu item you want, then
920 release it to make your selection.
922 If a command in the pull-down menu is not applicable in a given
923 situation, the command is disabled and its name appears faded. You
924 cannot invoke items that are faded. For example, many commands on the
925 Edit menu appear faded until you select text on which they are to
926 operate; after you select a block of text, edit commands are enabled.
927 *Note Mouse Selection::, for information on using the mouse to select
928 text. *Note Using X Selections::, for related information.
930 There are also `M-x' equivalents for each menu item. To find the
931 equivalent for any left-button menu item, do the following:
933 1. Type `C-h k' to get the `Describe Key' prompt.
935 2. Select the menu item and click.
937 Emacs displays the function associated with the menu item in a
938 separate window, usually together with some documentation.
942 * File Menu:: Items on the File menu.
943 * Edit Menu:: Items on the Edit menu.
944 * Apps Menu:: Items on the Apps menu.
945 * Options Menu:: Items on the Options menu.
946 * Buffers Menu:: Information about the Buffers menu.
947 * Tools Menu:: Items on the Tools menu.
948 * Help Menu:: Items on the Help menu.
949 * Menu Customization:: Adding and removing menu items and related
953 File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
958 The File menu bar item contains the items New Frame, Open File...,
959 Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
960 Frame, Kill Buffer and Exit Emacs on the pull-down menu. If you select
961 a menu item, Emacs executes the equivalent command.
963 Open File, New Frame...
964 Prompts you for a filename and loads that file into a new buffer
965 in a new Emacs frame, that is, a new X window running under the
966 same Emacs process. You can remove the frame using the Delete
967 Frame menu item. When you remove the last frame, you exit Emacs
968 and are prompted for confirmation.
971 Prompts you for a filename and loads that file into a new buffer.
972 Open File... is equivalent to the Emacs command `find-file' (`C-x
976 Prompts you for a filename and inserts the contents of that file
977 into the current buffer. The file associated with the current
978 buffer is not changed by this command. This is equivalent to the
979 Emacs command `insert-file' (`C-x i').
982 Writes and saves the current Emacs buffer as the latest version of
983 the current visited file. Save Buffer is equivalent to the Emacs
984 command `save-buffer' (`C-x C-s').
987 Writes and saves the current Emacs buffer to the filename you
988 specify. Save Buffer As... is equivalent to the Emacs command
989 `write-file' (`C-x C-w').
992 Restores the last saved version of the file to the current buffer.
993 When you edit a buffer containing a text file, you must save the
994 buffer before your changes become effective. Use Revert Buffer if
995 you do not want to keep the changes you have made in the buffer.
996 Revert Buffer is equivalent to the Emacs command `revert-file'
997 (`M-x revert-buffer').
1000 Kills the current buffer, prompting you first if there are unsaved
1001 changes. This is roughly equivalent to the Emacs command
1002 `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
1003 name of a buffer to kill.
1006 Prints a hardcopy of the current buffer. Equivalent to the Emacs
1007 command `print-buffer' (`M-x print-buffer').
1010 Creates a new Emacs frame displaying the `*scratch*' buffer. This
1011 is like the Open File, New Frame... menu item, except that it does
1012 not prompt for or load a file.
1015 Allows you to close all but one of the frames created by New Frame.
1016 If you created several Emacs frames belonging to the same Emacs
1017 process, you can close all but one of them. When you attempt to
1018 close the last frame, Emacs informs you that you are attempting to
1019 delete the last frame. You have to choose Exit Emacs for that.
1022 Divides the current window on the current frame into two
1023 equal-sized windows, both displaying the same buffer. Equivalent
1024 to the Emacs command `split-window-vertically' (`C-x 2').
1026 Un-split (Keep This)
1027 If the frame is divided into multiple windows, this removes all
1028 windows other than the selected one. Equivalent to the Emacs
1029 command `delete-other-windows' (`C-x 1').
1031 Un-split (Keep Others)
1032 If the frame is divided into multiple windows, this removes the
1033 selected window from the frame, giving the space back to one of the
1034 other windows. Equivalent to the Emacs command `delete-window'
1038 Shuts down (kills) the Emacs process. Equivalent to the Emacs
1039 command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
1040 Emacs process, the system asks which unsaved buffers to save by
1041 going through the list of all buffers in that Emacs process.
1044 File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
1049 The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
1050 Clear menu items. When you select a menu item, Emacs executes the
1051 equivalent command. Most commands on the Edit menu work on a block of
1052 text, the X selection. They appear faded until you select a block of
1053 text (activate a region) with the mouse. *Note Using X Selections::,
1054 *note Killing::, and *note Yanking:: for more information.
1057 Undoes the previous command. Undo is equivalent to the Emacs
1058 command `undo' (`C-x u').
1061 Removes the selected text block from the current buffer, makes it
1062 the X clipboard selection, and places it in the kill ring. Before
1063 executing this command, you have to select a region using Emacs
1064 region selection commands or with the mouse.
1067 Makes a selected text block the X clipboard selection, and places
1068 it in the kill ring. You can select text using one of the Emacs
1069 region selection commands or by selecting a text region with the
1073 Inserts the current value of the X clipboard selection in the
1074 current buffer. Note that this is not necessarily the same as the
1075 Emacs `yank' command, because the Emacs kill ring and the X
1076 clipboard selection are not the same thing. You can paste in text
1077 you have placed in the clipboard using Copy or Cut. You can also
1078 use Paste to insert text that was pasted into the clipboard from
1082 Removes the selected text block from the current buffer but does
1083 not place it in the kill ring or the X clipboard selection.
1085 Start Macro Recording
1086 After selecting this, Emacs will remember every keystroke you type
1087 until End Macro Recording is selected. This is the same as the
1088 Emacs command `start-kbd-macro' (`C-x (').
1091 Selecting this tells emacs to stop remembering your keystrokes.
1092 This is the same as the Emacs command `end-kbd-macro' (`C-x )').
1095 Selecting this item will cause emacs to re-interpret all of the
1096 keystrokes which were saved between selections of the Start Macro
1097 Recording and End Macro Recording menu items. This is the same as
1098 the Emacs command `call-last-kbd-macro' (`C-x e').
1101 File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
1106 The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
1107 (MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
1108 Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
1109 When you select a menu item, Emacs executes the equivalent command.
1110 For some of the menu items, there are sub-menus which you will need to